@stacks/api-toolkit 1.12.0

package/dist/helpers/events.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onceWhen = onceWhen;
+const node_events_1 = require("node:events");
+// This is a workaround for Node.js versions that do not support Symbol.dispose
+const DisposeSymbol = Symbol.dispose ?? Symbol.for('nodejs.dispose');
+/**
+ * Creates a Promise that resolves when the specified `eventName` is emitted by the `EventEmitter`
+ * and the provided predicate returns `true` for the emitted arguments.
+ *
+ * Similar to [`events.once`](https://nodejs.org/api/events.html#eventsonceemitter-name-options),
+ * but includes support for a predicate function to filter events. Only events for which
+ * the predicate returns `true` will cause the Promise to resolve.
+ *
+ * The resolved value is an array of the arguments emitted with the event.
+ *
+ * Supports typed `EventEmitter`s and optional cancellation via `AbortSignal`.
+ *
+ * @example
+ * ```ts
+ * import { EventEmitter } from 'node:events';
+ *
+ * const emitter = new EventEmitter<{
+ *   myEvent: [id: number, msg: string];
+ * }>();
+ *
+ * setTimeout(() => {
+ *   for (let i = 0; i <= 5; i++) {
+ *     emitter.emit('myEvent', i, `Message ${i}`);
+ *   }
+ * }, 100);
+ *
+ * const [id, msg] = await onceWhen(emitter, 'myEvent', (id, msg) => id === 3);
+ *
+ * // outputs: "Received event with id: 3, message: Message 3"
+ * console.log(`Received event with id: ${id}, message: ${msg}`);
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { EventEmitter } from 'node:events';
+ *
+ * const emitter = new EventEmitter<{ myEvent: [id: number, msg: string] }>();
+ *
+ * const signal = AbortSignal.timeout(10);
+ *
+ * setTimeout(() => emitter.emit('myEvent', 1, 'Hello'), 1000);
+ *
+ * const whenPromise = onceWhen(emitter, 'myEvent', id => id === 1, { signal });
+ *
+ * // This rejects because the signal is aborted before the event is emitted
+ * await expect(whenPromise).rejects.toThrow(signal.reason);
+ * ```
+ */
+function onceWhen(emitter, eventName, predicate, options) {
+    return new Promise((resolve, reject) => {
+        // Immediate abort check
+        if (options?.signal?.aborted) {
+            reject(options.signal.reason ?? new Error('Aborted'));
+            return;
+        }
+        // Cleanup helper: remove both the event listener and the abort listener
+        const cleanup = () => {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            emitter.off(eventName, listener);
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            disposable?.[DisposeSymbol]();
+        };
+        // Abort handler
+        const onAbort = () => {
+            cleanup();
+            reject(options?.signal?.reason ?? new Error('Aborted'));
+        };
+        // Our event listener that checks the predicate
+        const listener = (...args) => {
+            try {
+                if (predicate(...args)) {
+                    cleanup();
+                    resolve(args);
+                }
+            }
+            catch (err) {
+                cleanup();
+                reject(err);
+                return;
+            }
+        };
+        // Install the AbortSignal listener via Node’s helper
+        const disposable = options?.signal ? (0, node_events_1.addAbortListener)(options.signal, onAbort) : undefined;
+        emitter.on(eventName, listener);
+    });
+}
+//# sourceMappingURL=events.js.map

package/dist/helpers/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/helpers/events.ts"],"names":[],"mappings":";;AAqDA,4BAiDC;AAtGD,6CAA6D;AAE7D,+EAA+E;AAC/E,MAAM,aAAa,GAA0B,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,SAAgB,QAAQ,CAItB,OAA+B,EAC/B,SAAY,EACZ,SAA4C,EAC5C,OAAkC;IAElC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,wBAAwB;QACxB,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YAC7B,MAAM,CAAE,OAAO,CAAC,MAAM,CAAC,MAAgB,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YACjE,OAAO;QACT,CAAC;QAED,wEAAwE;QACxE,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,mEAAmE;YAClE,OAAwB,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACnD,mEAAmE;YACnE,UAAU,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC;QAChC,CAAC,CAAC;QAEF,gBAAgB;QAChB,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,OAAO,EAAE,CAAC;YACV,MAAM,CAAE,OAAO,EAAE,MAAM,EAAE,MAAgB,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC;QAEF,+CAA+C;QAC/C,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAiB,EAAE,EAAE;YACxC,IAAI,CAAC;gBACH,IAAI,SAAS,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;oBACvB,OAAO,EAAE,CAAC;oBACV,OAAO,CAAC,IAAI,CAAC,CAAC;gBAChB,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,EAAE,CAAC;gBACV,MAAM,CAAC,GAAY,CAAC,CAAC;gBACrB,OAAO;YACT,CAAC;QACH,CAAC,CAAC;QAEF,qDAAqD;QACrD,MAAM,UAAU,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAA,8BAAgB,EAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE1F,OAAwB,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,7 @@
+export * from './iterators';
+export * from './time';
+export * from './values';
+export * from './is-debugging';
+export * from './events';
+export { WorkerThreadManager } from './worker-thread-manager';
+export type { WorkerPoolModuleInterface } from './worker-thread-manager';

package/dist/helpers/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerThreadManager = void 0;
+__exportStar(require("./iterators"), exports);
+__exportStar(require("./time"), exports);
+__exportStar(require("./values"), exports);
+__exportStar(require("./is-debugging"), exports);
+__exportStar(require("./events"), exports);
+var worker_thread_manager_1 = require("./worker-thread-manager");
+Object.defineProperty(exports, "WorkerThreadManager", { enumerable: true, get: function () { return worker_thread_manager_1.WorkerThreadManager; } });
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,yCAAuB;AACvB,2CAAyB;AACzB,iDAA+B;AAC/B,2CAAyB;AACzB,iEAA8D;AAArD,4HAAA,mBAAmB,OAAA"}

package/dist/helpers/is-debugging.d.ts

@@ -0,0 +1 @@
+export declare function isDebugging(): boolean;

package/dist/helpers/is-debugging.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDebugging = isDebugging;
+/*
+ * Reliable way to check if we are debugging. Supports ts-node and other tools unlike some other
+ * approaches that check argv or env vars. It also lazy-loads the `node:inspector` module to avoid
+ * unnecessary overhead in production environments where this function might not be called.
+ */
+function isDebugging() {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const inspector = require('node:inspector');
+    const url = inspector.url();
+    return url !== undefined;
+}
+//# sourceMappingURL=is-debugging.js.map

package/dist/helpers/is-debugging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-debugging.js","sourceRoot":"","sources":["../../src/helpers/is-debugging.ts"],"names":[],"mappings":";;AAKA,kCAMC;AAXD;;;;GAIG;AACH,SAAgB,WAAW;IAEzB,8DAA8D;IAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAsB,CAAC;IACjE,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC;IAC5B,OAAO,GAAG,KAAK,SAAS,CAAC;AAC3B,CAAC"}

package/dist/helpers/iterators.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Iterate over an array, yielding multiple items at a time. If the size of the given array
+ * is not divisible by the given batch size, then the length of the last items returned will
+ * be smaller than the given batch size, i.e.:
+ * ```typescript
+ * items.length % batchSize
+ * ```
+ * @param items - The array to iterate over.
+ * @param batchSize - Maximum number of items to return at a time.
+ * @param printBenchmark - If we should print benchmark of items per second
+ */
+export declare function batchIterate<T>(items: T[], batchSize: number, printBenchmark?: boolean): Generator<T[]>;
+/**
+ * Iterate over an `AsyncIterable`, yielding multiple items at a time. If the size of the given
+ * array is not divisible by the given batch size, then the length of the last items returned will
+ * be smaller than the given batch size.
+ *
+ * @param items - AsyncIterable
+ * @param batchSize - Batch size
+ * @param printBenchmark - If we should print benchmark of items per second
+ */
+export declare function asyncBatchIterate<T>(items: AsyncIterable<T>, batchSize: number, printBenchmark?: boolean): AsyncGenerator<T[], void, unknown>;
+/**
+ * Convert an `AsyncIterable` to a generator
+ * @param iter - AsyncIterable
+ */
+export declare function asyncIterableToGenerator<T>(iter: AsyncIterable<T>): AsyncGenerator<Awaited<T>, void, unknown>;

package/dist/helpers/iterators.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchIterate = batchIterate;
+exports.asyncBatchIterate = asyncBatchIterate;
+exports.asyncIterableToGenerator = asyncIterableToGenerator;
+const logger_1 = require("../logger");
+const values_1 = require("./values");
+/**
+ * Iterate over an array, yielding multiple items at a time. If the size of the given array
+ * is not divisible by the given batch size, then the length of the last items returned will
+ * be smaller than the given batch size, i.e.:
+ * ```typescript
+ * items.length % batchSize
+ * ```
+ * @param items - The array to iterate over.
+ * @param batchSize - Maximum number of items to return at a time.
+ * @param printBenchmark - If we should print benchmark of items per second
+ */
+function* batchIterate(items, batchSize, printBenchmark = values_1.isDevEnv) {
+    if (items.length === 0)
+        return;
+    const startTime = Date.now();
+    for (let i = 0; i < items.length;) {
+        const itemsRemaining = items.length - i;
+        const sliceSize = Math.min(batchSize, itemsRemaining);
+        yield items.slice(i, i + sliceSize);
+        i += sliceSize;
+    }
+    if (printBenchmark) {
+        const itemsPerSecond = Math.round((items.length / (Date.now() - startTime)) * 1000);
+        const caller = new Error().stack?.split('at ')[3].trim();
+        logger_1.logger.debug(`Iterated ${itemsPerSecond} items/second at ${caller}`);
+    }
+}
+/**
+ * Iterate over an `AsyncIterable`, yielding multiple items at a time. If the size of the given
+ * array is not divisible by the given batch size, then the length of the last items returned will
+ * be smaller than the given batch size.
+ *
+ * @param items - AsyncIterable
+ * @param batchSize - Batch size
+ * @param printBenchmark - If we should print benchmark of items per second
+ */
+async function* asyncBatchIterate(items, batchSize, printBenchmark = values_1.isDevEnv) {
+    const startTime = Date.now();
+    let itemCount = 0;
+    let itemBatch = [];
+    for await (const item of items) {
+        itemBatch.push(item);
+        itemCount++;
+        if (itemBatch.length >= batchSize) {
+            yield itemBatch;
+            itemBatch = [];
+            if (printBenchmark) {
+                const itemsPerSecond = Math.round((itemCount / (Date.now() - startTime)) * 1000);
+                const caller = new Error().stack?.split('at ')[3].trim();
+                logger_1.logger.debug(`Iterated ${itemsPerSecond} items/second at ${caller}`);
+            }
+        }
+    }
+    if (itemBatch.length > 0) {
+        yield itemBatch;
+    }
+}
+/**
+ * Convert an `AsyncIterable` to a generator
+ * @param iter - AsyncIterable
+ */
+async function* asyncIterableToGenerator(iter) {
+    for await (const entry of iter) {
+        yield entry;
+    }
+}
+//# sourceMappingURL=iterators.js.map

package/dist/helpers/iterators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterators.js","sourceRoot":"","sources":["../../src/helpers/iterators.ts"],"names":[],"mappings":";;AAcA,oCAkBC;AAWD,8CAwBC;AAMD,4DAIC;AA7ED,sCAAmC;AACnC,qCAAoC;AAEpC;;;;;;;;;;GAUG;AACH,QAAe,CAAC,CAAC,YAAY,CAC3B,KAAU,EACV,SAAiB,EACjB,cAAc,GAAG,iBAAQ;IAEzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAI,CAAC;QACnC,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACxC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACtD,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC;QACpC,CAAC,IAAI,SAAS,CAAC;IACjB,CAAC;IACD,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACpF,MAAM,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzD,eAAM,CAAC,KAAK,CAAC,YAAY,cAAc,oBAAoB,MAAM,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,SAAS,CAAC,CAAC,iBAAiB,CACtC,KAAuB,EACvB,SAAiB,EACjB,cAAc,GAAG,iBAAQ;IAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,SAAS,GAAQ,EAAE,CAAC;IACxB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC/B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,SAAS,EAAE,CAAC;QACZ,IAAI,SAAS,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,SAAS,CAAC;YAChB,SAAS,GAAG,EAAE,CAAC;YACf,IAAI,cAAc,EAAE,CAAC;gBACnB,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBACjF,MAAM,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACzD,eAAM,CAAC,KAAK,CAAC,YAAY,cAAc,oBAAoB,MAAM,EAAE,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,SAAS,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;GAGG;AACI,KAAK,SAAS,CAAC,CAAC,wBAAwB,CAAI,IAAsB;IACvE,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QAC/B,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/helpers/serialize-error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Custom errors can only be deserialized correctly if they are registered here.
+ */
+export declare function addKnownErrorConstructor(constructor: new (message?: string, ..._arguments: unknown[]) => Error): void;
+type SerializedError = {
+    constructorName: string;
+    name: string;
+    message: string;
+    stack: string;
+    [key: string]: any;
+};
+export type ErrorLike = {
+    name: string;
+    message: string;
+    stack: string;
+};
+export declare function isErrorLike(value: unknown): value is ErrorLike;
+export declare function serializeError(subject: Error): SerializedError;
+export declare function deserializeError(subject: ErrorLike): Error;
+export {};

package/dist/helpers/serialize-error.js

@@ -0,0 +1,135 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addKnownErrorConstructor = addKnownErrorConstructor;
+exports.isErrorLike = isErrorLike;
+exports.serializeError = serializeError;
+exports.deserializeError = deserializeError;
+const errorConstructors = new Map([
+    // Native ES errors https://262.ecma-international.org/12.0/#sec-well-known-intrinsic-objects
+    Error,
+    EvalError,
+    RangeError,
+    ReferenceError,
+    SyntaxError,
+    TypeError,
+    URIError,
+    AggregateError,
+    // Built-in errors
+    globalThis.DOMException,
+    // Node-specific errors https://nodejs.org/api/errors.html
+    globalThis.AssertionError,
+    globalThis.SystemError,
+]
+    // Non-native Errors are used with `globalThis` because they might be missing. This filter drops them when undefined.
+    .filter(Boolean)
+    .map(constructor => [constructor.name, constructor]));
+/**
+ * Custom errors can only be deserialized correctly if they are registered here.
+ */
+function addKnownErrorConstructor(constructor) {
+    try {
+        new constructor();
+    }
+    catch (error) {
+        throw new Error(`The error constructor "${constructor.name}" is not compatible`, {
+            cause: error,
+        });
+    }
+    errorConstructors.set(constructor.name, constructor);
+}
+const commonProperties = {
+    name: false,
+    message: false,
+    stack: false,
+    code: true,
+    cause: false,
+    errors: false,
+};
+function isErrorLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'name' in value &&
+        'message' in value &&
+        'stack' in value &&
+        typeof value.name === 'string' &&
+        typeof value.message === 'string' &&
+        typeof value.stack === 'string');
+}
+function serializeError(subject) {
+    if (!isErrorLike(subject)) {
+        // If the subject is not an error, for example `throw "boom", then we throw.
+        // This function should only be passed error objects, callers can use `isErrorLike`.
+        throw new TypeError('Failed to serialize error, expected an error object');
+    }
+    const data = {
+        constructorName: subject.constructor.name ?? 'Error', // new field
+        name: subject.name,
+        message: '',
+        stack: '',
+    };
+    for (const key of Object.keys(commonProperties)) {
+        if (key in subject)
+            data[key] = deepSerialize(subject[key]);
+    }
+    // Include any other enumerable own properties
+    for (const key of Object.keys(subject)) {
+        if (!(key in data))
+            data[key] = deepSerialize(subject[key]);
+    }
+    return data;
+}
+function deserializeError(subject) {
+    if (!isErrorLike(subject)) {
+        // If the subject is not an error, for example `throw "boom", then we throw.
+        // This function should only be passed error objects, callers can use `isErrorLike`.
+        throw new TypeError('Failed to desserialize error, expected an error object');
+    }
+    let con = errorConstructors.get(subject.constructorName ?? subject.name);
+    if (!con) {
+        // If the constructor is not found, use the generic Error constructor
+        con = Error;
+        console.error(`Error constructor "${subject.name}" not found during worker error deserialization, using generic Error constructor`);
+    }
+    const output = Object.create(con.prototype);
+    for (const [key, enumerable] of Object.entries(commonProperties)) {
+        if (key in subject) {
+            Object.defineProperty(output, key, {
+                enumerable,
+                configurable: true,
+                writable: true,
+                value: deepDeserialize(subject[key]),
+            });
+        }
+    }
+    // Add any other properties (custom props not in commonProperties)
+    for (const key of Object.keys(subject)) {
+        if (!(key in commonProperties)) {
+            output[key] = deepDeserialize(subject[key]);
+        }
+    }
+    return output;
+}
+function deepSerialize(value) {
+    if (Array.isArray(value))
+        return value.map(deepSerialize);
+    if (isErrorLike(value))
+        return serializeError(value);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, deepSerialize(v)]));
+    }
+    return value;
+}
+function deepDeserialize(value) {
+    if (Array.isArray(value))
+        return value.map(deepDeserialize);
+    if (isErrorLike(value))
+        return deserializeError(value);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, deepDeserialize(v)]));
+    }
+    return value;
+}
+//# sourceMappingURL=serialize-error.js.map

package/dist/helpers/serialize-error.js.map

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

package/dist/helpers/time.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Wait a set amount of milliseconds or until the timer is aborted.
+ * @param ms - Number of milliseconds to wait
+ * @param abort - Abort controller
+ * @returns Promise
+ */
+export declare function timeout(ms: number, abort?: AbortController | AbortSignal): Promise<void>;
+/**
+ * Time the execution of an async function.
+ * @param fn - Async function
+ * @param onFinish - Callback with elapsed milliseconds
+ * @returns Promise
+ */
+export declare function time<T>(fn: () => Promise<T>, onFinish: (elapsedMs: number) => void): Promise<T>;
+/**
+ * Set an execution time limit for a promise.
+ * @param promise - The promise being capped to `timeoutMs` max execution time
+ * @param timeoutMs - Timeout limit in milliseconds
+ * @param wait - If we should wait another `timeoutMs` period for `promise` to resolve
+ * @param waitHandler - If `wait` is `true`, this closure will be executed before waiting another
+ * `timeoutMs` cycle
+ * @returns `true` if `promise` ended gracefully, `false` if timeout was reached
+ */
+export declare function resolveOrTimeout(promise: Promise<void>, timeoutMs: number, wait?: boolean, waitHandler?: () => void): Promise<unknown>;
+export interface Stopwatch {
+    /** Milliseconds since stopwatch was created. */
+    getElapsed: () => number;
+    /** Seconds since stopwatch was created. */
+    getElapsedSeconds: () => number;
+    getElapsedAndRestart: () => number;
+    restart(): void;
+}
+/**
+ * Start a `Stopwatch` that measures elapsed time based on `process.hrtime`.
+ * @returns Stopwatch
+ */
+export declare function stopwatch(): Stopwatch;
+export type Waiter<T = void, E = Error> = Promise<T> & {
+    /** Alias for `resolve` */
+    finish: (result: T) => void;
+    resolve: (result: T) => void;
+    reject: (error: E) => void;
+    /** True if the promise is resolved or rejected */
+    isFinished: boolean;
+    /** True only if the promise is resolved */
+    isResolved: boolean;
+    /** True only if the promise is rejected */
+    isRejected: boolean;
+};
+/**
+ * Creates a `Waiter` promise that can be resolved or rejected at a later time.
+ * @returns Waiter
+ */
+export declare function waiter<T = void, E = Error>(): Waiter<T, E>;

package/dist/helpers/time.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeout = timeout;
+exports.time = time;
+exports.resolveOrTimeout = resolveOrTimeout;
+exports.stopwatch = stopwatch;
+exports.waiter = waiter;
+const promises_1 = require("node:timers/promises");
+/**
+ * Wait a set amount of milliseconds or until the timer is aborted.
+ * @param ms - Number of milliseconds to wait
+ * @param abort - Abort controller
+ * @returns Promise
+ */
+function timeout(ms, abort) {
+    const signal = abort && (abort instanceof AbortSignal ? abort : abort.signal);
+    return (0, promises_1.setTimeout)(ms, undefined, { signal });
+}
+/**
+ * Time the execution of an async function.
+ * @param fn - Async function
+ * @param onFinish - Callback with elapsed milliseconds
+ * @returns Promise
+ */
+async function time(fn, onFinish) {
+    const watch = stopwatch();
+    try {
+        return await fn();
+    }
+    finally {
+        onFinish(watch.getElapsed());
+    }
+}
+/**
+ * Set an execution time limit for a promise.
+ * @param promise - The promise being capped to `timeoutMs` max execution time
+ * @param timeoutMs - Timeout limit in milliseconds
+ * @param wait - If we should wait another `timeoutMs` period for `promise` to resolve
+ * @param waitHandler - If `wait` is `true`, this closure will be executed before waiting another
+ * `timeoutMs` cycle
+ * @returns `true` if `promise` ended gracefully, `false` if timeout was reached
+ */
+async function resolveOrTimeout(promise, timeoutMs, wait = false, waitHandler) {
+    let timer;
+    const result = await Promise.race([
+        new Promise((resolve, reject) => {
+            promise
+                .then(() => resolve(true))
+                .catch(error => reject(error))
+                .finally(() => clearTimeout(timer));
+        }),
+        new Promise((resolve, _) => {
+            timer = setInterval(() => {
+                if (!wait) {
+                    clearTimeout(timer);
+                    resolve(false);
+                    return;
+                }
+                if (waitHandler) {
+                    waitHandler();
+                }
+            }, timeoutMs);
+        }),
+    ]);
+    return result;
+}
+/**
+ * Start a `Stopwatch` that measures elapsed time based on `process.hrtime`.
+ * @returns Stopwatch
+ */
+function stopwatch() {
+    let start = process.hrtime.bigint();
+    const result = {
+        getElapsedSeconds: () => {
+            const elapsedMs = result.getElapsed();
+            return elapsedMs / 1000;
+        },
+        getElapsed: () => {
+            const end = process.hrtime.bigint();
+            return Number((end - start) / 1000000n);
+        },
+        getElapsedAndRestart: () => {
+            const end = process.hrtime.bigint();
+            const result = Number((end - start) / 1000000n);
+            start = process.hrtime.bigint();
+            return result;
+        },
+        restart: () => {
+            start = process.hrtime.bigint();
+        },
+    };
+    return result;
+}
+/**
+ * Creates a `Waiter` promise that can be resolved or rejected at a later time.
+ * @returns Waiter
+ */
+function waiter() {
+    let resolveFn;
+    let rejectFn;
+    const promise = new Promise((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+    });
+    const completer = {
+        finish: (result) => completer.resolve(result),
+        resolve: (result) => {
+            void Object.assign(promise, { isFinished: true, isResolved: true });
+            resolveFn(result);
+        },
+        reject: (error) => {
+            void Object.assign(promise, { isFinished: true, isRejected: true });
+            rejectFn(error);
+        },
+        isFinished: false,
+        isResolved: false,
+        isRejected: false,
+    };
+    return Object.assign(promise, completer);
+}
+//# sourceMappingURL=time.js.map

package/dist/helpers/time.js.map

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