@mrjacket/ahko 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-22 — Throttle, Debounce & Rate Limiting
+
+### Added
+- Debounce scheduling strategy (`EScheduleStrategy.DEBOUNCE`) with quiet window timer resets.
+- Throttle scheduling strategy (`EScheduleStrategy.THROTTLE`) with immediate leading execution and coalesced trailing run.
+- Promise coalescing by explicit identity key (`key: string | symbol`): all concurrent callers awaiting the same key receive the exact same Promise resolution without artificial cancellation rejections.
+- Task start interval rate limiting via `minIntervalMs` on scheduler constructor (`IAhkoOptions`).
+- Automatic key cleanup and timer detachment upon settlement guaranteeing zero memory leaks.
+- Convenience API methods `ahko.debounce()` and `ahko.throttle()`.
+- Validation for keys, quiet windows, throttle periods, and rate limit intervals.
+- Comprehensive unit test suites for debounce coalescing, throttle leading/trailing runs, and interval rate limiting.
+
+---
+
 ## [0.4.0] - 2026-09-22 — Timeout & Robust Cancellation
 
 ### Added

package/README.md

@@ -179,7 +179,32 @@ try {
 }
 ```
 
-### 7. Telemetry (`stats`)
+### 7. Debounce & Throttle with Promise Coalescing
+
+Coalesce repeated invocations into shared executions by explicit `key`. Callers share the exact same returned Promise:
+
+```typescript
+// Debounce: waits for 300ms of quiet before running
+const results = await ahko.debounce("search_box", async () => {
+  return queryApi(text);
+}, 300);
+
+// Throttle: runs leading edge immediately, coalesces trailing calls
+await ahko.throttle("window_resize", async () => {
+  recalculateLayout();
+}, 100);
+```
+
+### 8. Paced Execution (`minIntervalMs`)
+
+Prevent burst spikes by ensuring a minimum interval elapses between consecutive task starts:
+
+```typescript
+// At most 2 concurrent tasks, paced at least 50ms apart
+const ahko = new Ahko({ concurrency: 2, minIntervalMs: 50 });
+```
+
+### 9. Telemetry (`stats`)
 
 Inspect real-time scheduler state without synthetic metrics:
 
@@ -222,6 +247,7 @@ Creates an AHKO scheduler instance.
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `concurrency` | `number` | `Infinity` | Maximum concurrent tasks allowed to run simultaneously. Must be $\ge 1$. |
+| `minIntervalMs` | `number` | `0` | Minimum interval in milliseconds between consecutive task starts. Must be $\ge 0$. |
 
 ### `ahko.schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>`
 
@@ -229,13 +255,23 @@ Schedules an asynchronous task with full return type inference.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `strategy` | `"immediate" \| "delay" \| "idle"` | `"immediate"` | Scheduling execution strategy. |
+| `strategy` | `"immediate" \| "delay" \| "idle" \| "throttle" \| "debounce"` | `"immediate"` | Scheduling execution strategy. |
 | `delay` | `number` | `0` | Delay in milliseconds when strategy is `"delay"`. |
+| `key` | `string \| symbol` | `undefined` | Explicit identity key for `"debounce"` and `"throttle"`. |
+| `waitMs` | `number` | `undefined` | Window duration in ms for debounce quiet period or throttle interval. |
 | `idleTimeout` | `number` | `undefined` | Maximum time to wait for idle window before forcing queue entry. |
 | `retry` | `IRetryOptions` | `undefined` | Automatic retry policy (attempts, backoff, jitter, predicate). |
 | `timeoutMs` | `number` | `undefined` | Maximum execution duration in milliseconds per attempt before aborting with `AhkoTimeoutError`. |
 | `signal` | `AbortSignal` | `undefined` | Optional external `AbortSignal` for cooperative cancellation. |
 
+### `ahko.debounce<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: IScheduleOptions): Promise<T>`
+
+Convenience method scheduling a debounced task with key-based Promise coalescing.
+
+### `ahko.throttle<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: IScheduleOptions): Promise<T>`
+
+Convenience method scheduling a throttled task with leading execution and coalesced trailing run.
+
 ### `ahko.idle<T>(task: ITask<T>, options?: Omit<IScheduleOptions, "strategy">): Promise<T>`
 
 Convenience method scheduling a task under `strategy: "idle"`.

package/dist/ahko.d.ts

@@ -44,6 +44,7 @@ export declare class Ahko {
      *
      * @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
@@ -73,15 +74,30 @@ export declare class Ahko {
      *
      * @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<T>(task: ITask<T>, options?: Omit<IScheduleOptions, "strategy">): Promise<T>;
+    /**
+     * 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<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: Omit<IScheduleOptions, "strategy" | "key" | "waitMs">): Promise<T>;
+    /**
+     * 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<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: Omit<IScheduleOptions, "strategy" | "key" | "waitMs">): Promise<T>;
     /**
      * Retrieves real-time telemetry metrics from the scheduler.
      *