@catbee/utils 0.0.1

package/build/esm/utils/async.utils.js

@@ -0,0 +1,474 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+/**
+ * Delays execution for a specified number of milliseconds.
+ *
+ * @param {number} ms - The number of milliseconds to sleep.
+ * @returns {Promise<void>} A Promise that resolves after the given time.
+ */
+export var sleep = function (ms) {
+    return new Promise(function (resolve) { return setTimeout(resolve, ms); });
+};
+/**
+ * Creates a debounced version of a function that delays its execution.
+ * Provides `.cancel()` and `.flush()` methods.
+ *
+ * @template T
+ * @param {T} fn - The function to debounce.
+ * @param {number} delay - Delay in milliseconds.
+ * @returns {T & { cancel: () => void; flush: () => void }} A debounced function.
+ */
+export function debounce(fn, delay) {
+    var timer = null;
+    var pendingArgs = null;
+    function debounced() {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        pendingArgs = args;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(function () {
+            fn.apply(void 0, __spreadArray([], __read(pendingArgs), false));
+            timer = null;
+        }, delay);
+    }
+    debounced.cancel = function () {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        pendingArgs = null;
+    };
+    debounced.flush = function () {
+        if (timer) {
+            clearTimeout(timer);
+            fn.apply(void 0, __spreadArray([], __read(pendingArgs), false));
+            timer = null;
+            pendingArgs = null;
+        }
+    };
+    return debounced;
+}
+/**
+ * Creates a throttled version of a function that limits its execution rate.
+ * Allows control over leading/trailing invocation.
+ *
+ * @template T
+ * @param {T} fn - The function to throttle.
+ * @param {number} limit - Minimum time between calls in milliseconds.
+ * @param {{ leading?: boolean, trailing?: boolean }} [opts] - Options for leading/trailing edge throttling.
+ * @returns {(...args: Parameters<T>) => void} A throttled function.
+ */
+export function throttle(fn, limit, opts) {
+    if (opts === void 0) { opts = {
+        leading: true,
+        trailing: false,
+    }; }
+    var lastCall = 0;
+    var timer = null;
+    var savedArgs = null;
+    return function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var now = Date.now();
+        var _a = opts.leading, leading = _a === void 0 ? true : _a, _b = opts.trailing, trailing = _b === void 0 ? false : _b;
+        if (!lastCall && !leading)
+            lastCall = now;
+        var remaining = limit - (now - lastCall);
+        if (remaining <= 0) {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            lastCall = now;
+            fn.apply(void 0, __spreadArray([], __read(args), false));
+        }
+        else if (trailing) {
+            savedArgs = args;
+            if (!timer) {
+                timer = setTimeout(function () {
+                    lastCall = leading ? Date.now() : 0;
+                    timer = null;
+                    if (savedArgs)
+                        fn.apply(void 0, __spreadArray([], __read(savedArgs), false));
+                }, remaining);
+            }
+        }
+    };
+}
+/**
+ * Retries an asynchronous function a given number of times with optional delay/backoff.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn - The async function to retry.
+ * @param {number} [retries=3] - Number of retry attempts.
+ * @param {number} [delay=500] - Delay in milliseconds between retries.
+ * @param {boolean} [backoff=false] - Use exponential backoff between attempts.
+ * @param {(error: unknown, attempt: number) => void} [onRetry] - Callback for each retry attempt.
+ * @returns {Promise<T>} The result of the async function if successful.
+ * @throws {*} The last encountered error if all retries fail.
+ */
+export function retry(fn_1) {
+    return __awaiter(this, arguments, void 0, function (fn, retries, delay, backoff, onRetry) {
+        var i, e_1;
+        if (retries === void 0) { retries = 3; }
+        if (delay === void 0) { delay = 500; }
+        if (backoff === void 0) { backoff = false; }
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    i = 0;
+                    _a.label = 1;
+                case 1:
+                    if (!(i < retries)) return [3 /*break*/, 7];
+                    _a.label = 2;
+                case 2:
+                    _a.trys.push([2, 4, , 6]);
+                    return [4 /*yield*/, fn()];
+                case 3: return [2 /*return*/, _a.sent()];
+                case 4:
+                    e_1 = _a.sent();
+                    if (i === retries - 1)
+                        throw e_1;
+                    if (onRetry)
+                        onRetry(e_1, i + 1);
+                    return [4 /*yield*/, sleep(backoff ? delay * Math.pow(2, i) : delay)];
+                case 5:
+                    _a.sent();
+                    return [3 /*break*/, 6];
+                case 6:
+                    i++;
+                    return [3 /*break*/, 1];
+                case 7: throw new Error("Retry failed"); // should never reach here
+            }
+        });
+    });
+}
+/**
+ * Wraps a promise and rejects it if it doesn't resolve within the specified timeout.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The original promise.
+ * @param {number} ms - Timeout in milliseconds.
+ * @param {string} [message="Operation timed out"] - Optional timeout message.
+ * @returns {Promise<T>} A promise that resolves or rejects within the timeout.
+ */
+export function withTimeout(promise, ms, message) {
+    if (message === void 0) { message = "Operation timed out"; }
+    return new Promise(function (resolve, reject) {
+        var timeoutHandle = setTimeout(function () { return reject(new Error(message)); }, ms);
+        promise
+            .then(function (result) {
+            clearTimeout(timeoutHandle);
+            resolve(result);
+        })
+            .catch(function (err) {
+            clearTimeout(timeoutHandle);
+            reject(err);
+        });
+    });
+}
+/**
+ * Executes async tasks in true batches.
+ * Each batch runs in parallel, but batches run sequentially.
+ * All tasks in a batch start at the same time, next batch waits for full completion.
+ * NOTE: For more granular concurrency, use a "queue" or "pooled" approach.
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} tasks - An array of functions that return Promises.
+ * @param {number} limit - Number of tasks to run in parallel per batch.
+ * @returns {Promise<T[]>} A promise that resolves to an array of resolved values.
+ */
+export function runInBatches(tasks, limit) {
+    return __awaiter(this, void 0, void 0, function () {
+        var results, i, batch, batchResults;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    results = [];
+                    i = 0;
+                    _a.label = 1;
+                case 1:
+                    if (!(i < tasks.length)) return [3 /*break*/, 4];
+                    batch = tasks.slice(i, i + limit);
+                    return [4 /*yield*/, Promise.all(batch.map(function (fn) { return fn(); }))];
+                case 2:
+                    batchResults = _a.sent();
+                    results.push.apply(results, __spreadArray([], __read(batchResults), false));
+                    _a.label = 3;
+                case 3:
+                    i += limit;
+                    return [3 /*break*/, 1];
+                case 4: return [2 /*return*/, results];
+            }
+        });
+    });
+}
+/**
+ * Wraps a function and ensures it is only called once at a time.
+ * Calls made while one is in progress will wait for the same Promise.
+ * Optionally, new calls can be dropped while in progress (drop=true).
+ *
+ * @template TArgs
+ * @template TResult
+ * @param {(...args: TArgs) => Promise<TResult>} fn - The async function to wrap.
+ * @param {boolean} [drop=false] - If true, new calls while one is pending are rejected.
+ * @returns {(...args: TArgs) => Promise<TResult>} A wrapped function with singleton behavior.
+ */
+export function singletonAsync(fn, drop) {
+    var _this = this;
+    if (drop === void 0) { drop = false; }
+    var promise = null;
+    return function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return __awaiter(_this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                if (!promise) {
+                    promise = fn.apply(void 0, __spreadArray([], __read(args), false)).finally(function () {
+                        promise = null;
+                    });
+                }
+                else if (drop) {
+                    return [2 /*return*/, Promise.reject(new Error("Busy: function already running"))];
+                }
+                return [2 /*return*/, promise];
+            });
+        });
+    };
+}
+/**
+ * Resolves a list of async tasks in parallel, returning both resolved and rejected results.
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.
+ * @returns {Promise<PromiseSettledResult<T>[]>} Results including status and value/reason.
+ */
+export function settleAll(tasks) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            return [2 /*return*/, Promise.allSettled(tasks.map(function (task) { return task(); }))];
+        });
+    });
+}
+/**
+ * A simple task queue that executes async tasks with a concurrency limit.
+ * Exposes pause, resume, and queue length getters.
+ *
+ * @param {number} limit - Maximum number of concurrent tasks.
+ * @returns {function & { pause: () => void, resume: () => void, length: number, isPaused: boolean }}
+ *   Enqueue function plus queue controls.
+ */
+export function createTaskQueue(limit) {
+    var queue = [];
+    var activeCount = 0;
+    var paused = false;
+    var state = {
+        /**
+         * Pause task processing.
+         */
+        pause: function () {
+            paused = true;
+        },
+        /**
+         * Resume task processing.
+         */
+        resume: function () {
+            paused = false;
+            next();
+        },
+        /**
+         * The current length of the queue.
+         * @type {number}
+         */
+        get length() {
+            return queue.length;
+        },
+        /**
+         * Whether the queue is currently paused.
+         * @type {boolean}
+         */
+        get isPaused() {
+            return paused;
+        },
+    };
+    var next = function () {
+        if (paused || queue.length === 0 || activeCount >= limit)
+            return;
+        var task = queue.shift();
+        activeCount++;
+        task().finally(function () {
+            activeCount--;
+            next();
+        });
+    };
+    /**
+     * Enqueues a new async task to the queue.
+     *
+     * @template T
+     * @param {() => Promise<T>} taskFn - The async task function.
+     * @returns {Promise<T>} Promise resolving when task completes.
+     */
+    var enqueue = function (taskFn) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                return [2 /*return*/, new Promise(function (resolve, reject) {
+                        queue.push(function () { return __awaiter(_this, void 0, void 0, function () {
+                            var result, err_1;
+                            return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0:
+                                        _a.trys.push([0, 2, , 3]);
+                                        return [4 /*yield*/, taskFn()];
+                                    case 1:
+                                        result = _a.sent();
+                                        resolve(result);
+                                        return [3 /*break*/, 3];
+                                    case 2:
+                                        err_1 = _a.sent();
+                                        reject(err_1);
+                                        return [3 /*break*/, 3];
+                                    case 3: return [2 /*return*/];
+                                }
+                            });
+                        }); });
+                        next();
+                    })];
+            });
+        });
+    };
+    enqueue.pause = state.pause;
+    enqueue.resume = state.resume;
+    Object.defineProperty(enqueue, "length", {
+        get: function () { return queue.length; },
+    });
+    Object.defineProperty(enqueue, "isPaused", {
+        get: function () { return paused; },
+    });
+    return enqueue;
+}
+/**
+ * Executes async functions sequentially and collects results.
+ * Useful when order matters or tasks depend on each other.
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.
+ * @returns {Promise<T[]>} Array of resolved values.
+ */
+export function runInSeries(tasks) {
+    return __awaiter(this, void 0, void 0, function () {
+        var results, tasks_1, tasks_1_1, task, _a, _b, e_2_1;
+        var e_2, _c;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
+                case 0:
+                    results = [];
+                    _d.label = 1;
+                case 1:
+                    _d.trys.push([1, 6, 7, 8]);
+                    tasks_1 = __values(tasks), tasks_1_1 = tasks_1.next();
+                    _d.label = 2;
+                case 2:
+                    if (!!tasks_1_1.done) return [3 /*break*/, 5];
+                    task = tasks_1_1.value;
+                    _b = (_a = results).push;
+                    return [4 /*yield*/, task()];
+                case 3:
+                    _b.apply(_a, [_d.sent()]);
+                    _d.label = 4;
+                case 4:
+                    tasks_1_1 = tasks_1.next();
+                    return [3 /*break*/, 2];
+                case 5: return [3 /*break*/, 8];
+                case 6:
+                    e_2_1 = _d.sent();
+                    e_2 = { error: e_2_1 };
+                    return [3 /*break*/, 8];
+                case 7:
+                    try {
+                        if (tasks_1_1 && !tasks_1_1.done && (_c = tasks_1.return)) _c.call(tasks_1);
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                    return [7 /*endfinally*/];
+                case 8: return [2 /*return*/, results];
+            }
+        });
+    });
+}
+//# sourceMappingURL=async.utils.js.map

package/build/esm/utils/async.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.utils.js","sourceRoot":"","sources":["../../../src/utils/async.utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,MAAM,CAAC,IAAM,KAAK,GAAG,UAAC,EAAU;IAC9B,OAAA,IAAI,OAAO,CAAC,UAAC,OAAO,IAAK,OAAA,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,EAAvB,CAAuB,CAAC;AAAjD,CAAiD,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,EAAK,EACL,KAAa;IAEb,IAAI,KAAK,GAA0B,IAAI,CAAC;IACxC,IAAI,WAAW,GAAyB,IAAI,CAAC;IAE7C,SAAS,SAAS;QAAC,cAAsB;aAAtB,UAAsB,EAAtB,qBAAsB,EAAtB,IAAsB;YAAtB,yBAAsB;;QACvC,WAAW,GAAG,IAAI,CAAC;QACnB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,GAAG,UAAU,CAAC;YACjB,EAAE,wCAAK,WAA6B,WAAE;YACtC,KAAK,GAAG,IAAI,CAAC;QACf,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;IAED,SAAS,CAAC,MAAM,GAAG;QACjB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,GAAG,IAAI,CAAC;QACb,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC,CAAC;IAEF,SAAS,CAAC,KAAK,GAAG;QAChB,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,EAAE,wCAAK,WAA6B,WAAE;YACtC,KAAK,GAAG,IAAI,CAAC;YACb,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,SAGN,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CACtB,EAAK,EACL,KAAa,EACb,IAGC;IAHD,qBAAA,EAAA;QACE,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,KAAK;KAChB;IAED,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,GAA0B,IAAI,CAAC;IACxC,IAAI,SAAS,GAAyB,IAAI,CAAC;IAE3C,OAAO;QAAU,cAAsB;aAAtB,UAAsB,EAAtB,qBAAsB,EAAtB,IAAsB;YAAtB,yBAAsB;;QACrC,IAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACf,IAAA,KAAqC,IAAI,QAA3B,EAAd,OAAO,mBAAG,IAAI,KAAA,EAAE,KAAqB,IAAI,SAAT,EAAhB,QAAQ,mBAAG,KAAK,KAAA,CAAU;QAElD,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO;YAAE,QAAQ,GAAG,GAAG,CAAC;QAE1C,IAAM,SAAS,GAAG,KAAK,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC;QAE3C,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YACnB,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;YACD,QAAQ,GAAG,GAAG,CAAC;YACf,EAAE,wCAAI,IAAI,WAAE;QACd,CAAC;aAAM,IAAI,QAAQ,EAAE,CAAC;YACpB,SAAS,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG,UAAU,CAAC;oBACjB,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;oBACpC,KAAK,GAAG,IAAI,CAAC;oBACb,IAAI,SAAS;wBAAE,EAAE,wCAAI,SAAS,WAAE;gBAClC,CAAC,EAAE,SAAS,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAgB,KAAK;wDACzB,EAAoB,EACpB,OAAW,EACX,KAAW,EACX,OAAe,EACf,OAAmD;;QAHnD,wBAAA,EAAA,WAAW;QACX,sBAAA,EAAA,WAAW;QACX,wBAAA,EAAA,eAAe;;;;oBAGN,CAAC,GAAG,CAAC;;;yBAAE,CAAA,CAAC,GAAG,OAAO,CAAA;;;;oBAEhB,qBAAM,EAAE,EAAE,EAAA;wBAAjB,sBAAO,SAAU,EAAC;;;oBAElB,IAAI,CAAC,KAAK,OAAO,GAAG,CAAC;wBAAE,MAAM,GAAC,CAAC;oBAC/B,IAAI,OAAO;wBAAE,OAAO,CAAC,GAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;oBAC/B,qBAAM,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAA;;oBAArD,SAAqD,CAAC;;;oBAN7B,CAAC,EAAE,CAAA;;wBAShC,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,0BAA0B;;;;CAC5D;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,OAAmB,EACnB,EAAU,EACV,OAA+B;IAA/B,wBAAA,EAAA,+BAA+B;IAE/B,OAAO,IAAI,OAAO,CAAI,UAAC,OAAO,EAAE,MAAM;QACpC,IAAM,aAAa,GAAG,UAAU,CAAC,cAAM,OAAA,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,EAA1B,CAA0B,EAAE,EAAE,CAAC,CAAC;QACvE,OAAO;aACJ,IAAI,CAAC,UAAC,MAAM;YACX,YAAY,CAAC,aAAa,CAAC,CAAC;YAC5B,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC,CAAC;aACD,KAAK,CAAC,UAAC,GAAG;YACT,YAAY,CAAC,aAAa,CAAC,CAAC;YAC5B,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAgB,YAAY,CAChC,KAA2B,EAC3B,KAAa;;;;;;oBAEP,OAAO,GAAQ,EAAE,CAAC;oBACf,CAAC,GAAG,CAAC;;;yBAAE,CAAA,CAAC,GAAG,KAAK,CAAC,MAAM,CAAA;oBACxB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC;oBACnB,qBAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,UAAC,EAAE,IAAK,OAAA,EAAE,EAAE,EAAJ,CAAI,CAAC,CAAC,EAAA;;oBAAzD,YAAY,GAAG,SAA0C;oBAC/D,OAAO,CAAC,IAAI,OAAZ,OAAO,2BAAS,YAAY,WAAE;;;oBAHE,CAAC,IAAI,KAAK,CAAA;;wBAK5C,sBAAO,OAAO,EAAC;;;;CAChB;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,EAAwC,EACxC,IAAqB;IAFvB,iBAgBC;IAdC,qBAAA,EAAA,YAAqB;IAErB,IAAI,OAAO,GAA4B,IAAI,CAAC;IAE5C,OAAO;QAAO,cAAc;aAAd,UAAc,EAAd,qBAAc,EAAd,IAAc;YAAd,yBAAc;;;;gBAC1B,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,GAAG,EAAE,wCAAI,IAAI,WAAE,OAAO,CAAC;wBAC5B,OAAO,GAAG,IAAI,CAAC;oBACjB,CAAC,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,IAAI,EAAE,CAAC;oBAChB,sBAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,EAAC;gBACrE,CAAC;gBACD,sBAAO,OAAO,EAAC;;;KAChB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAgB,SAAS,CAC7B,KAA2B;;;YAE3B,sBAAO,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,UAAC,IAAI,IAAK,OAAA,IAAI,EAAE,EAAN,CAAM,CAAC,CAAC,EAAC;;;CACxD;AAUD;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,IAAM,KAAK,GAAG;QACZ;;WAEG;QACH,KAAK;YACH,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD;;WAEG;QACH,MAAM;YACJ,MAAM,GAAG,KAAK,CAAC;YACf,IAAI,EAAE,CAAC;QACT,CAAC;QACD;;;WAGG;QACH,IAAI,MAAM;YACR,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QACD;;;WAGG;QACH,IAAI,QAAQ;YACV,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;IAEF,IAAM,IAAI,GAAG;QACX,IAAI,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,IAAI,KAAK;YAAE,OAAO;QACjE,IAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAC5B,WAAW,EAAE,CAAC;QACd,IAAI,EAAE,CAAC,OAAO,CAAC;YACb,WAAW,EAAE,CAAC;YACd,IAAI,EAAE,CAAC;QACT,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF;;;;;;OAMG;IACH,IAAM,OAAO,GAAG,UAAmB,MAAwB;;;;gBACzD,sBAAO,IAAI,OAAO,CAAI,UAAC,OAAO,EAAE,MAAM;wBACpC,KAAK,CAAC,IAAI,CAAC;;;;;;wCAEQ,qBAAM,MAAM,EAAE,EAAA;;wCAAvB,MAAM,GAAG,SAAc;wCAC7B,OAAO,CAAC,MAAM,CAAC,CAAC;;;;wCAEhB,MAAM,CAAC,KAAG,CAAC,CAAC;;;;;6BAEf,CAAC,CAAC;wBACH,IAAI,EAAE,CAAC;oBACT,CAAC,CAAC,EAAC;;;KACJ,CAAC;IAEF,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC5B,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC9B,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,QAAQ,EAAE;QACvC,GAAG,EAAE,cAAM,OAAA,KAAK,CAAC,MAAM,EAAZ,CAAY;KACxB,CAAC,CAAC;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE;QACzC,GAAG,EAAE,cAAM,OAAA,MAAM,EAAN,CAAM;KAClB,CAAC,CAAC;IAEH,OAAO,OAAoB,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAgB,WAAW,CAC/B,KAA2B;;;;;;;oBAErB,OAAO,GAAQ,EAAE,CAAC;;;;oBACL,UAAA,SAAA,KAAK,CAAA;;;;oBAAb,IAAI;oBACb,KAAA,CAAA,KAAA,OAAO,CAAA,CAAC,IAAI,CAAA;oBAAC,qBAAM,IAAI,EAAE,EAAA;;oBAAzB,cAAa,SAAY,EAAC,CAAC;;;;;;;;;;;;;;;;wBAE7B,sBAAO,OAAO,EAAC;;;;CAChB","sourcesContent":["/**\n * Delays execution for a specified number of milliseconds.\n *\n * @param {number} ms - The number of milliseconds to sleep.\n * @returns {Promise<void>} A Promise that resolves after the given time.\n */\nexport const sleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Creates a debounced version of a function that delays its execution.\n * Provides `.cancel()` and `.flush()` methods.\n *\n * @template T\n * @param {T} fn - The function to debounce.\n * @param {number} delay - Delay in milliseconds.\n * @returns {T & { cancel: () => void; flush: () => void }} A debounced function.\n */\nexport function debounce<T extends (...args: any[]) => void>(\n  fn: T,\n  delay: number,\n) {\n  let timer: NodeJS.Timeout | null = null;\n  let pendingArgs: Parameters<T> | null = null;\n\n  function debounced(...args: Parameters<T>) {\n    pendingArgs = args;\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(() => {\n      fn(...(pendingArgs as Parameters<T>));\n      timer = null;\n    }, delay);\n  }\n\n  debounced.cancel = () => {\n    if (timer) clearTimeout(timer);\n    timer = null;\n    pendingArgs = null;\n  };\n\n  debounced.flush = () => {\n    if (timer) {\n      clearTimeout(timer);\n      fn(...(pendingArgs as Parameters<T>));\n      timer = null;\n      pendingArgs = null;\n    }\n  };\n\n  return debounced as typeof debounced & {\n    cancel: () => void;\n    flush: () => void;\n  };\n}\n\n/**\n * Creates a throttled version of a function that limits its execution rate.\n * Allows control over leading/trailing invocation.\n *\n * @template T\n * @param {T} fn - The function to throttle.\n * @param {number} limit - Minimum time between calls in milliseconds.\n * @param {{ leading?: boolean, trailing?: boolean }} [opts] - Options for leading/trailing edge throttling.\n * @returns {(...args: Parameters<T>) => void} A throttled function.\n */\nexport function throttle<T extends (...args: any[]) => void>(\n  fn: T,\n  limit: number,\n  opts: { leading?: boolean; trailing?: boolean } = {\n    leading: true,\n    trailing: false,\n  },\n): (...args: Parameters<T>) => void {\n  let lastCall = 0;\n  let timer: NodeJS.Timeout | null = null;\n  let savedArgs: Parameters<T> | null = null;\n\n  return function (...args: Parameters<T>) {\n    const now = Date.now();\n    const { leading = true, trailing = false } = opts;\n\n    if (!lastCall && !leading) lastCall = now;\n\n    const remaining = limit - (now - lastCall);\n\n    if (remaining <= 0) {\n      if (timer) {\n        clearTimeout(timer);\n        timer = null;\n      }\n      lastCall = now;\n      fn(...args);\n    } else if (trailing) {\n      savedArgs = args;\n      if (!timer) {\n        timer = setTimeout(() => {\n          lastCall = leading ? Date.now() : 0;\n          timer = null;\n          if (savedArgs) fn(...savedArgs);\n        }, remaining);\n      }\n    }\n  };\n}\n\n/**\n * Retries an asynchronous function a given number of times with optional delay/backoff.\n *\n * @template T\n * @param {() => Promise<T>} fn - The async function to retry.\n * @param {number} [retries=3] - Number of retry attempts.\n * @param {number} [delay=500] - Delay in milliseconds between retries.\n * @param {boolean} [backoff=false] - Use exponential backoff between attempts.\n * @param {(error: unknown, attempt: number) => void} [onRetry] - Callback for each retry attempt.\n * @returns {Promise<T>} The result of the async function if successful.\n * @throws {*} The last encountered error if all retries fail.\n */\nexport async function retry<T>(\n  fn: () => Promise<T>,\n  retries = 3,\n  delay = 500,\n  backoff = false,\n  onRetry?: (error: unknown, attempt: number) => void,\n): Promise<T> {\n  for (let i = 0; i < retries; i++) {\n    try {\n      return await fn();\n    } catch (e) {\n      if (i === retries - 1) throw e;\n      if (onRetry) onRetry(e, i + 1);\n      await sleep(backoff ? delay * Math.pow(2, i) : delay);\n    }\n  }\n  throw new Error(\"Retry failed\"); // should never reach here\n}\n\n/**\n * Wraps a promise and rejects it if it doesn't resolve within the specified timeout.\n *\n * @template T\n * @param {Promise<T>} promise - The original promise.\n * @param {number} ms - Timeout in milliseconds.\n * @param {string} [message=\"Operation timed out\"] - Optional timeout message.\n * @returns {Promise<T>} A promise that resolves or rejects within the timeout.\n */\nexport function withTimeout<T>(\n  promise: Promise<T>,\n  ms: number,\n  message = \"Operation timed out\",\n): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timeoutHandle = setTimeout(() => reject(new Error(message)), ms);\n    promise\n      .then((result) => {\n        clearTimeout(timeoutHandle);\n        resolve(result);\n      })\n      .catch((err) => {\n        clearTimeout(timeoutHandle);\n        reject(err);\n      });\n  });\n}\n\n/**\n * Executes async tasks in true batches.\n * Each batch runs in parallel, but batches run sequentially.\n * All tasks in a batch start at the same time, next batch waits for full completion.\n * NOTE: For more granular concurrency, use a \"queue\" or \"pooled\" approach.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - An array of functions that return Promises.\n * @param {number} limit - Number of tasks to run in parallel per batch.\n * @returns {Promise<T[]>} A promise that resolves to an array of resolved values.\n */\nexport async function runInBatches<T>(\n  tasks: (() => Promise<T>)[],\n  limit: number,\n): Promise<T[]> {\n  const results: T[] = [];\n  for (let i = 0; i < tasks.length; i += limit) {\n    const batch = tasks.slice(i, i + limit);\n    const batchResults = await Promise.all(batch.map((fn) => fn()));\n    results.push(...batchResults);\n  }\n  return results;\n}\n\n/**\n * Wraps a function and ensures it is only called once at a time.\n * Calls made while one is in progress will wait for the same Promise.\n * Optionally, new calls can be dropped while in progress (drop=true).\n *\n * @template TArgs\n * @template TResult\n * @param {(...args: TArgs) => Promise<TResult>} fn - The async function to wrap.\n * @param {boolean} [drop=false] - If true, new calls while one is pending are rejected.\n * @returns {(...args: TArgs) => Promise<TResult>} A wrapped function with singleton behavior.\n */\nexport function singletonAsync<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => Promise<TResult>,\n  drop: boolean = false,\n): (...args: TArgs) => Promise<TResult> {\n  let promise: Promise<TResult> | null = null;\n\n  return async (...args: TArgs) => {\n    if (!promise) {\n      promise = fn(...args).finally(() => {\n        promise = null;\n      });\n    } else if (drop) {\n      return Promise.reject(new Error(\"Busy: function already running\"));\n    }\n    return promise;\n  };\n}\n\n/**\n * Resolves a list of async tasks in parallel, returning both resolved and rejected results.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.\n * @returns {Promise<PromiseSettledResult<T>[]>} Results including status and value/reason.\n */\nexport async function settleAll<T>(\n  tasks: (() => Promise<T>)[],\n): Promise<PromiseSettledResult<T>[]> {\n  return Promise.allSettled(tasks.map((task) => task()));\n}\n\nexport interface TaskQueue {\n  <T>(taskFn: () => Promise<T>): Promise<T>;\n  pause: () => void;\n  resume: () => void;\n  readonly length: number;\n  readonly isPaused: boolean;\n}\n\n/**\n * A simple task queue that executes async tasks with a concurrency limit.\n * Exposes pause, resume, and queue length getters.\n *\n * @param {number} limit - Maximum number of concurrent tasks.\n * @returns {function & { pause: () => void, resume: () => void, length: number, isPaused: boolean }}\n *   Enqueue function plus queue controls.\n */\nexport function createTaskQueue(limit: number): TaskQueue {\n  const queue: (() => Promise<void>)[] = [];\n  let activeCount = 0;\n  let paused = false;\n\n  const state = {\n    /**\n     * Pause task processing.\n     */\n    pause() {\n      paused = true;\n    },\n    /**\n     * Resume task processing.\n     */\n    resume() {\n      paused = false;\n      next();\n    },\n    /**\n     * The current length of the queue.\n     * @type {number}\n     */\n    get length() {\n      return queue.length;\n    },\n    /**\n     * Whether the queue is currently paused.\n     * @type {boolean}\n     */\n    get isPaused() {\n      return paused;\n    },\n  };\n\n  const next = () => {\n    if (paused || queue.length === 0 || activeCount >= limit) return;\n    const task = queue.shift()!;\n    activeCount++;\n    task().finally(() => {\n      activeCount--;\n      next();\n    });\n  };\n\n  /**\n   * Enqueues a new async task to the queue.\n   *\n   * @template T\n   * @param {() => Promise<T>} taskFn - The async task function.\n   * @returns {Promise<T>} Promise resolving when task completes.\n   */\n  const enqueue = async function <T>(taskFn: () => Promise<T>): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      queue.push(async () => {\n        try {\n          const result = await taskFn();\n          resolve(result);\n        } catch (err) {\n          reject(err);\n        }\n      });\n      next();\n    });\n  };\n\n  enqueue.pause = state.pause;\n  enqueue.resume = state.resume;\n  Object.defineProperty(enqueue, \"length\", {\n    get: () => queue.length,\n  });\n  Object.defineProperty(enqueue, \"isPaused\", {\n    get: () => paused,\n  });\n\n  return enqueue as TaskQueue;\n}\n\n/**\n * Executes async functions sequentially and collects results.\n * Useful when order matters or tasks depend on each other.\n *\n * @template T\n * @param {Array<() => Promise<T>>} tasks - Array of promise-returning functions.\n * @returns {Promise<T[]>} Array of resolved values.\n */\nexport async function runInSeries<T>(\n  tasks: (() => Promise<T>)[],\n): Promise<T[]> {\n  const results: T[] = [];\n  for (const task of tasks) {\n    results.push(await task());\n  }\n  return results;\n}\n"]}

package/build/esm/utils/cache.utils.d.ts

@@ -0,0 +1,90 @@
+/**
+ * An in-memory cache with time-to-live (TTL) support for each entry.
+ *
+ * @typeParam K - Type of the key.
+ * @typeParam V - Type of the value.
+ *
+ * @example
+ * const cache = new TTLCache<string, number>(1000);
+ * cache.set("x", 123);
+ * const value = cache.get("x"); // 123
+ */
+export declare class TTLCache<K, V> {
+    private ttlMs;
+    private cache;
+    /**
+     * @param ttlMs - Default time-to-live in milliseconds for cache entries.
+     */
+    constructor(ttlMs?: number);
+    /**
+     * Sets a key-value pair in the cache with the default TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     */
+    set(key: K, value: V): void;
+    /**
+     * Sets a key-value pair in the cache with a custom TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     * @param ttlMs - Time-to-live in milliseconds.
+     */
+    setWithTTL(key: K, value: V, ttlMs: number): void;
+    /**
+     * Retrieves the value for a given key if it hasn't expired.
+     *
+     * @param key - The key to retrieve.
+     * @returns The cached value, or undefined if not found or expired.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Checks if the key exists and hasn't expired.
+     *
+     * @param key - The key to check.
+     * @returns `true` if key exists and is valid, otherwise `false`.
+     */
+    has(key: K): boolean;
+    /**
+     * Deletes a key from the cache.
+     *
+     * @param key - The key to delete.
+     * @returns `true` if the key existed and was removed, `false` otherwise.
+     */
+    delete(key: K): boolean;
+    /**
+     * Clears all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).
+     *
+     * @returns Number of items in the cache (may include expired keys).
+     */
+    size(): number;
+    /**
+     * Removes all expired entries from the cache.
+     *
+     * @returns Number of entries removed.
+     */
+    cleanup(): number;
+    /**
+     * Returns an iterator of all current valid [key, value] pairs.
+     *
+     * @returns IterableIterator<[K, V]>
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Returns an iterator of all current valid keys.
+     *
+     * @returns IterableIterator<K>
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Returns an iterator of all current valid values.
+     *
+     * @returns IterableIterator<V>
+     */
+    values(): IterableIterator<V>;
+}
+//# sourceMappingURL=cache.utils.d.ts.map