@xrkseek/harness 0.4.8 → 0.4.9

package/node_modules/@xrkseek/cordis/src/fiber.d.ts

@@ -0,0 +1,202 @@
+import type { Awaitable, Dict } from '@xrkseek/cosmokit';
+import { Context } from './context.ts';
+import type { Plugin } from './registry.ts';
+import { DisposableList } from './utils.ts';
+import type { Impl } from './reflect.ts';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+declare module './context.ts' {
+    interface Context extends Pick<Fiber, 'effect'> {
+        /** The fiber (plugin runtime instance) that owns this context. */
+        fiber: Fiber;
+    }
+}
+/** Error raised when plugin configuration fails standard-schema validation. */
+export declare class ValidationError extends TypeError {
+    name: string;
+    /**
+     * Build the aggregated message from schema issues.
+     *
+     * @param issues — the standard-schema issues, one message line each.
+     */
+    constructor(issues: readonly StandardSchemaV1.Issue[]);
+}
+/**
+ * Validate and normalize config for a plugin runtime before it starts.
+ *
+ * @param runtime — the plugin runtime whose `Config` schema to apply.
+ * @param config — the raw user config.
+ * @returns the validated config, or `config` unchanged if the runtime has no schema.
+ * @throws {ValidationError} when validation reports issues.
+ */
+export declare function resolveConfig(runtime: Plugin.Runtime, config: any): any;
+interface AsyncDisposable<T extends Awaitable<void> = Awaitable<void>> extends PromiseLike<() => T> {
+    (): T;
+}
+/**
+ * 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.
+ */
+export type Disposable<T = any> = () => T;
+/**
+ * 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.
+ */
+export type Effect<T = any> = SyncEffect<T> | AsyncEffect<T>;
+type SyncEffect<T = any> = Disposable<T> | Iterable<Disposable<T>, void, void>;
+type AsyncEffect<T = any> = Promise<Disposable<T>> | AsyncIterable<Disposable<T>, void, void>;
+/** Tree node used to expose nested effect labels for diagnostics. */
+export 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[];
+}
+/**
+ * Lifecycle state for one plugin fiber.
+ *
+ * `PENDING` — waiting for required services; `LOADING` — the plugin callback
+ * is running; `ACTIVE` — loaded and providing; `FAILED` — the callback or its
+ * config threw; `UNLOADING` — disposers are running; `DISPOSED` — the fiber
+ * was removed and cannot restart.
+ */
+export declare const enum FiberState {
+    PENDING = 0,
+    LOADING = 1,
+    ACTIVE = 2,
+    FAILED = 3,
+    DISPOSED = 4,
+    UNLOADING = 5
+}
+/** Framework error with a stable machine-readable code. */
+export declare class CordisError extends Error {
+    code: CordisError.Code;
+    /**
+     * @param code — the stable error code; also the default message.
+     * @param message — optional human-readable override.
+     */
+    constructor(code: CordisError.Code, message?: string);
+}
+/** Cordis error code definitions. */
+export declare namespace CordisError {
+    type Code = keyof typeof Code;
+    const Code: {
+        readonly INACTIVE_EFFECT: "cannot create effect on inactive context";
+    };
+}
+/**
+ * Runtime instance of one plugin application.
+ *
+ * A fiber tracks dependency state, validated config, lifecycle effects, and
+ * cleanup for the plugin context returned by `ctx.plugin()`.
+ */
+export declare class Fiber {
+    parent: Context;
+    inject: Dict<any>;
+    runtime: Plugin.Runtime | null;
+    /** Unique id within the registry; 0 for the root fiber, `null` once disposed. */
+    uid: number | null;
+    /** The context this fiber's plugin runs in (extends the parent context). */
+    readonly ctx: Context;
+    /** The validated plugin config (updated by `update()`). */
+    config: any;
+    /** The raw plugin config, re-resolved before each activation. */
+    _config: any;
+    /** Current lifecycle state; transitions emit `internal/status`. */
+    state: FiberState;
+    /** Dispose this fiber: unload the plugin, then settle once cleanup finished. */
+    readonly dispose: () => Promise<void>;
+    /** Snapshot of required service implementations while loaded; `undefined` otherwise. */
+    store: Dict<Impl> | undefined;
+    /** The in-flight load/unload transition, if one is currently running. */
+    inertia: Promise<void> | undefined;
+    readonly _hooks: Dict<DisposableList<Function>>;
+    readonly _disposables: DisposableList<Disposable<any>>;
+    protected context: Context;
+    private _error;
+    private _runner;
+    private _store;
+    /**
+     * Create a fiber. Plugin authors normally obtain fibers from `ctx.plugin()`
+     * rather than constructing them directly.
+     *
+     * @param parent — the context the plugin was loaded from.
+     * @param config — raw config, validated against the runtime's schema.
+     * @param inject — resolved dependency map (service name → intercept config).
+     * @param runtime — the shared plugin runtime, or `null` for the root fiber.
+     * @param getOuterStack — captures the caller stack for effect diagnostics.
+     */
+    constructor(parent: Context, config: any, inject: Dict<any>, runtime: Plugin.Runtime | null, getOuterStack: () => string[]);
+    /** The plugin's display name, inherited from the nearest named ancestor, else `'root'`. */
+    get name(): string;
+    /**
+     * 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(): void;
+    private _execute;
+    /**
+     * 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>>;
+    /** Same as above for async effects; the disposer is also awaitable. */
+    effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>;
+    /**
+     * Return metadata for currently registered effects.
+     *
+     * @returns one {@link EffectMeta} tree per labeled live effect.
+     */
+    getEffects(): EffectMeta[];
+    private _getState;
+    private _updateState;
+    _checkImpl(name: string): boolean | undefined;
+    _refresh(): void;
+    private _setEpoch;
+    private _resolveConfig;
+    private _reload;
+    private _unload;
+    /**
+     * 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.
+     */
+    await(): Promise<this>;
+    /**
+     * 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.
+     */
+    restart(): Promise<void>;
+    /**
+     * 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?: boolean): void | Promise<void>;
+}
+export {};
+//# sourceMappingURL=fiber.d.ts.map

package/node_modules/@xrkseek/cordis/src/fiber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiber.d.ts","sourceRoot":"","sources":["fiber.ts"],"names":[],"mappings":"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"}