イベント
すべてのコンテキストに混在するイベントディスパッチ API です。Harness のイベント宣言とそのディスパッチモードは、所有する各サブシステムページに生成されます。
ctx.parallel(name, ...args)
ts
/**
* Dispatch an event, running all listeners concurrently.
*
* @param name — the event name.
* @param args — arguments passed to every listener.
* @returns a promise resolving once every listener has settled.
*/
parallel<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promise<void>
parallel<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promise<void>すべてのリスナーを同時に実行してイベントをディスパッチします。
name— イベント名です。args— すべてのリスナーに渡す引数です。
戻り値 すべてのリスナーが完了した時点で解決される Promise を返します。
ctx.emit(name, ...args)
ts
/**
* Dispatch an event synchronously, ignoring listener return values.
*
* @param name — the event name.
* @param args — arguments passed to every listener.
*/
emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void
emit<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): voidリスナーの戻り値を無視して、イベントを同期的にディスパッチします。
name— イベント名です。args— すべてのリスナーに渡す引数です。
ctx.serial(name, ...args)
ts
/**
* Dispatch an event, awaiting listeners in order until one bails.
*
* @param name — the event name.
* @param args — arguments passed to each listener.
* @returns the first bail value (non-null, non-false, non-undefined), if any.
*/
serial<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
serial<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>いずれかが中断するまで、リスナーを順番に待機しながらイベントをディスパッチします。
name— イベント名です。args— 各リスナーに渡す引数です。
戻り値 存在する場合は、最初の中断値（null、false、undefined 以外）を返します。
ctx.bail(name, ...args)
ts
/**
* Dispatch an event, calling listeners in order until one bails.
*
* @param name — the event name.
* @param args — arguments passed to each listener.
* @returns the first bail value (non-null, non-false, non-undefined), if any.
*/
bail<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
bail<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>いずれかが中断するまで、リスナーを順番に呼び出してイベントをディスパッチします。
name— イベント名です。args— 各リスナーに渡す引数です。
戻り値 存在する場合は、最初の中断値（null、false、undefined 以外）を返します。
ctx.waterfall(name, ...args)
ts
/**
* Dispatch an event whose last argument is a `next` continuation.
*
* Each listener wraps the rest of the chain: calling `next()` invokes the
* next listener (finally the built-in behavior); not calling it vetoes.
*
* @param name — the event name.
* @param args — listener arguments; the final one is the innermost `next`.
* @returns the outermost listener's return value.
*/
waterfall<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
waterfall<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>最後の引数がnext継続であるイベントをディスパッチします。
各リスナーはチェーンの残りをラップします。next()を呼び出すと次のリスナー（最後は組み込みの動作）が実行され、呼び出さない場合は拒否されます。
name— イベント名です。args— リスナー引数です。最後の引数は最も内側のnextです。
戻り値 最も外側のリスナーの戻り値を返します。
ctx.on(name, listener, options?)
ts
/**
* Register an event listener owned by the current fiber.
*
* @param name — the event name to listen for.
* @param listener — called with the dispatch arguments.
* @param options — listener options; a boolean is shorthand for `prepend`.
* @returns a disposer removing the listener; `true` if it was still registered.
*/
on<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean現在のファイバーが所有するイベントリスナーを登録します。
name— 監視するイベント名です。listener— ディスパッチ引数を指定して呼び出されます。options— リスナーオプションです。boolean はprependの省略表記です。
戻り値 リスナーを削除する disposer を返します。リスナーがまだ登録されていた場合はtrueです。
ctx.once(name, listener, options?)
ts
/**
* Same as `on()`, but the listener disposes itself after its first call.
*
* @param name — the event name to listen for.
* @param listener — called at most once with the dispatch arguments.
* @param options — listener options; a boolean is shorthand for `prepend`.
* @returns a disposer removing the listener; `true` if it was still registered.
*/
once<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => booleanon()と同じですが、リスナーは最初の呼び出し後に自身を破棄します。
name— 監視するイベント名です。listener— ディスパッチ引数を指定して最大 1 回呼び出されます。options— リスナーオプションです。boolean はprependの省略表記です。
戻り値 リスナーを削除する disposer を返します。リスナーがまだ登録されていた場合はtrueです。
EventOptions
ctx.on()とctx.once()が受け付けるオプションです。
ts
/** Options accepted by `ctx.on()` and `ctx.once()`. */
interface EventOptions {
/** Add the listener before existing listeners for the same event. */
prepend?: boolean
/** Receive the event regardless of context filter checks. */
global?: boolean
}DispatchMode
イベントサービスで使用するイベントディスパッチ戦略です。
emitは同期リスナーを待機せずに実行し、parallelはすべてのリスナーをまとめて待機し、serialはいずれかが中断するまで順番に待機し、bailは最初の同期的な中断値で停止し、waterfallは最終的なnextコールバックの周囲にリスナーを合成します。
ts
/**
* Event dispatch strategy used by the event service.
*
* `emit` runs synchronous listeners without awaiting them, `parallel` awaits
* all listeners together, `serial` awaits them in order until one bails,
* `bail` stops on the first synchronous bail value, and `waterfall` composes
* listeners around a final `next` callback.
*/
type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'