@ls-stack/utils 3.39.0 → 3.41.0

package/dist/asyncQueue.d.cts

@@ -2,18 +2,14 @@ import * as evtmitter from 'evtmitter';
 import { ResultValidErrors, Result } from 't-result';
 import { DurationObj } from './time.cjs';
 
-/**
- * Configuration for rate limiting task execution
- */
+/** Configuration for rate limiting task execution */
 type RateLimit = {
     /** Maximum number of tasks to execute within the interval */
     maxTasks: number;
     /** Time interval in milliseconds or as a duration object */
     interval: DurationObj | number;
 };
-/**
- * Configuration options for AsyncQueue initialization
- */
+/** Configuration options for AsyncQueue initialization */
 type AsyncQueueOptions = {
     /** Maximum number of tasks to run concurrently (default: 1) */
     concurrency?: number;
@@ -30,9 +26,7 @@ type AsyncQueueOptions = {
     /** Rate limit configuration to limit tasks per time interval */
     rateLimit?: RateLimit;
 };
-/**
- * Options for adding individual tasks to the queue
- */
+/** Options for adding individual tasks to the queue */
 type AddOptions<I, T, E extends ResultValidErrors> = {
     /** AbortSignal to cancel this specific task */
     signal?: AbortSignal;
@@ -45,9 +39,7 @@ type AddOptions<I, T, E extends ResultValidErrors> = {
     /** Callback invoked when task fails */
     onError?: (error: E | Error) => void;
 };
-/**
- * Runtime context passed to task functions
- */
+/** Runtime context passed to task functions */
 type RunCtx<I> = {
     /** Combined AbortSignal from task, queue, and timeout signals */
     signal?: AbortSignal;
@@ -57,88 +49,93 @@ type RunCtx<I> = {
 /**
  * A powerful async task queue with advanced error handling and flow control
  *
- * @template T - The type of value returned by successful tasks
- * @template E - The type of errors that tasks can produce (defaults to Error)
- * @template I - The type of metadata associated with tasks (defaults to unknown)
- *
- * @example Basic Usage
- * ```typescript
- * const queue = createAsyncQueue<string>({ concurrency: 2 });
+ * @example
+ *   Basic Usage
+ *   ```typescript
+ *   const queue = createAsyncQueue<string>({ concurrency: 2 });
  *
- * const processedItems: string[] = [];
+ *   const processedItems: string[] = [];
  *
- * queue.resultifyAdd(async () => {
+ *   queue.resultifyAdd(async () => {
  *   await delay(100);
  *   return 'task completed';
- * }).then(result => {
+ *   }).then(result => {
  *   if (result.ok) processedItems.push(result.value);
- * });
+ *   });
  *
- * await queue.onIdle();
- * console.log('Processed:', processedItems);
- * ```
+ *   await queue.onIdle();
+ *   console.log('Processed:', processedItems);
+ *   ```
  *
- * @example Error Recovery
- * ```typescript
- * const queue = createAsyncQueue<string>({
+ * @example
+ *   Error Recovery
+ *   ```typescript
+ *   const queue = createAsyncQueue<string>({
  *   stopOnError: true,
  *   rejectPendingOnError: false
- * });
+ *   });
  *
- * // Add batch of tasks
- * const items = ['item1', 'item2', 'bad-item', 'item3'];
- * items.forEach(item => {
+ *   // Add batch of tasks
+ *   const items = ['item1', 'item2', 'bad-item', 'item3'];
+ *   items.forEach(item => {
  *   queue.resultifyAdd(async () => {
- *     if (item === 'bad-item') throw new Error('Processing failed');
- *     return item.toUpperCase();
+ *   if (item === 'bad-item') throw new Error('Processing failed');
+ *   return item.toUpperCase();
+ *   });
  *   });
- * });
  *
- * await queue.onIdle();
+ *   await queue.onIdle();
  *
- * if (queue.isStopped) {
+ *   if (queue.isStopped) {
  *   console.log(`Stopped at ${queue.failed} failures, ${queue.size} remaining`);
  *   // Reset and continue with remaining tasks
  *   queue.reset();
  *   await queue.onIdle();
- * }
- * ```
+ *   }
+ *   ```
+ *
+ * @example
+ *   Lazy Start
+ *   ```typescript
+ *   const queue = createAsyncQueue<string>({ autoStart: false });
  *
- * @example Lazy Start
- * ```typescript
- * const queue = createAsyncQueue<string>({ autoStart: false });
+ *   // Prepare all tasks without starting
+ *   queue.resultifyAdd(() => processTask1());
+ *   queue.resultifyAdd(() => processTask2());
+ *   queue.resultifyAdd(() => processTask3());
  *
- * // Prepare all tasks without starting
- * queue.resultifyAdd(() => processTask1());
- * queue.resultifyAdd(() => processTask2());
- * queue.resultifyAdd(() => processTask3());
+ *   // Start processing when ready
+ *   queue.start();
+ *   await queue.onIdle();
+ *   ```
  *
- * // Start processing when ready
- * queue.start();
- * await queue.onIdle();
- * ```
+ * @template T - The type of value returned by successful tasks
+ * @template E - The type of errors that tasks can produce (defaults to Error)
+ * @template I - The type of metadata associated with tasks (defaults to
+ *   unknown)
  */
 declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
     #private;
     /**
      * Event emitter for tracking task lifecycle
      *
-     * @example Listening to Events
-     * ```typescript
-     * const queue = createAsyncQueue<string>();
+     * @example
+     *   Listening to Events
+     *   ```typescript
+     *   const queue = createAsyncQueue<string>();
      *
-     * queue.events.on('start', (event) => {
+     *   queue.events.on('start', (event) => {
      *   console.log('Task started:', event.payload.meta);
-     * });
+     *   });
      *
-     * queue.events.on('complete', (event) => {
+     *   queue.events.on('complete', (event) => {
      *   console.log('Task completed:', event.payload.value);
-     * });
+     *   });
      *
-     * queue.events.on('error', (event) => {
+     *   queue.events.on('error', (event) => {
      *   console.error('Task failed:', event.payload.error);
-     * });
-     * ```
+     *   });
+     *   ```
      */
     events: evtmitter.Emitter<{
         /** Emitted when a task starts executing */
@@ -170,32 +167,33 @@ declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
     /**
      * Add a task that returns a Result to the queue
      *
-     * Use this method when your task function already returns a Result type.
-     * For functions that throw errors or return plain values, use `resultifyAdd` instead.
+     * Use this method when your task function already returns a Result type. For
+     * functions that throw errors or return plain values, use `resultifyAdd`
+     * instead.
+     *
+     * @example
+     *   ```typescript
+     *   const queue = createAsyncQueue<string>();
+     *
+     *   const result = await queue.add(async () => {
+     *     try {
+     *       const data = await fetchData();
+     *       return Result.ok(data);
+     *     } catch (error) {
+     *       return Result.err(error);
+     *     }
+     *   });
+     *
+     *   if (result.ok) {
+     *     console.log('Success:', result.value);
+     *   } else {
+     *     console.log('Error:', result.error);
+     *   }
+     *   ```;
      *
      * @param fn - Task function that returns a Result
      * @param options - Optional configuration for this task
      * @returns Promise that resolves with the task result
-     *
-     * @example
-     * ```typescript
-     * const queue = createAsyncQueue<string>();
-     *
-     * const result = await queue.add(async () => {
-     *   try {
-     *     const data = await fetchData();
-     *     return Result.ok(data);
-     *   } catch (error) {
-     *     return Result.err(error);
-     *   }
-     * });
-     *
-     * if (result.ok) {
-     *   console.log('Success:', result.value);
-     * } else {
-     *   console.log('Error:', result.error);
-     * }
-     * ```
      */
     add(fn: (ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
     /**
@@ -204,63 +202,68 @@ declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
      * This is the most commonly used method. It automatically wraps your function
      * to handle errors and convert them to Result types.
      *
-     * @param fn - Task function that returns a value or throws
-     * @param options - Optional configuration for this task
-     * @returns Promise that resolves with the task result wrapped in Result
-     *
-     * @example Basic Usage
-     * ```typescript
-     * const queue = createAsyncQueue<string>();
+     * @example
+     *   Basic Usage
+     *   ```typescript
+     *   const queue = createAsyncQueue<string>();
      *
-     * queue.resultifyAdd(async () => {
+     *   queue.resultifyAdd(async () => {
      *   const response = await fetch('/api/data');
      *   return response.json();
-     * }).then(result => {
+     *   }).then(result => {
      *   if (result.ok) {
-     *     console.log('Data:', result.value);
+     *   console.log('Data:', result.value);
      *   } else {
-     *     console.error('Failed:', result.error);
+     *   console.error('Failed:', result.error);
      *   }
-     * });
-     * ```
+     *   });
+     *   ```
      *
-     * @example With Callbacks
-     * ```typescript
-     * queue.resultifyAdd(
+     * @example
+     *   With Callbacks
+     *   ```typescript
+     *   queue.resultifyAdd(
      *   async () => processData(),
      *   {
-     *     onComplete: (data) => console.log('Processed:', data),
-     *     onError: (error) => console.error('Failed:', error),
-     *     timeout: 5000
+     *   onComplete: (data) => console.log('Processed:', data),
+     *   onError: (error) => console.error('Failed:', error),
+     *   timeout: 5000
      *   }
-     * );
-     * ```
+     *   );
+     *   ```
+     *
+     * @param fn - Task function that returns a value or throws
+     * @param options - Optional configuration for this task
+     * @returns Promise that resolves with the task result wrapped in Result
      */
     resultifyAdd(fn: (ctx: RunCtx<I>) => Promise<T> | T, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
     /**
-     * Wait for the queue to become idle (no pending tasks, no queued tasks, and no rate-limit timers)
+     * Wait for the queue to become idle (no pending tasks, no queued tasks, and
+     * no rate-limit timers)
      *
      * This method resolves when:
+     *
      * - All tasks have completed (success or failure)
      * - The queue is stopped due to error (stopOnError), even with remaining tasks
-     * - There are no queued tasks, no running tasks, and no pending rate-limit timers
-     *
-     * @returns Promise that resolves when the queue is idle
+     * - There are no queued tasks, no running tasks, and no pending rate-limit
+     *   timers
      *
      * @example
-     * ```typescript
-     * const queue = createAsyncQueue<string>();
+     *   ```typescript
+     *   const queue = createAsyncQueue<string>();
      *
-     * // Add multiple tasks
-     * for (let i = 0; i < 10; i++) {
+     *   // Add multiple tasks
+     *   for (let i = 0; i < 10; i++) {
      *   queue.resultifyAdd(async () => `task ${i}`);
-     * }
+     *   }
      *
-     * // Wait for all tasks to complete
-     * await queue.onIdle();
+     *   // Wait for all tasks to complete
+     *   await queue.onIdle();
+     *
+     *   console.log(`Completed: ${queue.completed}, Failed: ${queue.failed}`);
+     *   ```
      *
-     * console.log(`Completed: ${queue.completed}, Failed: ${queue.failed}`);
-     * ```
+     * @returns Promise that resolves when the queue is idle
      */
     onIdle(): Promise<void>;
     /**
@@ -276,24 +279,24 @@ declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
     /**
      * Clear all queued tasks (does not affect currently running tasks)
      *
-     * This removes all tasks waiting in the queue but allows currently
-     * executing tasks to complete normally.
+     * This removes all tasks waiting in the queue but allows currently executing
+     * tasks to complete normally.
      *
      * @example
-     * ```typescript
-     * const queue = createAsyncQueue({ concurrency: 1 });
+     *   ```typescript
+     *   const queue = createAsyncQueue({ concurrency: 1 });
      *
-     * // Add multiple tasks
-     * queue.resultifyAdd(async () => longRunningTask()); // Will start immediately
-     * queue.resultifyAdd(async () => task2()); // Queued
-     * queue.resultifyAdd(async () => task3()); // Queued
+     *   // Add multiple tasks
+     *   queue.resultifyAdd(async () => longRunningTask()); // Will start immediately
+     *   queue.resultifyAdd(async () => task2()); // Queued
+     *   queue.resultifyAdd(async () => task3()); // Queued
      *
-     * // Clear remaining queued tasks
-     * queue.clear();
+     *   // Clear remaining queued tasks
+     *   queue.clear();
      *
-     * // Only the first task will complete
-     * await queue.onIdle();
-     * ```
+     *   // Only the first task will complete
+     *   await queue.onIdle();
+     *   ```;
      */
     clear(): void;
     /** Number of tasks that have completed successfully */
@@ -308,66 +311,64 @@ declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
      * Manually start processing tasks (only needed if autoStart: false)
      *
      * @example
-     * ```typescript
-     * const queue = createAsyncQueue({ autoStart: false });
+     *   ```typescript
+     *   const queue = createAsyncQueue({ autoStart: false });
      *
-     * // Add tasks without starting processing
-     * queue.resultifyAdd(async () => 'task1');
-     * queue.resultifyAdd(async () => 'task2');
+     *   // Add tasks without starting processing
+     *   queue.resultifyAdd(async () => 'task1');
+     *   queue.resultifyAdd(async () => 'task2');
      *
-     * // Start processing when ready
-     * queue.start();
-     * await queue.onIdle();
-     * ```
+     *   // Start processing when ready
+     *   queue.start();
+     *   await queue.onIdle();
+     *   ```;
      */
     start(): void;
     /**
      * Pause processing new tasks (currently running tasks continue)
      *
      * @example
-     * ```typescript
-     * const queue = createAsyncQueue();
+     *   ```typescript
+     *   const queue = createAsyncQueue();
      *
-     * // Start some tasks
-     * queue.resultifyAdd(async () => longRunningTask1());
-     * queue.resultifyAdd(async () => longRunningTask2());
+     *   // Start some tasks
+     *   queue.resultifyAdd(async () => longRunningTask1());
+     *   queue.resultifyAdd(async () => longRunningTask2());
      *
-     * // Pause before more tasks are picked up
-     * queue.pause();
+     *   // Pause before more tasks are picked up
+     *   queue.pause();
      *
-     * // Later, resume processing
-     * queue.resume();
-     * ```
+     *   // Later, resume processing
+     *   queue.resume();
+     *   ```;
      */
     pause(): void;
-    /**
-     * Resume processing tasks after pause
-     */
+    /** Resume processing tasks after pause */
     resume(): void;
     /**
      * Reset the queue after being stopped, allowing new tasks to be processed
      *
-     * This clears the stopped state and error reason, and resumes processing
-     * any remaining queued tasks if autoStart was enabled.
+     * This clears the stopped state and error reason, and resumes processing any
+     * remaining queued tasks if autoStart was enabled.
      *
      * @example
-     * ```typescript
-     * const queue = createAsyncQueue({ stopOnError: true });
+     *   ```typescript
+     *   const queue = createAsyncQueue({ stopOnError: true });
      *
-     * // Add tasks that will cause the queue to stop
-     * queue.resultifyAdd(async () => { throw new Error('fail'); });
-     * queue.resultifyAdd(async () => 'remaining task');
+     *   // Add tasks that will cause the queue to stop
+     *   queue.resultifyAdd(async () => { throw new Error('fail'); });
+     *   queue.resultifyAdd(async () => 'remaining task');
      *
-     * await queue.onIdle();
+     *   await queue.onIdle();
      *
-     * if (queue.isStopped) {
+     *   if (queue.isStopped) {
      *   console.log(`Queue stopped, ${queue.size} tasks remaining`);
      *
      *   // Reset and process remaining tasks
      *   queue.reset();
      *   await queue.onIdle();
-     * }
-     * ```
+     *   }
+     *   ```
      */
     reset(): void;
     /** Whether the queue is stopped due to an error */
@@ -379,9 +380,7 @@ declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
     /** The error that caused the queue to stop (if any) */
     get stoppedReason(): Error | undefined;
 }
-/**
- * AddOptions variant that requires metadata to be provided
- */
+/** AddOptions variant that requires metadata to be provided */
 type AddOptionsWithId<I, T, E extends ResultValidErrors> = Omit<AddOptions<I, T, E>, 'meta'> & {
     meta: I;
 };
@@ -391,29 +390,29 @@ type AddOptionsWithId<I, T, E extends ResultValidErrors> = Omit<AddOptions<I, T,
  * This class enforces that every task must include metadata, which is useful
  * when you need to track or identify tasks consistently.
  *
- * @template T - The type of value returned by successful tasks
- * @template I - The type of metadata (required for all tasks)
- * @template E - The type of errors that tasks can produce
- *
  * @example
- * ```typescript
- * interface TaskMeta {
+ *   ```typescript
+ *   interface TaskMeta {
  *   id: string;
  *   priority: number;
- * }
+ *   }
  *
- * const queue = createAsyncQueueWithMeta<string, TaskMeta>({ concurrency: 2 });
+ *   const queue = createAsyncQueueWithMeta<string, TaskMeta>({ concurrency: 2 });
  *
- * queue.resultifyAdd(
+ *   queue.resultifyAdd(
  *   async () => processImportantTask(),
  *   { meta: { id: 'task-1', priority: 1 } }
- * );
+ *   );
  *
- * // Listen to events with metadata
- * queue.events.on('complete', (event) => {
+ *   // Listen to events with metadata
+ *   queue.events.on('complete', (event) => {
  *   console.log(`Task ${event.payload.meta.id} completed`);
- * });
- * ```
+ *   });
+ *   ```
+ *
+ * @template T - The type of value returned by successful tasks
+ * @template I - The type of metadata (required for all tasks)
+ * @template E - The type of errors that tasks can produce
  */
 declare class AsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
     constructor(options?: AsyncQueueOptions);
@@ -423,63 +422,66 @@ declare class AsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error> exte
 /**
  * Create a new AsyncQueue instance
  *
- * @template T - The type of value returned by successful tasks
- * @template E - The type of errors that tasks can produce (defaults to Error)
- * @param options - Configuration options for the queue
- * @returns A new AsyncQueue instance
- *
- * @example Basic Queue
- * ```typescript
- * const queue = createAsyncQueue<string>({ concurrency: 3 });
- * ```
+ * @example
+ *   Basic Queue
+ *   ```typescript
+ *   const queue = createAsyncQueue<string>({ concurrency: 3 });
+ *   ```
  *
- * @example Error Handling Queue
- * ```typescript
- * const queue = createAsyncQueue<string>({
+ * @example
+ *   Error Handling Queue
+ *   ```typescript
+ *   const queue = createAsyncQueue<string>({
  *   concurrency: 2,
  *   stopOnError: true,
  *   rejectPendingOnError: true
- * });
- * ```
+ *   });
+ *   ```
  *
- * @example Lazy Start Queue
- * ```typescript
- * const queue = createAsyncQueue<string>({
+ * @example
+ *   Lazy Start Queue
+ *   ```typescript
+ *   const queue = createAsyncQueue<string>({
  *   autoStart: false,
  *   concurrency: 1
- * });
- * ```
+ *   });
+ *   ```
+ *
+ * @template T - The type of value returned by successful tasks
+ * @template E - The type of errors that tasks can produce (defaults to Error)
+ * @param options - Configuration options for the queue
+ * @returns A new AsyncQueue instance
  */
 declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E>;
 
 /**
  * Create a new AsyncQueueWithMeta instance that requires metadata for all tasks
  *
- * @template T - The type of value returned by successful tasks
- * @template I - The type of metadata (required for all tasks)
- * @template E - The type of errors that tasks can produce (defaults to Error)
- * @param options - Configuration options for the queue
- * @returns A new AsyncQueueWithMeta instance
- *
  * @example
- * ```typescript
- * interface TaskInfo {
+ *   ```typescript
+ *   interface TaskInfo {
  *   taskId: string;
  *   userId: string;
- * }
+ *   }
  *
- * const queue = createAsyncQueueWithMeta<ProcessResult, TaskInfo>({
+ *   const queue = createAsyncQueueWithMeta<ProcessResult, TaskInfo>({
  *   concurrency: 5
- * });
+ *   });
  *
- * queue.resultifyAdd(
+ *   queue.resultifyAdd(
  *   async (ctx) => {
- *     console.log(`Processing task ${ctx.meta.taskId} for user ${ctx.meta.userId}`);
- *     return await processUserTask(ctx.meta.userId);
+ *   console.log(`Processing task ${ctx.meta.taskId} for user ${ctx.meta.userId}`);
+ *   return await processUserTask(ctx.meta.userId);
  *   },
  *   { meta: { taskId: '123', userId: 'user456' } }
- * );
- * ```
+ *   );
+ *   ```
+ *
+ * @template T - The type of value returned by successful tasks
+ * @template I - The type of metadata (required for all tasks)
+ * @template E - The type of errors that tasks can produce (defaults to Error)
+ * @param options - Configuration options for the queue
+ * @returns A new AsyncQueueWithMeta instance
  */
 declare function createAsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithMeta<T, I, E>;