@zudojs/adapters 1.1.0 → 1.2.0

package/README.md

@@ -97,11 +97,19 @@ A `LifecycleAdapter` adds optional `configure(options)` and `health()` to the
 base contract. The registry calls them:
 
 ```typescript
-import { AdapterRegistry, createHealthyHealth, createMockAdapter } from "@zudojs/adapters";
+import {
+  AdapterRegistry,
+  createHealthyHealth,
+  createMockAdapter,
+} from "@zudojs/adapters";
 
 const registry = new AdapterRegistry();
 registry.register(
-  createMockAdapter({ name: "db", health: () => createHealthyHealth(), configure: () => {} }),
+  createMockAdapter({
+    name: "db",
+    health: () => createHealthyHealth(),
+    configure: () => {},
+  }),
 );
 
 await registry.configure("db", { poolSize: 10 }); // throws if the adapter has no configure()
@@ -112,6 +120,13 @@ report.adapters.db; // AdapterHealth; throwing, timed-out or aborted checks are
 
 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
 
 Type-only interfaces that extend `Adapter` for each transport:

package/dist/adapter/adapter.health.js

@@ -8,6 +8,7 @@
  * and `AdapterRegistry.configure()` delegate here.
  */
 import { AdapterConfigurationError } from "@zudojs/errors";
+import { withRetry } from "./adapter.retry.js";
 const RANK = {
     healthy: 0,
     degraded: 1,
@@ -16,8 +17,15 @@ const RANK = {
 function unhealthy(message) {
     return { status: "unhealthy", message, timestamp: Date.now() };
 }
-/** Runs one health check, bounded by `timeout` and `signal`. */
+/**
+ * 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;
@@ -54,7 +62,10 @@ async function checkOne(adapter, options) {
  * instead of failing the whole report.
  */
 export async function collectAdapterHealth(entries, options = {}) {
-    const adapters = {};
+    // `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]) => {

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

@@ -30,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;

package/dist/adapter/adapter.registry.js

@@ -13,6 +13,12 @@
  */
 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.
  *
@@ -26,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) {
@@ -33,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);
         }

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/adapters",
-  "version": "1.1.0",
+  "version": "1.2.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.1.0"
+    "@zudojs/errors": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",