@procedures/client 0.0.0-stage → 0.2.0

package/dist/events/types.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Event Bus Types
+ *
+ * Central pub/sub system for streaming coordination.
+ * Enables procedures to subscribe to events and emit updates.
+ */
+/**
+ * Event payload with channel and data.
+ */
+export interface Event<T = unknown> {
+    /** Channel the event was emitted on */
+    channel: string;
+    /** Event data */
+    data: T;
+    /** Timestamp when event was emitted */
+    timestamp: number;
+}
+/**
+ * Event handler function.
+ */
+export type EventHandler<T = unknown> = (data: T) => void | Promise<void>;
+/**
+ * Unsubscribe function returned from subscriptions.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Central event bus for pub/sub messaging.
+ *
+ * Features:
+ * - Type-safe channels (optional via generics)
+ * - Multiple subscribers per channel
+ * - Async iteration support via stream()
+ * - One-time subscriptions via once()
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to events
+ * const unsubscribe = bus.on("user:updated", (user) => {
+ *   console.log("User updated:", user);
+ * });
+ *
+ * // Emit events
+ * bus.emit("user:updated", { id: "123", name: "John" });
+ *
+ * // Unsubscribe
+ * unsubscribe();
+ *
+ * // One-time subscription
+ * const user = await bus.once("user:created");
+ *
+ * // Streaming iteration
+ * for await (const update of bus.stream("updates")) {
+ *   console.log("Update:", update);
+ * }
+ * ```
+ */
+export interface EventBus {
+    /**
+     * Emit an event on a channel.
+     *
+     * @param channel - Channel to emit on
+     * @param data - Event data
+     */
+    emit<T>(channel: string, data: T): void;
+    /**
+     * Subscribe to events on a channel.
+     *
+     * @param channel - Channel to subscribe to
+     * @param handler - Handler function called for each event
+     * @returns Unsubscribe function
+     */
+    on<T>(channel: string, handler: EventHandler<T>): Unsubscribe;
+    /**
+     * Subscribe to a single event on a channel.
+     * Returns a promise that resolves with the first event.
+     *
+     * @param channel - Channel to wait for
+     * @param options - A signal: when it aborts first, the promise rejects with an `AbortError`
+     * @returns Promise resolving to the event data
+     */
+    once<T>(channel: string, options?: EventWaitOptions): Promise<T>;
+    /**
+     * Create an async iterable for a channel.
+     * Yields events as they arrive until the reader stops, the signal aborts, or `clear()`.
+     *
+     * @param channel - Channel to stream
+     * @param options - A signal: when it aborts, the stream ends
+     * @returns AsyncIterable of event data
+     */
+    stream<T>(channel: string, options?: EventWaitOptions): AsyncIterable<T>;
+    /**
+     * Get the number of subscribers on a channel.
+     *
+     * @param channel - Channel to check
+     * @returns Number of subscribers
+     */
+    subscriberCount(channel: string): number;
+    /**
+     * Check if a channel has any subscribers.
+     *
+     * @param channel - Channel to check
+     */
+    hasSubscribers(channel: string): boolean;
+    /**
+     * Get all active channel names.
+     */
+    channels(): string[];
+    /**
+     * Remove all subscribers from a channel.
+     *
+     * @param channel - Channel to clear
+     */
+    clear(channel: string): void;
+    /**
+     * Remove all subscribers from all channels.
+     */
+    clearAll(): void;
+}
+/**
+ * Channel type map for type-safe event buses.
+ * Define your channels and their data types here.
+ *
+ * @example
+ * ```typescript
+ * interface MyChannels {
+ *   "user:created": { id: string; name: string };
+ *   "user:updated": { id: string; changes: Partial<User> };
+ *   "order:placed": { orderId: string; total: number };
+ * }
+ *
+ * const bus = createTypedEventBus<MyChannels>();
+ *
+ * // Type-safe emissions and subscriptions
+ * bus.emit("user:created", { id: "123", name: "John" }); // ✓
+ * bus.emit("user:created", { invalid: true }); // Type error
+ *
+ * bus.on("order:placed", (order) => {
+ *   console.log(order.orderId); // ✓ typed as string
+ * });
+ * ```
+ */
+export interface ChannelMap {
+    [channel: string]: unknown;
+}
+/**
+ * Type-safe event bus with predefined channels.
+ */
+export interface TypedEventBus<TChannels extends ChannelMap> {
+    emit<K extends keyof TChannels & string>(channel: K, data: TChannels[K]): void;
+    on<K extends keyof TChannels & string>(channel: K, handler: EventHandler<TChannels[K]>): Unsubscribe;
+    once<K extends keyof TChannels & string>(channel: K, options?: EventWaitOptions): Promise<TChannels[K]>;
+    stream<K extends keyof TChannels & string>(channel: K, options?: EventWaitOptions): AsyncIterable<TChannels[K]>;
+    subscriberCount(channel: string): number;
+    hasSubscribers(channel: string): boolean;
+    channels(): string[];
+    clear(channel: string): void;
+    clearAll(): void;
+}
+/**
+ * Standard system channels.
+ */
+export interface SystemChannels {
+    /** Error events */
+    "system:error": {
+        error: Error;
+        context?: string;
+    };
+    /** Warning events */
+    "system:warning": {
+        message: string;
+        context?: string;
+    };
+    /** Debug events */
+    "system:debug": {
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * Procedure-related channels.
+ */
+export interface ProcedureChannels {
+    /** Procedure execution started */
+    "procedure:start": {
+        path: string[];
+        input: unknown;
+    };
+    /** Procedure execution completed */
+    "procedure:complete": {
+        path: string[];
+        output: unknown;
+        duration: number;
+    };
+    /** Procedure execution failed */
+    "procedure:error": {
+        path: string[];
+        error: Error;
+    };
+    /** Procedure yielded (streaming) */
+    "procedure:yield": {
+        path: string[];
+        value: unknown;
+        index: number;
+    };
+}
+/**
+ * Default channel map combining system and procedure channels.
+ */
+export interface DefaultChannels extends SystemChannels, ProcedureChannels {
+    [channel: string]: unknown;
+}
+/**
+ * Options for a wait on a channel: `once()` and `stream()`.
+ */
+export interface EventWaitOptions {
+    /** When this signal aborts, the wait ends */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Options for creating an event bus.
+ */
+export interface EventBusOptions {
+    /**
+     * Maximum number of events to buffer for late subscribers.
+     * Set to 0 to disable buffering.
+     * Default: 0 (no buffering)
+     */
+    bufferSize?: number;
+    /**
+     * Handler for uncaught errors in event handlers.
+     * Default: console.error
+     */
+    onError?: (error: Error, channel: string) => void;
+    /**
+     * Enable debug logging.
+     * Default: false
+     */
+    debug?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/events/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":"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"}

package/dist/events/types.js

@@ -0,0 +1,8 @@
+/**
+ * Event Bus Types
+ *
+ * Central pub/sub system for streaming coordination.
+ * Enables procedures to subscribe to events and emit updates.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/events/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/events/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Universal Client Library
+ *
+ * Protocol-agnostic RPC client with middleware composition
+ * and transport adapters.
+ *
+ * This entry point is for Node. It exports the browser-safe entry point
+ * ("@procedures/client/browser") and the server transports, which use `http` and `ws`.
+ */
+export * from "./browser.js";
+export { HttpServerTransport, defaultServerUrlStrategy, rpcServerUrlStrategy, } from "./server/index.js";
+export type { HttpServerTransportOptions, HttpUrlStrategy, } from "./server/index.js";
+export { WebSocketServerTransport } from "./server/index.js";
+export { checkBrowserRequest, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
+export type { BrowserGuardOptions, GuardedRequest, GuardResult } from "./server/browser-guard.js";
+export type { WebSocketServerTransportOptions, WebSocketAuthHandler, WebSocketConnectionHandler, WebSocketMessage, } from "./server/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,cAAc,CAAC;AAK7B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,0BAA0B,EAC1B,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC/G,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAClG,YAAY,EACV,+BAA+B,EAC/B,oBAAoB,EACpB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Universal Client Library
+ *
+ * Protocol-agnostic RPC client with middleware composition
+ * and transport adapters.
+ *
+ * This entry point is for Node. It exports the browser-safe entry point
+ * ("@procedures/client/browser") and the server transports, which use `http` and `ws`.
+ */
+export * from "./browser.js";
+// ============================================================================
+// Server Transports (Node only)
+// ============================================================================
+export { HttpServerTransport, defaultServerUrlStrategy, rpcServerUrlStrategy, } from "./server/index.js";
+export { WebSocketServerTransport } from "./server/index.js";
+export { checkBrowserRequest, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,cAAc,CAAC;AAE7B,+EAA+E;AAC/E,gCAAgC;AAChC,+EAA+E;AAC/E,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/middleware/compose.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Middleware Composition Utilities
+ *
+ * Provides type-safe composition of middleware chains with proper context tracking.
+ * Uses recursive type inference (`MiddlewaresContext`) to validate middleware compatibility
+ * for any chain length - no manual overloads needed!
+ */
+import type { Middleware, MiddlewareRunner, MiddlewaresContext, AsyncMiddleware, SyncMiddleware } from "./types.js";
+/**
+ * Wraps an async function with a series of middlewares and returns a new async function
+ * representing their combined execution.
+ *
+ * The middlewares list is ordered from outer to inner, such that when the combined async function
+ * is executed, the first middleware in the list is run first and then executes the "next" function
+ * which represents the inner function wrapped by subsequent middlewares.
+ *
+ * Type safety: The `MiddlewaresContext` recursive type validates that each middleware's
+ * requirements are satisfied by the accumulated context from previous middleware.
+ * If incompatible, the return type becomes `never` (compile error).
+ *
+ * @example
+ * ```typescript
+ * const runner = wrapWithAsyncMiddlewares(
+ *   [timeoutMiddleware, retryMiddleware, cacheMiddleware],
+ *   async (ctx: BaseContext) => fetchData(ctx)
+ * );
+ * await runner({ request: req }); // Type-safe!
+ * ```
+ */
+export declare function wrapWithAsyncMiddlewares<TMiddlewares extends readonly AsyncMiddleware<any, any, any>[], TBaseContext, TReturn>(middlewares: TMiddlewares, fn: MiddlewareRunner<MiddlewaresContext<TMiddlewares, TBaseContext>, TReturn, true>): MiddlewareRunner<TBaseContext, TReturn, true>;
+/**
+ * Wraps a synchronous function with a series of middlewares.
+ * Same as async version but for synchronous execution.
+ *
+ * @example
+ * ```typescript
+ * const runner = wrapWithSyncMiddlewares(
+ *   [boundedMiddleware, eventedMiddleware],
+ *   (collection: Collection) => collection.size
+ * );
+ * const size = runner(baseCollection);
+ * ```
+ */
+export declare function wrapWithSyncMiddlewares<TMiddlewares extends readonly SyncMiddleware<any, any, any>[], TBaseContext, TReturn>(middlewares: TMiddlewares, fn: MiddlewareRunner<MiddlewaresContext<TMiddlewares, TBaseContext>, TReturn, false>): MiddlewareRunner<TBaseContext, TReturn, false>;
+/**
+ * Composes multiple middleware with an initial runner.
+ * Automatically detects sync vs async based on middleware type.
+ *
+ * This is a convenience wrapper around `wrapWithAsyncMiddlewares`/`wrapWithSyncMiddlewares`
+ * that accepts middleware as individual arguments instead of an array.
+ *
+ * @example
+ * ```typescript
+ * // Async composition
+ * const runner = compose(m1, m2, m3, async (ctx) => fetch(ctx.url));
+ * await runner({ url: "..." });
+ *
+ * // Sync composition
+ * const runner = compose(m1, m2, (ctx) => ctx.value * 2);
+ * const result = runner({ value: 21 });
+ * ```
+ */
+export declare function compose<TAsync extends boolean = false>(...args: [...Middleware<any, any, any, TAsync>[], any]): MiddlewareRunner<any, any, TAsync>;
+/**
+ * Bundles multiple middleware into a single composed middleware.
+ * This is useful for creating reusable middleware stacks.
+ *
+ * Unlike `compose`, `bundle` returns a middleware (not a runner), so it can be
+ * composed further or used with `.use()` on clients.
+ *
+ * @example
+ * ```typescript
+ * // Create a standard middleware bundle
+ * const standardStack = bundle(
+ *   timeoutMiddleware,
+ *   retryMiddleware,
+ *   cacheMiddleware
+ * );
+ *
+ * // Use it like any other middleware
+ * client.use(standardStack);
+ *
+ * // Or compose it further
+ * const enhanced = bundle(loggingMiddleware, standardStack);
+ * ```
+ */
+export declare function bundle<TAsync extends boolean = false>(...middleware: Middleware<any, any, any, TAsync>[]): Middleware<any, any, any, TAsync>;
+//# sourceMappingURL=compose.d.ts.map

package/dist/middleware/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/middleware/compose.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,SAAS,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAC9D,YAAY,EACZ,OAAO,EAEP,WAAW,EAAE,YAAY,EACzB,EAAE,EAAE,gBAAgB,CAClB,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC,EAC9C,OAAO,EACP,IAAI,CACL,GACA,gBAAgB,CAAC,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,CAY/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,SAAS,SAAS,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAC7D,YAAY,EACZ,OAAO,EAEP,WAAW,EAAE,YAAY,EACzB,EAAE,EAAE,gBAAgB,CAClB,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC,EAC9C,OAAO,EACP,KAAK,CACN,GACA,gBAAgB,CAAC,YAAY,EAAE,OAAO,EAAE,KAAK,CAAC,CAIhD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,MAAM,SAAS,OAAO,GAAG,KAAK,EACpD,GAAG,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,GACrD,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAYpC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAS,OAAO,GAAG,KAAK,EACnD,GAAG,UAAU,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,GACjD,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAOnC"}

package/dist/middleware/compose.js

@@ -0,0 +1,108 @@
+/**
+ * Middleware Composition Utilities
+ *
+ * Provides type-safe composition of middleware chains with proper context tracking.
+ * Uses recursive type inference (`MiddlewaresContext`) to validate middleware compatibility
+ * for any chain length - no manual overloads needed!
+ */
+/**
+ * Wraps an async function with a series of middlewares and returns a new async function
+ * representing their combined execution.
+ *
+ * The middlewares list is ordered from outer to inner, such that when the combined async function
+ * is executed, the first middleware in the list is run first and then executes the "next" function
+ * which represents the inner function wrapped by subsequent middlewares.
+ *
+ * Type safety: The `MiddlewaresContext` recursive type validates that each middleware's
+ * requirements are satisfied by the accumulated context from previous middleware.
+ * If incompatible, the return type becomes `never` (compile error).
+ *
+ * @example
+ * ```typescript
+ * const runner = wrapWithAsyncMiddlewares(
+ *   [timeoutMiddleware, retryMiddleware, cacheMiddleware],
+ *   async (ctx: BaseContext) => fetchData(ctx)
+ * );
+ * await runner({ request: req }); // Type-safe!
+ * ```
+ */
+export function wrapWithAsyncMiddlewares(middlewares, fn) {
+    const combinedRunner = middlewares.reduceRight((currentRunner, currentMiddleware) => {
+        return currentMiddleware(currentRunner);
+    }, fn);
+    // Wrap in async to ensure synchronous throws become rejected promises
+    return async (context) => {
+        return combinedRunner(context);
+    };
+}
+/**
+ * Wraps a synchronous function with a series of middlewares.
+ * Same as async version but for synchronous execution.
+ *
+ * @example
+ * ```typescript
+ * const runner = wrapWithSyncMiddlewares(
+ *   [boundedMiddleware, eventedMiddleware],
+ *   (collection: Collection) => collection.size
+ * );
+ * const size = runner(baseCollection);
+ * ```
+ */
+export function wrapWithSyncMiddlewares(middlewares, fn) {
+    return middlewares.reduceRight((currentRunner, currentMiddleware) => {
+        return currentMiddleware(currentRunner);
+    }, fn);
+}
+/**
+ * Composes multiple middleware with an initial runner.
+ * Automatically detects sync vs async based on middleware type.
+ *
+ * This is a convenience wrapper around `wrapWithAsyncMiddlewares`/`wrapWithSyncMiddlewares`
+ * that accepts middleware as individual arguments instead of an array.
+ *
+ * @example
+ * ```typescript
+ * // Async composition
+ * const runner = compose(m1, m2, m3, async (ctx) => fetch(ctx.url));
+ * await runner({ url: "..." });
+ *
+ * // Sync composition
+ * const runner = compose(m1, m2, (ctx) => ctx.value * 2);
+ * const result = runner({ value: 21 });
+ * ```
+ */
+export function compose(...args) {
+    // Last argument is the initial runner/function
+    const fn = args[args.length - 1];
+    const middleware = args.slice(0, -1);
+    // Compose middleware from right to left (onion model)
+    const combined = middleware.reduceRight((next, mw) => mw(next), fn);
+    return combined;
+}
+/**
+ * Bundles multiple middleware into a single composed middleware.
+ * This is useful for creating reusable middleware stacks.
+ *
+ * Unlike `compose`, `bundle` returns a middleware (not a runner), so it can be
+ * composed further or used with `.use()` on clients.
+ *
+ * @example
+ * ```typescript
+ * // Create a standard middleware bundle
+ * const standardStack = bundle(
+ *   timeoutMiddleware,
+ *   retryMiddleware,
+ *   cacheMiddleware
+ * );
+ *
+ * // Use it like any other middleware
+ * client.use(standardStack);
+ *
+ * // Or compose it further
+ * const enhanced = bundle(loggingMiddleware, standardStack);
+ * ```
+ */
+export function bundle(...middleware) {
+    return (next) => middleware.reduceRight((acc, mw) => mw(acc), next);
+}
+//# sourceMappingURL=compose.js.map

package/dist/middleware/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/middleware/compose.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,wBAAwB,CAKtC,WAAyB,EACzB,EAIC;IAED,MAAM,cAAc,GAAG,WAAW,CAAC,WAAW,CAC5C,CAAC,aAAa,EAAE,iBAAiB,EAAE,EAAE;QACnC,OAAO,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC,EACD,EAAE,CAC8C,CAAC;IAEnD,sEAAsE;IACtE,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAKrC,WAAyB,EACzB,EAIC;IAED,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC,aAAa,EAAE,iBAAiB,EAAE,EAAE;QAClE,OAAO,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC,EAAE,EAAE,CAAmD,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,OAAO,CACrB,GAAG,IAAmD;IAEtD,+CAA+C;IAC/C,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAwC,CAAC;IAE5E,sDAAsD;IACtD,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,CACrC,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,EACtB,EAAE,CACmC,CAAC;IAExC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,MAAM,CACpB,GAAG,UAA+C;IAElD,OAAO,CAAC,IAAI,EAAE,EAAE,CACd,UAAU,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,CAIhD,CAAC;AACN,CAAC"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unified Middleware System
+ *
+ * Provides type-safe middleware composition for both sync and async operations.
+ * Used by both API middleware (async) and Collections middleware (sync).
+ *
+ * Uses recursive type inference (`MiddlewaresContext`) to validate middleware
+ * compatibility at compile time - no manual overloads needed!
+ */
+export type { MiddlewareRunner, Middleware, AsyncMiddleware, SyncMiddleware, MiddlewaresContext, MiddlewareReturn, MiddlewareContextIn, MiddlewareContextOut, IsAsyncMiddleware, } from "./types.js";
+export { compose, bundle, wrapWithAsyncMiddlewares, wrapWithSyncMiddlewares, } from "./compose.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,OAAO,EACP,MAAM,EACN,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,cAAc,CAAC"}

package/dist/middleware/index.js

@@ -0,0 +1,11 @@
+/**
+ * Unified Middleware System
+ *
+ * Provides type-safe middleware composition for both sync and async operations.
+ * Used by both API middleware (async) and Collections middleware (sync).
+ *
+ * Uses recursive type inference (`MiddlewaresContext`) to validate middleware
+ * compatibility at compile time - no manual overloads needed!
+ */
+export { compose, bundle, wrapWithAsyncMiddlewares, wrapWithSyncMiddlewares, } from "./compose.js";
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,OAAO,EACL,OAAO,EACP,MAAM,EACN,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,cAAc,CAAC"}

package/dist/middleware/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Unified Middleware Type System
+ *
+ * This module provides a sophisticated type-safe middleware system that supports
+ * both synchronous and asynchronous middleware with full context tracking.
+ *
+ * Key features:
+ * - Type-level context tracking through middleware chains
+ * - Compile-time validation of middleware compatibility
+ * - Support for both sync and async execution
+ * - Recursive type inference for composed middleware
+ */
+/**
+ * MiddlewareRunner is a function that can be wrapped in middleware.
+ * It takes a context object and returns either a value or a promise.
+ *
+ * @template TContext - The context object type
+ * @template TReturn - The return value type
+ * @template TAsync - Whether the runner is async (true) or sync (false)
+ */
+export type MiddlewareRunner<TContext, TReturn, TAsync extends boolean = false> = TAsync extends true ? (context: TContext) => Promise<TReturn> : (context: TContext) => TReturn;
+/**
+ * Middleware represents a function that wraps another function, such that the inner
+ * function can be instrumented or provided with additional context.
+ *
+ * The middleware can:
+ * - Add new properties to the context (TContextOut)
+ * - Require existing properties from the context (TContextIn)
+ * - Transform the execution flow
+ * - Be composed with other middleware
+ *
+ * Type parameters express middleware capabilities and requirements:
+ * - TContextOut: What context fields this middleware provides/adds
+ * - TContextIn: What context fields this middleware requires
+ * - TReturn: The return type
+ * - TAsync: Whether execution is async (true) or sync (false)
+ *
+ * Example:
+ * ```typescript
+ * // Async middleware that adds retryCount to context
+ * type RetryMiddleware = Middleware<
+ *   { retryCount: number },  // Provides
+ *   {},                       // Requires nothing
+ *   Response,                 // Returns Response
+ *   true                      // Async
+ * >;
+ *
+ * // Middleware that requires retryCount
+ * type LogMiddleware = Middleware<
+ *   {},                       // Provides nothing
+ *   { retryCount: number },   // Requires retryCount
+ *   Response,                 // Returns Response
+ *   true                      // Async
+ * >;
+ * ```
+ */
+export interface Middleware<TContextOut, TContextIn, TReturn, TAsync extends boolean = false> {
+    (next: MiddlewareRunner<TContextIn & TContextOut, TReturn, TAsync>): MiddlewareRunner<TContextIn, TReturn, TAsync>;
+}
+/**
+ * AsyncMiddleware is a specialized version for async execution.
+ * This is the most common form for API/network operations.
+ */
+export type AsyncMiddleware<TContextOut, TContextIn, TReturn> = Middleware<TContextOut, TContextIn, TReturn, true>;
+/**
+ * SyncMiddleware is a specialized version for synchronous execution.
+ * This is common for in-memory data structure operations.
+ */
+export type SyncMiddleware<TContextOut, TContextIn, TReturn> = Middleware<TContextOut, TContextIn, TReturn, false>;
+/**
+ * Extracts the combined context after applying a series of middlewares.
+ *
+ * This recursive type validates that each middleware's requirements are satisfied
+ * by the accumulated context. If any middleware expects a context field that is
+ * not provided by previous middleware or the initial context, the result is `never`.
+ *
+ * Example:
+ * ```typescript
+ * type Mw1 = Middleware<{ a: number }, {}, Response, true>;
+ * type Mw2 = Middleware<{ b: string }, { a: number }, Response, true>;
+ * type Mw3 = Middleware<{}, { a: number; b: string }, Response, true>;
+ *
+ * // Valid: each middleware gets what it needs
+ * type Ctx = MiddlewaresContext<[Mw1, Mw2, Mw3], {}>;
+ * // Result: { a: number; b: string }
+ *
+ * // Invalid: Mw2 requires { a: number } but Mw1 is missing
+ * type BadCtx = MiddlewaresContext<[Mw2], {}>;
+ * // Result: never (compile error)
+ * ```
+ */
+export type MiddlewaresContext<TMiddlewares extends readonly Middleware<any, any, any, any>[], TContextIn = {}> = TMiddlewares extends readonly [
+    Middleware<infer TNextContextOut, infer TNextContextIn, any, any>,
+    ...infer TRest
+] ? TContextIn extends TNextContextIn ? TRest extends readonly Middleware<any, any, any, any>[] ? MiddlewaresContext<TRest, TContextIn & TNextContextOut> : never : never : TMiddlewares extends readonly [] ? TContextIn : never;
+/**
+ * Helper type to extract the return type from a middleware
+ */
+export type MiddlewareReturn<T> = T extends Middleware<any, any, infer R, any> ? R : never;
+/**
+ * Helper type to extract the context input from a middleware
+ */
+export type MiddlewareContextIn<T> = T extends Middleware<any, infer Ctx, any, any> ? Ctx : never;
+/**
+ * Helper type to extract the context output from a middleware
+ */
+export type MiddlewareContextOut<T> = T extends Middleware<infer Ctx, any, any, any> ? Ctx : never;
+/**
+ * Helper type to check if a middleware is async
+ */
+export type IsAsyncMiddleware<T> = T extends Middleware<any, any, any, infer A> ? A : never;
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,OAAO,GAAG,KAAK,IAC5E,MAAM,SAAS,IAAI,GACf,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,GACvC,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,UAAU,CACzB,WAAW,EACX,UAAU,EACV,OAAO,EACP,MAAM,SAAS,OAAO,GAAG,KAAK;IAE9B,CACE,IAAI,EAAE,gBAAgB,CAAC,UAAU,GAAG,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,GAChE,gBAAgB,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,IAAI,UAAU,CACxE,WAAW,EACX,UAAU,EACV,OAAO,EACP,IAAI,CACL,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,IAAI,UAAU,CACvE,WAAW,EACX,UAAU,EACV,OAAO,EACP,KAAK,CACN,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,kBAAkB,CAC5B,YAAY,SAAS,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAC9D,UAAU,GAAG,EAAE,IAGf,YAAY,SAAS,SAAS;IAC5B,UAAU,CAAC,MAAM,eAAe,EAAE,MAAM,cAAc,EAAE,GAAG,EAAE,GAAG,CAAC;IACjE,GAAG,MAAM,KAAK;CACf,GAEG,UAAU,SAAS,cAAc,GAE/B,KAAK,SAAS,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAErD,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,CAAC,GACvD,KAAK,GAEP,KAAK,GAET,YAAY,SAAS,SAAS,EAAE,GAC9B,UAAU,GACV,KAAK,CAAC;AAEZ;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAC1E,CAAC,GACD,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAC/E,GAAG,GACH,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAChF,GAAG,GACH,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,GAC3E,CAAC,GACD,KAAK,CAAC"}