@zudojs/adapters 1.0.0 → 1.1.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,23 @@ 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`.
 
 ## 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,83 @@
+/**
+ * @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";
+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`. */
+async function checkOne(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 = {}) {
+    const adapters = {};
+    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;
 /**
@@ -113,6 +115,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.
      */
@@ -130,6 +145,17 @@ export declare class AdapterRegistry {
      * @throws {AggregateError} After attempting all adapters, if any 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

package/dist/adapter/adapter.registry.js

@@ -12,6 +12,7 @@
  * `removeAndDispose()` / `disposeAll()` to also release adapter resources.
  */
 import { AdapterAlreadyRegisteredError, AdapterCapabilityMissingError, AdapterConfigurationError, AdapterNotFoundError, } from "@zudojs/errors";
+import { collectAdapterHealth, configureAdapter } from "./adapter.health.js";
 /**
  * Registry for Zudojs adapters.
  *
@@ -85,8 +86,7 @@ export class AdapterRegistry {
             return false;
         }
         this.adapters.delete(key);
-        await adapter.stop?.();
-        await adapter.dispose?.();
+        await this.teardown(adapter);
         return true;
     }
     /**
@@ -161,6 +161,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.
      */
@@ -187,8 +204,7 @@ export class AdapterRegistry {
         const failures = [];
         for (const adapter of adapters) {
             try {
-                await adapter.stop?.();
-                await adapter.dispose?.();
+                await this.teardown(adapter);
             }
             catch (error) {
                 failures.push(error);
@@ -198,6 +214,38 @@ 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

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/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,8 +1,12 @@
 {
   "name": "@zudojs/adapters",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Boundary layer between Zudojs and external platforms — adapter contracts, registry, capabilities, and transport abstractions.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,10 +27,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0",
-    "@zudojs/types": "1.0.0",
-    "@zudojs/lifecycle": "1.0.0"
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",