ファイバー
ファイバーは、読み込まれた 1 つのプラグインインスタンスです。ライフサイクル状態、検証済みの設定、登録済みのエフェクトを保持します。ctx.fiber は現在のファイバーであり、ctx.effect() はそれに処理を委譲します。
ctx.effect(execute, label?)
/**
* Register a cleanup-aware effect on this fiber.
*
* `execute` runs immediately; the disposers it produces are collected and
* run (in reverse order) either when the returned disposer is called or
* when the fiber unloads, whichever comes first. Calling the disposer twice
* is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
* already disposed, and `TypeError` if `execute` returns an invalid shape.
*
* @param execute — the effect body; see {@link Effect} for accepted shapes.
* @param label — effect label shown in `getEffects()` diagnostics.
* @returns a disposer that tears the effect down and settles once done.
*/
effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>このファイバーに、クリーンアップ対応のエフェクトを登録します。
execute は直ちに実行されます。生成されたディスポーザーは収集され、返されたディスポーザーが呼び出されたとき、またはファイバーがアンロードされたときのうち、先に発生した時点で（逆順に）実行されます。ディスポーザーを 2 回呼び出しても何も起こりません。ファイバーがすでに破棄されている場合は CordisError('INACTIVE_EFFECT') をスローし、execute が無効な形式を返した場合は TypeError をスローします。
execute— エフェクト本体です。受け入れられる形式についてはEffectを参照してください。label—getEffects()の診断に表示されるエフェクトラベルです。
戻り値 エフェクトを破棄し、完了後に解決されるディスポーザーを返します。
ctx.fiber
/** The fiber (plugin runtime instance) that owns this context. */
fiber: Fiberこのコンテキストを所有するファイバー（プラグインランタイムインスタンス）です。
Fiber クラス
1 つのプラグインアプリケーションのランタイムインスタンスです。
ファイバーは、ctx.plugin() が返すプラグインコンテキストの依存関係状態、検証済みの設定、ライフサイクルエフェクト、およびクリーンアップを追跡します。
fiber.uid
/** Unique id within the registry; 0 for the root fiber, `null` once disposed. */
public uid: number | nullレジストリ内で一意の ID です。ルートファイバーでは 0、破棄後は null です。
fiber.ctx
/** The context this fiber's plugin runs in (extends the parent context). */
public readonly ctx: Contextこのファイバーのプラグインが実行されるコンテキストです（親コンテキストを拡張します）。
fiber.config
/** The validated plugin config (updated by `update()`). */
public config: any検証済みのプラグイン設定です（update() により更新されます）。
fiber.state
/** Current lifecycle state; transitions emit `internal/status`. */
public state現在のライフサイクル状態です。遷移時には internal/status が発行されます。
fiber.dispose
/** Dispose this fiber: unload the plugin, then settle once cleanup finished. */
public readonly dispose: () => Promise<void>このファイバーを破棄します。プラグインをアンロードしてから、クリーンアップの完了後に解決されます。
fiber.store
/** Snapshot of required service implementations while loaded; `undefined` otherwise. */
public store: Dict<Impl> | undefined読み込み中に必要なサービス実装のスナップショットです。それ以外の場合は undefined です。
fiber.inertia
/** The in-flight load/unload transition, if one is currently running. */
public inertia: Promise<void> | undefined現在実行中の、進行中のロードまたはアンロード遷移です。
fiber.name
/** The plugin's display name, inherited from the nearest named ancestor, else `'root'`. */
get name()プラグインの表示名です。最も近い名前付き祖先から継承され、存在しない場合は 'root' です。
fiber.assertActive()
/**
* Throw if the fiber has already been disposed.
*
* @returns nothing when the fiber is still active.
* @throws {CordisError} `INACTIVE_EFFECT` when the fiber's uid has been cleared.
*/
assertActive()ファイバーがすでに破棄されている場合はスローします。
戻り値 ファイバーがまだアクティブな場合は何も返しません。
fiber.effect(execute, label?)
/**
* Register a cleanup-aware effect on this fiber.
*
* `execute` runs immediately; the disposers it produces are collected and
* run (in reverse order) either when the returned disposer is called or
* when the fiber unloads, whichever comes first. Calling the disposer twice
* is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
* already disposed, and `TypeError` if `execute` returns an invalid shape.
*
* @param execute — the effect body; see {@link Effect} for accepted shapes.
* @param label — effect label shown in `getEffects()` diagnostics.
* @returns a disposer that tears the effect down and settles once done.
*/
effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>このファイバーに、クリーンアップ対応のエフェクトを登録します。
execute は直ちに実行されます。生成されたディスポーザーは収集され、返されたディスポーザーが呼び出されたとき、またはファイバーがアンロードされたときのうち、先に発生した時点で（逆順に）実行されます。ディスポーザーを 2 回呼び出しても何も起こりません。ファイバーがすでに破棄されている場合は CordisError('INACTIVE_EFFECT') をスローし、execute が無効な形式を返した場合は TypeError をスローします。
execute— エフェクト本体です。受け入れられる形式についてはEffectを参照してください。label—getEffects()の診断に表示されるエフェクトラベルです。
戻り値 エフェクトを破棄し、完了後に解決されるディスポーザーを返します。
fiber.getEffects()
/**
* Return metadata for currently registered effects.
*
* @returns one {@link EffectMeta} tree per labeled live effect.
*/
getEffects()現在登録されているエフェクトのメタデータを返します。
戻り値 ラベル付きのライブエフェクトごとに 1 つの EffectMeta ツリーを返します。
fiber.await()
/**
* Wait for current lifecycle work and rethrow startup errors.
*
* @returns this fiber, once it has settled into a stable state.
* @throws the config-validation or plugin-startup error, if any.
*/
async await()現在のライフサイクル処理を待機し、起動エラーを再スローします。
戻り値 安定した状態に落ち着くと、このファイバーを返します。
fiber.restart()
/**
* Dispose and immediately reload this plugin with its current config.
*
* @returns a promise resolving once the reload settled.
* @throws {CordisError} `INACTIVE_EFFECT` when the fiber is already disposed.
*/
async restart()このプラグインを破棄し、現在の設定ですぐに再読み込みします。
戻り値 再読み込みが完了すると解決される Promise を返します。
fiber.update(config, noSave?)
/**
* Validate and apply new config, then restart the plugin.
*
* Runs the `internal/update` waterfall first, so update hooks (and HMR)
* can veto or replace the restart.
*
* @param config — the new raw config; validated before anything restarts.
* @param noSave — hint for persistence hooks not to write the change back.
* @returns the update waterfall result; the default restart returns a promise.
* @throws when validation, an update listener, or the restarted plugin fails.
*/
update(config: any, noSave = false)新しい設定を検証して適用し、プラグインを再起動します。
まずinternal/updateのウォーターフォールを実行するため、更新フック（および HMR）は再起動を拒否または置き換えられます。
config— 新しい生の設定です。再起動の前に検証されます。noSave— 永続化フックに、変更を書き戻さないよう伝えるヒントです。
返します 更新ウォーターフォールの結果を返します。デフォルトの再起動は promise を返します。
エフェクト
ctx.effect()とプラグインの起動で受け入れられる Effect 本体の結果です。
単一の disposer、その promise、または複数を生成する（非同期の場合もある）iterable のいずれかです。generator effect は、各 disposer が生成されるたびに登録します。
/**
* Effect body result accepted by `ctx.effect()` and plugin startup.
*
* Either a single disposer, a promise of one, or a (possibly async) iterable
* yielding several — generator effects register each yielded disposer as it
* is produced.
*/
type Effect<T = any> =
| SyncEffect<T>
| AsyncEffect<T>破棄可能オブジェクト
破棄時にリソースを解放するため、effect から返される関数です。
所有する fiber がアンロードされると、disposer は登録とは逆の順序で実行されます。非同期の場合、アンロードは完了を待機します。
/**
* Function returned by an effect to release resources during disposal.
*
* Disposers run in reverse registration order when the owning fiber unloads;
* they may be async, in which case unloading awaits them.
*/
type Disposable<T = any> = () => TEffectMeta
診断のためにネストした effect ラベルを公開するツリーノードです。
/** Tree node used to expose nested effect labels for diagnostics. */
interface EffectMeta {
/** Human-readable effect label, e.g. `ctx.on("event")` or `ctx.provide("name")`. */
label: string
/** Metadata of nested effects registered while this effect ran. */
children: EffectMeta[]
}CordisError
安定した機械可読コードを持つフレームワークエラーです。
/** Framework error with a stable machine-readable code. */
class CordisError extends Error {
/**
* @param code — the stable error code; also the default message.
* @param message — optional human-readable override.
*/
constructor(public code: CordisError.Code, message?: string)
}
/** Cordis error code definitions. */
namespace CordisError {
export type Code = keyof typeof Code
export const Code = {
INACTIVE_EFFECT: 'cannot create effect on inactive context',
} as const
}ValidationError
プラグイン設定が standard-schema の検証に失敗したときに発生するエラーです。
/** Error raised when plugin configuration fails standard-schema validation. */
class ValidationError extends TypeError {
name = 'ValidationError'
/**
* Build the aggregated message from schema issues.
*
* @param issues — the standard-schema issues, one message line each.
*/
constructor(issues: readonly StandardSchemaV1.Issue[])
}