@mrjacket/ahko 0.3.0 → 0.5.0

package/dist/index.js

@@ -33,9 +33,31 @@ var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
   EScheduleStrategy2["IMMEDIATE"] = "immediate";
   EScheduleStrategy2["DELAY"] = "delay";
   EScheduleStrategy2["IDLE"] = "idle";
+  EScheduleStrategy2["THROTTLE"] = "throttle";
+  EScheduleStrategy2["DEBOUNCE"] = "debounce";
   return EScheduleStrategy2;
 })(EScheduleStrategy || {});
 
+// src/errors/timeout.error.ts
+var AhkoTimeoutError = class extends AhkoError {
+  /**
+   * The timeout threshold in milliseconds that was exceeded, if configured.
+   */
+  timeoutMs;
+  /**
+   * Creates a new AhkoTimeoutError.
+   *
+   * @param message - Explanation of timeout expiry.
+   * @param options - Standard Error options including optional timeoutMs and cause.
+   */
+  constructor(message = "Task execution timed out", options) {
+    super(message, options);
+    this.name = "AhkoTimeoutError";
+    this.timeoutMs = options?.timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
 // src/models/state.model.ts
 var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   ETaskState2["PENDING"] = "pending";
@@ -72,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 {
   /**
@@ -111,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 */
@@ -125,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 */
@@ -139,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.
@@ -160,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(
@@ -182,6 +525,13 @@ var TaskQueue = class {
         );
       }
     }
+    if (options?.timeoutMs !== void 0) {
+      if (typeof options.timeoutMs !== "number" || Number.isNaN(options.timeoutMs) || !Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        throw new AhkoConfigurationError(
+          `Invalid timeoutMs "${options.timeoutMs}". timeoutMs must be a positive finite number greater than 0.`
+        );
+      }
+    }
     if (options) {
       this.runnerOptions.set(runner, options);
     }
@@ -284,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;
@@ -296,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;
+      }
     }
   }
   /**
@@ -324,7 +717,7 @@ var TaskQueue = class {
         this.scheduleRetry(runner, options);
         return;
       }
-      if (runner.state === "timed_out" /* TIMED_OUT */) {
+      if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
       } else {
         this.failedTasks++;
@@ -389,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,
@@ -399,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 {
@@ -427,6 +805,10 @@ var TaskRunner = class {
   task;
   /** User-supplied AbortSignal for external cancellation */
   externalSignal;
+  /** Maximum execution duration allowed in milliseconds */
+  timeoutMs;
+  /** Active timeout timer identifier */
+  timeoutTimerId;
   /** Abort event listener reference for clean detachment */
   abortListener;
   /** Promise resolve handler */
@@ -437,16 +819,20 @@ var TaskRunner = class {
   promise;
   /** Callback invoked when runner is cancelled while pending */
   onCancel;
+  /** Current execution attempt count (1-indexed) */
+  attempt = 1;
   /**
    * Creates a new TaskRunner instance.
    *
    * @param task - The asynchronous work unit to run.
    * @param externalSignal - Optional external AbortSignal to propagate.
+   * @param timeoutMs - Optional maximum execution time in milliseconds.
    */
-  constructor(task, externalSignal) {
+  constructor(task, externalSignal, timeoutMs) {
     this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
     this.task = task;
     this.externalSignal = externalSignal;
+    this.timeoutMs = timeoutMs;
     this.abortController = new AbortController();
     this.promise = new Promise((resolve, reject) => {
       this.resolvePromise = resolve;
@@ -460,6 +846,7 @@ var TaskRunner = class {
           typeof reason === "string" ? reason : "Task was cancelled prior to execution",
           { cause: reason instanceof Error ? reason : void 0 }
         );
+        this.abortController.abort(cancelError);
         this.rejectPromise(cancelError);
       } else {
         this.abortListener = () => {
@@ -475,8 +862,6 @@ var TaskRunner = class {
   get state() {
     return this._state;
   }
-  /** Current execution attempt count (1-indexed) */
-  attempt = 1;
   /**
    * Resolves the deferred promise.
    *
@@ -496,14 +881,14 @@ var TaskRunner = class {
     this.rejectPromise(reason);
   }
   /**
-   * Evaluates if the task should be retried following an execution failure.
+   * Evaluates if the task should be retried following an execution failure or timeout.
    *
    * @param error - The error encountered during the attempt.
    * @param retryOptions - Configured retry policy.
    * @returns A promise resolving to true if retry should proceed, false otherwise.
    */
   async canRetry(error, retryOptions) {
-    if (this._state === "cancelled" /* CANCELLED */ || this.abortController.signal.aborted) {
+    if (this._state === "cancelled" /* CANCELLED */ || (this.externalSignal?.aborted ?? false)) {
       return false;
     }
     if (!retryOptions || typeof retryOptions.attempts !== "number") {
@@ -524,12 +909,13 @@ var TaskRunner = class {
     }
     this.attempt++;
     this._state = "pending" /* PENDING */;
+    this.abortController = new AbortController();
     return true;
   }
   /**
    * Executes the task within an allocated concurrency slot.
    *
-   * @returns A promise resolving to the task result or rejecting on failure/cancellation.
+   * @returns A promise resolving to the task result or rejecting on failure/cancellation/timeout.
    */
   async run() {
     if (this._state === "cancelled" /* CANCELLED */) {
@@ -540,14 +926,100 @@ var TaskRunner = class {
       signal: this.abortController.signal,
       taskId: this.taskId
     };
+    let abortListener;
+    const abortPromise = new Promise((_, reject) => {
+      abortListener = () => {
+        if (this._state === "timed_out" /* TIMED_OUT */) {
+          reject(
+            new AhkoTimeoutError(
+              `Task execution timed out after ${this.timeoutMs}ms`,
+              { timeoutMs: this.timeoutMs }
+            )
+          );
+        } else {
+          const reason = this.abortController.signal.reason;
+          reject(
+            new AhkoCancellationError("Task was cancelled during execution", {
+              cause: reason instanceof Error ? reason : void 0
+            })
+          );
+        }
+      };
+      this.abortController.signal.addEventListener("abort", abortListener, { once: true });
+    });
+    let timeoutPromise;
+    if (this.timeoutMs !== void 0) {
+      timeoutPromise = new Promise((_, reject) => {
+        this.timeoutTimerId = setTimeout(() => {
+          if (this._state !== "running" /* RUNNING */) {
+            return;
+          }
+          this._state = "timed_out" /* TIMED_OUT */;
+          const timeoutError = new AhkoTimeoutError(
+            `Task execution timed out after ${this.timeoutMs}ms`,
+            { timeoutMs: this.timeoutMs }
+          );
+          this.abortController.abort(timeoutError);
+          reject(timeoutError);
+        }, this.timeoutMs);
+      });
+    }
+    let taskExecutionPromise;
+    try {
+      taskExecutionPromise = Promise.resolve(this.task(context));
+    } catch (syncError) {
+      taskExecutionPromise = Promise.reject(syncError);
+    }
+    taskExecutionPromise.catch(() => {
+    });
+    const racePromises = [
+      taskExecutionPromise,
+      abortPromise
+    ];
+    if (timeoutPromise) {
+      racePromises.push(timeoutPromise);
+    }
     try {
-      const result = await this.task(context);
+      const result = await Promise.race(racePromises);
+      this.clearTimeoutTimer();
+      if (abortListener) {
+        this.abortController.signal.removeEventListener("abort", abortListener);
+      }
+      if (this._state === "timed_out" /* TIMED_OUT */) {
+        throw new AhkoTimeoutError(
+          `Task execution timed out after ${this.timeoutMs}ms`,
+          { timeoutMs: this.timeoutMs }
+        );
+      }
+      if (this._state === "cancelled" /* CANCELLED */) {
+        throw new AhkoCancellationError("Task was cancelled during execution");
+      }
       this._state = "completed" /* COMPLETED */;
       return result;
     } catch (error) {
-      const isCancelled = this._state === "cancelled" /* CANCELLED */ || this.abortController.signal.aborted;
+      this.clearTimeoutTimer();
+      if (abortListener) {
+        this.abortController.signal.removeEventListener("abort", abortListener);
+      }
+      if (this._state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
+        this._state = "timed_out" /* TIMED_OUT */;
+        if (error instanceof AhkoTimeoutError) {
+          throw error;
+        }
+        throw new AhkoTimeoutError(
+          `Task execution timed out after ${this.timeoutMs}ms`,
+          {
+            timeoutMs: this.timeoutMs,
+            cause: error instanceof Error ? error : void 0
+          }
+        );
+      }
+      const isCancelled = this._state === "cancelled" /* CANCELLED */ || this.abortController.signal.aborted || (this.externalSignal?.aborted ?? false);
       if (isCancelled) {
         this._state = "cancelled" /* CANCELLED */;
+        if (error instanceof AhkoCancellationError) {
+          throw error;
+        }
         throw new AhkoCancellationError("Task was cancelled during execution", {
           cause: error instanceof Error ? error : void 0
         });
@@ -556,6 +1028,15 @@ var TaskRunner = class {
       throw error;
     }
   }
+  /**
+   * Clears the active timeout timer.
+   */
+  clearTimeoutTimer() {
+    if (this.timeoutTimerId !== void 0) {
+      clearTimeout(this.timeoutTimerId);
+      this.timeoutTimerId = void 0;
+    }
+  }
   /**
    * Cancels the task, aborting pending or running execution.
    *
@@ -567,6 +1048,7 @@ var TaskRunner = class {
     }
     const wasPending = this._state === "pending" /* PENDING */;
     this._state = "cancelled" /* CANCELLED */;
+    this.clearTimeoutTimer();
     this.abortController.abort(reason);
     this.cleanup();
     if (wasPending) {
@@ -588,6 +1070,7 @@ var TaskRunner = class {
    * Detaches event listeners from external signal to guarantee memory safety.
    */
   cleanup() {
+    this.clearTimeoutTimer();
     if (this.externalSignal && this.abortListener) {
       this.externalSignal.removeEventListener("abort", this.abortListener);
     }
@@ -610,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.
@@ -622,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
@@ -639,7 +1123,48 @@ var Ahko = class {
     if (typeof task !== "function") {
       throw new AhkoConfigurationError("Task must be a valid function.");
     }
-    const runner = new TaskRunner(task, options?.signal);
+    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);
   }
   /**
@@ -657,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, {
@@ -671,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.
    *
@@ -688,7 +1242,7 @@ var Ahko = class {
 };
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.5.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {
@@ -705,20 +1259,60 @@ var AhkoQueueError = class extends AhkoError {
   }
 };
 
-// src/errors/timeout.error.ts
-var AhkoTimeoutError = class extends AhkoError {
-  /**
-   * Creates a new AhkoTimeoutError.
-   *
-   * @param message - Explanation of timeout expiry.
-   * @param options - Standard Error options including cause.
-   */
-  constructor(message = "Task execution timed out", options) {
-    super(message, options);
-    this.name = "AhkoTimeoutError";
-    Object.setPrototypeOf(this, new.target.prototype);
+// src/scheduler/signal.ts
+function combineSignals(signals) {
+  const activeSignals = signals.filter(
+    (signal) => signal !== void 0
+  );
+  if (activeSignals.length === 0) {
+    const controller2 = new AbortController();
+    return {
+      signal: controller2.signal,
+      cleanup: () => {
+      }
+    };
   }
-};
+  const alreadyAborted = activeSignals.find((s) => s.aborted);
+  if (alreadyAborted) {
+    const controller2 = new AbortController();
+    controller2.abort(alreadyAborted.reason);
+    return {
+      signal: controller2.signal,
+      cleanup: () => {
+      }
+    };
+  }
+  if (activeSignals.length === 1) {
+    return {
+      signal: activeSignals[0],
+      cleanup: () => {
+      }
+    };
+  }
+  const controller = new AbortController();
+  const cleanupFns = [];
+  const onAbort = (event) => {
+    const target = event.target;
+    cleanup();
+    controller.abort(target.reason);
+  };
+  for (const sig of activeSignals) {
+    sig.addEventListener("abort", onAbort, { once: true });
+    cleanupFns.push(() => {
+      sig.removeEventListener("abort", onAbort);
+    });
+  }
+  const cleanup = () => {
+    for (const fn of cleanupFns) {
+      fn();
+    }
+    cleanupFns.length = 0;
+  };
+  return {
+    signal: controller.signal,
+    cleanup
+  };
+}
 export {
   Ahko,
   AhkoCancellationError,
@@ -731,6 +1325,7 @@ export {
   EScheduleStrategy,
   ETaskState,
   VERSION,
-  calculateBackoff
+  calculateBackoff,
+  combineSignals
 };
 //# sourceMappingURL=index.js.map