@zudojs/adapters 0.1.1 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,26 +11,113 @@ npm install @zudojs/adapters
 ## Quick Start
 
 ```typescript
-import { createAdapterRegistry } from "@zudojs/adapters";
+import { AdapterRegistry } from "@zudojs/adapters";
+import type { Adapter } from "@zudojs/adapters";
 
-const registry = createAdapterRegistry();
+const registry = new AdapterRegistry();
 
-registry.register({
+const postgres: Adapter = {
   name: "postgres",
-  capabilities: ["query", "transaction"],
-  connect: async () => {
-    /* ... */
+  version: "1.0.0",
+  // Capabilities are a declaration object, not a list of method names.
+  capabilities: { longRunning: true, gracefulShutdown: true },
+  initialize: async () => {
+    /* open the pool */
   },
-});
+  dispose: async () => {
+    /* close the pool */
+  },
+};
+
+registry.register(postgres);
+
+registry.get("postgres"); // Adapter | undefined
+registry.require("postgres"); // throws AdapterNotFoundError when absent
+```
+
+Names are case-insensitive: they are trimmed and lowercased for registration
+and lookup, and `getNames()` reports them in that form. A name that is blank
+after trimming is rejected with `AdapterConfigurationError` — it could never
+be looked up again. Registering the same name twice throws
+`AdapterAlreadyRegisteredError`.
+
+## Lifecycle
+
+An adapter may implement `initialize()`, `start()`, `stop()` and `dispose()`.
+The registry drives them across everything it holds:
+
+```typescript
+await registry.initializeAll(); // prepare resources
+await registry.startAll(); // begin processing
+await registry.stopAll(); // stop processing, stay registered
+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.
+
+`remove()` and `clear()` only drop references; `removeAndDispose()` and
+`disposeAll()` also release resources.
+
+## Capabilities
+
+Adapters declare what they support so runtime code can pick one that can do
+the job:
+
+```typescript
+registry.findByCapability("http"); // every adapter declaring http
+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`.
+
+## Health
+
+```typescript
+import {
+  createHealthyHealth,
+  createDegradedHealth,
+  createUnhealthyHealth,
+} from "@zudojs/adapters";
+
+const health = createDegradedHealth("replica lag above threshold");
+```
+
+A `LifecycleAdapter` adds optional `configure(options)` and `health()` to the
+base contract.
+
+## Transport contracts
+
+Type-only interfaces that extend `Adapter` for each transport:
+`HTTPAdapter`, `HTTPServerAdapter`, `MessageAdapter`, `StorageAdapter`,
+`QueueAdapter`, `RuntimeAdapter`, `WebSocketAdapter`, `CLIAdapter`,
+`SchedulerAdapter`.
+
+## Testing utilities
+
+```typescript
+import {
+  createMockAdapter,
+  createMockAdapterRegistry,
+  createMockHealth,
+} from "@zudojs/adapters";
+
+const { registry } = createMockAdapterRegistry([
+  createMockAdapter({ name: "fake-http", capabilities: { http: true } }),
+]);
 ```
 
-## Features
+## Errors
 
-- Adapter contracts and interfaces
-- Adapter registry for discovery
-- Capability-based selection
-- Transport abstractions
-- Health check integration
+Re-exported from `@zudojs/errors`: `AdapterError` · `AdapterNotFoundError` ·
+`AdapterAlreadyRegisteredError` · `AdapterNotSupportedError` ·
+`AdapterCapabilityMissingError` · `AdapterConnectionError` ·
+`AdapterOperationError` · `AdapterTimeoutError` · `AdapterDisposeError` ·
+`AdapterInitializationError` · `AdapterConfigurationError`.
 
 ## Use Cases
 

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

@@ -1,9 +1,20 @@
 /**
  * @zudojs/adapters/adapter
  *
- * Adapter registry — manages adapter registration, lookup, and lifecycle.
+ * Adapter registry — manages adapter registration and lookup.
+ *
+ * Adapter names are case-insensitive: they are trimmed and lowercased on
+ * registration and lookup, and `getNames()` reports them in that normalized
+ * form. The adapter object itself is stored untouched, so `getAll()` still
+ * reports whatever `adapter.name` it was built with.
+ *
+ * Note that `remove()` and `clear()` only drop references — use
+ * `removeAndDispose()` / `disposeAll()` to also release adapter resources.
  */
 import type { Adapter } from "./adapter.type.js";
+import type { AdapterCapabilities } from "../capabilities/capabilities.type.js";
+/** A capability an adapter can declare. */
+export type AdapterCapabilityName = keyof AdapterCapabilities;
 /**
  * Registry for Zudojs adapters.
  *
@@ -14,6 +25,9 @@ export declare class AdapterRegistry {
     /**
      * Registers an adapter.
      *
+     * @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 {AdapterAlreadyRegisteredError} If an adapter with the same name is already registered.
      */
     register(adapter: Adapter): void;
@@ -21,32 +35,118 @@ export declare class AdapterRegistry {
      * Returns an adapter by name.
      */
     get<T extends Adapter>(name: string): T | undefined;
+    /**
+     * Returns an adapter by name or throws.
+     *
+     * @throws {AdapterNotFoundError} If no adapter with the name is registered.
+     */
+    require<T extends Adapter>(name: string): T;
     /**
      * Returns whether an adapter is registered.
      */
     has(name: string): boolean;
     /**
-     * Removes an adapter by name.
+     * Removes an adapter by name without disposing it.
+     *
+     * The caller keeps responsibility for the adapter's resources —
+     * use {@link removeAndDispose} to also stop and dispose it.
      *
      * @returns True if the adapter was removed, false if it was not registered.
      */
     remove(name: string): boolean;
+    /**
+     * Removes an adapter by name and releases its resources
+     * (calls `stop()` then `dispose()` when defined).
+     *
+     * @returns True if the adapter was removed, false if it was not registered.
+     */
+    removeAndDispose(name: string): Promise<boolean>;
     /**
      * Returns all registered adapters.
      */
     getAll(): readonly Adapter[];
     /**
-     * Returns all registered adapter names.
+     * Returns all registered adapter names (normalized: trimmed, lowercase).
      */
     getNames(): readonly string[];
+    /**
+     * Returns every adapter that declares the given capability.
+     *
+     * Capabilities exist so runtime code can pick an adapter that can actually
+     * do the job; without a way to ask, every declaration was inert.
+     */
+    findByCapability(capability: AdapterCapabilityName): readonly Adapter[];
+    /**
+     * Returns whether a registered adapter declares a capability.
+     *
+     * A missing adapter reports `false` rather than throwing — use
+     * {@link requireCapability} when the absence should stop the caller.
+     */
+    supports(name: string, capability: AdapterCapabilityName): boolean;
+    /**
+     * Returns an adapter that declares the given capability, or throws.
+     *
+     * @throws {AdapterNotFoundError} If no adapter with the name is registered.
+     * @throws {AdapterCapabilityMissingError} If the adapter does not declare
+     * the capability.
+     */
+    requireCapability<T extends Adapter>(name: string, capability: AdapterCapabilityName): T;
+    /**
+     * Initializes every registered adapter, in registration order.
+     *
+     * The counterpart to {@link disposeAll}: `initialize()` and `start()` were
+     * 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.
+     *
+     * @throws {AggregateError} After attempting all adapters, if any failed.
+     */
+    initializeAll(): Promise<void>;
+    /**
+     * Starts every registered adapter, in registration order.
+     *
+     * @throws {AggregateError} After attempting all adapters, if any failed.
+     */
+    startAll(): Promise<void>;
+    /**
+     * Stops every registered adapter without disposing or unregistering them.
+     *
+     * @throws {AggregateError} After attempting all adapters, if any failed.
+     */
+    stopAll(): Promise<void>;
     /**
      * Returns the number of registered adapters.
      */
     get size(): number;
     /**
-     * Clears all registered adapters.
+     * Clears all registered adapters without disposing them.
+     *
+     * Use {@link disposeAll} to also release adapter resources.
      */
     clear(): void;
+    /**
+     * Clears the registry and releases every adapter's resources
+     * (calls `stop()` then `dispose()` when defined, best-effort).
+     *
+     * @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
+     * resources in a state nobody tracked.
+     */
+    private forEachAdapter;
     private normalizeName;
 }
 //# sourceMappingURL=adapter.registry.d.ts.map

package/dist/adapter/adapter.registry.js

@@ -1,9 +1,17 @@
 /**
  * @zudojs/adapters/adapter
  *
- * Adapter registry — manages adapter registration, lookup, and lifecycle.
+ * Adapter registry — manages adapter registration and lookup.
+ *
+ * Adapter names are case-insensitive: they are trimmed and lowercased on
+ * registration and lookup, and `getNames()` reports them in that normalized
+ * form. The adapter object itself is stored untouched, so `getAll()` still
+ * reports whatever `adapter.name` it was built with.
+ *
+ * Note that `remove()` and `clear()` only drop references — use
+ * `removeAndDispose()` / `disposeAll()` to also release adapter resources.
  */
-import { AdapterAlreadyRegisteredError, AdapterNotFoundError, } from "@zudojs/errors";
+import { AdapterAlreadyRegisteredError, AdapterCapabilityMissingError, AdapterConfigurationError, AdapterNotFoundError, } from "@zudojs/errors";
 /**
  * Registry for Zudojs adapters.
  *
@@ -14,10 +22,16 @@ export class AdapterRegistry {
     /**
      * Registers an adapter.
      *
+     * @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 {AdapterAlreadyRegisteredError} If an adapter with the same name is already registered.
      */
     register(adapter) {
         const name = this.normalizeName(adapter.name);
+        if (name === "") {
+            throw new AdapterConfigurationError(String(adapter.name), new Error("Adapter name cannot be blank."));
+        }
         if (this.adapters.has(name)) {
             throw new AdapterAlreadyRegisteredError(name);
         }
@@ -29,6 +43,18 @@ export class AdapterRegistry {
     get(name) {
         return this.adapters.get(this.normalizeName(name));
     }
+    /**
+     * Returns an adapter by name or throws.
+     *
+     * @throws {AdapterNotFoundError} If no adapter with the name is registered.
+     */
+    require(name) {
+        const adapter = this.get(name);
+        if (adapter === undefined) {
+            throw new AdapterNotFoundError(this.normalizeName(name));
+        }
+        return adapter;
+    }
     /**
      * Returns whether an adapter is registered.
      */
@@ -36,13 +62,32 @@ export class AdapterRegistry {
         return this.adapters.has(this.normalizeName(name));
     }
     /**
-     * Removes an adapter by name.
+     * Removes an adapter by name without disposing it.
+     *
+     * The caller keeps responsibility for the adapter's resources —
+     * use {@link removeAndDispose} to also stop and dispose it.
      *
      * @returns True if the adapter was removed, false if it was not registered.
      */
     remove(name) {
         return this.adapters.delete(this.normalizeName(name));
     }
+    /**
+     * Removes an adapter by name and releases its resources
+     * (calls `stop()` then `dispose()` when defined).
+     *
+     * @returns True if the adapter was removed, false if it was not registered.
+     */
+    async removeAndDispose(name) {
+        const key = this.normalizeName(name);
+        const adapter = this.adapters.get(key);
+        if (adapter === undefined) {
+            return false;
+        }
+        this.adapters.delete(key);
+        await this.teardown(adapter);
+        return true;
+    }
     /**
      * Returns all registered adapters.
      */
@@ -50,11 +95,71 @@ export class AdapterRegistry {
         return Object.freeze([...this.adapters.values()]);
     }
     /**
-     * Returns all registered adapter names.
+     * Returns all registered adapter names (normalized: trimmed, lowercase).
      */
     getNames() {
         return Object.freeze([...this.adapters.keys()]);
     }
+    /**
+     * Returns every adapter that declares the given capability.
+     *
+     * Capabilities exist so runtime code can pick an adapter that can actually
+     * do the job; without a way to ask, every declaration was inert.
+     */
+    findByCapability(capability) {
+        return Object.freeze([...this.adapters.values()].filter((adapter) => adapter.capabilities[capability] === true));
+    }
+    /**
+     * Returns whether a registered adapter declares a capability.
+     *
+     * A missing adapter reports `false` rather than throwing — use
+     * {@link requireCapability} when the absence should stop the caller.
+     */
+    supports(name, capability) {
+        return this.get(name)?.capabilities[capability] === true;
+    }
+    /**
+     * Returns an adapter that declares the given capability, or throws.
+     *
+     * @throws {AdapterNotFoundError} If no adapter with the name is registered.
+     * @throws {AdapterCapabilityMissingError} If the adapter does not declare
+     * the capability.
+     */
+    requireCapability(name, capability) {
+        const adapter = this.require(name);
+        if (adapter.capabilities[capability] !== true) {
+            throw new AdapterCapabilityMissingError(this.normalizeName(name), capability);
+        }
+        return adapter;
+    }
+    /**
+     * Initializes every registered adapter, in registration order.
+     *
+     * The counterpart to {@link disposeAll}: `initialize()` and `start()` were
+     * 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.
+     *
+     * @throws {AggregateError} After attempting all adapters, if any failed.
+     */
+    async initializeAll() {
+        await this.forEachAdapter((adapter) => adapter.initialize?.(), "One or more adapters failed to initialize.");
+    }
+    /**
+     * Starts every registered adapter, in registration order.
+     *
+     * @throws {AggregateError} After attempting all adapters, if any failed.
+     */
+    async startAll() {
+        await this.forEachAdapter((adapter) => adapter.start?.(), "One or more adapters failed to start.");
+    }
+    /**
+     * Stops every registered adapter without disposing or unregistering them.
+     *
+     * @throws {AggregateError} After attempting all adapters, if any failed.
+     */
+    async stopAll() {
+        await this.forEachAdapter((adapter) => adapter.stop?.(), "One or more adapters failed to stop.");
+    }
     /**
      * Returns the number of registered adapters.
      */
@@ -62,11 +167,86 @@ export class AdapterRegistry {
         return this.adapters.size;
     }
     /**
-     * Clears all registered adapters.
+     * Clears all registered adapters without disposing them.
+     *
+     * Use {@link disposeAll} to also release adapter resources.
      */
     clear() {
         this.adapters.clear();
     }
+    /**
+     * Clears the registry and releases every adapter's resources
+     * (calls `stop()` then `dispose()` when defined, best-effort).
+     *
+     * @throws {AggregateError} After attempting all adapters, if any failed.
+     */
+    async disposeAll() {
+        const adapters = [...this.adapters.values()];
+        this.adapters.clear();
+        const failures = [];
+        for (const adapter of adapters) {
+            try {
+                await this.teardown(adapter);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0) {
+            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();
     }

package/dist/adapter/index.d.ts

@@ -5,4 +5,5 @@
  */
 export type { Adapter } from "./adapter.type.js";
 export { AdapterRegistry } from "./adapter.registry.js";
+export type { AdapterCapabilityName } from "./adapter.registry.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -17,6 +17,7 @@
  */
 export type { Adapter } from "./adapter/index.js";
 export { AdapterRegistry } from "./adapter/index.js";
+export type { AdapterCapabilityName } 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/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/adapters",
-  "version": "0.1.1",
+  "version": "1.0.1",
   "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",
@@ -14,26 +18,22 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "engines": {
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/types": "0.1.0",
-    "@zudojs/lifecycle": "0.1.0"
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/constants": "1.0.1",
+    "@zudojs/types": "1.0.0",
+    "@zudojs/lifecycle": "1.1.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "publishConfig": {
@@ -47,8 +47,19 @@
     "integration"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/adapters"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}