@procedures/client 0.0.0-stage → 0.2.0

package/dist/client/middleware/items.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Helpers that the client middlewares share.
+ *
+ * The transports report a failure as an error item, not as a thrown error. The middlewares use
+ * the same style: a timeout, an abort or a refused retry is an error item, and `Client` throws
+ * it when `throwOnError` is on (deep dive TRN-7: before, the timeout middleware waited for a
+ * thrown error that the transports never threw).
+ */
+import type { ResponseItem } from "../types.js";
+/** This function makes an error item. */
+export declare function errorItem<TRes>(id: string, code: string, message: string, retryable: boolean): ResponseItem<TRes>;
+/** The error item of a request that its caller aborted. A retry does not repeat it. */
+export declare function abortedItem<TRes>(id: string): ResponseItem<TRes>;
+/**
+ * This function tells if a thrown error is a network failure: the connection failed or broke.
+ * A retry can repair a network failure. A validation error, an open circuit breaker or a rate
+ * limit cannot be repaired by a retry (deep dive TRN-8).
+ */
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * The item that stands for a thrown error, so that `shouldRetry` can decide about it. It is
+ * retryable only when the error is a network failure.
+ */
+export declare function thrownItem<TRes>(id: string, error: unknown): ResponseItem<TRes>;
+/**
+ * This function waits `ms` milliseconds. It returns false at once when the signal aborts (deep
+ * dive TRN-8: before, the backoff of the retry middleware ignored the signal).
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<boolean>;
+/** The value that `nextOrAbort` gives when the signal aborts first. */
+export declare const ABORTED_FIRST: unique symbol;
+/**
+ * The next result of an iterator, or `ABORTED_FIRST` when the signal aborts first. A transport
+ * that ignores the signal cannot keep the caller waiting past its timeout.
+ */
+export declare function nextOrAbort<T>(iterator: AsyncIterator<T>, signal: AbortSignal): Promise<IteratorResult<T> | typeof ABORTED_FIRST>;
+//# sourceMappingURL=items.d.ts.map

package/dist/client/middleware/items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"items.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/items.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,yCAAyC;AACzC,wBAAgB,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAEjH;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAEhE;AAkBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUtD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAQ/E;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAaxE;AAED,uEAAuE;AACvE,eAAO,MAAM,aAAa,EAAE,OAAO,MAAgC,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,aAAa,CAAC,CAgBnD"}

package/dist/client/middleware/items.js

@@ -0,0 +1,100 @@
+/**
+ * Helpers that the client middlewares share.
+ *
+ * The transports report a failure as an error item, not as a thrown error. The middlewares use
+ * the same style: a timeout, an abort or a refused retry is an error item, and `Client` throws
+ * it when `throwOnError` is on (deep dive TRN-7: before, the timeout middleware waited for a
+ * thrown error that the transports never threw).
+ */
+/** This function makes an error item. */
+export function errorItem(id, code, message, retryable) {
+    return { id, status: { type: "error", code, message, retryable }, payload: null, metadata: {} };
+}
+/** The error item of a request that its caller aborted. A retry does not repeat it. */
+export function abortedItem(id) {
+    return errorItem(id, "ABORTED", "Request was aborted", false);
+}
+const NETWORK_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ECONNABORTED",
+    "EPIPE",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "NETWORK_ERROR",
+    "CONNECTION_REFUSED",
+]);
+/**
+ * This function tells if a thrown error is a network failure: the connection failed or broke.
+ * A retry can repair a network failure. A validation error, an open circuit breaker or a rate
+ * limit cannot be repaired by a retry (deep dive TRN-8).
+ */
+export function isNetworkError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    if (typeof code === "string" && NETWORK_CODES.has(code))
+        return true;
+    const cause = error.cause;
+    if (cause !== undefined && cause !== error && isNetworkError(cause))
+        return true;
+    // fetch() rejects with TypeError("fetch failed") when the connection fails
+    if (error.name === "TypeError" && /fetch failed|network/i.test(error.message))
+        return true;
+    // The WebSocket transport fails the requests of a connection that closed or never opened
+    return /WebSocket (connection closed|disconnected)|Connection timeout/.test(error.message);
+}
+/**
+ * The item that stands for a thrown error, so that `shouldRetry` can decide about it. It is
+ * retryable only when the error is a network failure.
+ */
+export function thrownItem(id, error) {
+    const code = error?.code;
+    return errorItem(id, typeof code === "string" ? code : "THROWN", error instanceof Error ? error.message : String(error), isNetworkError(error));
+}
+/**
+ * This function waits `ms` milliseconds. It returns false at once when the signal aborts (deep
+ * dive TRN-8: before, the backoff of the retry middleware ignored the signal).
+ */
+export function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, Math.max(0, ms));
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** The value that `nextOrAbort` gives when the signal aborts first. */
+export const ABORTED_FIRST = Symbol("aborted first");
+/**
+ * The next result of an iterator, or `ABORTED_FIRST` when the signal aborts first. A transport
+ * that ignores the signal cannot keep the caller waiting past its timeout.
+ */
+export function nextOrAbort(iterator, signal) {
+    if (signal.aborted)
+        return Promise.resolve(ABORTED_FIRST);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => resolve(ABORTED_FIRST);
+        signal.addEventListener("abort", onAbort, { once: true });
+        iterator.next().then((result) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(result);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=items.js.map

package/dist/client/middleware/items.js.map

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

package/dist/client/middleware/lru.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A map with a capacity, for the cache middleware.
+ *
+ * A JavaScript `Map` keeps its keys in the order of insertion. A read moves its key to the end,
+ * so the first key is always the least recently used one. A write that goes over the capacity
+ * removes the first key. The core has this small map itself, so it does not depend on
+ * `@procedures/collections` (roadmap 3.3: before, the cache composed `lruMap` and
+ * `hashMap` of that package).
+ */
+export declare class LruMap<K, V> {
+    private readonly capacity;
+    private readonly onEvict?;
+    private readonly entries;
+    /**
+     * @param capacity - The largest number of keys. A positive whole number.
+     * @param onEvict - Called for each key that a write removes to keep the capacity.
+     */
+    constructor(capacity: number, onEvict?: ((key: K, value: V) => void) | undefined);
+    /** The number of keys. */
+    get size(): number;
+    /** True when the map has the key. This does not count as a use. */
+    has(key: K): boolean;
+    /** The value of the key, or undefined. A read makes the key the most recently used one. */
+    get(key: K): V | undefined;
+    /** Set the value of a key, as the most recently used one. Over the capacity, the oldest key goes. */
+    set(key: K, value: V): void;
+    /** Delete a key. True when it existed. */
+    delete(key: K): boolean;
+    /** Delete every key. */
+    clear(): void;
+}
+//# sourceMappingURL=lru.d.ts.map

package/dist/client/middleware/lru.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/lru.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,MAAM,CAAC,CAAC,EAAE,CAAC;IAQpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAR3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAE3C;;;OAGG;IACH,YACmB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,GAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,aAAA,EAKtD;IAED,0BAA0B;IAC1B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAEnB;IAED,2FAA2F;IAC3F,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAMzB;IAED,qGAAqG;IACrG,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAS1B;IAED,0CAA0C;IAC1C,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAEtB;IAED,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/client/middleware/lru.js

@@ -0,0 +1,62 @@
+/**
+ * A map with a capacity, for the cache middleware.
+ *
+ * A JavaScript `Map` keeps its keys in the order of insertion. A read moves its key to the end,
+ * so the first key is always the least recently used one. A write that goes over the capacity
+ * removes the first key. The core has this small map itself, so it does not depend on
+ * `@procedures/collections` (roadmap 3.3: before, the cache composed `lruMap` and
+ * `hashMap` of that package).
+ */
+export class LruMap {
+    capacity;
+    onEvict;
+    entries = new Map();
+    /**
+     * @param capacity - The largest number of keys. A positive whole number.
+     * @param onEvict - Called for each key that a write removes to keep the capacity.
+     */
+    constructor(capacity, onEvict) {
+        this.capacity = capacity;
+        this.onEvict = onEvict;
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new RangeError(`The capacity of an LRU map must be a positive whole number, not ${capacity}`);
+        }
+    }
+    /** The number of keys. */
+    get size() {
+        return this.entries.size;
+    }
+    /** True when the map has the key. This does not count as a use. */
+    has(key) {
+        return this.entries.has(key);
+    }
+    /** The value of the key, or undefined. A read makes the key the most recently used one. */
+    get(key) {
+        if (!this.entries.has(key))
+            return undefined;
+        const value = this.entries.get(key);
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        return value;
+    }
+    /** Set the value of a key, as the most recently used one. Over the capacity, the oldest key goes. */
+    set(key, value) {
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        while (this.entries.size > this.capacity) {
+            const oldest = this.entries.keys().next().value;
+            const evicted = this.entries.get(oldest);
+            this.entries.delete(oldest);
+            this.onEvict?.(oldest, evicted);
+        }
+    }
+    /** Delete a key. True when it existed. */
+    delete(key) {
+        return this.entries.delete(key);
+    }
+    /** Delete every key. */
+    clear() {
+        this.entries.clear();
+    }
+}
+//# sourceMappingURL=lru.js.map

package/dist/client/middleware/lru.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.js","sourceRoot":"","sources":["../../../src/client/middleware/lru.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,MAAM;IAQE,QAAQ;IACR,OAAO;IART,OAAO,GAAG,IAAI,GAAG,EAAQ,CAAC;IAE3C;;;OAGG;IACH,YACmB,QAAgB,EAChB,OAAoC;wBADpC,QAAQ;uBACR,OAAO;QAExB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,UAAU,CAAC,mEAAmE,QAAQ,EAAE,CAAC,CAAC;QACtG,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,mEAAmE;IACnE,GAAG,CAAC,GAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,2FAA2F;IAC3F,GAAG,CAAC,GAAM;QACR,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;QAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;QACzC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,qGAAqG;IACrG,GAAG,CAAC,GAAM,EAAE,KAAQ;QAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAU,CAAC;YACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAM,CAAC;YAC9C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,IAAI,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,MAAM,CAAC,GAAM;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,wBAAwB;IACxB,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/client/middleware/pagination.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Universal Pagination Middleware
+ *
+ * Protocol-agnostic pagination handling.
+ * Works with any transport!
+ */
+import type { TypedClientMiddleware } from "../types.js";
+import type { PaginationContext } from "./contexts.js";
+/**
+ * Pagination middleware options.
+ */
+export interface PaginationOptions {
+    /**
+     * Default page size
+     * @default 50
+     */
+    defaultLimit?: number;
+    /**
+     * Maximum page size (prevents abuse)
+     * @default 1000
+     */
+    maxLimit?: number;
+    /**
+     * Page parameter name in metadata
+     * @default "page"
+     */
+    pageKey?: string;
+    /**
+     * Limit parameter name in metadata
+     * @default "limit"
+     */
+    limitKey?: string;
+    /**
+     * Offset parameter name in metadata (alternative to page)
+     * @default "offset"
+     */
+    offsetKey?: string;
+    /**
+     * Whether to use offset-based pagination instead of page-based
+     * @default false
+     */
+    useOffset?: boolean;
+}
+/**
+ * Create pagination middleware.
+ *
+ * Automatically handles pagination parameters in request metadata:
+ * - Applies default limit if not specified
+ * - Enforces maximum limit to prevent abuse
+ * - Supports both page-based and offset-based pagination
+ *
+ * @param options - Pagination configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Page-based pagination
+ * client.use(createPaginationMiddleware({
+ *   defaultLimit: 50,
+ *   maxLimit: 1000
+ * }));
+ *
+ * await client.call(
+ *   { service: "users", operation: "list" },
+ *   {},
+ *   { page: 2, limit: 100 } // Metadata
+ * );
+ *
+ * // Offset-based pagination
+ * client.use(createPaginationMiddleware({
+ *   useOffset: true,
+ *   defaultLimit: 50
+ * }));
+ *
+ * await client.call(
+ *   { service: "users", operation: "list" },
+ *   {},
+ *   { offset: 100, limit: 50 } // Metadata
+ * );
+ * ```
+ */
+export declare function createPaginationMiddleware(options?: PaginationOptions): TypedClientMiddleware<PaginationContext, {}>;
+/**
+ * Helper to create an async iterator for paginated results.
+ *
+ * Automatically fetches all pages and yields items as they arrive.
+ *
+ * @param client - The client instance
+ * @param method - Method to call
+ * @param payload - Request payload
+ * @param options - Pagination options
+ * @returns Async iterable of all items across all pages
+ *
+ * @example
+ * ```typescript
+ * // Fetch all users across all pages
+ * for await (const user of paginateAll(client, { service: "users", operation: "list" }, {})) {
+ *   console.log(user);
+ * }
+ * ```
+ */
+export declare function paginateAll<TReq, TRes extends {
+    items: any[];
+    hasMore?: boolean;
+    total?: number;
+}>(client: {
+    call: (method: any, payload: TReq, metadata?: any) => Promise<TRes>;
+}, method: any, payload: TReq, options?: {
+    limit?: number;
+    maxPages?: number;
+}): AsyncIterable<TRes extends {
+    items: (infer U)[];
+} ? U : never>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/client/middleware/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/pagination.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAA+B,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,iBAAsB,GAC9B,qBAAqB,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAsE9C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuB,WAAW,CAAC,IAAI,EAAE,IAAI,SAAS;IAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACvG,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,EAC/E,MAAM,EAAE,GAAG,EACX,OAAO,EAAE,IAAI,EACb,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,aAAa,CAAC,IAAI,SAAS;IAAE,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAyBhE"}

package/dist/client/middleware/pagination.js

@@ -0,0 +1,148 @@
+/**
+ * Universal Pagination Middleware
+ *
+ * Protocol-agnostic pagination handling.
+ * Works with any transport!
+ */
+/**
+ * Create pagination middleware.
+ *
+ * Automatically handles pagination parameters in request metadata:
+ * - Applies default limit if not specified
+ * - Enforces maximum limit to prevent abuse
+ * - Supports both page-based and offset-based pagination
+ *
+ * @param options - Pagination configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Page-based pagination
+ * client.use(createPaginationMiddleware({
+ *   defaultLimit: 50,
+ *   maxLimit: 1000
+ * }));
+ *
+ * await client.call(
+ *   { service: "users", operation: "list" },
+ *   {},
+ *   { page: 2, limit: 100 } // Metadata
+ * );
+ *
+ * // Offset-based pagination
+ * client.use(createPaginationMiddleware({
+ *   useOffset: true,
+ *   defaultLimit: 50
+ * }));
+ *
+ * await client.call(
+ *   { service: "users", operation: "list" },
+ *   {},
+ *   { offset: 100, limit: 50 } // Metadata
+ * );
+ * ```
+ */
+export function createPaginationMiddleware(options = {}) {
+    const { defaultLimit = 50, maxLimit = 1000, pageKey = "page", limitKey = "limit", offsetKey = "offset", useOffset = false, } = options;
+    return (next) => {
+        return async function* (context) {
+            const { metadata } = context.message;
+            // Extract pagination params
+            let page = metadata[pageKey];
+            let limit = metadata[limitKey];
+            let offset = metadata[offsetKey];
+            // Apply defaults and limits
+            if (limit === undefined) {
+                limit = defaultLimit;
+            }
+            else {
+                // Enforce maximum limit
+                limit = Math.min(Math.max(1, limit), maxLimit);
+            }
+            if (useOffset) {
+                // Offset-based pagination
+                if (offset === undefined) {
+                    offset = 0;
+                }
+                else {
+                    offset = Math.max(0, offset);
+                }
+                // Update message metadata, with the state as one object (PaginationContext)
+                context.message.metadata = {
+                    ...metadata,
+                    [offsetKey]: offset,
+                    [limitKey]: limit,
+                    pagination: { offset, limit },
+                };
+            }
+            else {
+                // Page-based pagination
+                if (page === undefined) {
+                    page = 1;
+                }
+                else {
+                    page = Math.max(1, page);
+                }
+                // Update message metadata, with the state as one object (PaginationContext)
+                context.message.metadata = {
+                    ...metadata,
+                    [pageKey]: page,
+                    [limitKey]: limit,
+                    pagination: { page, limit },
+                };
+                // Optionally compute offset for backends that need it
+                const computedOffset = (page - 1) * limit;
+                if (metadata["includeOffset"]) {
+                    context.message.metadata[offsetKey] = computedOffset;
+                    context.message.metadata["pagination"] = { page, offset: computedOffset, limit };
+                }
+            }
+            // Execute request
+            yield* next(context);
+        };
+    };
+}
+/**
+ * Helper to create an async iterator for paginated results.
+ *
+ * Automatically fetches all pages and yields items as they arrive.
+ *
+ * @param client - The client instance
+ * @param method - Method to call
+ * @param payload - Request payload
+ * @param options - Pagination options
+ * @returns Async iterable of all items across all pages
+ *
+ * @example
+ * ```typescript
+ * // Fetch all users across all pages
+ * for await (const user of paginateAll(client, { service: "users", operation: "list" }, {})) {
+ *   console.log(user);
+ * }
+ * ```
+ */
+export async function* paginateAll(client, method, payload, options = {}) {
+    const { limit = 50, maxPages = Infinity } = options;
+    let page = 1;
+    let hasMore = true;
+    while (hasMore && page <= maxPages) {
+        const response = await client.call(method, payload, { page, limit });
+        // Yield all items from this page
+        for (const item of response.items) {
+            yield item;
+        }
+        // Check if there are more pages
+        if (response.hasMore !== undefined) {
+            hasMore = response.hasMore;
+        }
+        else if (response.total !== undefined) {
+            hasMore = page * limit < response.total;
+        }
+        else {
+            // If no pagination metadata, check if we got a full page
+            hasMore = response.items.length === limit;
+        }
+        page++;
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/client/middleware/pagination.js.map

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

package/dist/client/middleware/rate-limit.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Rate Limiting Middleware
+ *
+ * Throttles requests using token bucket algorithm.
+ * Prevents overwhelming services with too many requests.
+ *
+ * Works with both client and server!
+ */
+import type { ClientMiddleware, TypedClientMiddleware } from "../types.js";
+import type { RateLimitContext } from "./contexts.js";
+/**
+ * Rate limiting options.
+ */
+export interface RateLimitOptions {
+    /**
+     * Maximum number of requests per time window.
+     * @default 100
+     */
+    maxRequests?: number;
+    /**
+     * Time window in milliseconds.
+     * @default 60000 (1 minute)
+     */
+    window?: number;
+    /**
+     * Behavior when rate limit is exceeded.
+     * - "reject": Throw error immediately
+     * - "queue": Queue requests and process when capacity available
+     * @default "reject"
+     */
+    strategy?: "reject" | "queue";
+    /**
+     * Maximum queue size (only for "queue" strategy).
+     * @default 100
+     */
+    maxQueueSize?: number;
+    /**
+     * Custom error message.
+     */
+    message?: string;
+    /**
+     * Callback when rate limit is exceeded.
+     */
+    onRateLimitExceeded?: (stats: RateLimitStats) => void;
+}
+/**
+ * Rate limit statistics.
+ */
+export interface RateLimitStats {
+    tokensAvailable: number;
+    maxTokens: number;
+    queueSize: number;
+    totalRequests: number;
+    rejectedRequests: number;
+}
+/**
+ * Rate limit error thrown when limit exceeded.
+ */
+export declare class RateLimitError extends Error {
+    readonly stats: RateLimitStats;
+    constructor(message: string, stats: RateLimitStats);
+}
+/**
+ * Create rate limiting middleware using token bucket algorithm.
+ *
+ * @param options - Rate limiting configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * // Reject strategy (default)
+ * client.use(createRateLimitMiddleware({
+ *   maxRequests: 100,    // 100 requests
+ *   window: 60000,       // per minute
+ *   strategy: "reject"   // Throw error when exceeded
+ * }));
+ *
+ * // Queue strategy
+ * client.use(createRateLimitMiddleware({
+ *   maxRequests: 10,
+ *   window: 1000,
+ *   strategy: "queue",   // Queue requests when exceeded
+ *   maxQueueSize: 50
+ * }));
+ * ```
+ */
+export declare function createRateLimitMiddleware(options?: RateLimitOptions): TypedClientMiddleware<RateLimitContext, {}>;
+/**
+ * Create per-service rate limiter.
+ *
+ * Applies different rate limits based on service name.
+ *
+ * @example
+ * ```typescript
+ * client.use(createPerServiceRateLimiter({
+ *   users: { maxRequests: 100, window: 60000 },
+ *   orders: { maxRequests: 50, window: 60000 },
+ *   default: { maxRequests: 200, window: 60000 }
+ * }));
+ * ```
+ */
+export declare function createPerServiceRateLimiter(limits: Record<string, RateLimitOptions> & {
+    default?: RateLimitOptions;
+}): ClientMiddleware;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/client/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAA+B,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE9B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;aAGrB,KAAK,EAAE,cAAc;IAFvC,YACE,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,cAAc,EAItC;CACF;AAWD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,gBAAqB,GAC7B,qBAAqB,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAwJ7C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAAE,GACxE,gBAAgB,CA+BlB"}