bytekit 1.0.21 → 1.0.23

package/dist/utils/async/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AsyncUtils Module
+ *
+ * Comprehensive utilities for managing asynchronous operations in TypeScript.
+ * Provides Promise-based utilities for delays, timeouts, retries, parallel/sequential
+ * execution, and rate limiting with zero dependencies.
+ */
+export { TimeoutError, AbortError, RetryError } from "./errors.js";
+export type { BackoffStrategy, Task, SequentialTask, AsyncFunction, RetryOptions, ParallelOptions, SequentialOptions, AllSettledResult, DebounceOptions, DebouncedFunction, ThrottleOptions, ThrottledFunction, } from "./types.js";
+export { sleep } from "./sleep.js";
+export { timeout, withTimeout } from "./timeout.js";
+export { retry } from "./retry.js";
+export { parallel } from "./parallel.js";
+export { sequential } from "./sequential.js";
+export { race } from "./race.js";
+export { allSettled } from "./allSettled.js";
+export { debounceAsync } from "./debounce.js";
+export { throttleAsync } from "./throttle.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/async/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGnE,YAAY,EACR,eAAe,EACf,IAAI,EACJ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/utils/async/index.js

@@ -0,0 +1,20 @@
+/**
+ * AsyncUtils Module
+ *
+ * Comprehensive utilities for managing asynchronous operations in TypeScript.
+ * Provides Promise-based utilities for delays, timeouts, retries, parallel/sequential
+ * execution, and rate limiting with zero dependencies.
+ */
+// Export error classes
+export { TimeoutError, AbortError, RetryError } from "./errors.js";
+// Utility functions will be exported as they are implemented
+export { sleep } from "./sleep.js";
+export { timeout, withTimeout } from "./timeout.js";
+export { retry } from "./retry.js";
+export { parallel } from "./parallel.js";
+export { sequential } from "./sequential.js";
+export { race } from "./race.js";
+export { allSettled } from "./allSettled.js";
+export { debounceAsync } from "./debounce.js";
+export { throttleAsync } from "./throttle.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/async/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uBAAuB;AACvB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkBnE,6DAA6D;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/utils/async/parallel.d.ts

@@ -0,0 +1,24 @@
+import type { Task, ParallelOptions } from "./types.js";
+/**
+ * Execute multiple async tasks in parallel with optional concurrency control
+ *
+ * @param tasks - Array of async task functions to execute
+ * @param options - Optional configuration for concurrency control
+ * @returns Promise that resolves with array of results in original order
+ * @throws First error encountered if any task fails
+ *
+ * @example
+ * ```typescript
+ * // Unlimited concurrency
+ * const results = await parallel([
+ *   () => fetchUser(1),
+ *   () => fetchUser(2),
+ *   () => fetchUser(3)
+ * ]);
+ *
+ * // Limited concurrency
+ * const results = await parallel(tasks, { concurrency: 2 });
+ * ```
+ */
+export declare function parallel<T>(tasks: Array<Task<T>>, options?: ParallelOptions): Promise<T[]>;
+//# sourceMappingURL=parallel.d.ts.map

package/dist/utils/async/parallel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../../src/utils/async/parallel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC5B,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EACrB,OAAO,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,CAAC,EAAE,CAAC,CAqCd"}

package/dist/utils/async/parallel.js

@@ -0,0 +1,98 @@
+/**
+ * Execute multiple async tasks in parallel with optional concurrency control
+ *
+ * @param tasks - Array of async task functions to execute
+ * @param options - Optional configuration for concurrency control
+ * @returns Promise that resolves with array of results in original order
+ * @throws First error encountered if any task fails
+ *
+ * @example
+ * ```typescript
+ * // Unlimited concurrency
+ * const results = await parallel([
+ *   () => fetchUser(1),
+ *   () => fetchUser(2),
+ *   () => fetchUser(3)
+ * ]);
+ *
+ * // Limited concurrency
+ * const results = await parallel(tasks, { concurrency: 2 });
+ * ```
+ */
+export async function parallel(tasks, options) {
+    // Validate input
+    if (!Array.isArray(tasks)) {
+        throw new TypeError("tasks must be an array");
+    }
+    // Handle empty array
+    if (tasks.length === 0) {
+        return [];
+    }
+    // Validate all tasks are functions
+    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 concurrency = options?.concurrency;
+    // Validate concurrency if provided
+    if (concurrency !== undefined) {
+        if (typeof concurrency !== "number" || !Number.isInteger(concurrency)) {
+            throw new TypeError("concurrency must be an integer");
+        }
+        if (concurrency < 1) {
+            throw new TypeError("concurrency must be at least 1");
+        }
+    }
+    // If no concurrency limit, use Promise.all for maximum performance
+    if (concurrency === undefined) {
+        return Promise.all(tasks.map((task) => task()));
+    }
+    // Queue-based execution with concurrency limit
+    return executeWithConcurrencyLimit(tasks, concurrency);
+}
+/**
+ * Execute tasks with a concurrency limit using a queue-based approach
+ */
+async function executeWithConcurrencyLimit(tasks, concurrency) {
+    const results = new Array(tasks.length);
+    let nextIndex = 0;
+    let hasError = false;
+    let firstError = null;
+    // Worker function that processes tasks from the queue
+    const worker = async () => {
+        while (nextIndex < tasks.length && !hasError) {
+            const index = nextIndex++;
+            try {
+                const result = await tasks[index]();
+                // Only store result if no error has occurred
+                if (!hasError) {
+                    results[index] = result;
+                }
+            }
+            catch (err) {
+                // Store first error and set flag
+                if (!hasError) {
+                    hasError = true;
+                    firstError = err;
+                }
+                // Stop this worker
+                return;
+            }
+        }
+    };
+    // Start workers up to concurrency limit
+    const workers = [];
+    const workerCount = Math.min(concurrency, tasks.length);
+    for (let i = 0; i < workerCount; i++) {
+        workers.push(worker());
+    }
+    // Wait for all workers to complete
+    await Promise.all(workers);
+    // If an error occurred, throw it
+    if (hasError) {
+        throw firstError;
+    }
+    return results;
+}
+//# sourceMappingURL=parallel.js.map

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

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

package/dist/utils/async/race.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Enhanced Promise.race implementation with better error handling
+ *
+ * Unlike native Promise.race, this implementation:
+ * - Validates non-empty array input
+ * - Returns AggregateError when all promises reject
+ * - Tracks all promise settlements for comprehensive error reporting
+ */
+/**
+ * Race multiple promises and resolve/reject with the first settled promise.
+ * If all promises reject, rejects with an AggregateError containing all rejection reasons.
+ *
+ * @param promises - Array of promises to race
+ * @returns Promise that resolves/rejects with the first settled promise
+ * @throws TypeError if promises array is empty
+ *
+ * @example
+ * ```typescript
+ * // Resolves with the fastest promise
+ * const result = await race([
+ *   fetch('/api/fast'),
+ *   fetch('/api/slow')
+ * ]);
+ *
+ * // Rejects with AggregateError if all fail
+ * try {
+ *   await race([
+ *     Promise.reject('error 1'),
+ *     Promise.reject('error 2')
+ *   ]);
+ * } catch (error) {
+ *   console.log(error.errors); // ['error 1', 'error 2']
+ * }
+ * ```
+ */
+export declare function race<T>(promises: Array<Promise<T>>): Promise<T>;
+//# sourceMappingURL=race.d.ts.map

package/dist/utils/async/race.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"race.d.ts","sourceRoot":"","sources":["../../../src/utils/async/race.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4C/D"}

package/dist/utils/async/race.js

@@ -0,0 +1,69 @@
+/**
+ * Enhanced Promise.race implementation with better error handling
+ *
+ * Unlike native Promise.race, this implementation:
+ * - Validates non-empty array input
+ * - Returns AggregateError when all promises reject
+ * - Tracks all promise settlements for comprehensive error reporting
+ */
+/**
+ * Race multiple promises and resolve/reject with the first settled promise.
+ * If all promises reject, rejects with an AggregateError containing all rejection reasons.
+ *
+ * @param promises - Array of promises to race
+ * @returns Promise that resolves/rejects with the first settled promise
+ * @throws TypeError if promises array is empty
+ *
+ * @example
+ * ```typescript
+ * // Resolves with the fastest promise
+ * const result = await race([
+ *   fetch('/api/fast'),
+ *   fetch('/api/slow')
+ * ]);
+ *
+ * // Rejects with AggregateError if all fail
+ * try {
+ *   await race([
+ *     Promise.reject('error 1'),
+ *     Promise.reject('error 2')
+ *   ]);
+ * } catch (error) {
+ *   console.log(error.errors); // ['error 1', 'error 2']
+ * }
+ * ```
+ */
+export function race(promises) {
+    // Validate non-empty array
+    if (!Array.isArray(promises)) {
+        throw new TypeError("Expected an array of promises");
+    }
+    if (promises.length === 0) {
+        throw new TypeError("Cannot race an empty array of promises");
+    }
+    // Use a custom implementation to support AggregateError when ALL reject
+    return new Promise((resolve, reject) => {
+        let rejectionCount = 0;
+        const errors = new Array(promises.length);
+        let settled = false;
+        promises.forEach((promise, index) => {
+            Promise.resolve(promise).then((value) => {
+                if (!settled) {
+                    settled = true;
+                    resolve(value);
+                }
+            }, (error) => {
+                errors[index] = error;
+                rejectionCount++;
+                // If all promises have rejected, reject with AggregateError
+                if (rejectionCount === promises.length) {
+                    if (!settled) {
+                        settled = true;
+                        reject(new AggregateError(errors, `All ${promises.length} promises rejected`));
+                    }
+                }
+            });
+        });
+    });
+}
+//# sourceMappingURL=race.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"race.js","sourceRoot":"","sources":["../../../src/utils/async/race.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,IAAI,CAAI,QAA2B;IAC/C,2BAA2B;IAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CAAC,+BAA+B,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAClE,CAAC;IAED,wEAAwE;IACxE,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,MAAM,MAAM,GAAc,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;YAChC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CACzB,CAAC,KAAK,EAAE,EAAE;gBACN,IAAI,CAAC,OAAO,EAAE,CAAC;oBACX,OAAO,GAAG,IAAI,CAAC;oBACf,OAAO,CAAC,KAAK,CAAC,CAAC;gBACnB,CAAC;YACL,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;gBACN,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;gBACtB,cAAc,EAAE,CAAC;gBAEjB,4DAA4D;gBAC5D,IAAI,cAAc,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;oBACrC,IAAI,CAAC,OAAO,EAAE,CAAC;wBACX,OAAO,GAAG,IAAI,CAAC;wBACf,MAAM,CACF,IAAI,cAAc,CACd,MAAM,EACN,OAAO,QAAQ,CAAC,MAAM,oBAAoB,CAC7C,CACJ,CAAC;oBACN,CAAC;gBACL,CAAC;YACL,CAAC,CACJ,CAAC;QACN,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/utils/async/retry.d.ts

@@ -0,0 +1,34 @@
+import type { RetryOptions } from "./types.js";
+/**
+ * Retry a failed async operation with configurable backoff strategies
+ *
+ * @param fn - The async function to retry
+ * @param options - Configuration options for retry behavior
+ * @returns Promise that resolves with the function result or rejects after all attempts fail
+ * @throws {RetryError} If all retry attempts are exhausted
+ * @throws {AbortError} If the operation is aborted via AbortSignal
+ * @throws {TypeError} If invalid options are provided
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults (3 attempts, exponential backoff)
+ * const result = await retry(() => fetchData());
+ *
+ * // Custom configuration
+ * const result = await retry(() => fetchData(), {
+ *   maxAttempts: 5,
+ *   baseDelay: 500,
+ *   maxDelay: 10000,
+ *   backoff: 'linear',
+ *   shouldRetry: (error) => error instanceof NetworkError
+ * });
+ *
+ * // With cancellation
+ * const controller = new AbortController();
+ * const result = await retry(() => fetchData(), {
+ *   signal: controller.signal
+ * });
+ * ```
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/async/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/async/retry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,KAAK,CAAC,CAAC,EACzB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,YAAiB,GAC3B,OAAO,CAAC,CAAC,CAAC,CA8EZ"}

package/dist/utils/async/retry.js

@@ -0,0 +1,118 @@
+import { sleep } from "./sleep.js";
+import { AbortError, RetryError } from "./errors.js";
+/**
+ * Retry a failed async operation with configurable backoff strategies
+ *
+ * @param fn - The async function to retry
+ * @param options - Configuration options for retry behavior
+ * @returns Promise that resolves with the function result or rejects after all attempts fail
+ * @throws {RetryError} If all retry attempts are exhausted
+ * @throws {AbortError} If the operation is aborted via AbortSignal
+ * @throws {TypeError} If invalid options are provided
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults (3 attempts, exponential backoff)
+ * const result = await retry(() => fetchData());
+ *
+ * // Custom configuration
+ * const result = await retry(() => fetchData(), {
+ *   maxAttempts: 5,
+ *   baseDelay: 500,
+ *   maxDelay: 10000,
+ *   backoff: 'linear',
+ *   shouldRetry: (error) => error instanceof NetworkError
+ * });
+ *
+ * // With cancellation
+ * const controller = new AbortController();
+ * const result = await retry(() => fetchData(), {
+ *   signal: controller.signal
+ * });
+ * ```
+ */
+export async function retry(fn, options = {}) {
+    // Validate function parameter
+    if (typeof fn !== "function") {
+        throw new TypeError("First argument must be a function");
+    }
+    // Extract and validate options with defaults
+    const { maxAttempts = 3, baseDelay = 1000, maxDelay = Infinity, backoff = "exponential", shouldRetry, signal, } = options;
+    // Validate numeric options
+    if (maxAttempts < 1) {
+        throw new TypeError(`maxAttempts must be at least 1, got ${maxAttempts}`);
+    }
+    if (baseDelay < 0) {
+        throw new TypeError(`baseDelay must be non-negative, got ${baseDelay}`);
+    }
+    if (maxDelay < 0) {
+        throw new TypeError(`maxDelay must be non-negative, got ${maxDelay}`);
+    }
+    // Check if already aborted
+    if (signal?.aborted) {
+        throw new AbortError("Retry aborted before starting");
+    }
+    let lastError;
+    // Attempt execution up to maxAttempts times
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            // Execute the function
+            const result = await fn();
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry this error
+            if (shouldRetry && !shouldRetry(error)) {
+                throw error;
+            }
+            // If this was the last attempt, don't delay
+            if (attempt === maxAttempts) {
+                break;
+            }
+            // Calculate delay based on backoff strategy
+            const delay = calculateDelay(attempt, baseDelay, maxDelay, backoff);
+            // Wait before next attempt (with abort support)
+            try {
+                await sleep(delay, signal);
+            }
+            catch (sleepError) {
+                // If sleep was aborted, throw AbortError
+                if (sleepError instanceof AbortError) {
+                    throw sleepError;
+                }
+                // Otherwise, rethrow the error
+                throw sleepError;
+            }
+        }
+    }
+    // All attempts exhausted, throw RetryError
+    throw new RetryError(`Failed after ${maxAttempts} attempts`, maxAttempts, lastError);
+}
+/**
+ * Calculate the delay for a retry attempt based on the backoff strategy
+ *
+ * @param attempt - Current attempt number (1-indexed)
+ * @param baseDelay - Base delay in milliseconds
+ * @param maxDelay - Maximum delay cap in milliseconds
+ * @param backoff - Backoff strategy to use
+ * @returns Delay in milliseconds, capped at maxDelay
+ */
+function calculateDelay(attempt, baseDelay, maxDelay, backoff) {
+    let delay;
+    if (typeof backoff === "function") {
+        // Custom backoff function
+        delay = backoff(attempt);
+    }
+    else if (backoff === "linear") {
+        // Linear backoff: baseDelay * attempt
+        delay = baseDelay * attempt;
+    }
+    else {
+        // Exponential backoff: baseDelay * (2 ^ (attempt - 1))
+        delay = baseDelay * Math.pow(2, attempt - 1);
+    }
+    // Apply maxDelay cap
+    return Math.min(delay, maxDelay);
+}
+//# sourceMappingURL=retry.js.map

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

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

package/dist/utils/async/sequential.d.ts

@@ -0,0 +1,28 @@
+import type { SequentialTask, SequentialOptions } from "./types.js";
+/**
+ * Execute async tasks sequentially, one after another
+ *
+ * Each task receives the result of the previous task as an optional parameter.
+ * By default, execution stops on the first error. Use continueOnError option
+ * to execute all tasks regardless of failures.
+ *
+ * @param tasks - Array of async task functions to execute sequentially
+ * @param options - Optional configuration for error handling
+ * @returns Promise that resolves with array of results in execution order
+ * @throws First error encountered if any task fails (unless continueOnError is true)
+ *
+ * @example
+ * ```typescript
+ * // Basic sequential execution
+ * const results = await sequential([
+ *   () => fetchUser(1),
+ *   (user) => fetchPosts(user.id),
+ *   (posts) => processPosts(posts)
+ * ]);
+ *
+ * // Continue on error
+ * const results = await sequential(tasks, { continueOnError: true });
+ * ```
+ */
+export declare function sequential<T>(tasks: Array<SequentialTask<T>>, options?: SequentialOptions): Promise<T[]>;
+//# sourceMappingURL=sequential.d.ts.map

package/dist/utils/async/sequential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequential.d.ts","sourceRoot":"","sources":["../../../src/utils/async/sequential.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAC9B,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CA0Cd"}

package/dist/utils/async/sequential.js

@@ -0,0 +1,66 @@
+/**
+ * Execute async tasks sequentially, one after another
+ *
+ * Each task receives the result of the previous task as an optional parameter.
+ * By default, execution stops on the first error. Use continueOnError option
+ * to execute all tasks regardless of failures.
+ *
+ * @param tasks - Array of async task functions to execute sequentially
+ * @param options - Optional configuration for error handling
+ * @returns Promise that resolves with array of results in execution order
+ * @throws First error encountered if any task fails (unless continueOnError is true)
+ *
+ * @example
+ * ```typescript
+ * // Basic sequential execution
+ * const results = await sequential([
+ *   () => fetchUser(1),
+ *   (user) => fetchPosts(user.id),
+ *   (posts) => processPosts(posts)
+ * ]);
+ *
+ * // Continue on error
+ * const results = await sequential(tasks, { continueOnError: true });
+ * ```
+ */
+export async function sequential(tasks, options) {
+    // Validate input
+    if (!Array.isArray(tasks)) {
+        throw new TypeError("tasks must be an array");
+    }
+    // Handle empty array
+    if (tasks.length === 0) {
+        return [];
+    }
+    // Validate all tasks are functions
+    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 continueOnError = options?.continueOnError ?? false;
+    const results = [];
+    let previousResult = undefined;
+    // Execute tasks one by one using for...of loop
+    for (let i = 0; i < tasks.length; i++) {
+        try {
+            // Pass previous result to current task
+            const result = await tasks[i](previousResult);
+            results.push(result);
+            previousResult = result;
+        }
+        catch (error) {
+            if (continueOnError) {
+                // Store error as result and continue
+                results.push(error);
+                previousResult = error;
+            }
+            else {
+                // Fail fast - reject immediately
+                throw error;
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=sequential.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sequential.js","sourceRoot":"","sources":["../../../src/utils/async/sequential.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC5B,KAA+B,EAC/B,OAA2B;IAE3B,iBAAiB;IACjB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAC;IAClD,CAAC;IAED,qBAAqB;IACrB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACd,CAAC;IAED,mCAAmC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,CAAC;QAChE,CAAC;IACL,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,KAAK,CAAC;IAC1D,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,IAAI,cAAc,GAAQ,SAAS,CAAC;IAEpC,+CAA+C;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,CAAC;YACD,uCAAuC;YACvC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;YAC9C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,cAAc,GAAG,MAAM,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,eAAe,EAAE,CAAC;gBAClB,qCAAqC;gBACrC,OAAO,CAAC,IAAI,CAAC,KAAU,CAAC,CAAC;gBACzB,cAAc,GAAG,KAAK,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACJ,iCAAiC;gBACjC,MAAM,KAAK,CAAC;YAChB,CAAC;QACL,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/dist/utils/async/sleep.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Promise-based delay function with optional cancellation support
+ *
+ * @param ms - Duration to sleep in milliseconds (must be non-negative)
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Promise that resolves after the specified duration
+ * @throws {TypeError} If ms is negative
+ * @throws {AbortError} If the operation is aborted via AbortSignal
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await sleep(1000); // Wait 1 second
+ *
+ * // With cancellation
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 500);
+ * try {
+ *   await sleep(1000, controller.signal);
+ * } catch (error) {
+ *   if (error instanceof AbortError) {
+ *     console.log('Sleep was cancelled');
+ *   }
+ * }
+ * ```
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/utils/async/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../../src/utils/async/sleep.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CrE"}

package/dist/utils/async/sleep.js

@@ -0,0 +1,64 @@
+import { AbortError } from "./errors.js";
+/**
+ * Promise-based delay function with optional cancellation support
+ *
+ * @param ms - Duration to sleep in milliseconds (must be non-negative)
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Promise that resolves after the specified duration
+ * @throws {TypeError} If ms is negative
+ * @throws {AbortError} If the operation is aborted via AbortSignal
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await sleep(1000); // Wait 1 second
+ *
+ * // With cancellation
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 500);
+ * try {
+ *   await sleep(1000, controller.signal);
+ * } catch (error) {
+ *   if (error instanceof AbortError) {
+ *     console.log('Sleep was cancelled');
+ *   }
+ * }
+ * ```
+ */
+export function sleep(ms, signal) {
+    // Validate input
+    if (ms < 0) {
+        throw new TypeError(`Sleep duration must be non-negative, got ${ms} milliseconds`);
+    }
+    // Check if already aborted
+    if (signal?.aborted) {
+        return Promise.reject(new AbortError("Sleep aborted before starting"));
+    }
+    return new Promise((resolve, reject) => {
+        // Handle zero milliseconds - resolve immediately
+        if (ms === 0) {
+            resolve();
+            return;
+        }
+        // Set up the timeout
+        const timeoutId = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        // Set up abort handler
+        const abortHandler = () => {
+            cleanup();
+            reject(new AbortError("Sleep aborted"));
+        };
+        // Cleanup function to prevent memory leaks
+        const cleanup = () => {
+            clearTimeout(timeoutId);
+            signal?.removeEventListener("abort", abortHandler);
+        };
+        // Register abort listener if signal provided
+        if (signal) {
+            signal.addEventListener("abort", abortHandler, { once: true });
+        }
+    });
+}
+//# sourceMappingURL=sleep.js.map