@zudojs/adapters 1.2.2 → 1.3.0

package/README.md

@@ -61,7 +61,22 @@ await registry.disposeAll(); // stop, dispose, and empty the registry
 
 Each of these attempts every adapter and then throws an `AggregateError`
 carrying the failures, rather than stopping at the first one — a half-applied
-transition leaves resources nobody is tracking.
+transition leaves resources nobody is tracking. From `initializeAll()`,
+`startAll()` and `stopAll()` every entry in `errors` is typed and names its
+adapter — `AdapterInitializationError`, `AdapterOperationError` (operation
+`"start"` or `"stop"`), or `AdapterTimeoutError` when the hook exceeded
+`timeout` — with the hook's own error as `cause`. `disposeAll()` and
+`removeAndDispose()` rethrow the hooks' own errors (an `AggregateError` of
+both when `stop()` and `dispose()` both failed).
+
+`initializeAll()` and `startAll()` run in registration order; `stopAll()` and
+`disposeAll()` run in reverse, so an adapter is torn down before the ones
+registered ahead of it that it may depend on. `initializeAll()`,
+`startAll()` and `stopAll()` take the same `AdapterOperationOptions` as
+`healthAll()`: `timeout` bounds each hook, `retry: { attempts, delay }`
+re-runs a failed one, and `signal` stops the pass.
+`runAdapterLifecycle(adapter, "start", options)` runs one hook the same way,
+and `withRetry` is exported for your own operations.
 
 `remove()` and `clear()` only drop references; `removeAndDispose()` and
 `disposeAll()` also release resources.
@@ -77,9 +92,12 @@ registry.supports("postgres", "gracefulShutdown"); // boolean, never throws
 registry.requireCapability("edge", "streaming"); // throws AdapterCapabilityMissingError
 ```
 
-Declared capabilities: `http`, `websocket`, `streaming`, `filesystem`, `tcp`,
-`udp`, `backgroundTasks`, `longRunning`, `edgeRuntime`, `serverless`,
-`gracefulShutdown`, `abortSignal`.
+Well-known capabilities (`KnownAdapterCapabilities`): `http`, `websocket`,
+`streaming`, `filesystem`, `tcp`, `udp`, `backgroundTasks`, `longRunning`,
+`edgeRuntime`, `serverless`, `gracefulShutdown`, `abortSignal`.
+`AdapterCapabilities` is open: an adapter may declare any other name
+(`capabilities: { refunds: true }`) and `findByCapability("refunds")`,
+`supports()` and `requireCapability()` look it up like any other.
 
 ## Health
 
@@ -118,7 +136,9 @@ report.status; // worst of the per-adapter statuses: "healthy" | "degraded" | "u
 report.adapters.db; // AdapterHealth; throwing, timed-out or aborted checks are "unhealthy"
 ```
 
-Adapters without `health()` are left out of `report.adapters`.
+Adapters without `health()` are left out of `report.adapters`; the rest appear
+in registration order, whichever check finished first. `collectAdapterHealth`
+and `configureAdapter` are exported for registries of your own.
 
 `healthAll({ retry: { attempts, delay } })` re-runs a check that reports
 `unhealthy`, up to `attempts` tries in total, pausing `delay` ms between

package/dist/adapter/adapter.health.d.ts

@@ -28,4 +28,3 @@ export declare function collectAdapterHealth(entries: ReadonlyArray<readonly [st
  * @throws {AdapterConfigurationError} If the adapter has no `configure()` hook.
  */
 export declare function configureAdapter(name: string, adapter: Adapter, options: unknown): Promise<void>;
-//# sourceMappingURL=adapter.health.d.ts.map

package/dist/adapter/adapter.health.js

@@ -66,11 +66,13 @@ export async function collectAdapterHealth(entries, options = {}) {
     // ordinary object runs the inherited prototype setter, so the entry would
     // vanish from the report and an unhealthy adapter would be invisible.
     const adapters = Object.create(null);
-    await Promise.all(entries
-        .filter(([, adapter]) => typeof adapter.health === "function")
-        .map(async ([name, adapter]) => {
-        adapters[name] = await checkOne(adapter, options);
-    }));
+    const checked = entries.filter(([, adapter]) => typeof adapter.health === "function");
+    // Checks run concurrently but are recorded in registration order, so the
+    // report's key order does not depend on which check finished first.
+    const results = await Promise.all(checked.map(([, adapter]) => checkOne(adapter, options)));
+    checked.forEach(([name], index) => {
+        adapters[name] = results[index];
+    });
     let status = "healthy";
     for (const health of Object.values(adapters)) {
         const rank = RANK[health.status] ?? RANK.unhealthy;
@@ -91,4 +93,3 @@ export async function configureAdapter(name, adapter, options) {
     }
     await configurable.configure(options);
 }
-//# sourceMappingURL=adapter.health.js.map

package/dist/adapter/adapter.registry.d.ts

@@ -12,11 +12,15 @@
  * `removeAndDispose()` / `disposeAll()` to also release adapter resources.
  */
 import type { Adapter } from "./adapter.type.js";
-import type { AdapterCapabilities } from "../capabilities/capabilities.type.js";
+import type { KnownAdapterCapabilities } from "../capabilities/capabilities.type.js";
 import type { AdapterHealthReport } from "./adapter.health.js";
 import type { AdapterOperationOptions } from "../lifecycle/lifecycle.type.js";
-/** A capability an adapter can declare. */
-export type AdapterCapabilityName = keyof AdapterCapabilities;
+/**
+ * A capability an adapter can declare: one of the well-known names, with
+ * completion, or any other string (a business capability such as
+ * `"refunds"`).
+ */
+export type AdapterCapabilityName = (keyof KnownAdapterCapabilities & string) | (string & {});
 /**
  * Registry for Zudojs adapters.
  *
@@ -104,21 +108,34 @@ export declare class AdapterRegistry {
      * part of the adapter contract with nothing in the package that ever called
      * them, so an adapter could only be torn down, never brought up.
      *
+     * `options.timeout` bounds each adapter's hook, `options.retry` re-runs a
+     * failed one and `options.signal` stops the whole pass, as for
+     * {@link healthAll}.
+     *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is an `AdapterInitializationError` (or `AdapterTimeoutError`)
+     * naming its adapter, with the hook's own error as `cause`.
      */
-    initializeAll(): Promise<void>;
+    initializeAll(options?: AdapterOperationOptions): Promise<void>;
     /**
      * Starts every registered adapter, in registration order.
      *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is an `AdapterOperationError` (or `AdapterTimeoutError`)
+     * naming its adapter, with the hook's own error as `cause`.
      */
-    startAll(): Promise<void>;
+    startAll(options?: AdapterOperationOptions): Promise<void>;
     /**
-     * Stops every registered adapter without disposing or unregistering them.
+     * Stops every registered adapter without disposing or unregistering them,
+     * in reverse registration order — the mirror of {@link startAll}, so an
+     * adapter is stopped before anything registered ahead of it that it may
+     * depend on.
      *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is an `AdapterOperationError` (or `AdapterTimeoutError`)
+     * naming its adapter, with the hook's own error as `cause`.
      */
-    stopAll(): Promise<void>;
+    stopAll(options?: AdapterOperationOptions): Promise<void>;
     /**
      * Checks the health of every adapter that implements `health()`. Failures,
      * timeouts (`options.timeout`) and aborts (`options.signal`) are reported
@@ -143,29 +160,15 @@ export declare class AdapterRegistry {
      */
     clear(): void;
     /**
-     * Clears the registry and releases every adapter's resources
-     * (calls `stop()` then `dispose()` when defined, best-effort).
+     * Clears the registry and releases every adapter's resources (calls
+     * `stop()` then `dispose()` when defined, best-effort), in reverse
+     * registration order like {@link stopAll}.
      *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is what {@link removeAndDispose} would have thrown for that
+     * adapter: the hook's own error, or an `AggregateError` of both when its
+     * `stop()` and `dispose()` both failed.
      */
     disposeAll(): Promise<void>;
-    /**
-     * Stops, then disposes, one adapter.
-     *
-     * `dispose()` runs even when `stop()` throws: the adapter has already
-     * left the registry by the time this is called, so skipping disposal
-     * would orphan its connections and timers with nothing left holding a
-     * reference to release them. A `stop()` failure is still reported — on
-     * its own when disposal succeeds, alongside the disposal error when
-     * both fail.
-     */
-    private teardown;
-    /**
-     * Runs an operation against every adapter, collecting failures rather than
-     * stopping at the first one — a half-applied lifecycle transition leaves
-     * resources in a state nobody tracked.
-     */
-    private forEachAdapter;
     private normalizeName;
 }
-//# sourceMappingURL=adapter.registry.d.ts.map

package/dist/adapter/adapter.registry.js

@@ -13,6 +13,7 @@
  */
 import { AdapterAlreadyRegisteredError, AdapterCapabilityMissingError, AdapterConfigurationError, AdapterNotFoundError, } from "@zudojs/errors";
 import { collectAdapterHealth, configureAdapter } from "./adapter.health.js";
+import { runAdapterLifecycleAll, teardownAdapter, } from "./adapterLifecycle/index.js";
 /** Names that are unsafe as a plain-object key, so no adapter may claim them. */
 const RESERVED_NAMES = new Set([
     "__proto__",
@@ -99,7 +100,7 @@ export class AdapterRegistry {
             return false;
         }
         this.adapters.delete(key);
-        await this.teardown(adapter);
+        await teardownAdapter(adapter);
         return true;
     }
     /**
@@ -153,26 +154,39 @@ export class AdapterRegistry {
      * part of the adapter contract with nothing in the package that ever called
      * them, so an adapter could only be torn down, never brought up.
      *
+     * `options.timeout` bounds each adapter's hook, `options.retry` re-runs a
+     * failed one and `options.signal` stops the whole pass, as for
+     * {@link healthAll}.
+     *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is an `AdapterInitializationError` (or `AdapterTimeoutError`)
+     * naming its adapter, with the hook's own error as `cause`.
      */
-    async initializeAll() {
-        await this.forEachAdapter((adapter) => adapter.initialize?.(), "One or more adapters failed to initialize.");
+    async initializeAll(options = {}) {
+        await runAdapterLifecycleAll([...this.adapters.values()], "initialize", options, "One or more adapters failed to initialize.");
     }
     /**
      * Starts every registered adapter, in registration order.
      *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is an `AdapterOperationError` (or `AdapterTimeoutError`)
+     * naming its adapter, with the hook's own error as `cause`.
      */
-    async startAll() {
-        await this.forEachAdapter((adapter) => adapter.start?.(), "One or more adapters failed to start.");
+    async startAll(options = {}) {
+        await runAdapterLifecycleAll([...this.adapters.values()], "start", options, "One or more adapters failed to start.");
     }
     /**
-     * Stops every registered adapter without disposing or unregistering them.
+     * Stops every registered adapter without disposing or unregistering them,
+     * in reverse registration order — the mirror of {@link startAll}, so an
+     * adapter is stopped before anything registered ahead of it that it may
+     * depend on.
      *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is an `AdapterOperationError` (or `AdapterTimeoutError`)
+     * naming its adapter, with the hook's own error as `cause`.
      */
-    async stopAll() {
-        await this.forEachAdapter((adapter) => adapter.stop?.(), "One or more adapters failed to stop.");
+    async stopAll(options = {}) {
+        await runAdapterLifecycleAll([...this.adapters.values()].reverse(), "stop", options, "One or more adapters failed to stop.");
     }
     /**
      * Checks the health of every adapter that implements `health()`. Failures,
@@ -206,18 +220,22 @@ export class AdapterRegistry {
         this.adapters.clear();
     }
     /**
-     * Clears the registry and releases every adapter's resources
-     * (calls `stop()` then `dispose()` when defined, best-effort).
+     * Clears the registry and releases every adapter's resources (calls
+     * `stop()` then `dispose()` when defined, best-effort), in reverse
+     * registration order like {@link stopAll}.
      *
      * @throws {AggregateError} After attempting all adapters, if any failed.
+     * Each entry is what {@link removeAndDispose} would have thrown for that
+     * adapter: the hook's own error, or an `AggregateError` of both when its
+     * `stop()` and `dispose()` both failed.
      */
     async disposeAll() {
-        const adapters = [...this.adapters.values()];
+        const adapters = [...this.adapters.values()].reverse();
         this.adapters.clear();
         const failures = [];
         for (const adapter of adapters) {
             try {
-                await this.teardown(adapter);
+                await teardownAdapter(adapter);
             }
             catch (error) {
                 failures.push(error);
@@ -227,59 +245,7 @@ export class AdapterRegistry {
             throw new AggregateError(failures, "One or more adapters failed to dispose.");
         }
     }
-    /**
-     * Stops, then disposes, one adapter.
-     *
-     * `dispose()` runs even when `stop()` throws: the adapter has already
-     * left the registry by the time this is called, so skipping disposal
-     * would orphan its connections and timers with nothing left holding a
-     * reference to release them. A `stop()` failure is still reported — on
-     * its own when disposal succeeds, alongside the disposal error when
-     * both fail.
-     */
-    async teardown(adapter) {
-        let stopError;
-        let stopFailed = false;
-        try {
-            await adapter.stop?.();
-        }
-        catch (error) {
-            stopFailed = true;
-            stopError = error;
-        }
-        try {
-            await adapter.dispose?.();
-        }
-        catch (error) {
-            if (stopFailed) {
-                throw new AggregateError([stopError, error], `Adapter "${adapter.name}" failed to stop and to dispose.`);
-            }
-            throw error;
-        }
-        if (stopFailed)
-            throw stopError;
-    }
-    /**
-     * Runs an operation against every adapter, collecting failures rather than
-     * stopping at the first one — a half-applied lifecycle transition leaves
-     * resources in a state nobody tracked.
-     */
-    async forEachAdapter(operation, message) {
-        const failures = [];
-        for (const adapter of [...this.adapters.values()]) {
-            try {
-                await operation(adapter);
-            }
-            catch (error) {
-                failures.push(error);
-            }
-        }
-        if (failures.length > 0) {
-            throw new AggregateError(failures, message);
-        }
-    }
     normalizeName(name) {
         return name.trim().toLowerCase();
     }
 }
-//# sourceMappingURL=adapter.registry.js.map

package/dist/adapter/adapter.retry.d.ts

@@ -32,4 +32,3 @@ export declare function wait(ms: number, signal?: AbortSignal): Promise<void>;
  * @returns The first accepted result, or the last one produced.
  */
 export declare function withRetry<T>(attempt: () => Promise<T>, accept: (result: T) => boolean, options: AdapterOperationOptions): Promise<T>;
-//# sourceMappingURL=adapter.retry.d.ts.map

package/dist/adapter/adapter.retry.js

@@ -71,4 +71,3 @@ export async function withRetry(attempt, accept, options) {
     }
     return result;
 }
-//# sourceMappingURL=adapter.retry.js.map

package/dist/adapter/adapter.type.d.ts

@@ -45,4 +45,3 @@ export interface Adapter {
      */
     dispose?(): Promise<void> | void;
 }
-//# sourceMappingURL=adapter.type.d.ts.map

package/dist/adapter/adapter.type.js

@@ -4,4 +4,3 @@
  * Core adapter contract — the base interface all adapters implement.
  */
 export {};
-//# sourceMappingURL=adapter.type.js.map

package/dist/adapter/adapterLifecycle/adapterLifecycle.all.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Lifecycle operations over a set of adapters: every adapter is attempted
+ * and the failures are collected, because stopping at the first one leaves a
+ * half-applied transition nobody tracks.
+ */
+import type { Adapter } from "../adapter.type.js";
+import { type AdapterLifecycleOperation } from "./adapterLifecycle.ops.js";
+import type { AdapterOperationOptions } from "../../lifecycle/lifecycle.type.js";
+/**
+ * Runs one lifecycle hook on every adapter, in the order given, and throws
+ * an `AggregateError` of the typed per-adapter failures once all have been
+ * attempted.
+ */
+export declare function runAdapterLifecycleAll(adapters: readonly Adapter[], operation: AdapterLifecycleOperation, options: AdapterOperationOptions, message: string): Promise<void>;
+/**
+ * Stops, then disposes, one adapter, rethrowing the hooks' own errors.
+ *
+ * `dispose()` runs even when `stop()` throws: by the time this is called the
+ * adapter has left the registry, so skipping disposal would orphan its
+ * connections and timers with nothing left holding a reference to release
+ * them. A `stop()` failure is still reported — on its own when disposal
+ * succeeds, alongside the disposal error when both fail.
+ *
+ * @throws {AggregateError} of the stop and dispose errors when both failed.
+ */
+export declare function teardownAdapter(adapter: Adapter): Promise<void>;

package/dist/adapter/adapterLifecycle/adapterLifecycle.all.js

@@ -0,0 +1,60 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Lifecycle operations over a set of adapters: every adapter is attempted
+ * and the failures are collected, because stopping at the first one leaves a
+ * half-applied transition nobody tracks.
+ */
+import { runAdapterLifecycle, } from "./adapterLifecycle.ops.js";
+/**
+ * Runs one lifecycle hook on every adapter, in the order given, and throws
+ * an `AggregateError` of the typed per-adapter failures once all have been
+ * attempted.
+ */
+export async function runAdapterLifecycleAll(adapters, operation, options, message) {
+    const failures = [];
+    for (const adapter of adapters) {
+        try {
+            await runAdapterLifecycle(adapter, operation, options);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length > 0) {
+        throw new AggregateError(failures, message);
+    }
+}
+/**
+ * Stops, then disposes, one adapter, rethrowing the hooks' own errors.
+ *
+ * `dispose()` runs even when `stop()` throws: by the time this is called the
+ * adapter has left the registry, so skipping disposal would orphan its
+ * connections and timers with nothing left holding a reference to release
+ * them. A `stop()` failure is still reported — on its own when disposal
+ * succeeds, alongside the disposal error when both fail.
+ *
+ * @throws {AggregateError} of the stop and dispose errors when both failed.
+ */
+export async function teardownAdapter(adapter) {
+    let stopError;
+    let stopFailed = false;
+    try {
+        await adapter.stop?.();
+    }
+    catch (error) {
+        stopFailed = true;
+        stopError = error;
+    }
+    try {
+        await adapter.dispose?.();
+    }
+    catch (error) {
+        if (stopFailed) {
+            throw new AggregateError([stopError, error], `Adapter "${adapter.name}" failed to stop and to dispose.`);
+        }
+        throw error;
+    }
+    if (stopFailed)
+        throw stopError;
+}

package/dist/adapter/adapterLifecycle/adapterLifecycle.ops.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Bounded execution of one adapter lifecycle hook.
+ *
+ * `initializeAll()`, `startAll()` and `stopAll()` used to run each hook bare:
+ * no timeout, no retry, no abort, and a failure surfaced as whatever the hook
+ * threw, so an `AggregateError` from `initializeAll()` never said which
+ * adapter had failed. Every hook now runs under the same
+ * `AdapterOperationOptions` as `healthAll()`, and a failure is wrapped in the
+ * typed error for its operation, naming the adapter and keeping the original
+ * as `cause`.
+ */
+import { AdapterError } from "@zudojs/errors";
+import type { Adapter } from "../adapter.type.js";
+import type { AdapterOperationOptions } from "../../lifecycle/lifecycle.type.js";
+/** The lifecycle hooks of {@link Adapter}. */
+export type AdapterLifecycleOperation = "initialize" | "start" | "stop" | "dispose";
+/**
+ * Wraps a hook's failure in the typed error for `operation`, naming the
+ * adapter. An `AdapterError` — an `AdapterTimeoutError` from the timeout
+ * here, or one the adapter threw on purpose — already does, so it passes
+ * through unchanged.
+ */
+export declare function toAdapterLifecycleError(adapter: Adapter, operation: AdapterLifecycleOperation, error: unknown): AdapterError;
+/**
+ * Runs one lifecycle hook of `adapter` under `options` — `timeout` bounds
+ * each try, `retry` re-runs a failed try, `signal` stops the whole thing —
+ * and throws the typed error for the operation when the last try failed.
+ * An adapter without the hook succeeds immediately.
+ *
+ * @throws {AdapterInitializationError} when `initialize()` failed.
+ * @throws {AdapterOperationError} when `start()` or `stop()` failed, or the
+ * signal aborted.
+ * @throws {AdapterDisposeError} when `dispose()` failed.
+ * @throws {AdapterTimeoutError} when the last try exceeded `timeout`.
+ */
+export declare function runAdapterLifecycle(adapter: Adapter, operation: AdapterLifecycleOperation, options?: AdapterOperationOptions): Promise<void>;

package/dist/adapter/adapterLifecycle/adapterLifecycle.ops.js

@@ -0,0 +1,95 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Bounded execution of one adapter lifecycle hook.
+ *
+ * `initializeAll()`, `startAll()` and `stopAll()` used to run each hook bare:
+ * no timeout, no retry, no abort, and a failure surfaced as whatever the hook
+ * threw, so an `AggregateError` from `initializeAll()` never said which
+ * adapter had failed. Every hook now runs under the same
+ * `AdapterOperationOptions` as `healthAll()`, and a failure is wrapped in the
+ * typed error for its operation, naming the adapter and keeping the original
+ * as `cause`.
+ */
+import { AdapterDisposeError, AdapterError, AdapterInitializationError, AdapterOperationError, AdapterTimeoutError, } from "@zudojs/errors";
+import { withRetry } from "../adapter.retry.js";
+const OK = Object.freeze({ ok: true });
+/**
+ * Wraps a hook's failure in the typed error for `operation`, naming the
+ * adapter. An `AdapterError` — an `AdapterTimeoutError` from the timeout
+ * here, or one the adapter threw on purpose — already does, so it passes
+ * through unchanged.
+ */
+export function toAdapterLifecycleError(adapter, operation, error) {
+    if (error instanceof AdapterError)
+        return error;
+    switch (operation) {
+        case "initialize":
+            return new AdapterInitializationError(adapter.name, error);
+        case "dispose":
+            return new AdapterDisposeError(adapter.name, error);
+        default:
+            return new AdapterOperationError(adapter.name, operation, error);
+    }
+}
+/** One attempt at the hook, bounded by `timeout` and `signal`. */
+async function attemptOnce(adapter, operation, options) {
+    const abortError = () => ({
+        ok: false,
+        error: new AdapterOperationError(adapter.name, operation, options.signal?.reason),
+    });
+    if (options.signal?.aborted)
+        return abortError();
+    const hook = adapter[operation];
+    if (typeof hook !== "function")
+        return OK;
+    let timer;
+    let onAbort;
+    const guards = [];
+    if (options.timeout !== undefined) {
+        const timeout = options.timeout;
+        guards.push(new Promise((resolve) => {
+            timer = setTimeout(() => resolve({
+                ok: false,
+                error: new AdapterTimeoutError(adapter.name, operation, timeout),
+            }), timeout);
+        }));
+    }
+    if (options.signal) {
+        const signal = options.signal;
+        guards.push(new Promise((resolve) => {
+            onAbort = () => resolve(abortError());
+            signal.addEventListener("abort", onAbort, { once: true });
+        }));
+    }
+    try {
+        const run = Promise.resolve()
+            .then(() => hook.call(adapter))
+            .then(() => OK, (error) => ({ ok: false, error }));
+        return await Promise.race([run, ...guards]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort)
+            options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+/**
+ * Runs one lifecycle hook of `adapter` under `options` — `timeout` bounds
+ * each try, `retry` re-runs a failed try, `signal` stops the whole thing —
+ * and throws the typed error for the operation when the last try failed.
+ * An adapter without the hook succeeds immediately.
+ *
+ * @throws {AdapterInitializationError} when `initialize()` failed.
+ * @throws {AdapterOperationError} when `start()` or `stop()` failed, or the
+ * signal aborted.
+ * @throws {AdapterDisposeError} when `dispose()` failed.
+ * @throws {AdapterTimeoutError} when the last try exceeded `timeout`.
+ */
+export async function runAdapterLifecycle(adapter, operation, options = {}) {
+    const outcome = await withRetry(() => attemptOnce(adapter, operation, options), (result) => result.ok, options);
+    if (!outcome.ok) {
+        throw toAdapterLifecycleError(adapter, operation, outcome.error);
+    }
+}

package/dist/adapter/adapterLifecycle/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/adapters/adapter/adapterLifecycle
+ *
+ * Bounded, typed execution of adapter lifecycle hooks, singly and across a
+ * registry's adapters.
+ */
+export { runAdapterLifecycle, toAdapterLifecycleError, } from "./adapterLifecycle.ops.js";
+export type { AdapterLifecycleOperation } from "./adapterLifecycle.ops.js";
+export { runAdapterLifecycleAll, teardownAdapter, } from "./adapterLifecycle.all.js";

package/dist/adapter/adapterLifecycle/index.js

@@ -0,0 +1,8 @@
+/**
+ * @zudojs/adapters/adapter/adapterLifecycle
+ *
+ * Bounded, typed execution of adapter lifecycle hooks, singly and across a
+ * registry's adapters.
+ */
+export { runAdapterLifecycle, toAdapterLifecycleError, } from "./adapterLifecycle.ops.js";
+export { runAdapterLifecycleAll, teardownAdapter, } from "./adapterLifecycle.all.js";

package/dist/adapter/index.d.ts

@@ -8,4 +8,6 @@ export { AdapterRegistry } from "./adapter.registry.js";
 export type { AdapterCapabilityName } from "./adapter.registry.js";
 export { collectAdapterHealth, configureAdapter } from "./adapter.health.js";
 export type { AdapterHealthReport } from "./adapter.health.js";
-//# sourceMappingURL=index.d.ts.map
+export { withRetry } from "./adapter.retry.js";
+export { runAdapterLifecycle, toAdapterLifecycleError, } from "./adapterLifecycle/index.js";
+export type { AdapterLifecycleOperation } from "./adapterLifecycle/index.js";

package/dist/adapter/index.js

@@ -5,4 +5,5 @@
  */
 export { AdapterRegistry } from "./adapter.registry.js";
 export { collectAdapterHealth, configureAdapter } from "./adapter.health.js";
-//# sourceMappingURL=index.js.map
+export { withRetry } from "./adapter.retry.js";
+export { runAdapterLifecycle, toAdapterLifecycleError, } from "./adapterLifecycle/index.js";

package/dist/capabilities/capabilities.type.d.ts

@@ -8,8 +8,23 @@
  *
  * Not every platform supports every feature. Adapters declare their
  * capabilities so runtime code can adapt behavior accordingly.
+ *
+ * The well-known keys are listed in {@link KnownAdapterCapabilities}; any
+ * other name (`refunds`, `bulkExport`, …) is a business capability an
+ * adapter may declare and `findByCapability` / `supports` /
+ * `requireCapability` can look up. The interface used to be closed, so a
+ * capability outside the list was a compile error and could never be
+ * queried.
+ */
+export interface AdapterCapabilities extends KnownAdapterCapabilities {
+    readonly [capability: string]: boolean | undefined;
+}
+/**
+ * The capability names this package defines. Kept separate from
+ * {@link AdapterCapabilities} so `AdapterCapabilityName` can still offer
+ * them for completion while accepting any string.
  */
-export interface AdapterCapabilities {
+export interface KnownAdapterCapabilities {
     /** Supports HTTP request/response handling. */
     readonly http?: boolean;
     /** Supports WebSocket connections. */
@@ -35,4 +50,3 @@ export interface AdapterCapabilities {
     /** Supports request cancellation via AbortSignal. */
     readonly abortSignal?: boolean;
 }
-//# sourceMappingURL=capabilities.type.d.ts.map

package/dist/capabilities/capabilities.type.js

@@ -4,4 +4,3 @@
  * Adapter capabilities — declares what an adapter supports.
  */
 export {};
-//# sourceMappingURL=capabilities.type.js.map

package/dist/capabilities/index.d.ts

@@ -4,4 +4,4 @@
  * Adapter capabilities types.
  */
 export type { AdapterCapabilities } from "./capabilities.type.js";
-//# sourceMappingURL=index.d.ts.map
+export type { KnownAdapterCapabilities } from "./capabilities.type.js";

package/dist/capabilities/index.js

@@ -4,4 +4,3 @@
  * Adapter capabilities types.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/cli/cliAdapter.type.d.ts

@@ -28,4 +28,3 @@ export interface CLIResult {
     readonly stdout: string;
     readonly stderr: string;
 }
-//# sourceMappingURL=cliAdapter.type.d.ts.map

package/dist/cli/cliAdapter.type.js

@@ -4,4 +4,3 @@
  * CLI adapter contracts — bridges Zudojs to command-line interfaces.
  */
 export {};
-//# sourceMappingURL=cliAdapter.type.js.map

package/dist/cli/index.d.ts

@@ -4,4 +4,3 @@
  * CLI adapter contracts.
  */
 export type { CLIAdapter, CLIOptions, CLIResult } from "./cliAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -4,4 +4,3 @@
  * CLI adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/errors/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { AdapterError, AdapterNotFoundError, AdapterAlreadyRegisteredError, AdapterNotSupportedError, AdapterCapabilityMissingError, AdapterConnectionError, AdapterOperationError, AdapterTimeoutError, AdapterDisposeError, AdapterInitializationError, AdapterConfigurationError, createAdapterError, isAdapterError, } from "@zudojs/errors";
 export type { AdapterErrorOptions } from "@zudojs/errors";
-//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.js

@@ -4,4 +4,3 @@
  * Adapter error types — re-exported from @zudojs/errors.
  */
 export { AdapterError, AdapterNotFoundError, AdapterAlreadyRegisteredError, AdapterNotSupportedError, AdapterCapabilityMissingError, AdapterConnectionError, AdapterOperationError, AdapterTimeoutError, AdapterDisposeError, AdapterInitializationError, AdapterConfigurationError, createAdapterError, isAdapterError, } from "@zudojs/errors";
-//# sourceMappingURL=index.js.map

package/dist/http/httpAdapter.type.d.ts

@@ -82,4 +82,3 @@ export interface HTTPServerAdapter extends Adapter {
     listen(options?: HTTPListenOptions): Promise<void>;
     close(): Promise<void>;
 }
-//# sourceMappingURL=httpAdapter.type.d.ts.map

package/dist/http/httpAdapter.type.js

@@ -4,4 +4,3 @@
  * HTTP adapter contracts — request/response translation and server lifecycle.
  */
 export {};
-//# sourceMappingURL=httpAdapter.type.js.map

package/dist/http/index.d.ts

@@ -4,4 +4,3 @@
  * HTTP adapter contracts.
  */
 export type { HTTPRequestLike, HTTPResponseLike, HTTPAdapter, HTTPListenOptions, HTTPRequestAdapter, HTTPResponseAdapter, HTTPServerAdapter, } from "./httpAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -4,4 +4,3 @@
  * HTTP adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -16,10 +16,9 @@
  * @module @zudojs/adapters
  */
 export type { Adapter } from "./adapter/index.js";
-export { AdapterRegistry } from "./adapter/index.js";
-export type { AdapterCapabilityName } from "./adapter/index.js";
-export type { AdapterHealthReport } from "./adapter/index.js";
-export type { AdapterCapabilities } from "./capabilities/index.js";
+export { AdapterRegistry, collectAdapterHealth, configureAdapter, withRetry, runAdapterLifecycle, toAdapterLifecycleError, } from "./adapter/index.js";
+export type { AdapterCapabilityName, AdapterHealthReport, AdapterLifecycleOperation, } from "./adapter/index.js";
+export type { AdapterCapabilities, KnownAdapterCapabilities, } from "./capabilities/index.js";
 export type { AdapterMetadata } from "./metadata/index.js";
 export type { AdapterHealthStatus, AdapterHealth, AdapterOperationOptions, LifecycleAdapter, } from "./lifecycle/index.js";
 export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./lifecycle/index.js";
@@ -37,4 +36,3 @@ export type { Adapter as MockAdapter } from "./testing/index.js";
 export type { AdapterHealth as MockAdapterHealth } from "./testing/index.js";
 export type { AdapterRegistry as MockAdapterRegistry } from "./testing/index.js";
 export { createMockAdapter, createMockAdapterRegistry, createMockHealth, } from "./testing/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -15,9 +15,8 @@
  *
  * @module @zudojs/adapters
  */
-export { AdapterRegistry } from "./adapter/index.js";
+export { AdapterRegistry, collectAdapterHealth, configureAdapter, withRetry, runAdapterLifecycle, toAdapterLifecycleError, } from "./adapter/index.js";
 export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./lifecycle/index.js";
 // Errors
 export { AdapterError, AdapterNotFoundError, AdapterAlreadyRegisteredError, AdapterNotSupportedError, AdapterCapabilityMissingError, AdapterConnectionError, AdapterOperationError, AdapterTimeoutError, AdapterDisposeError, AdapterInitializationError, AdapterConfigurationError, createAdapterError, isAdapterError, } from "./errors/index.js";
 export { createMockAdapter, createMockAdapterRegistry, createMockHealth, } from "./testing/index.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycle/index.d.ts

@@ -5,4 +5,3 @@
  */
 export type { AdapterHealthStatus, AdapterHealth, AdapterOperationOptions, LifecycleAdapter, } from "./lifecycle.type.js";
 export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./lifecycle.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.js

@@ -4,4 +4,3 @@
  * Adapter lifecycle contracts.
  */
 export { createHealthyHealth, createDegradedHealth, createUnhealthyHealth, } from "./lifecycle.type.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycle/lifecycle.type.d.ts

@@ -59,4 +59,3 @@ export declare function createDegradedHealth(message: string): AdapterHealth;
  * Creates an unhealthy health report.
  */
 export declare function createUnhealthyHealth(message: string): AdapterHealth;
-//# sourceMappingURL=lifecycle.type.d.ts.map

package/dist/lifecycle/lifecycle.type.js

@@ -32,4 +32,3 @@ export function createUnhealthyHealth(message) {
         timestamp: Date.now(),
     };
 }
-//# sourceMappingURL=lifecycle.type.js.map

package/dist/messaging/index.d.ts

@@ -4,4 +4,3 @@
  * Messaging adapter contracts.
  */
 export type { MessageAdapter, MessageHandler, Subscription, } from "./messageAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/messaging/index.js

@@ -4,4 +4,3 @@
  * Messaging adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/messaging/messageAdapter.type.d.ts

@@ -29,4 +29,3 @@ export interface Subscription {
     readonly topic: string;
     unsubscribe(): Promise<void>;
 }
-//# sourceMappingURL=messageAdapter.type.d.ts.map

package/dist/messaging/messageAdapter.type.js

@@ -4,4 +4,3 @@
  * Messaging adapter contracts — bridges Zudojs messaging to external providers.
  */
 export {};
-//# sourceMappingURL=messageAdapter.type.js.map

package/dist/metadata/index.d.ts

@@ -4,4 +4,3 @@
  * Adapter metadata types.
  */
 export type { AdapterMetadata } from "./metadata.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/metadata/index.js

@@ -4,4 +4,3 @@
  * Adapter metadata types.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/metadata/metadata.type.d.ts

@@ -31,4 +31,3 @@ export interface AdapterMetadata {
     /** Peer dependencies. */
     readonly peerDependencies?: Readonly<Record<string, string>>;
 }
-//# sourceMappingURL=metadata.type.d.ts.map

package/dist/metadata/metadata.type.js

@@ -4,4 +4,3 @@
  * Adapter metadata — identification and compatibility information.
  */
 export {};
-//# sourceMappingURL=metadata.type.js.map

package/dist/queue/index.d.ts

@@ -4,4 +4,3 @@
  * Queue adapter contracts.
  */
 export type { QueueAdapter, QueueStats } from "./queueAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/queue/index.js

@@ -4,4 +4,3 @@
  * Queue adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/queue/queueAdapter.type.d.ts

@@ -31,4 +31,3 @@ export interface QueueStats {
     readonly failed: number;
     readonly delayed: number;
 }
-//# sourceMappingURL=queueAdapter.type.d.ts.map

package/dist/queue/queueAdapter.type.js

@@ -6,4 +6,3 @@
  * Examples: BullMQ, RabbitMQ, AWS SQS, Redis, Kafka.
  */
 export {};
-//# sourceMappingURL=queueAdapter.type.js.map

package/dist/runtime/index.d.ts

@@ -4,4 +4,3 @@
  * Runtime adapter contracts.
  */
 export type { RuntimeAdapter } from "./runtimeAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -4,4 +4,3 @@
  * Runtime adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/runtime/runtimeAdapter.type.d.ts

@@ -25,4 +25,3 @@ export interface RuntimeAdapter extends Adapter {
         cancel: () => void;
     };
 }
-//# sourceMappingURL=runtimeAdapter.type.d.ts.map

package/dist/runtime/runtimeAdapter.type.js

@@ -6,4 +6,3 @@
  * Examples: Node.js, Bun, Deno, AWS Lambda, Cloudflare Workers.
  */
 export {};
-//# sourceMappingURL=runtimeAdapter.type.js.map

package/dist/scheduler/index.d.ts

@@ -4,4 +4,3 @@
  * Scheduler adapter contracts.
  */
 export type { SchedulerAdapter, ScheduledTask, ScheduledJob, } from "./schedulerAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.js

@@ -4,4 +4,3 @@
  * Scheduler adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/scheduler/schedulerAdapter.type.d.ts

@@ -33,4 +33,3 @@ export interface ScheduledJob {
     readonly nextRun: number;
     cancel(): Promise<void>;
 }
-//# sourceMappingURL=schedulerAdapter.type.d.ts.map

package/dist/scheduler/schedulerAdapter.type.js

@@ -4,4 +4,3 @@
  * Scheduler adapter contracts — bridges Zudojs to scheduling providers.
  */
 export {};
-//# sourceMappingURL=schedulerAdapter.type.js.map

package/dist/storage/index.d.ts

@@ -4,4 +4,3 @@
  * Storage adapter contracts.
  */
 export type { StorageAdapter } from "./storageAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.js

@@ -4,4 +4,3 @@
  * Storage adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/storage/storageAdapter.type.d.ts

@@ -21,4 +21,3 @@ export interface StorageAdapter extends Adapter {
     /** Lists objects with optional prefix. */
     list(prefix?: string, options?: AdapterOperationOptions): Promise<readonly string[]>;
 }
-//# sourceMappingURL=storageAdapter.type.d.ts.map

package/dist/storage/storageAdapter.type.js

@@ -6,4 +6,3 @@
  * Examples: Local filesystem, AWS S3, Cloudflare R2, Google Cloud Storage, Azure Blob.
  */
 export {};
-//# sourceMappingURL=storageAdapter.type.js.map

package/dist/testing/adapterTesting.helper.d.ts

@@ -27,4 +27,3 @@ export declare function createMockAdapterRegistry(adapters?: Adapter[]): {
  * Creates a default healthy health report.
  */
 export declare function createMockHealth(): AdapterHealth;
-//# sourceMappingURL=adapterTesting.helper.d.ts.map

package/dist/testing/adapterTesting.helper.js

@@ -58,4 +58,3 @@ export function createMockHealth() {
         timestamp: Date.now(),
     };
 }
-//# sourceMappingURL=adapterTesting.helper.js.map

package/dist/testing/index.d.ts

@@ -8,4 +8,3 @@ export type { AdapterCapabilities } from "../capabilities/capabilities.type.js";
 export type { AdapterRegistry } from "../adapter/adapter.registry.js";
 export type { AdapterHealth } from "../lifecycle/lifecycle.type.js";
 export { createMockAdapter, createMockAdapterRegistry, createMockHealth, } from "./adapterTesting.helper.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.js

@@ -4,4 +4,3 @@
  * Testing utilities for adapter implementations.
  */
 export { createMockAdapter, createMockAdapterRegistry, createMockHealth, } from "./adapterTesting.helper.js";
-//# sourceMappingURL=index.js.map

package/dist/websocket/index.d.ts

@@ -4,4 +4,3 @@
  * WebSocket adapter contracts.
  */
 export type { WebSocketAdapter, WebSocketSession, WebSocketReadyState, } from "./websocketAdapter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/websocket/index.js

@@ -4,4 +4,3 @@
  * WebSocket adapter contracts.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/websocket/websocketAdapter.type.d.ts

@@ -35,4 +35,3 @@ export declare enum WebSocketReadyState {
     CLOSING = 2,
     CLOSED = 3
 }
-//# sourceMappingURL=websocketAdapter.type.d.ts.map

package/dist/websocket/websocketAdapter.type.js

@@ -13,4 +13,3 @@ export var WebSocketReadyState;
     WebSocketReadyState[WebSocketReadyState["CLOSING"] = 2] = "CLOSING";
     WebSocketReadyState[WebSocketReadyState["CLOSED"] = 3] = "CLOSED";
 })(WebSocketReadyState || (WebSocketReadyState = {}));
-//# sourceMappingURL=websocketAdapter.type.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/adapters",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Boundary layer between Zudojs and external platforms — adapter contracts, registry, capabilities, and transport abstractions.",
   "license": "MIT",
   "author": {
@@ -27,7 +27,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.3.1"
+    "@zudojs/errors": "1.4.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",