@mrjacket/ahko 0.4.0 → 0.5.0

package/dist/index.js

@@ -33,6 +33,8 @@ var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
   EScheduleStrategy2["IMMEDIATE"] = "immediate";
   EScheduleStrategy2["DELAY"] = "delay";
   EScheduleStrategy2["IDLE"] = "idle";
+  EScheduleStrategy2["THROTTLE"] = "throttle";
+  EScheduleStrategy2["DEBOUNCE"] = "debounce";
   return EScheduleStrategy2;
 })(EScheduleStrategy || {});
 
@@ -92,6 +94,163 @@ function calculateBackoff(attempt, options, randomFn = Math.random) {
   return Math.floor(cappedDelay);
 }
 
+// src/errors/cancellation.error.ts
+var AhkoCancellationError = class extends AhkoError {
+  /**
+   * Creates a new AhkoCancellationError.
+   *
+   * @param message - Reason for cancellation.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message = "Task was cancelled", options) {
+    super(message, options);
+    this.name = "AhkoCancellationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/scheduler/debounce-coordinator.ts
+var DebounceCoordinator = class {
+  entries = /* @__PURE__ */ new Map();
+  /**
+   * Schedules a task under the debounce strategy.
+   *
+   * @param key - Explicit identity key.
+   * @param task - Work to execute once calls stop arriving.
+   * @param waitMs - Quiet window duration in milliseconds.
+   * @param options - Scheduling options.
+   * @param dispatchFn - Callback invoked when the debounce window expires to dispatch the task to the queue.
+   * @returns Shared promise that resolves/rejects with the final execution outcome.
+   */
+  schedule(key, task, waitMs, options, dispatchFn) {
+    const existing = this.entries.get(key);
+    if (existing) {
+      clearTimeout(existing.timerId);
+      if (existing.options?.signal && existing.abortListener) {
+        existing.options.signal.removeEventListener("abort", existing.abortListener);
+      }
+      existing.task = task;
+      existing.options = options;
+      if (options?.signal?.aborted) {
+        this.entries.delete(key);
+        const err = new AhkoCancellationError(
+          typeof options.signal.reason === "string" ? options.signal.reason : "Debounced task was cancelled prior to execution",
+          { cause: options.signal.reason instanceof Error ? options.signal.reason : void 0 }
+        );
+        existing.reject(err);
+        return existing.promise;
+      }
+      if (options?.signal) {
+        const listener = () => {
+          this.cancel(key, options.signal?.reason);
+        };
+        existing.abortListener = listener;
+        options.signal.addEventListener("abort", listener, { once: true });
+      }
+      existing.timerId = setTimeout(() => {
+        void this.flush(key, dispatchFn);
+      }, waitMs);
+      return existing.promise;
+    }
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+    if (options?.signal?.aborted) {
+      const err = new AhkoCancellationError(
+        typeof options.signal.reason === "string" ? options.signal.reason : "Debounced task was cancelled prior to execution",
+        { cause: options.signal.reason instanceof Error ? options.signal.reason : void 0 }
+      );
+      rejectPromise(err);
+      return promise;
+    }
+    let abortListener;
+    if (options?.signal) {
+      abortListener = () => {
+        this.cancel(key, options.signal?.reason);
+      };
+      options.signal.addEventListener("abort", abortListener, { once: true });
+    }
+    const timerId = setTimeout(() => {
+      void this.flush(key, dispatchFn);
+    }, waitMs);
+    const entry = {
+      key,
+      task,
+      options,
+      timerId,
+      resolve: resolvePromise,
+      reject: rejectPromise,
+      promise,
+      abortListener
+    };
+    this.entries.set(key, entry);
+    return promise;
+  }
+  /**
+   * Dispatches the coalesced task when the quiet window expires.
+   */
+  async flush(key, dispatchFn) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    this.entries.delete(key);
+    if (entry.options?.signal && entry.abortListener) {
+      entry.options.signal.removeEventListener("abort", entry.abortListener);
+    }
+    try {
+      const result = await dispatchFn(entry.task, entry.options);
+      entry.resolve(result);
+    } catch (error) {
+      entry.reject(error);
+    }
+  }
+  /**
+   * Cancels a pending debounced task by key.
+   *
+   * @param key - Identity key to cancel.
+   * @param reason - Optional cancellation reason.
+   */
+  cancel(key, reason) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    clearTimeout(entry.timerId);
+    this.entries.delete(key);
+    if (entry.options?.signal && entry.abortListener) {
+      entry.options.signal.removeEventListener("abort", entry.abortListener);
+    }
+    const cancelError = new AhkoCancellationError(
+      typeof reason === "string" ? reason : "Debounced task was cancelled prior to execution",
+      { cause: reason instanceof Error ? reason : void 0 }
+    );
+    entry.reject(cancelError);
+  }
+  /**
+   * Number of pending debounced tasks waiting for quiet window expiry.
+   */
+  get size() {
+    return this.entries.size;
+  }
+  /**
+   * Cancels all pending debounced entries and clears the map.
+   */
+  clear() {
+    for (const [key, entry] of this.entries) {
+      clearTimeout(entry.timerId);
+      if (entry.options?.signal && entry.abortListener) {
+        entry.options.signal.removeEventListener("abort", entry.abortListener);
+      }
+      entry.reject(new AhkoCancellationError("Debounced tasks cleared"));
+    }
+    this.entries.clear();
+  }
+};
+
 // src/scheduler/idle-scheduler.ts
 var IdleScheduler = class {
   /**
@@ -131,10 +290,150 @@ var IdleScheduler = class {
   }
 };
 
+// src/scheduler/throttle-coordinator.ts
+var ThrottleCoordinator = class {
+  entries = /* @__PURE__ */ new Map();
+  /**
+   * Schedules a task under the throttle strategy.
+   *
+   * @param key - Explicit identity key.
+   * @param task - Work to execute.
+   * @param waitMs - Throttle interval duration in milliseconds.
+   * @param options - Scheduling options.
+   * @param dispatchFn - Callback invoked to dispatch task execution into the queue.
+   * @returns Promise resolving with the leading execution or coalesced trailing result.
+   */
+  schedule(key, task, waitMs, options, dispatchFn) {
+    const existing = this.entries.get(key);
+    if (!existing) {
+      const entry = {
+        key
+      };
+      entry.windowTimerId = setTimeout(() => {
+        void this.onWindowExpire(key, waitMs, dispatchFn);
+      }, waitMs);
+      this.entries.set(key, entry);
+      return dispatchFn(task, options);
+    }
+    existing.trailingTask = task;
+    existing.trailingOptions = options;
+    if (existing.trailingPromise) {
+      return existing.trailingPromise;
+    }
+    let resolvePromise;
+    let rejectPromise;
+    existing.trailingPromise = new Promise((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+    existing.trailingResolve = resolvePromise;
+    existing.trailingReject = rejectPromise;
+    if (options?.signal) {
+      const listener = () => {
+        if (existing.trailingReject) {
+          existing.trailingReject(
+            new AhkoCancellationError("Throttled trailing task was cancelled", {
+              cause: options.signal?.reason instanceof Error ? options.signal.reason : void 0
+            })
+          );
+          existing.trailingTask = void 0;
+          existing.trailingOptions = void 0;
+          existing.trailingPromise = void 0;
+          existing.trailingResolve = void 0;
+          existing.trailingReject = void 0;
+        }
+      };
+      existing.abortListener = listener;
+      options.signal.addEventListener("abort", listener, { once: true });
+    }
+    return existing.trailingPromise;
+  }
+  /**
+   * Invoked when the throttle interval window timer expires.
+   */
+  async onWindowExpire(key, waitMs, dispatchFn) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    if (entry.trailingTask) {
+      const task = entry.trailingTask;
+      const options = entry.trailingOptions;
+      const resolve = entry.trailingResolve;
+      const reject = entry.trailingReject;
+      entry.trailingTask = void 0;
+      entry.trailingOptions = void 0;
+      entry.trailingPromise = void 0;
+      entry.trailingResolve = void 0;
+      entry.trailingReject = void 0;
+      entry.windowTimerId = setTimeout(() => {
+        void this.onWindowExpire(key, waitMs, dispatchFn);
+      }, waitMs);
+      try {
+        const result = await dispatchFn(task, options);
+        resolve?.(result);
+      } catch (error) {
+        reject?.(error);
+      }
+      return;
+    }
+    this.entries.delete(key);
+  }
+  /**
+   * Cancels any pending trailing throttled task for a given key.
+   *
+   * @param key - Identity key to cancel.
+   * @param reason - Optional cancellation reason.
+   */
+  cancel(key, reason) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    if (entry.windowTimerId !== void 0) {
+      clearTimeout(entry.windowTimerId);
+    }
+    this.entries.delete(key);
+    if (entry.trailingReject) {
+      const cancelError = new AhkoCancellationError(
+        typeof reason === "string" ? reason : "Throttled task was cancelled",
+        { cause: reason instanceof Error ? reason : void 0 }
+      );
+      entry.trailingReject(cancelError);
+    }
+  }
+  /**
+   * Number of keys currently actively throttled.
+   */
+  get size() {
+    return this.entries.size;
+  }
+  /**
+   * Clears all throttled entries and timers.
+   */
+  clear() {
+    for (const [key, entry] of this.entries) {
+      if (entry.windowTimerId !== void 0) {
+        clearTimeout(entry.windowTimerId);
+      }
+      if (entry.trailingReject) {
+        entry.trailingReject(new AhkoCancellationError("Throttled tasks cleared"));
+      }
+    }
+    this.entries.clear();
+  }
+};
+
 // src/scheduler/task-queue.ts
 var TaskQueue = class {
   /** Maximum concurrent active tasks */
   concurrency;
+  /** Minimum interval in milliseconds between consecutive task starts */
+  minIntervalMs;
+  /** Timestamp of the most recent task start */
+  lastTaskStartTime = 0;
+  /** Active rate limit timer for pacing consecutive tasks */
+  rateLimitTimer;
   /** Queue of pending task runners waiting for a concurrency slot */
   queue = [];
   /** Set of task runners currently executing */
@@ -145,6 +444,10 @@ var TaskQueue = class {
   idleEntries = /* @__PURE__ */ new Set();
   /** Set of tasks currently awaiting a retry backoff timer */
   retryEntries = /* @__PURE__ */ new Set();
+  /** Coordinator for debounced tasks with key coalescing */
+  debounceCoordinator = new DebounceCoordinator();
+  /** Coordinator for throttled tasks with leading/trailing coalescing */
+  throttleCoordinator = new ThrottleCoordinator();
   /** WeakMap associating task runners with their scheduling options */
   runnerOptions = /* @__PURE__ */ new WeakMap();
   /** Cumulative completed tasks counter */
@@ -159,15 +462,22 @@ var TaskQueue = class {
    * Creates a new TaskQueue.
    *
    * @param concurrency - Maximum concurrent tasks (defaults to Infinity).
-   * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.
+   * @param minIntervalMs - Minimum interval in milliseconds between task dispatches.
+   * @throws {AhkoConfigurationError} If concurrency is less than 1 or minIntervalMs is invalid.
    */
-  constructor(concurrency = Infinity) {
+  constructor(concurrency = Infinity, minIntervalMs = 0) {
     if (Number.isNaN(concurrency) || concurrency < 1) {
       throw new AhkoConfigurationError(
         `Invalid concurrency "${concurrency}". Must be a number greater than or equal to 1.`
       );
     }
+    if (typeof minIntervalMs !== "number" || Number.isNaN(minIntervalMs) || !Number.isFinite(minIntervalMs) || minIntervalMs < 0) {
+      throw new AhkoConfigurationError(
+        `Invalid minIntervalMs "${minIntervalMs}". minIntervalMs must be a non-negative finite number.`
+      );
+    }
     this.concurrency = concurrency;
+    this.minIntervalMs = minIntervalMs;
   }
   /**
    * Enqueues a task runner according to the specified schedule options.
@@ -180,11 +490,24 @@ var TaskQueue = class {
    */
   enqueue(runner, options) {
     const strategy = options?.strategy ?? "immediate" /* IMMEDIATE */;
-    if (strategy !== "immediate" /* IMMEDIATE */ && strategy !== "delay" /* DELAY */ && strategy !== "idle" /* IDLE */) {
+    if (strategy !== "immediate" /* IMMEDIATE */ && strategy !== "delay" /* DELAY */ && strategy !== "idle" /* IDLE */ && strategy !== "throttle" /* THROTTLE */ && strategy !== "debounce" /* DEBOUNCE */) {
       throw new AhkoConfigurationError(
-        `Unsupported schedule strategy "${String(strategy)}". Supported strategies: "immediate", "delay", "idle".`
+        `Unsupported schedule strategy "${String(strategy)}". Supported strategies: "immediate", "delay", "idle", "throttle", "debounce".`
       );
     }
+    if (strategy === "throttle" /* THROTTLE */ || strategy === "debounce" /* DEBOUNCE */) {
+      if (!options?.key || typeof options.key !== "string" && typeof options.key !== "symbol") {
+        throw new AhkoConfigurationError(
+          `Strategy "${strategy}" requires a valid "key" of type string or symbol.`
+        );
+      }
+      const waitMs = options.waitMs ?? options.delay;
+      if (typeof waitMs !== "number" || Number.isNaN(waitMs) || !Number.isFinite(waitMs) || waitMs < 0) {
+        throw new AhkoConfigurationError(
+          `Strategy "${strategy}" requires a non-negative finite "waitMs" or "delay" in milliseconds.`
+        );
+      }
+    }
     if (options?.retry) {
       if (typeof options.retry.attempts !== "number" || Number.isNaN(options.retry.attempts) || options.retry.attempts < 1 || !Number.isInteger(options.retry.attempts)) {
         throw new AhkoConfigurationError(
@@ -311,10 +634,41 @@ var TaskQueue = class {
   }
   /**
    * Pumps the queue by picking pending tasks and executing them
-   * as long as concurrency capacity is available.
+   * as long as concurrency capacity is available and minIntervalMs is respected.
    */
   pump() {
+    if (this.queue.length === 0 || this.activeRunners.size >= this.concurrency) {
+      return;
+    }
+    if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
+      const now = Date.now();
+      const elapsed = now - this.lastTaskStartTime;
+      if (elapsed < this.minIntervalMs) {
+        if (this.rateLimitTimer === void 0) {
+          const delay = this.minIntervalMs - elapsed;
+          this.rateLimitTimer = setTimeout(() => {
+            this.rateLimitTimer = void 0;
+            this.pump();
+          }, delay);
+        }
+        return;
+      }
+    }
     while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {
+      if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
+        const now = Date.now();
+        const elapsed = now - this.lastTaskStartTime;
+        if (elapsed < this.minIntervalMs) {
+          if (this.rateLimitTimer === void 0) {
+            const delay = this.minIntervalMs - elapsed;
+            this.rateLimitTimer = setTimeout(() => {
+              this.rateLimitTimer = void 0;
+              this.pump();
+            }, delay);
+          }
+          break;
+        }
+      }
       const runner = this.queue.shift();
       if (!runner) {
         break;
@@ -323,7 +677,19 @@ var TaskQueue = class {
         continue;
       }
       this.activeRunners.add(runner);
+      this.lastTaskStartTime = Date.now();
       void this.executeRunner(runner);
+      if (this.minIntervalMs > 0) {
+        if (this.queue.length > 0 && this.activeRunners.size < this.concurrency) {
+          if (this.rateLimitTimer === void 0) {
+            this.rateLimitTimer = setTimeout(() => {
+              this.rateLimitTimer = void 0;
+              this.pump();
+            }, this.minIntervalMs);
+          }
+        }
+        break;
+      }
     }
   }
   /**
@@ -416,7 +782,7 @@ var TaskQueue = class {
   getStats() {
     return Object.freeze({
       activeTasks: this.activeRunners.size,
-      pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size + this.retryEntries.size,
+      pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size + this.retryEntries.size + this.debounceCoordinator.size + this.throttleCoordinator.size,
       completedTasks: this.completedTasks,
       failedTasks: this.failedTasks,
       cancelledTasks: this.cancelledTasks,
@@ -426,21 +792,6 @@ var TaskQueue = class {
   }
 };
 
-// src/errors/cancellation.error.ts
-var AhkoCancellationError = class extends AhkoError {
-  /**
-   * Creates a new AhkoCancellationError.
-   *
-   * @param message - Reason for cancellation.
-   * @param options - Standard Error options including cause.
-   */
-  constructor(message = "Task was cancelled", options) {
-    super(message, options);
-    this.name = "AhkoCancellationError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-
 // src/scheduler/task-runner.ts
 var taskIdCounter = 0;
 var TaskRunner = class {
@@ -742,7 +1093,7 @@ var Ahko = class {
    * ```
    */
   constructor(options) {
-    this.queue = new TaskQueue(options?.concurrency);
+    this.queue = new TaskQueue(options?.concurrency, options?.minIntervalMs);
   }
   /**
    * Schedules a task for execution with full return type inference.
@@ -754,6 +1105,7 @@ var Ahko = class {
    *
    * @throws {AhkoConfigurationError} If the task is not a function or options are invalid.
    * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.
+   * @throws {AhkoTimeoutError} If task execution exceeds timeoutMs.
    *
    * @example
    * ```typescript
@@ -771,6 +1123,47 @@ var Ahko = class {
     if (typeof task !== "function") {
       throw new AhkoConfigurationError("Task must be a valid function.");
     }
+    const strategy = options?.strategy ?? "immediate" /* IMMEDIATE */;
+    if (strategy === "debounce" /* DEBOUNCE */) {
+      if (!options?.key || typeof options.key !== "string" && typeof options.key !== "symbol") {
+        throw new AhkoConfigurationError(
+          `Strategy "debounce" requires a valid "key" of type string or symbol.`
+        );
+      }
+      const waitMs = options.waitMs ?? options.delay;
+      if (typeof waitMs !== "number" || Number.isNaN(waitMs) || !Number.isFinite(waitMs) || waitMs < 0) {
+        throw new AhkoConfigurationError(
+          `Strategy "debounce" requires a non-negative finite "waitMs" or "delay" in milliseconds.`
+        );
+      }
+      return this.queue.debounceCoordinator.schedule(
+        options.key,
+        task,
+        waitMs,
+        options,
+        (t, opts) => this.schedule(t, { ...opts, strategy: "immediate" /* IMMEDIATE */ })
+      );
+    }
+    if (strategy === "throttle" /* THROTTLE */) {
+      if (!options?.key || typeof options.key !== "string" && typeof options.key !== "symbol") {
+        throw new AhkoConfigurationError(
+          `Strategy "throttle" requires a valid "key" of type string or symbol.`
+        );
+      }
+      const waitMs = options.waitMs ?? options.delay;
+      if (typeof waitMs !== "number" || Number.isNaN(waitMs) || !Number.isFinite(waitMs) || waitMs < 0) {
+        throw new AhkoConfigurationError(
+          `Strategy "throttle" requires a non-negative finite "waitMs" or "delay" in milliseconds.`
+        );
+      }
+      return this.queue.throttleCoordinator.schedule(
+        options.key,
+        task,
+        waitMs,
+        options,
+        (t, opts) => this.schedule(t, { ...opts, strategy: "immediate" /* IMMEDIATE */ })
+      );
+    }
     const runner = new TaskRunner(task, options?.signal, options?.timeoutMs);
     return this.queue.enqueue(runner, options);
   }
@@ -789,13 +1182,6 @@ var Ahko = class {
    *
    * @throws {AhkoConfigurationError} If the task is not a function or options are invalid.
    * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.
-   *
-   * @example
-   * ```typescript
-   * const result = await ahko.idle(async ({ signal }) => {
-   *   return computeAnalytics();
-   * });
-   * ```
    */
   idle(task, options) {
     return this.schedule(task, {
@@ -803,6 +1189,42 @@ var Ahko = class {
       strategy: "idle" /* IDLE */
     });
   }
+  /**
+   * Convenience method to schedule a debounced task with key-based Promise coalescing.
+   *
+   * @template T - Inferred return type of the task.
+   * @param key - Explicit identity key.
+   * @param task - Work to execute once calls stop arriving.
+   * @param waitMs - Quiet window duration in milliseconds.
+   * @param options - Additional schedule options.
+   * @returns Shared promise resolving with the final execution outcome.
+   */
+  debounce(key, task, waitMs, options) {
+    return this.schedule(task, {
+      ...options,
+      strategy: "debounce" /* DEBOUNCE */,
+      key,
+      waitMs
+    });
+  }
+  /**
+   * Convenience method to schedule a throttled task with leading execution and coalesced trailing run.
+   *
+   * @template T - Inferred return type of the task.
+   * @param key - Explicit identity key.
+   * @param task - Work to execute.
+   * @param waitMs - Throttle interval duration in milliseconds.
+   * @param options - Additional schedule options.
+   * @returns Promise resolving with the leading or coalesced trailing result.
+   */
+  throttle(key, task, waitMs, options) {
+    return this.schedule(task, {
+      ...options,
+      strategy: "throttle" /* THROTTLE */,
+      key,
+      waitMs
+    });
+  }
   /**
    * Retrieves real-time telemetry metrics from the scheduler.
    *
@@ -820,7 +1242,7 @@ var Ahko = class {
 };
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {