@mrjacket/ahko 0.4.0 → 0.6.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 entry of this.entries.values()) {
+      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,218 @@ 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 entry of this.entries.values()) {
+      if (entry.windowTimerId !== void 0) {
+        clearTimeout(entry.windowTimerId);
+      }
+      if (entry.trailingReject) {
+        entry.trailingReject(new AhkoCancellationError("Throttled tasks cleared"));
+      }
+    }
+    this.entries.clear();
+  }
+};
+
+// src/events/event-emitter.ts
+var AhkoEventEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  /**
+   * Subscribes a listener to a specific Ahko lifecycle event.
+   *
+   * @param event - The event name to subscribe to.
+   * @param handler - The callback function to invoke when the event is emitted.
+   * @returns An unsubscribe function to remove the listener.
+   */
+  on(event, handler) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => {
+      this.off(event, handler);
+    };
+  }
+  /**
+   * Unsubscribes a listener from a specific Ahko lifecycle event.
+   *
+   * @param event - The event name.
+   * @param handler - The callback function to remove.
+   */
+  off(event, handler) {
+    const set = this.listeners.get(event);
+    if (set) {
+      set.delete(handler);
+      if (set.size === 0) {
+        this.listeners.delete(event);
+      }
+    }
+  }
+  /**
+   * Emits an event with the corresponding typed payload to all subscribed listeners.
+   * Listener invocations are safely isolated in try/catch to protect scheduler integrity.
+   *
+   * @param event - The event name to emit.
+   * @param payload - The event-specific payload data.
+   */
+  emit(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) {
+      return;
+    }
+    const handlers = Array.from(set);
+    for (const handler of handlers) {
+      try {
+        const result = handler(payload);
+        if (result && typeof result.catch === "function") {
+          result.catch(() => {
+          });
+        }
+      } catch {
+      }
+    }
+  }
+  /**
+   * Removes all registered event listeners.
+   */
+  clear() {
+    this.listeners.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 +512,14 @@ 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();
+  /** Lifecycle event emitter for task and scheduler events */
+  emitter = new AhkoEventEmitter();
+  /** Set of pending resolvers awaiting scheduler idle transition */
+  idleResolvers = /* @__PURE__ */ new Set();
   /** WeakMap associating task runners with their scheduling options */
   runnerOptions = /* @__PURE__ */ new WeakMap();
   /** Cumulative completed tasks counter */
@@ -155,19 +530,30 @@ var TaskQueue = class {
   cancelledTasks = 0;
   /** Cumulative timed out tasks counter */
   timedOutTasks = 0;
+  /** Cumulative count of retry attempts triggered */
+  retriedTasks = 0;
+  /** Cumulative count of tasks dispatched to concurrency slots */
+  totalDispatched = 0;
   /**
    * 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 +566,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(
@@ -240,6 +639,11 @@ var TaskQueue = class {
       if (index !== -1) {
         this.queue.splice(index, 1);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled while queued"
+        });
+        this.checkIdle();
       }
     };
     this.queue.push(runner);
@@ -263,6 +667,11 @@ var TaskQueue = class {
           if (index !== -1) {
             this.queue.splice(index, 1);
             this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+            this.checkIdle();
           }
         };
         this.queue.push(runner);
@@ -275,6 +684,11 @@ var TaskQueue = class {
         clearTimeout(delayedEntry.timerId);
         this.delayedEntries.delete(delayedEntry);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled while waiting in delay"
+        });
+        this.checkIdle();
       }
     };
   }
@@ -294,6 +708,11 @@ var TaskQueue = class {
         if (index !== -1) {
           this.queue.splice(index, 1);
           this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while queued"
+          });
+          this.checkIdle();
         }
       };
       this.queue.push(runner);
@@ -306,15 +725,51 @@ var TaskQueue = class {
         handle.cancel();
         this.idleEntries.delete(idleEntry);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled while waiting for idle"
+        });
+        this.checkIdle();
       }
     };
   }
   /**
    * 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 +778,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;
+      }
     }
   }
   /**
@@ -331,36 +798,69 @@ var TaskQueue = class {
    */
   async executeRunner(runner) {
     const options = this.runnerOptions.get(runner);
+    this.totalDispatched++;
+    this.emitter.emit("task:start", {
+      taskId: runner.taskId,
+      attempt: runner.attempt
+    });
     try {
       const result = await runner.run();
       this.completedTasks++;
       this.activeRunners.delete(runner);
       this.runnerOptions.delete(runner);
+      this.emitter.emit("task:complete", {
+        taskId: runner.taskId,
+        attempt: runner.attempt,
+        durationMs: runner.lastDurationMs,
+        result
+      });
       runner.resolve(result);
     } catch (error) {
       if (runner.state === "cancelled" /* CANCELLED */) {
         this.cancelledTasks++;
         this.activeRunners.delete(runner);
         this.runnerOptions.delete(runner);
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: error
+        });
         runner.reject(error);
         return;
       }
       const shouldRetry = await runner.canRetry(error, options?.retry);
       if (shouldRetry) {
+        this.retriedTasks++;
         this.activeRunners.delete(runner);
+        this.emitter.emit("task:fail", {
+          taskId: runner.taskId,
+          attempt: runner.attempt - 1,
+          error,
+          willRetry: true
+        });
         this.scheduleRetry(runner, options);
         return;
       }
       if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
+        this.emitter.emit("task:timeout", {
+          taskId: runner.taskId,
+          timeoutMs: runner.timeoutMs
+        });
       } else {
         this.failedTasks++;
       }
       this.activeRunners.delete(runner);
       this.runnerOptions.delete(runner);
+      this.emitter.emit("task:fail", {
+        taskId: runner.taskId,
+        attempt: runner.attempt,
+        error,
+        willRetry: false
+      });
       runner.reject(error);
     } finally {
       this.pump();
+      this.checkIdle();
     }
   }
   /**
@@ -375,6 +875,11 @@ var TaskQueue = class {
         if (index !== -1) {
           this.queue.splice(index, 1);
           this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while queued"
+          });
+          this.checkIdle();
         }
       };
       this.queue.push(runner);
@@ -393,6 +898,11 @@ var TaskQueue = class {
           if (index !== -1) {
             this.queue.splice(index, 1);
             this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+            this.checkIdle();
           }
         };
         this.queue.push(runner);
@@ -405,9 +915,91 @@ var TaskQueue = class {
         clearTimeout(retryEntry.timerId);
         this.retryEntries.delete(retryEntry);
         this.cancelledTasks++;
+        this.emitter.emit("task:cancel", {
+          taskId: runner.taskId,
+          reason: "Task cancelled during retry backoff"
+        });
+        this.checkIdle();
       }
     };
   }
+  /**
+   * Checks whether the scheduler has transitioned to idle and notifies listeners/resolvers.
+   */
+  checkIdle() {
+    if (this.isIdle()) {
+      if (this.idleResolvers.size > 0) {
+        for (const resolve of this.idleResolvers) {
+          resolve();
+        }
+        this.idleResolvers.clear();
+      }
+      this.emitter.emit("idle", { timestamp: Date.now() });
+    }
+  }
+  /**
+   * Checks whether the scheduler is currently idle (no active runners and no pending tasks).
+   *
+   * @returns True if completely idle, false otherwise.
+   */
+  isIdle() {
+    return this.activeRunners.size === 0 && this.queue.length === 0 && this.delayedEntries.size === 0 && this.idleEntries.size === 0 && this.retryEntries.size === 0 && this.debounceCoordinator.size === 0 && this.throttleCoordinator.size === 0;
+  }
+  /**
+   * Returns a promise that resolves once the scheduler has processed all tasks and is idle.
+   *
+   * @returns Promise resolving when idle.
+   */
+  onIdle() {
+    if (this.isIdle()) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.idleResolvers.add(resolve);
+    });
+  }
+  /**
+   * Clears all pending and waiting tasks from the scheduler, cancelling their runners.
+   * Active tasks currently in flight will continue to run to completion or abort via signal.
+   */
+  clear() {
+    while (this.queue.length > 0) {
+      const runner = this.queue.shift();
+      if (runner && runner.state !== "cancelled" /* CANCELLED */) {
+        runner.cancel("Scheduler cleared");
+        this.cancelledTasks++;
+        this.emitter.emit("task:cancel", { taskId: runner.taskId, reason: "Scheduler cleared" });
+      }
+    }
+    for (const entry of this.delayedEntries.values()) {
+      clearTimeout(entry.timerId);
+      entry.runner.cancel("Scheduler cleared");
+      this.cancelledTasks++;
+      this.emitter.emit("task:cancel", { taskId: entry.runner.taskId, reason: "Scheduler cleared" });
+    }
+    this.delayedEntries.clear();
+    for (const entry of this.idleEntries.values()) {
+      entry.handle.cancel();
+      entry.runner.cancel("Scheduler cleared");
+      this.cancelledTasks++;
+      this.emitter.emit("task:cancel", { taskId: entry.runner.taskId, reason: "Scheduler cleared" });
+    }
+    this.idleEntries.clear();
+    for (const entry of this.retryEntries.values()) {
+      clearTimeout(entry.timerId);
+      entry.runner.cancel("Scheduler cleared");
+      this.cancelledTasks++;
+      this.emitter.emit("task:cancel", { taskId: entry.runner.taskId, reason: "Scheduler cleared" });
+    }
+    this.retryEntries.clear();
+    this.debounceCoordinator.clear();
+    this.throttleCoordinator.clear();
+    if (this.rateLimitTimer !== void 0) {
+      clearTimeout(this.rateLimitTimer);
+      this.rateLimitTimer = void 0;
+    }
+    this.checkIdle();
+  }
   /**
    * Returns telemetry snapshot for the scheduler.
    *
@@ -416,31 +1008,18 @@ 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,
       timedOutTasks: this.timedOutTasks,
+      retriedTasks: this.retriedTasks,
+      totalDispatched: this.totalDispatched,
       capacity: this.concurrency
     });
   }
 };
 
-// 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 {
@@ -470,6 +1049,8 @@ var TaskRunner = class {
   onCancel;
   /** Current execution attempt count (1-indexed) */
   attempt = 1;
+  /** Duration of the most recent execution attempt in milliseconds */
+  lastDurationMs = 0;
   /**
    * Creates a new TaskRunner instance.
    *
@@ -628,9 +1209,11 @@ var TaskRunner = class {
     if (timeoutPromise) {
       racePromises.push(timeoutPromise);
     }
+    const startTime = Date.now();
     try {
       const result = await Promise.race(racePromises);
       this.clearTimeoutTimer();
+      this.lastDurationMs = Math.max(0, Date.now() - startTime);
       if (abortListener) {
         this.abortController.signal.removeEventListener("abort", abortListener);
       }
@@ -647,6 +1230,7 @@ var TaskRunner = class {
       return result;
     } catch (error) {
       this.clearTimeoutTimer();
+      this.lastDurationMs = Math.max(0, Date.now() - startTime);
       if (abortListener) {
         this.abortController.signal.removeEventListener("abort", abortListener);
       }
@@ -742,7 +1326,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 +1338,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 +1356,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 +1415,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 +1422,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.
    *
@@ -817,10 +1472,87 @@ var Ahko = class {
   stats() {
     return this.queue.getStats();
   }
+  /**
+   * Subscribes to a scheduler lifecycle event.
+   *
+   * @param event - Event name to listen for.
+   * @param handler - Callback function invoked when the event is emitted.
+   * @returns Unsubscribe function to remove the listener.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = ahko.on("task:start", ({ taskId, attempt }) => {
+   *   console.log(`Task ${taskId} started attempt ${attempt}`);
+   * });
+   * ```
+   */
+  on(event, handler) {
+    return this.queue.emitter.on(event, handler);
+  }
+  /**
+   * Unsubscribes an event listener from a scheduler lifecycle event.
+   *
+   * @param event - Event name.
+   * @param handler - The exact listener callback to remove.
+   */
+  off(event, handler) {
+    this.queue.emitter.off(event, handler);
+  }
+  /**
+   * Checks whether the scheduler is currently idle (no active runners and no pending tasks).
+   *
+   * @returns True if completely idle, false otherwise.
+   */
+  isIdle() {
+    return this.queue.isIdle();
+  }
+  /**
+   * Returns a promise that resolves once the scheduler has completed all tasks and is idle.
+   *
+   * @returns Promise resolving when the scheduler is idle.
+   *
+   * @example
+   * ```typescript
+   * ahko.schedule(doWork);
+   * await ahko.onIdle();
+   * console.log("All work finished!");
+   * ```
+   */
+  onIdle() {
+    return this.queue.onIdle();
+  }
+  /**
+   * Clears all pending, delayed, and throttled/debounced tasks from the scheduler.
+   * In-flight active tasks will continue executing to completion or abort via signal.
+   */
+  clear() {
+    this.queue.clear();
+  }
+  /**
+   * Returns the delightful Ahko mascot battery telemetry status.
+   *
+   * Low energy, completely chill.
+   */
+  battery() {
+    return {
+      level: 3,
+      chill: true,
+      status: "low-energy",
+      quote: "Mwee... my battery is low, but all your tasks are handled completely chill."
+    };
+  }
+  /**
+   * Delightful alias for `onIdle()`: wait for all tasks to settle chill and relaxed.
+   *
+   * @returns Promise resolving when all tasks have finished.
+   */
+  chill() {
+    return this.onIdle();
+  }
 };
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.6.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {