bytekit 2.2.0 → 2.4.3

package/dist/utils/async/pipeline.js

@@ -0,0 +1,154 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// ── Pipeline class ────────────────────────────────────────────────────────────
+/**
+ * An immutable, lazy pipeline that accumulates transformation operators and
+ * executes them sequentially when {@link Pipeline.process} is called.
+ *
+ * Build pipelines with the {@link pipe} factory function or by calling
+ * `.pipe(op)` on an existing instance. Each `.pipe()` call returns a **new**
+ * `Pipeline` — the original is never mutated.
+ *
+ * @template TIn  - Type of the data accepted by {@link Pipeline.process}.
+ * @template TOut - Type of the value resolved by {@link Pipeline.process}.
+ *
+ * @example
+ * const pipeline = pipe(
+ *   filter<number>((n) => n > 0),
+ *   map<number, string>((n) => String(n)),
+ * );
+ * const result = await pipeline.process([1, -2, 3]); // ["1", "3"]
+ */
+export class Pipeline {
+    /**
+     * @internal — Use {@link pipe} to create pipelines.
+     */
+    constructor(ops) {
+        /** @internal */
+        Object.defineProperty(this, "ops", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.ops = ops;
+    }
+    /**
+     * Appends an operator and returns a **new** `Pipeline` instance.
+     * The original pipeline is not mutated.
+     *
+     * @param op - The operator to append.
+     * @returns A new `Pipeline<TIn, TNext>` with the operator appended.
+     *
+     * @example
+     * const base = pipe(filter<number>((n) => n > 0));
+     * const doubled = base.pipe(map<number, number>((n) => n * 2));
+     * // base is unchanged
+     */
+    pipe(op) {
+        return new Pipeline([...this.ops, op]);
+    }
+    /**
+     * Executes all accumulated operators sequentially, passing the output of
+     * each as the input to the next. Always returns a `Promise`.
+     *
+     * @param data - The initial input value.
+     * @returns A `Promise` that resolves to the final transformed value.
+     * @throws The error thrown by the first operator that rejects.
+     *
+     * @example
+     * const result = await pipeline.process([1, 2, 3]);
+     */
+    async process(data) {
+        let result = data;
+        for (const op of this.ops) {
+            result = await op(result);
+        }
+        return result;
+    }
+}
+// ── Implementation ────────────────────────────────────────────────────────────
+export function pipe(...ops) {
+    return new Pipeline(ops);
+}
+// ── Operator factories ────────────────────────────────────────────────────────
+/**
+ * Creates a pipeline operator that transforms each element of an array.
+ * Async mapper functions are awaited **concurrently** via `Promise.all`,
+ * so all items are processed in parallel. Order is preserved.
+ *
+ * @param fn - A mapping function that receives `(item, index)` and returns the
+ *   transformed value synchronously or as a `Promise`.
+ * @returns A `PipelineOp<T[], U[]>`.
+ *
+ * @example
+ * const double = map<number, number>((n) => n * 2);
+ * const result = await pipe(double).process([1, 2, 3]); // [2, 4, 6]
+ *
+ * @example
+ * // Async map — all fetch calls run concurrently
+ * const enrich = map<string, { id: string; name: string }>(async (id) => {
+ *   const res = await fetch(`/api/users/${id}`);
+ *   return res.json();
+ * });
+ */
+export function map(fn) {
+    return (items) => Promise.all(items.map((item, index) => fn(item, index)));
+}
+/**
+ * Creates a pipeline operator that retains only the elements for which the
+ * predicate returns `true` (or resolves to `true`).
+ * Predicate calls run **concurrently** via `Promise.all`; the original order
+ * of retained elements is preserved.
+ *
+ * @param fn - A predicate function that receives `(item, index)` and returns a
+ *   `boolean` or `Promise<boolean>`.
+ * @returns A `PipelineOp<T[], T[]>`.
+ *
+ * @example
+ * const positives = filter<number>((n) => n > 0);
+ * const result = await pipe(positives).process([1, -2, 3]); // [1, 3]
+ *
+ * @example
+ * // Async filter
+ * const active = filter<string>(async (id) => {
+ *   const res = await fetch(`/api/items/${id}/active`);
+ *   return res.ok;
+ * });
+ */
+export function filter(fn) {
+    return async (items) => {
+        const results = await Promise.all(items.map((item, index) => fn(item, index)));
+        return items.filter((_, index) => results[index]);
+    };
+}
+/**
+ * Creates a pipeline operator that reduces an array to a single accumulated
+ * value. The reducer function runs **sequentially** — each step awaits the
+ * previous accumulator before proceeding, ensuring deterministic results.
+ *
+ * @param fn - A reducer function that receives `(accumulator, item, index)` and
+ *   returns the next accumulator value synchronously or as a `Promise`.
+ * @param initial - The initial accumulator value.
+ * @returns A `PipelineOp<T[], U>`.
+ *
+ * @example
+ * const sum = reduce<number, number>((acc, n) => acc + n, 0);
+ * const result = await pipe(sum).process([1, 2, 3]); // 6
+ *
+ * @example
+ * // Async sequential reduce
+ * const writeAll = reduce<string, string[]>(async (acc, id) => {
+ *   await db.delete(id);
+ *   return [...acc, id];
+ * }, []);
+ */
+export function reduce(fn, initial) {
+    return async (items) => {
+        let acc = initial;
+        for (let i = 0; i < items.length; i++) {
+            acc = await fn(acc, items[i], i);
+        }
+        return acc;
+    };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/utils/async/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../../src/utils/async/pipeline.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAevD,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,QAAQ;IAIjB;;OAEG;IACH,YAAY,GAA2B;QANvC,gBAAgB;QACC;;;;;WAA4B;QAMzC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,CAAQ,EAA2B;QACnC,OAAO,IAAI,QAAQ,CAAa,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAAC,IAAS;QACnB,IAAI,MAAM,GAAQ,IAAI,CAAC;QACvB,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACxB,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,MAAc,CAAC;IAC1B,CAAC;CACJ;AAkFD,iFAAiF;AACjF,MAAM,UAAU,IAAI,CAAI,GAAG,GAA2B;IAClD,OAAO,IAAI,QAAQ,CAAS,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,GAAG,CACf,EAA8C;IAE9C,OAAO,CAAC,KAAU,EAAgB,EAAE,CAChC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,MAAM,CAClB,EAA0D;IAE1D,OAAO,KAAK,EAAE,KAAU,EAAgB,EAAE;QACtC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAC9C,CAAC;QACF,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,MAAM,CAClB,EAAsD,EACtD,OAAU;IAEV,OAAO,KAAK,EAAE,KAAU,EAAc,EAAE;QACpC,IAAI,GAAG,GAAG,OAAO,CAAC;QAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,GAAG,GAAG,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC,CAAC;AACN,CAAC"}

package/dist/utils/async/promise-pool.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Options for PromisePool configuration
+ */
+export interface PromisePoolOptions {
+    /** Maximum number of tasks that can run concurrently. Minimum: 1. */
+    concurrency: number;
+    /** Optional timeout in milliseconds per individual task. Must be > 0. */
+    timeout?: number;
+    /**
+     * Optional callback invoked when a task fails.
+     * Does NOT stop the pool — remaining tasks continue executing.
+     * @param error     The error thrown by the failing task.
+     * @param taskIndex Zero-based index of the failing task in the original array.
+     */
+    onError?: (error: Error, taskIndex: number) => void;
+}
+/**
+ * Error thrown when a task exceeds the configured per-task timeout.
+ */
+export declare class PoolTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/**
+ * Executes an array of async tasks with a configurable concurrency limit.
+ *
+ * Unlike `parallel()`, PromisePool:
+ * - Is stateful and reusable across multiple `run()` calls.
+ * - Does NOT fail fast: individual task errors are isolated via `onError`.
+ * - Supports per-task timeouts.
+ *
+ * @example
+ * ```typescript
+ * const pool = new PromisePool({ concurrency: 3, timeout: 5000 });
+ * const results = await pool.run([
+ *   () => fetch("/api/1").then(r => r.json()),
+ *   () => fetch("/api/2").then(r => r.json()),
+ * ]);
+ * ```
+ */
+export declare class PromisePool {
+    private readonly options;
+    private running;
+    private queue;
+    constructor(options: PromisePoolOptions);
+    /**
+     * Runs an array of task factory functions with concurrency control.
+     * Tasks are lazy — they are not started until the pool has a free slot.
+     *
+     * @param tasks   Array of functions that return Promises.
+     * @returns       Promise resolving to an array of results in original order.
+     * @throws TypeError  If `tasks` is not an array or any element is not a function.
+     */
+    run<T>(tasks: Array<() => Promise<T>>): Promise<T[]>;
+    private addTask;
+    private processQueue;
+    private executeTask;
+    private withTimeout;
+}
+//# sourceMappingURL=promise-pool.d.ts.map

package/dist/utils/async/promise-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise-pool.d.ts","sourceRoot":"","sources":["../../../src/utils/async/promise-pool.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC3B,SAAS,EAAE,MAAM;CAIhC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAKL;gBAEI,OAAO,EAAE,kBAAkB;IAUvC;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAoB1D,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;YAWN,WAAW;IA2BzB,OAAO,CAAC,WAAW;CAYtB"}

package/dist/utils/async/promise-pool.js

@@ -0,0 +1,130 @@
+/**
+ * Error thrown when a task exceeds the configured per-task timeout.
+ */
+export class PoolTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Task timed out after ${timeoutMs}ms`);
+        this.name = "PoolTimeoutError";
+    }
+}
+/**
+ * Executes an array of async tasks with a configurable concurrency limit.
+ *
+ * Unlike `parallel()`, PromisePool:
+ * - Is stateful and reusable across multiple `run()` calls.
+ * - Does NOT fail fast: individual task errors are isolated via `onError`.
+ * - Supports per-task timeouts.
+ *
+ * @example
+ * ```typescript
+ * const pool = new PromisePool({ concurrency: 3, timeout: 5000 });
+ * const results = await pool.run([
+ *   () => fetch("/api/1").then(r => r.json()),
+ *   () => fetch("/api/2").then(r => r.json()),
+ * ]);
+ * ```
+ */
+export class PromisePool {
+    constructor(options) {
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "running", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        if (options.concurrency < 1) {
+            throw new TypeError("concurrency must be at least 1");
+        }
+        if (options.timeout !== undefined && options.timeout <= 0) {
+            throw new TypeError("timeout must be a positive number");
+        }
+        this.options = { ...options };
+    }
+    /**
+     * Runs an array of task factory functions with concurrency control.
+     * Tasks are lazy — they are not started until the pool has a free slot.
+     *
+     * @param tasks   Array of functions that return Promises.
+     * @returns       Promise resolving to an array of results in original order.
+     * @throws TypeError  If `tasks` is not an array or any element is not a function.
+     */
+    async run(tasks) {
+        if (!Array.isArray(tasks)) {
+            throw new TypeError("tasks must be an array");
+        }
+        if (tasks.length === 0) {
+            return [];
+        }
+        for (let i = 0; i < tasks.length; i++) {
+            if (typeof tasks[i] !== "function") {
+                throw new TypeError(`Task at index ${i} is not a function`);
+            }
+        }
+        const results = new Array(tasks.length);
+        await Promise.all(tasks.map((task, index) => this.addTask(task, index, results)));
+        return results;
+    }
+    addTask(task, index, results) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                task: task,
+                resolve: resolve,
+                reject,
+                index,
+            });
+            this.processQueue(results);
+        });
+    }
+    processQueue(results) {
+        while (this.running < this.options.concurrency &&
+            this.queue.length > 0) {
+            const item = this.queue.shift();
+            this.running++;
+            this.executeTask(item, results);
+        }
+    }
+    async executeTask(item, results) {
+        try {
+            const promise = item.task();
+            const result = this.options.timeout
+                ? await this.withTimeout(promise, this.options.timeout)
+                : await promise;
+            results[item.index] = result;
+            item.resolve(result);
+        }
+        catch (error) {
+            if (this.options.onError) {
+                this.options.onError(error, item.index);
+            }
+            item.reject(error);
+        }
+        finally {
+            this.running--;
+            this.processQueue(results);
+        }
+    }
+    withTimeout(promise, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new PoolTimeoutError(timeoutMs));
+            }, timeoutMs);
+            promise
+                .then(resolve)
+                .catch(reject)
+                .finally(() => clearTimeout(timer));
+        });
+    }
+}
+//# sourceMappingURL=promise-pool.js.map

package/dist/utils/async/promise-pool.js.map

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

package/dist/utils/async/request-batcher.d.ts

@@ -0,0 +1,82 @@
+/**
+ * RequestBatcher — Time-window deduplication batcher for HTTP requests.
+ * Feature: 004-batching-system
+ * Zero external dependencies: Map, setTimeout/clearTimeout (built-in).
+ */
+/** Constructor options for {@link RequestBatcher}. */
+export interface BatchOptions {
+    /**
+     * Time window in milliseconds for collecting requests before dispatching.
+     * Must be greater than 0.
+     */
+    windowMs: number;
+    /**
+     * Maximum requests per batch. Flushes early when reached.
+     * Default: `Infinity`.
+     */
+    maxSize?: number;
+    /**
+     * If `true`, the window timer resets on each new request (sliding window).
+     * Default: `false` — fixed window: timer fires once after the first request.
+     */
+    sliding?: boolean;
+    /**
+     * Custom function to compute the batch deduplication key.
+     * Requests with the same key within a window are coalesced.
+     * Default: `"METHOD:url:serialized(body)"`.
+     */
+    keyFn?: (url: string, init: RequestInit) => string;
+}
+/**
+ * Coalesces same-key HTTP requests within a time window into a single fetch invocation.
+ * All callers sharing the same key receive the same resolved value.
+ *
+ * The deduplication key defaults to `"METHOD:url:serialized(body)"` and can be
+ * overridden via `BatchOptions.keyFn`.
+ *
+ * @example
+ * ```typescript
+ * const batcher = new RequestBatcher({ windowMs: 50 });
+ *
+ * // These three calls share the same key → fetcher invoked once
+ * const [a, b, c] = await Promise.all([
+ *   batcher.add("/api/users", { method: "GET" }, fetch),
+ *   batcher.add("/api/users", { method: "GET" }, fetch),
+ *   batcher.add("/api/users", { method: "GET" }, fetch),
+ * ]);
+ * ```
+ */
+export declare class RequestBatcher {
+    private readonly _windowMs;
+    private readonly _maxSize;
+    private readonly _sliding;
+    private readonly _keyFn;
+    private readonly _buckets;
+    private readonly _timers;
+    /**
+     * Creates a new RequestBatcher.
+     * @throws {TypeError} if `windowMs` is not greater than 0.
+     * @throws {TypeError} if `maxSize` is less than 1.
+     */
+    constructor(options: BatchOptions);
+    /**
+     * Adds a request to the current batch window.
+     * Requests with the same key (method + url + body) are coalesced —
+     * all callers receive the same resolved value when the window fires.
+     *
+     * @param url      The request URL.
+     * @param init     The RequestInit options (method, headers, body).
+     * @param fetcher  The actual fetch function to invoke when the window fires.
+     * @returns `Promise<T>` resolving to the fetch result.
+     */
+    add<T>(url: string, init: RequestInit, fetcher: (url: string, init: RequestInit) => Promise<T>): Promise<T>;
+    private _dispatch;
+    /**
+     * Forces immediate dispatch of all pending batches.
+     * Resolves when all dispatched fetchers have settled.
+     */
+    flush(): Promise<void>;
+    /** Total pending requests across all batch buckets. */
+    get pendingCount(): number;
+}
+//# sourceMappingURL=request-batcher.d.ts.map

package/dist/utils/async/request-batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-batcher.d.ts","sourceRoot":"","sources":["../../../src/utils/async/request-batcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sDAAsD;AACtD,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC;CACtD;AAmCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoD;IAE5E;;;;OAIG;gBACS,OAAO,EAAE,YAAY;IAajC;;;;;;;;;OASG;IACH,GAAG,CAAC,CAAC,EACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACxD,OAAO,CAAC,CAAC,CAAC;YAgCC,SAAS;IA4BvB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,uDAAuD;IACvD,IAAI,YAAY,IAAI,MAAM,CAMzB;CACJ"}

package/dist/utils/async/request-batcher.js

@@ -0,0 +1,179 @@
+/**
+ * RequestBatcher — Time-window deduplication batcher for HTTP requests.
+ * Feature: 004-batching-system
+ * Zero external dependencies: Map, setTimeout/clearTimeout (built-in).
+ */
+function stableSerialize(body) {
+    if (body === undefined || body === null)
+        return "";
+    if (typeof body === "string" ||
+        typeof body === "number" ||
+        typeof body === "boolean") {
+        return String(body);
+    }
+    try {
+        return JSON.stringify(body);
+    }
+    catch {
+        return String(body);
+    }
+}
+function defaultKeyFn(url, init) {
+    const method = (init.method ?? "GET").toUpperCase();
+    const body = stableSerialize(init.body);
+    return `${method}:${url}:${body}`;
+}
+/**
+ * Coalesces same-key HTTP requests within a time window into a single fetch invocation.
+ * All callers sharing the same key receive the same resolved value.
+ *
+ * The deduplication key defaults to `"METHOD:url:serialized(body)"` and can be
+ * overridden via `BatchOptions.keyFn`.
+ *
+ * @example
+ * ```typescript
+ * const batcher = new RequestBatcher({ windowMs: 50 });
+ *
+ * // These three calls share the same key → fetcher invoked once
+ * const [a, b, c] = await Promise.all([
+ *   batcher.add("/api/users", { method: "GET" }, fetch),
+ *   batcher.add("/api/users", { method: "GET" }, fetch),
+ *   batcher.add("/api/users", { method: "GET" }, fetch),
+ * ]);
+ * ```
+ */
+export class RequestBatcher {
+    /**
+     * Creates a new RequestBatcher.
+     * @throws {TypeError} if `windowMs` is not greater than 0.
+     * @throws {TypeError} if `maxSize` is less than 1.
+     */
+    constructor(options) {
+        Object.defineProperty(this, "_windowMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_maxSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_sliding", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_keyFn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_buckets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "_timers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        if (options.windowMs <= 0) {
+            throw new TypeError("windowMs must be > 0");
+        }
+        if (options.maxSize !== undefined && options.maxSize < 1) {
+            throw new TypeError("maxSize must be >= 1");
+        }
+        this._windowMs = options.windowMs;
+        this._maxSize = options.maxSize ?? Infinity;
+        this._sliding = options.sliding ?? false;
+        this._keyFn = options.keyFn ?? defaultKeyFn;
+    }
+    /**
+     * Adds a request to the current batch window.
+     * Requests with the same key (method + url + body) are coalesced —
+     * all callers receive the same resolved value when the window fires.
+     *
+     * @param url      The request URL.
+     * @param init     The RequestInit options (method, headers, body).
+     * @param fetcher  The actual fetch function to invoke when the window fires.
+     * @returns `Promise<T>` resolving to the fetch result.
+     */
+    add(url, init, fetcher) {
+        const key = this._keyFn(url, init);
+        return new Promise((resolve, reject) => {
+            const entry = { fetcher, url, init, resolve, reject };
+            if (!this._buckets.has(key)) {
+                this._buckets.set(key, []);
+            }
+            this._buckets.get(key).push(entry);
+            // Sliding window: reset timer on each new request
+            if (this._sliding && this._timers.has(key)) {
+                clearTimeout(this._timers.get(key));
+                this._timers.delete(key);
+            }
+            // Start timer if not already running (or just cleared for sliding)
+            if (!this._timers.has(key)) {
+                const timer = setTimeout(() => {
+                    void this._dispatch(key);
+                }, this._windowMs);
+                this._timers.set(key, timer);
+            }
+            // Early flush if maxSize reached
+            if (this._buckets.get(key).length >= this._maxSize) {
+                void this._dispatch(key);
+            }
+        });
+    }
+    async _dispatch(key) {
+        // Cancel the timer for this key
+        const timer = this._timers.get(key);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this._timers.delete(key);
+        }
+        // Splice the bucket — guard against double dispatch
+        const entries = this._buckets.get(key);
+        /* v8 ignore next — defensive guard against double-dispatch; unreachable via public API */
+        if (!entries || entries.length === 0)
+            return;
+        this._buckets.delete(key);
+        // Call the first entry's fetcher once; share result with all callers
+        const first = entries[0];
+        try {
+            const result = await first.fetcher(first.url, first.init);
+            for (const entry of entries) {
+                entry.resolve(result);
+            }
+        }
+        catch (err) {
+            for (const entry of entries) {
+                entry.reject(err);
+            }
+        }
+    }
+    /**
+     * Forces immediate dispatch of all pending batches.
+     * Resolves when all dispatched fetchers have settled.
+     */
+    async flush() {
+        const keys = [...this._buckets.keys()];
+        await Promise.allSettled(keys.map((key) => this._dispatch(key)));
+    }
+    /** Total pending requests across all batch buckets. */
+    get pendingCount() {
+        let count = 0;
+        for (const bucket of this._buckets.values()) {
+            count += bucket.length;
+        }
+        return count;
+    }
+}
+//# sourceMappingURL=request-batcher.js.map

package/dist/utils/async/request-batcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-batcher.js","sourceRoot":"","sources":["../../../src/utils/async/request-batcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsCH,SAAS,eAAe,CAAC,IAAa;IAClC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACnD,IACI,OAAO,IAAI,KAAK,QAAQ;QACxB,OAAO,IAAI,KAAK,QAAQ;QACxB,OAAO,IAAI,KAAK,SAAS,EAC3B,CAAC;QACC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IACD,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CAAC,GAAW,EAAE,IAAiB;IAChD,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IACpD,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,GAAG,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,cAAc;IAQvB;;;;OAIG;IACH,YAAY,OAAqB;QAZhB;;;;;WAAkB;QAClB;;;;;WAAiB;QACjB;;;;;WAAkB;QAClB;;;;;WAAmD;QACnD;;;;mBAAW,IAAI,GAAG,EAAwB;WAAC;QAC3C;;;;mBAAU,IAAI,GAAG,EAAyC;WAAC;QAQxE,IAAI,OAAO,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,SAAS,CAAC,sBAAsB,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,SAAS,CAAC,sBAAsB,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAChD,CAAC;IAED;;;;;;;;;OASG;IACH,GAAG,CACC,GAAW,EACX,IAAiB,EACjB,OAAuD;QAEvD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAEnC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACtC,MAAM,KAAK,GAAe,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;YAElE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC/B,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAEpC,kDAAkD;YAClD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,CAAC;gBACrC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YAED,mEAAmE;YACnE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC1B,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC7B,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;gBACnB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;YAED,iCAAiC;YACjC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClD,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,GAAW;QAC/B,gCAAgC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAED,oDAAoD;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,0FAA0F;QAC1F,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC7C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAE1B,qEAAqE;QACrE,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC1B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC1B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;QACL,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK;QACP,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACvC,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,uDAAuD;IACvD,IAAI,YAAY;QACZ,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}