bytekit 2.2.0 → 2.2.3

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;IA2BvB;;;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,178 @@
+/**
+ * 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);
+        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":"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"}

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

@@ -0,0 +1,115 @@
+/**
+ * RequestQueue — Priority-aware, concurrency-limited task queue with AbortSignal cancellation.
+ * Feature: 004-batching-system
+ * Zero external dependencies: AbortController, Map (built-in).
+ */
+/** The three fixed priority lanes for task execution ordering. */
+export type QueuePriority = "high" | "normal" | "low";
+/** Constructor options for {@link RequestQueue}. */
+export interface RequestQueueOptions {
+    /**
+     * Max tasks running simultaneously. Minimum: 1.
+     */
+    concurrency: number;
+    /**
+     * Called when a task rejects. Queue continues executing remaining tasks.
+     * @param error  The rejection reason (cast to Error).
+     * @param id     The task's unique identifier.
+     */
+    onError?: (error: Error, id: string) => void;
+}
+/** Per-task options for {@link RequestQueue.add}. */
+export interface AddOptions {
+    /**
+     * Lane priority. Defaults to `"normal"`.
+     * Tasks in `high` always dequeue before `normal`; `normal` before `low`.
+     */
+    priority?: QueuePriority;
+    /**
+     * External AbortSignal. If it fires before the task starts,
+     * the task is cancelled immediately with {@link QueueAbortError}.
+     * This is the **public consumer cancellation path**.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Thrown when a queued task is cancelled — either via an external AbortSignal
+ * or via the internal `cancel(id)` mechanism.
+ */
+export declare class QueueAbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * A priority-aware, concurrency-limited task queue with AbortSignal-based cancellation.
+ *
+ * Tasks are organised into three lanes (`high`, `normal`, `low`). At any moment,
+ * at most `concurrency` tasks execute simultaneously. When a slot opens, the
+ * highest-priority queued task is dequeued and started.
+ *
+ * **Consumer cancellation** is done via `AddOptions.signal`.
+ * The `cancel(id)` method is an internal queue-management mechanism.
+ *
+ * @example
+ * ```typescript
+ * const queue = new RequestQueue({ concurrency: 3 });
+ *
+ * const result = await queue.add(
+ *   (signal) => fetch("/api/data", { signal }),
+ *   { priority: "high" }
+ * );
+ * ```
+ */
+export declare class RequestQueue {
+    private readonly _concurrency;
+    private readonly _onError?;
+    private readonly _high;
+    private readonly _normal;
+    private readonly _low;
+    private _running;
+    private readonly _active;
+    private _counter;
+    private _flushWaiters;
+    /**
+     * Creates a new RequestQueue.
+     * @throws {TypeError} if `concurrency` is less than 1.
+     */
+    constructor(options: RequestQueueOptions);
+    /**
+     * Enqueues a task. The task factory receives an internal AbortSignal
+     * that fires when the task is cancelled via `cancel(id)`.
+     *
+     * @returns `Promise<T>` resolving to the task's return value.
+     * @throws {@link QueueAbortError} if cancelled before or during execution.
+     * @throws Whatever the task itself throws.
+     */
+    add<T>(task: (signal: AbortSignal) => Promise<T>, options?: AddOptions): Promise<T>;
+    private _drain;
+    private _notifyFlushWaiters;
+    /**
+     * Cancels a task by ID.
+     * - **Queued task**: removed from its lane; promise rejects with {@link QueueAbortError}.
+     *   Task factory is never called.
+     * - **In-flight task**: internal AbortSignal is fired. The task is responsible
+     *   for reacting to signal abortion and rejecting its promise.
+     *
+     * @returns `true` if the ID was found; `false` otherwise.
+     * @internal Public consumers should use `AddOptions.signal` for cancellation.
+     */
+    cancel(id: string): boolean;
+    /**
+     * Resolves when all currently queued and running tasks have settled.
+     * Tasks added after `flush()` is called are included in the wait.
+     */
+    flush(): Promise<void>;
+    /** @internal Returns IDs of all queued (not yet running) items across all lanes. */
+    _queuedIds(): string[];
+    /** @internal Returns IDs of all currently running items. */
+    _runningIds(): string[];
+    /** Number of tasks waiting to start (across all priority lanes). */
+    get size(): number;
+    /** Number of tasks currently executing. */
+    get running(): number;
+    /** Total active work: `size + running`. */
+    get pending(): number;
+}
+//# sourceMappingURL=request-queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"request-queue.d.ts","sourceRoot":"","sources":["../../../src/utils/async/request-queue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtD,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AAED,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC1B,OAAO,CAAC,EAAE,MAAM;CAI/B;AAcD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,aAAa,CAAyB;IAE9C;;;OAGG;gBACS,OAAO,EAAE,mBAAmB;IAQxC;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,EACD,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACzC,OAAO,CAAC,EAAE,UAAU,GACrB,OAAO,CAAC,CAAC,CAAC;IA2Cb,OAAO,CAAC,MAAM;IAmCd,OAAO,CAAC,mBAAmB;IAO3B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAoB3B;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,oFAAoF;IACpF,UAAU,IAAI,MAAM,EAAE;IAQtB,4DAA4D;IAC5D,WAAW,IAAI,MAAM,EAAE;IAIvB,oEAAoE;IACpE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,2CAA2C;IAC3C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,2CAA2C;IAC3C,IAAI,OAAO,IAAI,MAAM,CAEpB;CACJ"}