@zudojs/adapters 1.0.1 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Boundary layer between Zudojs and external platforms with adapter contracts, registry, capabilities, and transport abstractions.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-adapters](https://zudojs.oyinlola.site/docs/packages-adapters) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-adapters.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -88,7 +94,38 @@ const health = createDegradedHealth("replica lag above threshold");
 ```
 
 A `LifecycleAdapter` adds optional `configure(options)` and `health()` to the
-base contract.
+base contract. The registry calls them:
+
+```typescript
+import {
+  AdapterRegistry,
+  createHealthyHealth,
+  createMockAdapter,
+} from "@zudojs/adapters";
+
+const registry = new AdapterRegistry();
+registry.register(
+  createMockAdapter({
+    name: "db",
+    health: () => createHealthyHealth(),
+    configure: () => {},
+  }),
+);
+
+await registry.configure("db", { poolSize: 10 }); // throws if the adapter has no configure()
+const report = await registry.healthAll({ timeout: 2_000 });
+report.status; // worst of the per-adapter statuses: "healthy" | "degraded" | "unhealthy"
+report.adapters.db; // AdapterHealth; throwing, timed-out or aborted checks are "unhealthy"
+```
+
+Adapters without `health()` are left out of `report.adapters`.
+
+`healthAll({ retry: { attempts, delay } })` re-runs a check that reports
+`unhealthy`, up to `attempts` tries in total, pausing `delay` ms between
+them; `timeout` bounds each try and an aborted `signal` stops the retries.
+Adapter names are checked on `register()`: `__proto__`, `constructor` and
+`prototype` are refused, because a report keyed by adapter name cannot hold
+them.
 
 ## Transport contracts
 

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

@@ -0,0 +1,31 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Health aggregation and configuration for registered adapters.
+ *
+ * `LifecycleAdapter.health()` and `configure()` were part of the contract
+ * with nothing in the package that called them. `AdapterRegistry.healthAll()`
+ * and `AdapterRegistry.configure()` delegate here.
+ */
+import type { Adapter } from "./adapter.type.js";
+import type { AdapterHealth, AdapterHealthStatus, AdapterOperationOptions } from "../lifecycle/lifecycle.type.js";
+/** Aggregated health of every adapter that implements `health()`. */
+export interface AdapterHealthReport {
+    /** The worst status across `adapters`; `"healthy"` when none report. */
+    readonly status: AdapterHealthStatus;
+    /** Per-adapter health, keyed by normalized adapter name. */
+    readonly adapters: Readonly<Record<string, AdapterHealth>>;
+}
+/**
+ * Collects health from every adapter that implements `health()`. A check that
+ * throws, rejects, times out or is aborted is reported as `"unhealthy"`
+ * instead of failing the whole report.
+ */
+export declare function collectAdapterHealth(entries: ReadonlyArray<readonly [string, Adapter]>, options?: AdapterOperationOptions): Promise<AdapterHealthReport>;
+/**
+ * Passes options to an adapter's `configure()` hook.
+ *
+ * @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

@@ -0,0 +1,94 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Health aggregation and configuration for registered adapters.
+ *
+ * `LifecycleAdapter.health()` and `configure()` were part of the contract
+ * with nothing in the package that called them. `AdapterRegistry.healthAll()`
+ * and `AdapterRegistry.configure()` delegate here.
+ */
+import { AdapterConfigurationError } from "@zudojs/errors";
+import { withRetry } from "./adapter.retry.js";
+const RANK = {
+    healthy: 0,
+    degraded: 1,
+    unhealthy: 2,
+};
+function unhealthy(message) {
+    return { status: "unhealthy", message, timestamp: Date.now() };
+}
+/**
+ * Runs one health check, bounded by `timeout` and `signal`, retried according
+ * to `retry`.
+ */
+async function checkOne(adapter, options) {
+    return withRetry(() => attemptCheck(adapter, options), (health) => health.status !== "unhealthy", options);
+}
+/** Runs a single health-check attempt, bounded by `timeout` and `signal`. */
+async function attemptCheck(adapter, options) {
+    if (options.signal?.aborted)
+        return unhealthy("Health check aborted.");
+    let timer;
+    let onAbort;
+    const guards = [];
+    if (options.timeout !== undefined) {
+        guards.push(new Promise((resolve) => {
+            timer = setTimeout(() => resolve(unhealthy(`Health check timed out after ${options.timeout} ms.`)), options.timeout);
+        }));
+    }
+    if (options.signal) {
+        const signal = options.signal;
+        guards.push(new Promise((resolve) => {
+            onAbort = () => resolve(unhealthy("Health check aborted."));
+            signal.addEventListener("abort", onAbort, { once: true });
+        }));
+    }
+    try {
+        const check = Promise.resolve()
+            .then(() => adapter.health?.())
+            .catch((error) => unhealthy(error instanceof Error ? error.message : String(error)));
+        return await Promise.race([check, ...guards]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort)
+            options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+/**
+ * Collects health from every adapter that implements `health()`. A check that
+ * throws, rejects, times out or is aborted is reported as `"unhealthy"`
+ * instead of failing the whole report.
+ */
+export async function collectAdapterHealth(entries, options = {}) {
+    // `Object.create(null)`, not `{}`: assigning `adapters["__proto__"]` on an
+    // 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);
+    }));
+    let status = "healthy";
+    for (const health of Object.values(adapters)) {
+        const rank = RANK[health.status] ?? RANK.unhealthy;
+        if (rank > RANK[status])
+            status = rank === RANK.unhealthy ? "unhealthy" : health.status;
+    }
+    return Object.freeze({ status, adapters: Object.freeze(adapters) });
+}
+/**
+ * Passes options to an adapter's `configure()` hook.
+ *
+ * @throws {AdapterConfigurationError} If the adapter has no `configure()` hook.
+ */
+export async function configureAdapter(name, adapter, options) {
+    const configurable = adapter;
+    if (typeof configurable.configure !== "function") {
+        throw new AdapterConfigurationError(name, new Error(`Adapter "${name}" does not implement configure().`));
+    }
+    await configurable.configure(options);
+}
+//# sourceMappingURL=adapter.health.js.map

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

@@ -13,6 +13,8 @@
  */
 import type { Adapter } from "./adapter.type.js";
 import type { AdapterCapabilities } 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;
 /**
@@ -28,6 +30,10 @@ export declare class AdapterRegistry {
      * @throws {AdapterConfigurationError} If the adapter name is blank. A name
      * that normalizes to the empty string is unaddressable — `get("")` is the
      * only way back to it, and every other blank name collides with it.
+     * @throws {AdapterConfigurationError} If the adapter name is a prototype
+     * member (`__proto__`, `constructor`, `prototype`). Those names survive the
+     * registry's `Map`, but any consumer keying a plain object by adapter name
+     * loses or corrupts the entry, so they are refused at the door.
      * @throws {AdapterAlreadyRegisteredError} If an adapter with the same name is already registered.
      */
     register(adapter: Adapter): void;
@@ -113,6 +119,19 @@ export declare class AdapterRegistry {
      * @throws {AggregateError} After attempting all adapters, if any failed.
      */
     stopAll(): Promise<void>;
+    /**
+     * Checks the health of every adapter that implements `health()`. Failures,
+     * timeouts (`options.timeout`) and aborts (`options.signal`) are reported
+     * as `"unhealthy"` entries rather than thrown.
+     */
+    healthAll(options?: AdapterOperationOptions): Promise<AdapterHealthReport>;
+    /**
+     * Passes options to one adapter's `configure()` hook.
+     *
+     * @throws {AdapterNotFoundError} If no adapter with the name is registered.
+     * @throws {AdapterConfigurationError} If the adapter has no `configure()`.
+     */
+    configure(name: string, options: unknown): Promise<void>;
     /**
      * Returns the number of registered adapters.
      */

package/dist/adapter/adapter.registry.js

@@ -12,6 +12,13 @@
  * `removeAndDispose()` / `disposeAll()` to also release adapter resources.
  */
 import { AdapterAlreadyRegisteredError, AdapterCapabilityMissingError, AdapterConfigurationError, AdapterNotFoundError, } from "@zudojs/errors";
+import { collectAdapterHealth, configureAdapter } from "./adapter.health.js";
+/** Names that are unsafe as a plain-object key, so no adapter may claim them. */
+const RESERVED_NAMES = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
 /**
  * Registry for Zudojs adapters.
  *
@@ -25,6 +32,10 @@ export class AdapterRegistry {
      * @throws {AdapterConfigurationError} If the adapter name is blank. A name
      * that normalizes to the empty string is unaddressable — `get("")` is the
      * only way back to it, and every other blank name collides with it.
+     * @throws {AdapterConfigurationError} If the adapter name is a prototype
+     * member (`__proto__`, `constructor`, `prototype`). Those names survive the
+     * registry's `Map`, but any consumer keying a plain object by adapter name
+     * loses or corrupts the entry, so they are refused at the door.
      * @throws {AdapterAlreadyRegisteredError} If an adapter with the same name is already registered.
      */
     register(adapter) {
@@ -32,6 +43,9 @@ export class AdapterRegistry {
         if (name === "") {
             throw new AdapterConfigurationError(String(adapter.name), new Error("Adapter name cannot be blank."));
         }
+        if (RESERVED_NAMES.has(name)) {
+            throw new AdapterConfigurationError(String(adapter.name), new Error(`Adapter name "${name}" is reserved.`));
+        }
         if (this.adapters.has(name)) {
             throw new AdapterAlreadyRegisteredError(name);
         }
@@ -160,6 +174,23 @@ export class AdapterRegistry {
     async stopAll() {
         await this.forEachAdapter((adapter) => adapter.stop?.(), "One or more adapters failed to stop.");
     }
+    /**
+     * Checks the health of every adapter that implements `health()`. Failures,
+     * timeouts (`options.timeout`) and aborts (`options.signal`) are reported
+     * as `"unhealthy"` entries rather than thrown.
+     */
+    async healthAll(options) {
+        return collectAdapterHealth([...this.adapters.entries()], options);
+    }
+    /**
+     * Passes options to one adapter's `configure()` hook.
+     *
+     * @throws {AdapterNotFoundError} If no adapter with the name is registered.
+     * @throws {AdapterConfigurationError} If the adapter has no `configure()`.
+     */
+    async configure(name, options) {
+        await configureAdapter(this.normalizeName(name), this.require(name), options);
+    }
     /**
      * Returns the number of registered adapters.
      */

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

@@ -0,0 +1,35 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Retry support for adapter operations.
+ *
+ * `AdapterOperationOptions.retry` was part of the contract with nothing that
+ * read it, so a caller asking for three attempts silently got one.
+ */
+import type { AdapterOperationOptions } from "../lifecycle/lifecycle.type.js";
+/**
+ * Total attempts requested, clamped to at least one.
+ *
+ * A missing, non-finite, fractional or non-positive `attempts` means a single
+ * attempt: a retry policy nobody can express as "run fewer than once".
+ */
+export declare function retryAttempts(options: AdapterOperationOptions): number;
+/** Delay between attempts in milliseconds; negative and non-finite mean none. */
+export declare function retryDelay(options: AdapterOperationOptions): number;
+/** Waits `ms`, resolving early when `signal` aborts so a retry cannot outlive it. */
+export declare function wait(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Runs `attempt` until `accept` approves its result or the attempt budget from
+ * `options.retry` is spent, returning the last result either way.
+ *
+ * An aborted signal stops further attempts immediately — the caller has already
+ * said it no longer wants the answer.
+ *
+ * @typeParam T - The attempt's result type.
+ * @param attempt - The operation to run; it must not throw.
+ * @param accept - Whether a result is final.
+ * @param options - Operation options carrying the retry policy.
+ * @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

@@ -0,0 +1,74 @@
+/**
+ * @zudojs/adapters/adapter
+ *
+ * Retry support for adapter operations.
+ *
+ * `AdapterOperationOptions.retry` was part of the contract with nothing that
+ * read it, so a caller asking for three attempts silently got one.
+ */
+/**
+ * Total attempts requested, clamped to at least one.
+ *
+ * A missing, non-finite, fractional or non-positive `attempts` means a single
+ * attempt: a retry policy nobody can express as "run fewer than once".
+ */
+export function retryAttempts(options) {
+    const attempts = options.retry?.attempts;
+    if (typeof attempts !== "number" || !Number.isFinite(attempts))
+        return 1;
+    return Math.max(1, Math.floor(attempts));
+}
+/** Delay between attempts in milliseconds; negative and non-finite mean none. */
+export function retryDelay(options) {
+    const delay = options.retry?.delay;
+    if (typeof delay !== "number" || !Number.isFinite(delay))
+        return 0;
+    return Math.max(0, delay);
+}
+/** Waits `ms`, resolving early when `signal` aborts so a retry cannot outlive it. */
+export function wait(ms, signal) {
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener("abort", finish, { once: true });
+        // A signal that aborted before the listener was attached never fires it.
+        if (signal?.aborted === true)
+            finish();
+    });
+}
+/**
+ * Runs `attempt` until `accept` approves its result or the attempt budget from
+ * `options.retry` is spent, returning the last result either way.
+ *
+ * An aborted signal stops further attempts immediately — the caller has already
+ * said it no longer wants the answer.
+ *
+ * @typeParam T - The attempt's result type.
+ * @param attempt - The operation to run; it must not throw.
+ * @param accept - Whether a result is final.
+ * @param options - Operation options carrying the retry policy.
+ * @returns The first accepted result, or the last one produced.
+ */
+export async function withRetry(attempt, accept, options) {
+    const attempts = retryAttempts(options);
+    const delay = retryDelay(options);
+    const aborted = () => options.signal?.aborted === true;
+    let result = await attempt();
+    for (let remaining = attempts - 1; remaining > 0; remaining--) {
+        if (accept(result))
+            return result;
+        if (aborted())
+            return result;
+        if (delay > 0)
+            await wait(delay, options.signal);
+        if (aborted())
+            return result;
+        result = await attempt();
+    }
+    return result;
+}
+//# sourceMappingURL=adapter.retry.js.map

package/dist/adapter/index.d.ts

@@ -6,4 +6,6 @@
 export type { Adapter } from "./adapter.type.js";
 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

package/dist/adapter/index.js

@@ -4,4 +4,5 @@
  * Core adapter types and registry.
  */
 export { AdapterRegistry } from "./adapter.registry.js";
+export { collectAdapterHealth, configureAdapter } from "./adapter.health.js";
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -18,6 +18,7 @@
 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 type { AdapterMetadata } from "./metadata/index.js";
 export type { AdapterHealthStatus, AdapterHealth, AdapterOperationOptions, LifecycleAdapter, } from "./lifecycle/index.js";

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

@@ -25,7 +25,14 @@ export interface AdapterOperationOptions {
     readonly signal?: AbortSignal;
     /** Timeout in milliseconds. */
     readonly timeout?: number;
-    /** Retry configuration. */
+    /**
+     * Retry configuration.
+     *
+     * `attempts` is the total number of tries, not the number of extra ones:
+     * `1` (or anything below it) runs the operation once. `delay` is the pause
+     * in milliseconds between tries, ended early by `signal`. A health check is
+     * retried only while it reports `"unhealthy"`; `timeout` bounds each try.
+     */
     readonly retry?: {
         readonly attempts: number;
         readonly delay?: number;

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

@@ -5,13 +5,17 @@
  */
 import type { Adapter } from "../adapter/adapter.type.js";
 import { AdapterRegistry } from "../adapter/adapter.registry.js";
-import type { AdapterHealth } from "../lifecycle/lifecycle.type.js";
+import type { AdapterHealth, LifecycleAdapter } from "../lifecycle/lifecycle.type.js";
 /**
  * Creates a minimal mock adapter for testing.
+ *
+ * Accepts the `LifecycleAdapter` hooks too: `health` and `configure` are
+ * forwarded when given, so the result can be exercised with
+ * `AdapterRegistry.healthAll()` and `configure()`.
  */
-export declare function createMockAdapter(overrides?: Partial<Adapter> & {
+export declare function createMockAdapter(overrides?: Partial<LifecycleAdapter> & {
     name: string;
-}): Adapter;
+}): LifecycleAdapter;
 /**
  * Creates a mock adapter registry pre-populated with adapters.
  */

package/dist/testing/adapterTesting.helper.js

@@ -6,6 +6,10 @@
 import { AdapterRegistry } from "../adapter/adapter.registry.js";
 /**
  * Creates a minimal mock adapter for testing.
+ *
+ * Accepts the `LifecycleAdapter` hooks too: `health` and `configure` are
+ * forwarded when given, so the result can be exercised with
+ * `AdapterRegistry.healthAll()` and `configure()`.
  */
 export function createMockAdapter(overrides = { name: "mock" }) {
     const capabilities = {
@@ -31,6 +35,8 @@ export function createMockAdapter(overrides = { name: "mock" }) {
         start: overrides.start,
         stop: overrides.stop,
         dispose: overrides.dispose,
+        ...(overrides.health ? { health: overrides.health } : {}),
+        ...(overrides.configure ? { configure: overrides.configure } : {}),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/adapters",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Boundary layer between Zudojs and external platforms — adapter contracts, registry, capabilities, and transport abstractions.",
   "license": "MIT",
   "author": {
@@ -27,10 +27,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1",
-    "@zudojs/types": "1.0.0",
-    "@zudojs/lifecycle": "1.1.0"
+    "@zudojs/errors": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",