@ls-stack/utils 3.38.0 → 3.40.0

package/dist/asyncQueue.cjs

@@ -38,8 +38,24 @@ function defer() {
   return { resolve, reject, promise };
 }
 
+// src/time.ts
+var MINUTE_AS_MS = 60 * 1e3;
+var HOUR_AS_MS = 60 * MINUTE_AS_MS;
+var DAY_AS_MS = 24 * HOUR_AS_MS;
+var WEEK_AS_MS = 7 * DAY_AS_MS;
+var MONTH_AS_MS = 30 * DAY_AS_MS;
+var YEAR_AS_MS = 365 * DAY_AS_MS;
+var HOUR_AS_SECS = 60 * 60;
+var DAY_AS_SECS = 24 * HOUR_AS_SECS;
+var WEEK_AS_SECS = 7 * DAY_AS_SECS;
+var MONTH_AS_SECS = 30 * DAY_AS_SECS;
+var YEAR_AS_SECS = 365 * DAY_AS_SECS;
+function durationObjToMs(durationObj) {
+  return (durationObj.hours ?? 0) * HOUR_AS_MS + (durationObj.minutes ?? 0) * MINUTE_AS_MS + (durationObj.seconds ?? 0) * 1e3 + (durationObj.ms ?? 0) + (durationObj.days ?? 0) * DAY_AS_MS;
+}
+
 // src/asyncQueue.ts
-var AsyncQueue = class {
+var AsyncQueue = class _AsyncQueue {
   #queue = [];
   #pending = 0;
   #size = 0;
@@ -47,19 +63,61 @@ var AsyncQueue = class {
   #completed = 0;
   #failed = 0;
   #idleResolvers = [];
+  #sizeLessThanWaiters = [];
+  /**
+   * Event emitter for tracking task lifecycle
+   *
+   * @example Listening to Events
+   * ```typescript
+   * const queue = createAsyncQueue<string>();
+   *
+   * queue.events.on('start', (event) => {
+   *   console.log('Task started:', event.payload.meta);
+   * });
+   *
+   * queue.events.on('complete', (event) => {
+   *   console.log('Task completed:', event.payload.value);
+   * });
+   *
+   * queue.events.on('error', (event) => {
+   *   console.error('Task failed:', event.payload.error);
+   * });
+   * ```
+   */
   events = (0, import_evtmitter.evtmitter)();
   #signal;
   #taskTimeout;
+  #stopped = false;
+  #paused = false;
+  #started = false;
+  #stopOnError = false;
+  #rejectPendingOnError = false;
+  #autoStart = true;
+  #stoppedReason;
+  #rateLimit;
+  #taskExecutionTimes = [];
+  #rateLimitTimeouts = /* @__PURE__ */ new Set();
+  /** Array of all task failures with metadata for debugging and analysis */
   failures = [];
+  /** Array of all task completions with metadata for debugging and analysis */
   completions = [];
   constructor({
     concurrency = 1,
     signal,
-    timeout: taskTimeout
+    timeout: taskTimeout,
+    stopOnError = false,
+    rejectPendingOnError = false,
+    autoStart = true,
+    rateLimit
   } = {}) {
     this.#concurrency = concurrency;
     this.#signal = signal;
     this.#taskTimeout = taskTimeout;
+    this.#stopOnError = stopOnError;
+    this.#rejectPendingOnError = rejectPendingOnError;
+    this.#autoStart = autoStart;
+    this.#started = autoStart;
+    this.#rateLimit = rateLimit;
     this.events.on("error", (e) => {
       this.failures.push(e.payload);
     });
@@ -67,14 +125,113 @@ var AsyncQueue = class {
       this.completions.push(e.payload);
     });
   }
+  #getRateLimitIntervalMs() {
+    if (!this.#rateLimit) return 0;
+    return typeof this.#rateLimit.interval === "number" ? this.#rateLimit.interval : durationObjToMs(this.#rateLimit.interval);
+  }
+  #cleanupExpiredExecutionTimes(now) {
+    if (!this.#rateLimit) return;
+    const intervalMs = this.#getRateLimitIntervalMs();
+    const cutoff = now - intervalMs;
+    this.#taskExecutionTimes = this.#taskExecutionTimes.filter(
+      (time) => time > cutoff
+    );
+  }
+  #isRateLimited() {
+    if (!this.#rateLimit) return false;
+    const now = Date.now();
+    this.#cleanupExpiredExecutionTimes(now);
+    return this.#taskExecutionTimes.length >= this.#rateLimit.maxTasks;
+  }
+  #getRateLimitDelay() {
+    if (!this.#rateLimit || this.#taskExecutionTimes.length === 0) return 0;
+    const oldestExecution = this.#taskExecutionTimes[0];
+    if (oldestExecution === void 0) return 0;
+    const intervalMs = this.#getRateLimitIntervalMs();
+    const timeUntilSlotOpens = oldestExecution + intervalMs - Date.now();
+    return Math.max(0, timeUntilSlotOpens);
+  }
+  #recordTaskExecution() {
+    if (!this.#rateLimit) return;
+    const now = Date.now();
+    this.#taskExecutionTimes.push(now);
+    this.#cleanupExpiredExecutionTimes(now);
+  }
   #enqueue(task) {
     this.#queue.push(task);
     this.#size++;
   }
+  static #createTimeoutSignal(ms) {
+    const controller = new AbortController();
+    const id = setTimeout(() => {
+      controller.abort(
+        new DOMException(
+          "The operation was aborted due to timeout",
+          "TimeoutError"
+        )
+      );
+    }, ms);
+    controller.signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(id);
+      },
+      { once: true }
+    );
+    return controller.signal;
+  }
+  // removed: onEmpty-related waiters
+  #resolveSizeLessThanWaiters() {
+    if (this.#sizeLessThanWaiters.length === 0) return;
+    const remaining = [];
+    for (const waiter of this.#sizeLessThanWaiters) {
+      if (this.#size < waiter.limit) {
+        waiter.resolve();
+      } else {
+        remaining.push(waiter);
+      }
+    }
+    this.#sizeLessThanWaiters = remaining;
+  }
+  /**
+   * 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.
+   *
+   * @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) {
       return import_t_result.Result.err(
-        this.#signal.reason instanceof Error ? this.#signal.reason : new DOMException("Queue aborted", "AbortError")
+        this.#signal.reason instanceof Error ? this.#signal.reason : new DOMException("This operation was aborted", "AbortError")
+      );
+    }
+    if (this.#stopped) {
+      return import_t_result.Result.err(
+        this.#stoppedReason ?? new Error("Queue has been stopped")
       );
     }
     const deferred = defer();
@@ -90,7 +247,9 @@ var AsyncQueue = class {
       timeout: taskTimeout
     };
     this.#enqueue(task);
-    this.#processQueue();
+    if (this.#autoStart && this.#started) {
+      this.#processQueue();
+    }
     const r = await deferred.promise;
     if (options?.onComplete) {
       r.onOk(options.onComplete);
@@ -100,6 +259,44 @@ var AsyncQueue = class {
     }
     return r;
   }
+  /**
+   * Add a task that returns a plain value or throws errors to the queue
+   *
+   * 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>();
+   *
+   * queue.resultifyAdd(async () => {
+   *   const response = await fetch('/api/data');
+   *   return response.json();
+   * }).then(result => {
+   *   if (result.ok) {
+   *     console.log('Data:', result.value);
+   *   } else {
+   *     console.error('Failed:', result.error);
+   *   }
+   * });
+   * ```
+   *
+   * @example With Callbacks
+   * ```typescript
+   * queue.resultifyAdd(
+   *   async () => processData(),
+   *   {
+   *     onComplete: (data) => console.log('Processed:', data),
+   *     onError: (error) => console.error('Failed:', error),
+   *     timeout: 5000
+   *   }
+   * );
+   * ```
+   */
   resultifyAdd(fn, options) {
     return this.add(
       (ctx) => (0, import_t_result.resultify)(async () => {
@@ -113,15 +310,31 @@ var AsyncQueue = class {
       this.clear();
       return;
     }
+    if (this.#stopped || this.#paused || !this.#started) {
+      return;
+    }
     if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
       return;
     }
+    if (this.#isRateLimited()) {
+      const delay = this.#getRateLimitDelay();
+      if (delay > 0) {
+        const timeoutId = setTimeout(() => {
+          this.#rateLimitTimeouts.delete(timeoutId);
+          this.#processQueue();
+        }, delay);
+        this.#rateLimitTimeouts.add(timeoutId);
+        return;
+      }
+    }
     const task = this.#queue.shift();
     if (!task) {
       return;
     }
     this.#pending++;
     this.#size--;
+    this.#resolveSizeLessThanWaiters();
+    this.#recordTaskExecution();
     const signals = [];
     if (task.signal) {
       signals.push(task.signal);
@@ -129,8 +342,8 @@ var AsyncQueue = class {
     if (this.#signal) {
       signals.push(this.#signal);
     }
-    if (task.timeout) {
-      signals.push(AbortSignal.timeout(task.timeout));
+    if (task.timeout !== void 0) {
+      signals.push(_AsyncQueue.#createTimeoutSignal(task.timeout));
     }
     const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
     let abortListener;
@@ -141,10 +354,11 @@ var AsyncQueue = class {
       }
       const signalAbortPromise = new Promise((_, reject) => {
         if (signal) {
-          const error = signal.reason instanceof Error ? signal.reason : new DOMException("This operation was aborted", "AbortError");
           abortListener = () => {
+            const reason = signal.reason;
+            const err = reason instanceof Error ? reason : new DOMException("This operation was aborted", "AbortError");
             setTimeout(() => {
-              reject(error);
+              reject(err);
             }, 0);
           };
           signal.addEventListener("abort", abortListener, { once: true });
@@ -155,12 +369,13 @@ var AsyncQueue = class {
       const result = await Promise.race([taskRunPromise, signalAbortPromise]);
       if ((0, import_t_result.isResult)(result)) {
         task.resolve(result);
-        if (result.error) {
+        if (!result.ok) {
           this.#failed++;
           this.events.emit("error", {
             meta: task.meta,
             error: result.error
           });
+          this.#stopOnErrorAndRejectPending((0, import_t_result.unknownToError)(result.error));
         } else {
           this.#completed++;
           this.events.emit("complete", {
@@ -176,21 +391,24 @@ var AsyncQueue = class {
           meta: task.meta,
           error
         });
+        this.#stopOnErrorAndRejectPending(error);
       }
     } catch (error) {
-      task.resolve(import_t_result.Result.err(error));
+      const processedError = (0, import_t_result.unknownToError)(error);
+      task.resolve(import_t_result.Result.err(processedError));
       this.#failed++;
       this.events.emit("error", {
         meta: task.meta,
-        error: (0, import_t_result.unknownToError)(error)
+        error: processedError
       });
+      this.#stopOnErrorAndRejectPending(processedError);
     } finally {
       if (signal && abortListener) {
         signal.removeEventListener("abort", abortListener);
       }
       this.#pending--;
       this.#processQueue();
-      if (this.#pending === 0 && this.#size === 0) {
+      if (this.#pending === 0 && this.#size === 0 && this.#rateLimitTimeouts.size === 0) {
         this.#resolveIdleWaiters();
       }
     }
@@ -203,33 +421,227 @@ var AsyncQueue = class {
       }
     }
   }
+  #stopOnErrorAndRejectPending(error) {
+    if (!this.#stopOnError) {
+      return;
+    }
+    this.#stopped = true;
+    this.#stoppedReason = error;
+    if (this.#rejectPendingOnError) {
+      while (this.#queue.length > 0) {
+        const task = this.#queue.shift();
+        if (task) {
+          task.resolve(import_t_result.Result.err(error));
+        }
+      }
+      this.#size = 0;
+      this.#resolveSizeLessThanWaiters();
+    }
+    this.#resolveIdleWaiters();
+  }
+  /**
+   * 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
+   *
+   * @example
+   * ```typescript
+   * const queue = createAsyncQueue<string>();
+   *
+   * // Add multiple tasks
+   * for (let i = 0; i < 10; i++) {
+   *   queue.resultifyAdd(async () => `task ${i}`);
+   * }
+   *
+   * // Wait for all tasks to complete
+   * await queue.onIdle();
+   *
+   * console.log(`Completed: ${queue.completed}, Failed: ${queue.failed}`);
+   * ```
+   */
   async onIdle() {
-    if (this.#pending === 0 && this.#size === 0) {
+    if (this.#stopped || this.#pending === 0 && this.#size === 0 && this.#rateLimitTimeouts.size === 0) {
       return Promise.resolve();
     }
     return new Promise((resolve) => {
       this.#idleResolvers.push(resolve);
     });
   }
+  // removed: onEmpty()
+  /**
+   * Wait until the queued task count is below a limit
+   *
+   * Resolves immediately if `size < limit` at the moment of calling. This only
+   * considers queued (not yet started) tasks; running tasks are tracked by
+   * `pending`.
+   *
+   * @param limit Threshold that `size` must be below to resolve
+   */
+  onSizeLessThan(limit) {
+    if (this.#size < limit) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.#sizeLessThanWaiters.push({ limit, resolve });
+    });
+  }
+  /**
+   * 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.
+   *
+   * @example
+   * ```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
+   *
+   * // Clear remaining queued tasks
+   * queue.clear();
+   *
+   * // Only the first task will complete
+   * await queue.onIdle();
+   * ```
+   */
   clear() {
     this.#queue = [];
     this.#size = 0;
+    for (const timeoutId of this.#rateLimitTimeouts) {
+      clearTimeout(timeoutId);
+    }
+    this.#rateLimitTimeouts.clear();
     if (this.#pending === 0) {
       this.#resolveIdleWaiters();
     }
+    this.#resolveSizeLessThanWaiters();
   }
+  /** Number of tasks that have completed successfully */
   get completed() {
     return this.#completed;
   }
+  /** Number of tasks that have failed */
   get failed() {
     return this.#failed;
   }
+  /** Number of tasks currently being processed */
   get pending() {
     return this.#pending;
   }
+  /** Number of tasks waiting in the queue to be processed */
   get size() {
     return this.#size;
   }
+  /**
+   * Manually start processing tasks (only needed if autoStart: false)
+   *
+   * @example
+   * ```typescript
+   * const queue = createAsyncQueue({ autoStart: false });
+   *
+   * // Add tasks without starting processing
+   * queue.resultifyAdd(async () => 'task1');
+   * queue.resultifyAdd(async () => 'task2');
+   *
+   * // Start processing when ready
+   * queue.start();
+   * await queue.onIdle();
+   * ```
+   */
+  start() {
+    if (this.#stopped) {
+      return;
+    }
+    this.#started = true;
+    this.#processQueue();
+  }
+  /**
+   * Pause processing new tasks (currently running tasks continue)
+   *
+   * @example
+   * ```typescript
+   * const queue = createAsyncQueue();
+   *
+   * // Start some tasks
+   * queue.resultifyAdd(async () => longRunningTask1());
+   * queue.resultifyAdd(async () => longRunningTask2());
+   *
+   * // Pause before more tasks are picked up
+   * queue.pause();
+   *
+   * // Later, resume processing
+   * queue.resume();
+   * ```
+   */
+  pause() {
+    this.#paused = true;
+  }
+  /**
+   * Resume processing tasks after pause
+   */
+  resume() {
+    this.#paused = false;
+    if (this.#started && !this.#stopped) {
+      this.#processQueue();
+    }
+  }
+  /**
+   * 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.
+   *
+   * @example
+   * ```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');
+   *
+   * await queue.onIdle();
+   *
+   * 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;
+    this.#stoppedReason = void 0;
+    if (this.#autoStart) {
+      this.#started = true;
+      this.#processQueue();
+    }
+  }
+  /** Whether the queue is stopped due to an error */
+  get isStopped() {
+    return this.#stopped;
+  }
+  /** Whether the queue is currently paused */
+  get isPaused() {
+    return this.#paused;
+  }
+  /** Whether the queue has been started (relevant for autoStart: false) */
+  get isStarted() {
+    return this.#started;
+  }
+  /** The error that caused the queue to stop (if any) */
+  get stoppedReason() {
+    return this.#stoppedReason;
+  }
 };
 var AsyncQueueWithMeta = class extends AsyncQueue {
   constructor(options) {