@zudojs/plugins 0.0.1 → 1.0.0

package/dist/pluginLifecycle/pluginLifecycle.core.js

@@ -1,126 +1,188 @@
-import { VALID_STATE_TRANSITIONS } from "../pluginTypes/pluginState.type.js";
-import { PluginStateError } from "@zudojs/errors";
+import { isValidTransition } from "../pluginTypes/pluginState.type.js";
+import { PluginDisposeError, PluginStateError, PluginTimeoutError, } from "@zudojs/errors";
 import { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "../pluginEvents/pluginEvent.core.js";
 /**
  * Emits a plugin lifecycle event if the context supports events.
+ *
+ * A throwing subscriber must not abort the lifecycle phase that emitted
+ * the event, so delivery failures are contained here.
  */
-function emitLifecycleEvent(context, eventName, pluginName, state, previousState, error) {
+function emitLifecycleEvent(context, eventName, plugin, state, previousState, error) {
     if (!context.events?.emit) {
         return;
     }
-    const event = createPluginLifecycleEvent({ name: pluginName }, state, previousState, error);
-    context.events.emit(eventName, event);
+    const event = createPluginLifecycleEvent(plugin, state, previousState, error);
+    try {
+        context.events.emit(eventName, event);
+    }
+    catch (emitError) {
+        queueMicrotask(() => {
+            console.error(`[@zudojs/plugins] Listener for "${eventName}" threw.`, emitError);
+        });
+    }
 }
+/** Largest delay a timer can represent. */
+const MAX_TIMER_DELAY = 2_147_483_647;
 /**
  * Executes plugin lifecycle phases with state management and event emission.
  */
 export class LifecycleController {
-    async install(registered, context) {
-        const name = registered.plugin.metadata.name;
-        const from = registered.state;
-        this.ensureTransition(registered, "installing");
-        registered.setState("installing");
-        emitLifecycleEvent(context, PLUGIN_EVENTS.INSTALLING, name, "installing", from);
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Runs a hook under the configured timeout, clearing the timer either
+     * way so a completed hook never leaves one armed.
+     */
+    async runHook(pluginName, phase, run) {
+        const timeout = this.options.hookTimeout ?? 0;
+        if (timeout <= 0) {
+            await run();
+            return;
+        }
+        let timer;
+        const hook = Promise.resolve().then(run);
+        // The hook keeps running if the timeout wins; handle its eventual
+        // rejection so it is never unhandled.
+        hook.catch(() => { });
         try {
-            await registered.plugin.install?.(context, registered.options);
-            this.ensureTransition(registered, "installed");
-            registered.setState("installed");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.INSTALLED, name, "installed", "installing");
+            await Promise.race([
+                hook,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new PluginTimeoutError(pluginName, timeout, {
+                        metadata: { phase },
+                    })), Math.min(timeout, MAX_TIMER_DELAY));
+                    timer.unref?.();
+                }),
+            ]);
         }
-        catch (error) {
-            registered.setState("failed");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.FAILED, name, "failed", from, error);
-            throw error;
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
         }
     }
+    async install(registered, context) {
+        await this.runPhase(registered, context, "installing", "installed", PLUGIN_EVENTS.INSTALLING, PLUGIN_EVENTS.INSTALLED, () => registered.plugin.install?.(context, registered.options));
+    }
     async initialize(registered, context) {
-        const name = registered.plugin.metadata.name;
-        const from = registered.state;
-        this.ensureTransition(registered, "initializing");
-        registered.setState("initializing");
-        emitLifecycleEvent(context, PLUGIN_EVENTS.INITIALIZING, name, "initializing", from);
-        try {
-            await registered.plugin.initialize?.(context);
-            this.ensureTransition(registered, "initialized");
-            registered.setState("initialized");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.INITIALIZED, name, "initialized", "initializing");
-        }
-        catch (error) {
-            registered.setState("failed");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.FAILED, name, "failed", from, error);
-            throw error;
-        }
+        await this.runPhase(registered, context, "initializing", "initialized", PLUGIN_EVENTS.INITIALIZING, PLUGIN_EVENTS.INITIALIZED, () => registered.plugin.initialize?.(context));
     }
     async start(registered, context) {
-        const name = registered.plugin.metadata.name;
-        const from = registered.state;
-        this.ensureTransition(registered, "starting");
-        registered.setState("starting");
-        emitLifecycleEvent(context, PLUGIN_EVENTS.STARTING, name, "starting", from);
-        try {
-            await registered.plugin.start?.(context);
-            this.ensureTransition(registered, "started");
-            registered.setState("started");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.STARTED, name, "started", "starting");
-        }
-        catch (error) {
-            registered.setState("failed");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.FAILED, name, "failed", from, error);
-            throw error;
-        }
+        await this.runPhase(registered, context, "starting", "started", PLUGIN_EVENTS.STARTING, PLUGIN_EVENTS.STARTED, () => registered.plugin.start?.(context));
     }
     async stop(registered, context) {
-        const name = registered.plugin.metadata.name;
+        await this.runPhase(registered, context, "stopping", "stopped", PLUGIN_EVENTS.STOPPING, PLUGIN_EVENTS.STOPPED, () => registered.plugin.stop?.(context));
+    }
+    /**
+     * Runs one lifecycle phase, moving through its transient state.
+     *
+     * On failure the plugin moves to `failed` through the state machine
+     * rather than around it, so the recorded state is always one the
+     * machine actually permits.
+     */
+    async runPhase(registered, context, transient, settled, startEvent, endEvent, run) {
+        const metadata = registered.plugin.metadata;
         const from = registered.state;
-        this.ensureTransition(registered, "stopping");
-        registered.setState("stopping");
-        emitLifecycleEvent(context, PLUGIN_EVENTS.STOPPING, name, "stopping", from);
+        this.ensureTransition(registered, transient);
+        registered.setState(transient);
+        emitLifecycleEvent(context, startEvent, metadata, transient, from);
         try {
-            await registered.plugin.stop?.(context);
-            this.ensureTransition(registered, "stopped");
-            registered.setState("stopped");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.STOPPED, name, "stopped", "stopping");
+            await this.runHook(metadata.name, transient, run);
+            this.ensureTransition(registered, settled);
+            registered.setState(settled);
+            emitLifecycleEvent(context, endEvent, metadata, settled, transient);
         }
         catch (error) {
-            registered.setState("failed");
-            emitLifecycleEvent(context, PLUGIN_EVENTS.FAILED, name, "failed", from, error);
+            registered.setError(error);
+            this.transitionToFailed(registered);
+            emitLifecycleEvent(context, PLUGIN_EVENTS.FAILED, metadata, "failed", transient, error);
             throw error;
         }
     }
+    /**
+     * Disposes a plugin and everything it registered for cleanup.
+     *
+     * Disposables run in reverse registration order — the mirror of how
+     * they were acquired — and the list is emptied so a second dispose
+     * cannot run them again. Every failure is collected; the plugin still
+     * reaches a terminal state so it cannot be disposed twice.
+     */
     async dispose(registered, context) {
-        const name = registered.plugin.metadata.name;
+        const metadata = registered.plugin.metadata;
         const from = registered.state;
+        if (from === "disposed" || from === "disposing") {
+            return;
+        }
         this.ensureTransition(registered, "disposing");
         registered.setState("disposing");
-        emitLifecycleEvent(context, PLUGIN_EVENTS.DISPOSING, name, "disposing", from);
+        emitLifecycleEvent(context, PLUGIN_EVENTS.DISPOSING, metadata, "disposing", from);
         const errors = [];
-        for (const disposable of registered.disposables) {
+        // Take the list before running it: a disposable that registers
+        // another during teardown must not extend the loop indefinitely.
+        const disposables = registered.disposables.splice(0, registered.disposables.length);
+        for (const disposable of disposables.reverse()) {
             try {
-                await disposable.dispose();
+                await this.runHook(metadata.name, "disposing", () => disposable.dispose());
             }
             catch (error) {
                 errors.push(error);
             }
         }
         try {
-            await registered.plugin.dispose?.(context);
+            await this.runHook(metadata.name, "disposing", () => registered.plugin.dispose?.(context));
         }
         catch (error) {
             errors.push(error);
         }
         registered.setState("disposed");
-        emitLifecycleEvent(context, PLUGIN_EVENTS.DISPOSED, name, "disposed", "disposing");
+        emitLifecycleEvent(context, PLUGIN_EVENTS.DISPOSED, metadata, "disposed", "disposing");
         if (errors.length > 0) {
-            throw errors[0];
+            const error = new PluginDisposeError(errors.length === 1
+                ? `Plugin "${metadata.name}" failed to dispose.`
+                : `Plugin "${metadata.name}" reported ${errors.length} disposal failures.`, metadata.name, { cause: errors[0] });
+            // Every failure is retained; reporting only the first would hide
+            // the rest of a partially failed teardown.
+            Object.defineProperty(error, "errors", {
+                value: Object.freeze([...errors]),
+                enumerable: true,
+                configurable: true,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Moves a plugin to `failed`, via `stopping` when required.
+     */
+    transitionToFailed(registered) {
+        if (registered.state === "failed") {
+            return;
         }
+        if (this.canTransition(registered.state, "failed")) {
+            registered.setState("failed");
+            return;
+        }
+        // A phase can fail from a settled state (a hook that threw after
+        // the state had already advanced). Route through `stopping`, which
+        // every settled state permits, so the machine stays consistent.
+        if (this.canTransition(registered.state, "stopping")) {
+            registered.setState("stopping");
+        }
+        registered.setState("failed");
+    }
+    canTransition(from, to) {
+        // Delegates to the exported predicate rather than re-deriving it:
+        // two copies of the transition rule can disagree, and the public
+        // `isValidTransition` must describe what the controller actually does.
+        return isValidTransition(from, to);
     }
     ensureTransition(registered, to) {
         const from = registered.state;
         if (from === to) {
             return;
         }
-        const valid = VALID_STATE_TRANSITIONS[from]?.includes(to) ?? false;
-        if (!valid) {
+        if (!this.canTransition(from, to)) {
             throw new PluginStateError(registered.plugin.metadata.name, from, to);
         }
     }

package/dist/pluginManager/pluginManager.core.d.ts

@@ -1,6 +1,46 @@
 import type { Plugin } from "../pluginTypes/plugin.type.js";
-import type { PluginContext } from "../pluginTypes/pluginContext.type.js";
+import type { PluginContext, PluginEvents } from "../pluginTypes/pluginContext.type.js";
 import type { PluginDiagnosticReport } from "../pluginDiagnostics/pluginDiagnostic.core.js";
+/**
+ * Options for a plugin manager.
+ */
+export interface PluginManagerOptions {
+    /**
+     * Whether declared dependency versions are enforced at startup.
+     * Defaults to `true`. A declared version that is never checked is
+     * worse than no version at all.
+     */
+    readonly checkVersions?: boolean;
+    /**
+     * Receives errors raised during shutdown. Teardown continues past a
+     * failing plugin either way, but without this the failures are
+     * invisible.
+     */
+    readonly onError?: (error: unknown, pluginName: string) => void;
+    /**
+     * Maximum time a single lifecycle hook may run, in milliseconds.
+     * Defaults to `0` (unbounded). Set a value so one hanging plugin
+     * cannot hang boot or shutdown.
+     */
+    readonly hookTimeout?: number;
+    /**
+     * Capabilities plugins are permitted to declare.
+     *
+     * When set, a plugin whose `metadata.capabilities` includes anything
+     * outside this list is rejected at registration. Leave unset to allow
+     * any capability.
+     */
+    readonly allowedCapabilities?: readonly string[];
+    /**
+     * Event sink for `plugin:registered`.
+     *
+     * Registration happens before any plugin context exists, so the
+     * lifecycle events emitted through `context.events` cannot cover it.
+     * Without this, `PLUGIN_EVENTS.REGISTERED` was a name nothing ever
+     * emitted.
+     */
+    readonly events?: PluginEvents;
+}
 /**
  * Plugin manager coordinates registration, dependency resolution, lifecycle, and disposal.
  */
@@ -9,14 +49,92 @@ export declare class PluginManager {
     private readonly resolver;
     private readonly lifecycle;
     private readonly plugins;
-    constructor();
-    register<TPlugin extends Plugin>(plugin: TPlugin): void;
+    private readonly options;
+    /**
+     * Dependency-first order from the last successful resolution.
+     *
+     * Shutdown reverses this rather than registration order: tearing down
+     * in registration order destroys a dependency while its dependents are
+     * still using it.
+     */
+    private startupOrder;
+    private starting;
+    /**
+     * Per-plugin context views and their abort handles.
+     *
+     * Each plugin gets a context whose `onDispose` and
+     * `registerDisposable` write to that plugin's own disposables list —
+     * the list the lifecycle actually drains — and whose `signal` this
+     * manager aborts on shutdown.
+     */
+    private readonly contexts;
+    constructor(options?: PluginManagerOptions);
+    /**
+     * Registers a plugin.
+     *
+     * @throws {PluginAlreadyRegisteredError} when the name is taken, so
+     * callers can implement idempotent registration.
+     */
+    register<TPlugin extends Plugin>(plugin: TPlugin, options?: unknown): void;
+    /**
+     * Removes a plugin that has not been started.
+     *
+     * Keeps the manager's own view in step with the registry; leaving a
+     * removed plugin in `plugins` would keep it in dependency resolution.
+     */
+    unregister(name: string): boolean;
     get<TPlugin extends Plugin>(name: string): TPlugin | undefined;
     has(name: string): boolean;
     list(): readonly Plugin[];
+    /**
+     * Installs, initializes and starts every plugin in dependency order.
+     *
+     * A failure anywhere rolls back: everything already brought up is
+     * stopped and disposed before the error is rethrown, so an aborted
+     * startup does not strand resources with no route to release them.
+     */
     start(context: PluginContext): Promise<void>;
+    /**
+     * Stops and disposes every plugin, in reverse dependency order.
+     *
+     * Teardown continues past a failing plugin so one bad `stop` cannot
+     * strand the rest, and every failure is reported through `onError`
+     * rather than swallowed.
+     */
     stop(context: PluginContext): Promise<void>;
     diagnostics(): PluginDiagnosticReport;
+    /**
+     * Tears down everything brought up by a failed startup.
+     */
+    private rollback;
+    /**
+     * Registered plugins in reverse dependency order.
+     *
+     * Falls back to reverse registration order for plugins registered
+     * after the last resolution, which is the best available guess.
+     */
+    private teardownOrder;
+    /**
+     * Returns the plugin's own context view, creating it on first use.
+     *
+     * The base context supplies the shared services; only the identity,
+     * the disposables collection and the abort signal are per-plugin.
+     */
+    private contextFor;
+    /**
+     * Aborts a plugin's signal, keeping the context available.
+     *
+     * The entry stays so `dispose` still receives the same — now aborted —
+     * context; removing it here would hand the dispose hook a fresh
+     * context whose signal had never fired.
+     */
+    private abortContext;
+    /**
+     * Emits `plugin:registered`, containing a throwing subscriber so a bad
+     * listener cannot fail the registration that triggered it.
+     */
+    private emitRegistered;
+    private report;
     private toDependencyMap;
 }
 //# sourceMappingURL=pluginManager.core.d.ts.map