@zudojs/plugins 1.2.0 → 1.3.0

package/README.md

@@ -155,7 +155,31 @@ const manager = new PluginManager({
 });
 ```
 
-A throwing subscriber never fails the phase that emitted the event.
+A throwing subscriber never fails the phase that emitted the event, and
+neither does an async `emit` whose promise rejects: both are reported
+(through `onError`, the logger, or a `ZudoPluginWarning`) instead of
+propagating. Before 1.3 an async rejection escaped as an
+`unhandledRejection`, which terminates Node by default, after `start()` had
+already resolved.
+
+### Using an `@zudojs/events` bus
+
+Both the manager's `events` option and `createPluginContext`'s `events`
+accept an `EventBus` directly. It is adapted with `toPluginEvents`, so
+`context.events` is still a `PluginEvents`: `emit(name, payload)` publishes
+`{ type: name, payload }` (the bus normalises `plugin:started` to
+`plugin.started`), `on(name, handler)` subscribes and hands the handler the
+event's payload, and `off(name, handler)` cancels that subscription.
+
+```typescript
+import { EventBus } from "@zudojs/events";
+
+const bus = new EventBus();
+bus.on("plugin.*", (event) => console.log(event.type, event.payload));
+
+const manager = new PluginManager({ events: bus });
+await manager.start(createPluginContext({ name: "host" }, { events: bus }));
+```
 
 ## Diagnostics
 

package/dist/index.d.ts

@@ -55,11 +55,12 @@ export { LifecycleController } from "./pluginLifecycle/pluginLifecycle.core.js";
 export type { LifecycleControllerOptions } from "./pluginLifecycle/pluginLifecycle.core.js";
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvents/pluginEvent.core.js";
 export type { PluginLifecycleEvent } from "./pluginEvents/pluginEvent.core.js";
+export { isPluginEventBus, toPluginEvents, } from "./pluginEvents/pluginEvent.bus.js";
 export { buildDiagnosticReport, createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
 export type { PluginHealth, PluginHealthStatus, PluginDiagnostic, PluginDiagnosticReport, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
 export { isValidTransition, VALID_STATE_TRANSITIONS, } from "./pluginTypes/pluginState.type.js";
 export { createPluginContext, createOwnedPluginContext, } from "./pluginIntegration/pluginContext.core.js";
 export type { CreatePluginContextOptions, OwnedPluginContext, } from "./pluginIntegration/pluginContext.core.js";
 export { PluginError, PluginRegistrationError, PluginAlreadyRegisteredError, PluginNotFoundError, PluginDependencyError, PluginDependencyCycleError, PluginInitializationError, PluginStartError, PluginStopError, PluginDisposeError, PluginTimeoutError, PluginStateError, createPluginError, isPluginError, } from "@zudojs/errors";
-export type { PluginState, PluginMetadata, PluginDependency, PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginDisposable, Plugin, PluginErrorOptions, } from "./pluginTypes/index.js";
+export type { PluginState, PluginMetadata, PluginDependency, PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginEventBus, PluginEventSource, PluginDisposable, Plugin, PluginErrorOptions, } from "./pluginTypes/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -49,6 +49,7 @@ export { parseVersion, compareVersions, satisfiesVersion, assertDependencyVersio
 export { PluginDependencyVersionError } from "./pluginDependencies/versionCheck.core.js";
 export { LifecycleController } from "./pluginLifecycle/pluginLifecycle.core.js";
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvents/pluginEvent.core.js";
+export { isPluginEventBus, toPluginEvents, } from "./pluginEvents/pluginEvent.bus.js";
 export { buildDiagnosticReport, createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./pluginDiagnostics/pluginDiagnostic.core.js";
 export { isValidTransition, VALID_STATE_TRANSITIONS, } from "./pluginTypes/pluginState.type.js";
 export { createPluginContext, createOwnedPluginContext, } from "./pluginIntegration/pluginContext.core.js";

package/dist/pluginEvents/index.d.ts

@@ -5,4 +5,6 @@
  */
 export type { PluginLifecycleEvent } from "./pluginEvent.core.js";
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvent.core.js";
+export { isPluginEventBus, toPluginEvents } from "./pluginEvent.bus.js";
+export { deliverPluginEvent } from "./pluginEvent.deliver.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/pluginEvents/index.js

@@ -4,4 +4,6 @@
  * Plugin lifecycle event types and event names.
  */
 export { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "./pluginEvent.core.js";
+export { isPluginEventBus, toPluginEvents } from "./pluginEvent.bus.js";
+export { deliverPluginEvent } from "./pluginEvent.deliver.js";
 //# sourceMappingURL=index.js.map

package/dist/pluginEvents/pluginEvent.bus.d.ts

@@ -0,0 +1,26 @@
+import type { PluginEventBus, PluginEvents, PluginEventSource } from "../pluginTypes/pluginContext.type.js";
+/**
+ * Whether an event source is an event bus (such as `@zudojs/events`'
+ * `EventBus`) rather than a {@link PluginEvents} sink.
+ *
+ * A bus publishes objects (`publishEvent({ type, payload })`); a sink
+ * emits a name and a payload. Calling a bus's `emit` with a bare name
+ * throws `InvalidEventError`, so the two must be told apart.
+ */
+export declare function isPluginEventBus(source: PluginEventSource): source is PluginEventBus;
+/**
+ * Adapts an event bus to the {@link PluginEvents} interface plugins use.
+ *
+ * - `emit(name, payload)` publishes `{ type: name, payload }` and returns
+ *   the publish promise, so a rejection can be caught by the caller.
+ * - `on(name, handler)` subscribes on the bus and hands the handler the
+ *   event's `payload` — the same value a sink's `emit` would pass.
+ * - `off(name, handler)` cancels that subscription.
+ *
+ * A {@link PluginEvents} sink is returned unchanged.
+ *
+ * @param source - An event bus or a plugin events sink.
+ * @returns A {@link PluginEvents} view of it.
+ */
+export declare function toPluginEvents(source: PluginEventSource): PluginEvents;
+//# sourceMappingURL=pluginEvent.bus.d.ts.map

package/dist/pluginEvents/pluginEvent.bus.js

@@ -0,0 +1,56 @@
+/**
+ * Whether an event source is an event bus (such as `@zudojs/events`'
+ * `EventBus`) rather than a {@link PluginEvents} sink.
+ *
+ * A bus publishes objects (`publishEvent({ type, payload })`); a sink
+ * emits a name and a payload. Calling a bus's `emit` with a bare name
+ * throws `InvalidEventError`, so the two must be told apart.
+ */
+export function isPluginEventBus(source) {
+    return (typeof source.publishEvent === "function");
+}
+/**
+ * Adapts an event bus to the {@link PluginEvents} interface plugins use.
+ *
+ * - `emit(name, payload)` publishes `{ type: name, payload }` and returns
+ *   the publish promise, so a rejection can be caught by the caller.
+ * - `on(name, handler)` subscribes on the bus and hands the handler the
+ *   event's `payload` — the same value a sink's `emit` would pass.
+ * - `off(name, handler)` cancels that subscription.
+ *
+ * A {@link PluginEvents} sink is returned unchanged.
+ *
+ * @param source - An event bus or a plugin events sink.
+ * @returns A {@link PluginEvents} view of it.
+ */
+export function toPluginEvents(source) {
+    if (!isPluginEventBus(source))
+        return source;
+    const bus = source;
+    const subscriptions = new Map();
+    return {
+        on(event, handler) {
+            const byHandler = subscriptions.get(event) ?? new Map();
+            subscriptions.set(event, byHandler);
+            if (byHandler.has(handler))
+                return;
+            byHandler.set(handler, bus.on(event, (published) => {
+                handler(published.payload);
+            }));
+        },
+        off(event, handler) {
+            const byHandler = subscriptions.get(event);
+            const subscription = byHandler?.get(handler);
+            if (!byHandler || !subscription)
+                return;
+            subscription.unsubscribe();
+            byHandler.delete(handler);
+            if (byHandler.size === 0)
+                subscriptions.delete(event);
+        },
+        emit(event, payload) {
+            return bus.publishEvent({ type: event, payload });
+        },
+    };
+}
+//# sourceMappingURL=pluginEvent.bus.js.map

package/dist/pluginEvents/pluginEvent.deliver.d.ts

@@ -0,0 +1,18 @@
+import type { PluginEvents } from "../pluginTypes/pluginContext.type.js";
+/**
+ * Emits an event and contains every way delivery can fail.
+ *
+ * A subscriber that throws synchronously, and an `emit` that returns a
+ * promise which later rejects, are both passed to `onFailure` and never
+ * propagate: a lifecycle phase must not fail because of a listener, and
+ * an unobserved rejection would otherwise surface as an
+ * `unhandledRejection` — which terminates Node by default — after the
+ * phase has already resolved.
+ *
+ * @param events - Where to emit.
+ * @param name - The event name.
+ * @param payload - The event payload.
+ * @param onFailure - Receives a synchronous throw or an async rejection.
+ */
+export declare function deliverPluginEvent(events: PluginEvents, name: string, payload: unknown, onFailure: (error: unknown) => void): void;
+//# sourceMappingURL=pluginEvent.deliver.d.ts.map

package/dist/pluginEvents/pluginEvent.deliver.js

@@ -0,0 +1,41 @@
+/**
+ * Emits an event and contains every way delivery can fail.
+ *
+ * A subscriber that throws synchronously, and an `emit` that returns a
+ * promise which later rejects, are both passed to `onFailure` and never
+ * propagate: a lifecycle phase must not fail because of a listener, and
+ * an unobserved rejection would otherwise surface as an
+ * `unhandledRejection` — which terminates Node by default — after the
+ * phase has already resolved.
+ *
+ * @param events - Where to emit.
+ * @param name - The event name.
+ * @param payload - The event payload.
+ * @param onFailure - Receives a synchronous throw or an async rejection.
+ */
+export function deliverPluginEvent(events, name, payload, onFailure) {
+    let result;
+    try {
+        result = events.emit(name, payload);
+    }
+    catch (error) {
+        onFailure(error);
+        return;
+    }
+    if (isThenable(result)) {
+        result.then(undefined, (error) => {
+            try {
+                onFailure(error);
+            }
+            catch {
+                // A throwing failure hook must not become an unhandled rejection.
+            }
+        });
+    }
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+//# sourceMappingURL=pluginEvent.deliver.js.map

package/dist/pluginIntegration/pluginContext.core.d.ts

@@ -1,5 +1,5 @@
 import type { PluginMetadata } from "../pluginTypes/pluginMetadata.type.js";
-import type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginDisposable } from "../pluginTypes/pluginContext.type.js";
+import type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEventSource, PluginDisposable } from "../pluginTypes/pluginContext.type.js";
 /**
  * Options for creating a plugin context.
  */
@@ -7,7 +7,11 @@ export interface CreatePluginContextOptions {
     readonly container?: PluginContainer;
     readonly config?: PluginConfig;
     readonly logger?: PluginLogger;
-    readonly events?: PluginEvents;
+    /**
+     * Event sink, or an event bus such as `@zudojs/events`' `EventBus`,
+     * which is adapted so `context.events` is always a `PluginEvents`.
+     */
+    readonly events?: PluginEventSource;
     /**
      * Collection that receives everything the plugin registers for
      * cleanup. The plugin manager passes the registered plugin's own

package/dist/pluginIntegration/pluginContext.core.js

@@ -1,3 +1,4 @@
+import { toPluginEvents } from "../pluginEvents/pluginEvent.bus.js";
 /**
  * Creates a plugin context and returns it with its teardown handles.
  *
@@ -14,7 +15,7 @@ export function createOwnedPluginContext(plugin, options = {}) {
         container: options.container,
         config: options.config,
         logger: options.logger,
-        events: options.events,
+        events: options.events ? toPluginEvents(options.events) : undefined,
         onDispose(handler) {
             disposables.push({ dispose: handler });
         },

package/dist/pluginLifecycle/pluginLifecycle.core.js

@@ -3,25 +3,24 @@ import { PluginDisposeError, PluginStateError, PluginTimeoutError, } from "@zudo
 import { PLUGIN_EVENTS, createPluginLifecycleEvent, } from "../pluginEvents/pluginEvent.core.js";
 import { AbandonedHooks } from "./pluginLifecycle.abandoned.js";
 import { reportPluginFailure } from "./pluginLifecycle.report.js";
+import { deliverPluginEvent } from "../pluginEvents/pluginEvent.deliver.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.
+ * the event, so delivery failures — a synchronous throw or an async
+ * `emit` that rejects — are contained and reported here.
  */
 function emitLifecycleEvent(context, eventName, plugin, state, previousState, error) {
     if (!context.events?.emit) {
         return;
     }
     const event = createPluginLifecycleEvent(plugin, state, previousState, error);
-    try {
-        context.events.emit(eventName, event);
-    }
-    catch (emitError) {
+    deliverPluginEvent(context.events, eventName, event, (emitError) => {
         queueMicrotask(() => {
             reportPluginFailure(context.logger, `Listener for "${eventName}" threw.`, emitError, { plugin: plugin.name, event: eventName });
         });
-    }
+    });
 }
 /** Largest delay a timer can represent. */
 const MAX_TIMER_DELAY = 2_147_483_647;

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

@@ -1,5 +1,5 @@
 import type { Plugin } from "../pluginTypes/plugin.type.js";
-import type { PluginContext, PluginEvents } from "../pluginTypes/pluginContext.type.js";
+import type { PluginContext, PluginEventSource } from "../pluginTypes/pluginContext.type.js";
 import type { PluginDiagnosticReport } from "../pluginDiagnostics/pluginDiagnostic.core.js";
 import type { PluginLogger } from "../pluginTypes/pluginContext.type.js";
 /**
@@ -39,8 +39,11 @@ export interface PluginManagerOptions {
      * lifecycle events emitted through `context.events` cannot cover it.
      * Without this, `PLUGIN_EVENTS.REGISTERED` was a name nothing ever
      * emitted.
+     *
+     * Accepts an event bus such as `@zudojs/events`' `EventBus` as well as a
+     * `PluginEvents` sink.
      */
-    readonly events?: PluginEvents;
+    readonly events?: PluginEventSource;
     /**
      * Logger for teardown failures when `onError` is not supplied.
      * Defaults to the logger on the context passed to `start()`/`stop()`.
@@ -56,6 +59,8 @@ export declare class PluginManager {
     private readonly lifecycle;
     private readonly plugins;
     private readonly options;
+    /** `options.events`, adapted to the sink interface. */
+    private readonly events;
     /**
      * Dependency-first order from the last successful resolution.
      *
@@ -138,8 +143,9 @@ export declare class PluginManager {
      */
     private abortContext;
     /**
-     * Emits `plugin:registered`, containing a throwing subscriber so a bad
-     * listener cannot fail the registration that triggered it.
+     * Emits `plugin:registered`, containing a throwing subscriber — or a
+     * rejecting async `emit` — so a bad listener cannot fail the
+     * registration that triggered it.
      */
     private emitRegistered;
     private report;

package/dist/pluginManager/pluginManager.core.js

@@ -1,3 +1,5 @@
+import { toPluginEvents } from "../pluginEvents/pluginEvent.bus.js";
+import { deliverPluginEvent } from "../pluginEvents/pluginEvent.deliver.js";
 import { PluginRegistryImpl } from "../pluginRegistry/pluginRegistry.core.js";
 import { DependencyResolver, assertResolutionValid, } from "../pluginDependencies/dependencyResolver.core.js";
 import { assertDependencyVersions } from "../pluginDependencies/versionCheck.core.js";
@@ -25,6 +27,8 @@ export class PluginManager {
     lifecycle;
     plugins = new Map();
     options;
+    /** `options.events`, adapted to the sink interface. */
+    events;
     /**
      * Dependency-first order from the last successful resolution.
      *
@@ -52,6 +56,7 @@ export class PluginManager {
             ? { hookTimeout: options.hookTimeout }
             : {});
         this.options = options;
+        this.events = options.events ? toPluginEvents(options.events) : undefined;
     }
     /**
      * Registers a plugin.
@@ -312,20 +317,15 @@ export class PluginManager {
         this.contexts.get(name)?.abort(reason);
     }
     /**
-     * Emits `plugin:registered`, containing a throwing subscriber so a bad
-     * listener cannot fail the registration that triggered it.
+     * Emits `plugin:registered`, containing a throwing subscriber — or a
+     * rejecting async `emit` — so a bad listener cannot fail the
+     * registration that triggered it.
      */
     emitRegistered(plugin) {
-        const events = this.options.events;
-        if (!events) {
+        if (!this.events) {
             return;
         }
-        try {
-            events.emit(PLUGIN_EVENTS.REGISTERED, createPluginLifecycleEvent(plugin.metadata, "registered"));
-        }
-        catch (error) {
-            this.report(error, plugin.metadata.name);
-        }
+        deliverPluginEvent(this.events, PLUGIN_EVENTS.REGISTERED, createPluginLifecycleEvent(plugin.metadata, "registered"), (error) => this.report(error, plugin.metadata.name));
     }
     report(error, pluginName) {
         if (this.options.onError) {

package/dist/pluginTypes/index.d.ts

@@ -6,7 +6,7 @@
 export type { PluginState } from "./pluginState.type.js";
 export type { PluginMetadata } from "./pluginMetadata.type.js";
 export type { PluginDependency } from "./pluginDependency.type.js";
-export type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginDisposable, } from "./pluginContext.type.js";
+export type { PluginContext, PluginContainer, PluginConfig, PluginLogger, PluginEvents, PluginEventBus, PluginEventSource, PluginDisposable, } from "./pluginContext.type.js";
 export type { Plugin } from "./plugin.type.js";
 export type { PluginErrorOptions } from "@zudojs/errors";
 //# sourceMappingURL=index.d.ts.map

package/dist/pluginTypes/pluginContext.type.d.ts

@@ -21,12 +21,37 @@ export interface PluginLogger {
 }
 /**
  * Minimal events interface for plugin context.
+ *
+ * `emit` may return a promise. A rejection is contained and reported, just
+ * like a synchronous throw — it never fails the phase that emitted.
  */
 export interface PluginEvents {
     on(event: string, handler: (event: unknown) => void): void;
     off(event: string, handler: (event: unknown) => void): void;
-    emit(event: string, payload: unknown): void;
+    emit(event: string, payload: unknown): void | PromiseLike<unknown>;
 }
+/**
+ * The part of an event bus the plugin system uses — satisfied by
+ * `@zudojs/events`' `EventBus`, which can be passed wherever
+ * {@link PluginEventSource} is accepted.
+ */
+export interface PluginEventBus {
+    publishEvent(input: {
+        readonly type: string;
+        readonly payload: unknown;
+    }): Promise<unknown>;
+    on(eventType: string, handler: (event: {
+        readonly payload: unknown;
+    }) => unknown): {
+        unsubscribe(): void;
+    };
+}
+/**
+ * What the plugin system accepts as an event source: a
+ * {@link PluginEvents} sink, or an event bus it adapts with
+ * `toPluginEvents`.
+ */
+export type PluginEventSource = PluginEvents | PluginEventBus;
 /**
  * Something a plugin registers so the manager releases it on shutdown.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/plugins",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Plugin system for extending Zudojs applications with modular capabilities.",
   "license": "MIT",
   "author": {
@@ -24,12 +24,13 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0"
+    "@zudojs/errors": "1.3.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.2",
+    "@zudojs/events": "1.3.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -42,7 +43,7 @@
     "plugins",
     "extensions"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-plugins",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },