@ls-stack/utils 3.40.0 → 3.42.0

package/dist/asyncQueue.cjs

@@ -67,22 +67,23 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * 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 = (0, import_evtmitter.evtmitter)();
   #signal;
@@ -196,32 +197,33 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * 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);
-   * }
-   * ```
    */
   async add(fn, options) {
     if (this.#signal?.aborted) {
@@ -265,37 +267,39 @@ var AsyncQueue = class _AsyncQueue {
    * 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, options) {
     return this.add(
@@ -440,29 +444,32 @@ var AsyncQueue = class _AsyncQueue {
     this.#resolveIdleWaiters();
   }
   /**
-   * 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
    */
   async onIdle() {
     if (this.#stopped || this.#pending === 0 && this.#size === 0 && this.#rateLimitTimeouts.size === 0) {
@@ -493,24 +500,24 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * 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() {
     this.#queue = [];
@@ -544,17 +551,17 @@ var AsyncQueue = class _AsyncQueue {
    * 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() {
     if (this.#stopped) {
@@ -567,26 +574,24 @@ var AsyncQueue = class _AsyncQueue {
    * 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() {
     this.#paused = true;
   }
-  /**
-   * Resume processing tasks after pause
-   */
+  /** Resume processing tasks after pause */
   resume() {
     this.#paused = false;
     if (this.#started && !this.#stopped) {
@@ -596,27 +601,27 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * 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() {
     this.#stopped = false;