@esauflores/plugin-sdk 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { HookSchemas, Hooks } from "./hooks.ts";
+/** Any schema library implementing https://standardschema.dev: zod, valibot, ArkType... */
+export type { StandardSchemaV1 };
+export interface AppInfo {
+    /** Also the default `package.json` key plugins use for their manifest. */
+    name: string;
+    version: string;
+}
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * `H` is the app's hook map, `S` its service map, e.g.
+ *   interface MyHooks { "request": (req: Request) => void }
+ *   interface MyServices { db: Database }
+ * `Options` is what the plugin receives in `ctx.options`; `Input` is what callers pass to
+ * `register()` / `load()`. They differ when `optionsSchema` applies defaults or transforms.
+ */
+export interface Plugin<Options = any, H extends object = any, S extends object = any, Input = Options> {
+    /** Unique within a host. */
+    name: string;
+    version?: string;
+    /** Plugins that must set up and start before this one. If one fails, this plugin is disabled. */
+    dependsOn?: readonly string[];
+    /** Ordered before this plugin when present; ignored when missing or failed. */
+    optionalDependsOn?: readonly string[];
+    /**
+     * Validates the options before `setup`; `ctx.options` is the parsed result (defaults applied)
+     * and its type is inferred from the schema. Invalid options mark the plugin failed.
+     */
+    optionsSchema?: StandardSchemaV1<Input, Options>;
+    /** Register hooks and provide services. Avoid side effects (sockets, timers) here: that is what `start` is for. */
+    setup(ctx: PluginContext<Options, H, S>): void | Promise<void>;
+    /** Called once every plugin has set up, in dependency order. */
+    start?(ctx: PluginContext<Options, H, S>): void | Promise<void>;
+    /** Called in reverse dependency order. `ctx.signal` is already aborted; disposers run right after. */
+    stop?(ctx: PluginContext<Options, H, S>): void | Promise<void>;
+}
+export interface PluginContext<Options = any, H extends object = any, S extends object = any> {
+    readonly name: string;
+    readonly options: Options;
+    readonly app: AppInfo;
+    /** Aborted when the plugin starts stopping, fails, or times out. Pass it to fetch, timers, servers... */
+    readonly signal: AbortSignal;
+    readonly log: Logger;
+    /** Handlers registered here are removed automatically when the plugin is torn down. */
+    readonly hooks: Hooks<H>;
+    /** Removed automatically when the plugin is torn down. */
+    provide<K extends keyof S & string>(key: K, value: S[K]): void;
+    /** Throws if missing, or if the provider is not listed in `dependsOn` / `optionalDependsOn`. */
+    use<K extends keyof S & string>(key: K): S[K];
+    /** Like `use`, but returns undefined when the service is missing (for optional dependencies). */
+    tryUse<K extends keyof S & string>(key: K): S[K] | undefined;
+    /** Runs on teardown in reverse registration order, after `stop`. */
+    onDispose(fn: () => unknown): void;
+}
+export type PluginState = "registered" | "setup" | "started" | "stopped" | "failed" | "disabled";
+export interface PluginInfo {
+    name: string;
+    version?: string;
+    /** "inline" for `host.register()`, otherwise the package specifier passed to `host.load()`. */
+    source: string;
+    state: PluginState;
+    /** Why the plugin failed or was disabled. */
+    reason?: string;
+    error?: unknown;
+}
+export type HookErrorPolicy = 
+/** Log the error, skip that handler and continue. */
+"log"
+/** Log the error, then stop the plugin (state "failed") and the started plugins that depend on it. */
+ | "disable"
+/** Make the hook call reject with the PluginError. */
+ | "throw";
+export type FailurePolicy = 
+/** A failing plugin is torn down, its dependents disabled, and the rest keep running. */
+"isolate"
+/** The first failure stops everything and rejects `start()` / `load()`. */
+ | "strict";
+export interface HostOptions<H extends object = any> {
+    app: AppInfo;
+    /**
+     * Schemas for values plugins return from `waterfall` and `bail` hooks. A handler returning
+     * an invalid value makes the hook call reject with a PluginError naming that plugin.
+     */
+    hookSchemas?: NoInfer<HookSchemas<H>>;
+    /** Plugins declare the API version they target in their manifest; it must match. Bump it on breaking changes. Default 1. */
+    apiVersion?: number;
+    /** `package.json` field holding the plugin manifest. Defaults to `app.name`. */
+    manifestKey?: string;
+    logger?: Logger;
+    /** Per-plugin limit for each of setup/start/stop. 0 disables. Default 10s. */
+    timeoutMs?: number;
+    /** Default "isolate". */
+    failure?: FailurePolicy;
+    /**
+     * What happens when a plugin's hook handler throws, or returns a value its hook schema rejects,
+     * while the app runs. Errors from your app's own handlers always propagate. Default "log".
+     */
+    hookErrors?: HookErrorPolicy;
+}
+/** A package name (`"my-plugin"`, `"@scope/my-plugin"`), a path (`"./plugins/foo"`), or either with options. */
+export type PluginSpec = string | readonly [specifier: string, options: unknown];
+/** What a plugin package puts under its manifest key in package.json. */
+export interface PluginManifest {
+    apiVersion: number;
+    /** Relative to the package root, e.g. "./dist/index.js". */
+    entry: string;
+}
+export type HostPhase = "idle" | "starting" | "started" | "stopping" | "stopped";
+export type StateListener = (plugin: PluginInfo, previous: PluginState) => void;
+export type ErrorPhase = "register" | "load" | "setup" | "start" | "stop" | "dispose" | "hook" | "service";
+/** Every error the SDK raises about a specific plugin. `cause` holds the original error, if any. */
+export declare class PluginError extends Error {
+    readonly plugin: string;
+    readonly phase: ErrorPhase;
+    /** The message without the `[plugin]` prefix. */
+    readonly reason: string;
+    constructor(plugin: string, phase: ErrorPhase, message: string, options?: ErrorOptions);
+}
+export declare class TimeoutError extends Error {
+    constructor(ms: number);
+}
+export declare class SchemaError extends Error {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(issues: readonly StandardSchemaV1.Issue[]);
+}
+/** Runs a Standard Schema and returns its output, or throws a SchemaError listing the issues. */
+export declare function parseWith<T>(schema: StandardSchemaV1<unknown, T>, value: unknown): Promise<T>;
+export declare function isPlugin(value: unknown): value is Plugin;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,49 @@
+/** Every error the SDK raises about a specific plugin. `cause` holds the original error, if any. */
+export class PluginError extends Error {
+    plugin;
+    phase;
+    /** The message without the `[plugin]` prefix. */
+    reason;
+    constructor(plugin, phase, message, options) {
+        super(`[${plugin}] ${message}`, options);
+        this.name = "PluginError";
+        this.plugin = plugin;
+        this.phase = phase;
+        this.reason = message;
+    }
+}
+export class TimeoutError extends Error {
+    constructor(ms) {
+        super(`timed out after ${ms}ms`);
+        this.name = "TimeoutError";
+    }
+}
+export class SchemaError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues.map(formatIssue).join("; "));
+        this.name = "SchemaError";
+        this.issues = issues;
+    }
+}
+/** Runs a Standard Schema and returns its output, or throws a SchemaError listing the issues. */
+export async function parseWith(schema, value) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues)
+        throw new SchemaError(result.issues);
+    return result.value;
+}
+function formatIssue(issue) {
+    const path = (issue.path ?? []).map((p) => String(typeof p === "object" ? p.key : p)).join(".");
+    return path ? `${path}: ${issue.message}` : issue.message;
+}
+// Duck-typed rather than branded: a plugin may have been built against a
+// different copy of this SDK, so instanceof/symbol checks would reject it.
+export function isPlugin(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.name === "string" &&
+        value.name.length > 0 &&
+        typeof value.setup === "function");
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0IA,oGAAoG;AACpG,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAS;IACf,KAAK,CAAa;IAC3B,iDAAiD;IACxC,MAAM,CAAS;IAExB,YAAY,MAAc,EAAE,KAAiB,EAAE,OAAe,EAAE,OAAsB;QACpF,KAAK,CAAC,IAAI,MAAM,KAAK,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;IACxB,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,EAAU;QACpB,KAAK,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAoC;IAEnD,YAAY,MAAyC;QACnD,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,iGAAiG;AACjG,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,MAAoC,EAAE,KAAc;IACrF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzD,IAAI,MAAM,CAAC,MAAM;QAAE,MAAM,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAExD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,SAAS,WAAW,CAAC,KAA6B;IAChD,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEhG,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;AAC5D,CAAC;AAED,yEAAyE;AACzE,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAgB,CAAC,IAAI,KAAK,QAAQ;QACzC,KAAgB,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QACjC,OAAQ,KAAgB,CAAC,KAAK,KAAK,UAAU,CAC9C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@esauflores/plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A small plugin system for Bun and Node: typed hooks, ordered lifecycle, services, npm loading and Standard Schema validation.",
+  "keywords": [
+    "bun",
+    "hooks",
+    "lifecycle",
+    "microkernel",
+    "plugin",
+    "plugin-system",
+    "plugins",
+    "standard-schema"
+  ],
+  "homepage": "https://github.com/esauflores/plugin-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/esauflores/plugin-sdk/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/esauflores/plugin-sdk.git"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "check": "vp fmt --check && vp lint && tsc --noEmit",
+    "check:fix": "vp fmt && vp lint --fix && tsc --noEmit",
+    "test": "vp test",
+    "test:watch": "vp test --watch",
+    "test:bun": "bun test",
+    "example": "cd examples/basic && bun install && bun app.ts && node app.ts",
+    "prepublishOnly": "bun run check && bun run test && bun run test:bun && bun run build"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^7.0.2",
+    "vite-plus": "^1.1.0",
+    "zod": "^4.6.7"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,253 @@
+import { parseWith, PluginError, type StandardSchemaV1 } from "./types.ts";
+
+export type HookFn = (...args: any[]) => unknown;
+export type HookName<H> = keyof H & string;
+type Fn<H, K extends keyof H> = H[K] extends HookFn ? H[K] : never;
+type Args<H, K extends keyof H> = H[K] extends (...args: infer A) => any ? A : never[];
+type Result<H, K extends keyof H> = H[K] extends (...args: any[]) => infer R ? Awaited<R> : never;
+
+/** Per hook, a schema for the values handlers return (checked by `waterfall` and `bail`). */
+export type HookSchemas<H> = {
+  [K in HookName<H>]?: StandardSchemaV1<unknown, Exclude<Result<H, K>, undefined | void>>;
+};
+
+/** "pre" handlers run first, then "normal" (the default), then "post"; registration order within each. */
+export type HookOrder = "pre" | "normal" | "post";
+
+export interface HookOptions {
+  order?: HookOrder;
+}
+
+export type HookStyle = "call" | "parallel" | "waterfall" | "bail";
+
+/** Observes every hook call on the host's bus: for tracing, metrics, finding slow plugins. */
+export interface HookInterceptor {
+  /** A hook was called, before any handler runs. */
+  call?(event: { hook: string; style: HookStyle; args: readonly unknown[] }): void;
+  /**
+   * One handler finished. `plugin` is undefined for the app's own handlers; `ms` excludes
+   * error handling; `error` is the PluginError if it threw or returned an invalid value.
+   */
+  handler?(event: { hook: string; plugin: string | undefined; ms: number; error?: unknown }): void;
+}
+
+export interface Hooks<H extends object> {
+  /** Returns a function that removes the handler. */
+  on<K extends HookName<H>>(name: K, fn: Fn<H, K>, options?: HookOptions): () => void;
+  /** Runs handlers one after another, in order. */
+  call<K extends HookName<H>>(name: K, ...args: Args<H, K>): Promise<void>;
+  /** Runs all handlers concurrently. */
+  parallel<K extends HookName<H>>(name: K, ...args: Args<H, K>): Promise<void>;
+  /**
+   * Each handler receives the previous one's result as its first argument; returning undefined keeps the value.
+   * Results are checked against the hook's schema, if it has one.
+   */
+  waterfall<K extends HookName<H>>(name: K, ...args: Args<H, K>): Promise<Args<H, K>[0]>;
+  /** Returns the first result that is not undefined, skipping the remaining handlers. Checked like `waterfall`. */
+  bail<K extends HookName<H>>(
+    name: K,
+    ...args: Args<H, K>
+  ): Promise<Exclude<Result<H, K>, undefined | void> | undefined>;
+  count(name: HookName<H>): number;
+}
+
+interface Handler {
+  fn: HookFn;
+  owner?: string;
+  rank: number;
+}
+
+const RANKS: Record<HookOrder, number> = { pre: 0, normal: 1, post: 2 };
+
+/**
+ * Called when a plugin's handler throws or returns an invalid value. Rethrow to make the hook
+ * call reject; return to skip that handler and continue. App handlers (no owner) always rethrow.
+ */
+export type HookErrorHandler = (error: PluginError) => void | Promise<void>;
+
+export class HookBus<H extends object = any> implements Hooks<H> {
+  #handlers = new Map<string, Handler[]>();
+  readonly #schemas: HookSchemas<H>;
+  readonly #onError?: HookErrorHandler;
+  #interceptors: readonly HookInterceptor[] = [];
+
+  constructor(schemas: HookSchemas<H> = {}, onError?: HookErrorHandler) {
+    this.#schemas = schemas;
+    this.#onError = onError;
+  }
+
+  on<K extends HookName<H>>(name: K, fn: Fn<H, K>, options?: HookOptions): () => void {
+    return this.#on(name, fn, undefined, options);
+  }
+
+  /**
+   * Adds an observer of every hook call; returns a function that removes it. Host-only: the
+   * scoped view plugins get has no `intercept`. Errors thrown by an interceptor propagate.
+   */
+  intercept(interceptor: HookInterceptor): () => void {
+    this.#interceptors = [...this.#interceptors, interceptor];
+
+    return () => {
+      this.#interceptors = this.#interceptors.filter((i) => i !== interceptor);
+    };
+  }
+
+  /** A view whose `on` tags handlers with `owner`, so `removeOwner` can drop them all. */
+  scope(owner: string): Hooks<H> {
+    return {
+      on: (name, fn, options) => this.#on(name, fn, owner, options),
+      call: (name, ...args) => this.call(name, ...args),
+      parallel: (name, ...args) => this.parallel(name, ...args),
+      waterfall: (name, ...args) => this.waterfall(name, ...args),
+      bail: (name, ...args) => this.bail(name, ...args),
+      count: (name) => this.count(name),
+    };
+  }
+
+  removeOwner(owner: string): void {
+    for (const [name, list] of this.#handlers) {
+      this.#handlers.set(
+        name,
+        list.filter((h) => h.owner !== owner),
+      );
+    }
+  }
+
+  count(name: HookName<H>): number {
+    return this.#handlers.get(name)?.length ?? 0;
+  }
+
+  async call<K extends HookName<H>>(name: K, ...args: Args<H, K>): Promise<void> {
+    this.#notifyCall(name, "call", args);
+
+    for (const h of this.#snapshot(name)) await this.#handle(h, name, args, false);
+  }
+
+  async parallel<K extends HookName<H>>(name: K, ...args: Args<H, K>): Promise<void> {
+    this.#notifyCall(name, "parallel", args);
+
+    await Promise.all(this.#snapshot(name).map((h) => this.#handle(h, name, args, false)));
+  }
+
+  async waterfall<K extends HookName<H>>(name: K, ...args: Args<H, K>): Promise<Args<H, K>[0]> {
+    this.#notifyCall(name, "waterfall", args);
+
+    let [value, ...rest] = args;
+
+    for (const h of this.#snapshot(name)) {
+      const next = await this.#handle(h, name, [value, ...rest], true);
+      if (next?.value !== undefined) value = next.value;
+    }
+
+    return value;
+  }
+
+  async bail<K extends HookName<H>>(
+    name: K,
+    ...args: Args<H, K>
+  ): Promise<Exclude<Result<H, K>, undefined | void> | undefined> {
+    this.#notifyCall(name, "bail", args);
+
+    for (const h of this.#snapshot(name)) {
+      const result = await this.#handle(h, name, args, true);
+      if (result?.value !== undefined) return result.value as Exclude<Result<H, K>, undefined | void>;
+    }
+
+    return undefined;
+  }
+
+  #on(name: string, fn: HookFn, owner: string | undefined, options: HookOptions = {}): () => void {
+    if (typeof fn !== "function") throw new TypeError(`Hook handler for "${name}" must be a function`);
+
+    const rank = RANKS[options.order ?? "normal"];
+    if (rank === undefined) throw new TypeError(`Hook order must be "pre", "normal" or "post", got "${options.order}"`);
+
+    // Insert after the last handler of the same or an earlier bucket.
+    const handler: Handler = { fn, owner, rank };
+    const list = this.#handlers.get(name) ?? [];
+    const at = list.findIndex((h) => h.rank > rank);
+    this.#handlers.set(name, at === -1 ? [...list, handler] : [...list.slice(0, at), handler, ...list.slice(at)]);
+
+    return () => {
+      const list = this.#handlers.get(name);
+      if (list)
+        this.#handlers.set(
+          name,
+          list.filter((h) => h !== handler),
+        );
+    };
+  }
+
+  // Lists are replaced, never mutated, so handlers added mid-emit don't run in that emit.
+  // Handlers removed mid-emit (e.g. their plugin was disabled) are skipped by #handle.
+  #snapshot(name: string): readonly Handler[] {
+    return this.#handlers.get(name) ?? [];
+  }
+
+  /** Runs one handler (and checks its result); `undefined` means it was skipped or its error was handled. */
+  async #handle(h: Handler, name: string, args: unknown[], checked: boolean): Promise<{ value: unknown } | undefined> {
+    if (!this.#handlers.get(name)?.includes(h)) return undefined;
+
+    const startedAt = performance.now();
+    let result: { value: unknown };
+
+    try {
+      const value = await this.#invoke(h, name, args);
+
+      result = { value: checked && value !== undefined ? await this.#check(h, name, value) : value };
+    } catch (error) {
+      this.#notifyHandler(name, h, startedAt, error);
+
+      if (!this.#onError || h.owner === undefined || !(error instanceof PluginError)) throw error;
+
+      await this.#onError(error);
+
+      return undefined;
+    }
+
+    this.#notifyHandler(name, h, startedAt);
+
+    return result;
+  }
+
+  #notifyCall(hook: string, style: HookStyle, args: readonly unknown[]): void {
+    for (const interceptor of this.#interceptors) interceptor.call?.({ hook, style, args });
+  }
+
+  #notifyHandler(hook: string, h: Handler, startedAt: number, error?: unknown): void {
+    if (this.#interceptors.length === 0) return;
+
+    const event = {
+      hook,
+      plugin: h.owner,
+      ms: performance.now() - startedAt,
+      ...(error === undefined ? {} : { error }),
+    };
+    for (const interceptor of this.#interceptors) interceptor.handler?.(event);
+  }
+
+  async #invoke(h: Handler, name: string, args: unknown[]): Promise<unknown> {
+    try {
+      return await h.fn(...args);
+    } catch (cause) {
+      if (cause instanceof PluginError && cause.phase === "hook") throw cause;
+
+      throw new PluginError(h.owner ?? "<host>", "hook", `handler for "${name}" threw`, { cause });
+    }
+  }
+
+  async #check(h: Handler, name: string, value: unknown): Promise<any> {
+    const schema = this.#schemas[name as HookName<H>];
+    if (!schema) return value;
+
+    try {
+      return await parseWith(schema, value);
+    } catch (cause) {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+
+      throw new PluginError(h.owner ?? "<host>", "hook", `handler for "${name}" returned an invalid value: ${detail}`, {
+        cause,
+      });
+    }
+  }
+}