@mrjacket/ahko 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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
+- Execution timeout control via `timeoutMs` in `IScheduleOptions`.
+- Rejection with `AhkoTimeoutError` containing exceeded `timeoutMs` threshold and descriptive message.
+- Immediate rejection and slot recovery for hanging, uncooperative tasks via `Promise.race`.
+- Active execution timeout isolation (queued waiting time and backoff delays do not consume execution timeout).
+- Fresh `timeoutMs` window allocation on retry attempts.
+- Unified signal coordination via `combineSignals` utility with deterministic listener detachment.
+- Strict configuration validation for `timeoutMs` (positive finite numbers).
+- Comprehensive unit test suite covering execution timeouts, cancellation precedence, uncooperative tasks, retries, and signal combination.
+
+---
+
 ## [0.3.0] - 2026-09-22 — Retry & Backoff
 
 ### Added

package/README.md

@@ -160,7 +160,51 @@ const taskPromise = ahko.schedule(
 controller.abort();
 ```
 
-### 6. Telemetry (`stats`)
+### 6. Execution Deadlines & Timeouts (`timeoutMs`)
+
+Enforce deadlines per attempt. If a task exceeds `timeoutMs`, its context signal is aborted and the task rejects with `AhkoTimeoutError`:
+
+```typescript
+try {
+  await ahko.schedule(
+    async ({ signal }) => {
+      return callLongRunningApi({ signal });
+    },
+    { timeoutMs: 3000 } // aborts and rejects if running longer than 3 seconds
+  );
+} catch (error) {
+  if (error instanceof AhkoTimeoutError) {
+    console.error(`Timed out after ${error.timeoutMs}ms`);
+  }
+}
+```
+
+### 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:
 
@@ -174,7 +218,7 @@ console.log(stats);
 //   completedTasks: 42,
 //   failedTasks: 1,
 //   cancelledTasks: 2,
-//   timedOutTasks: 0,
+//   timedOutTasks: 1,
 //   capacity: 3
 // }
 ```
@@ -203,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>`
 
@@ -210,12 +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.
      *

package/dist/errors/timeout.error.d.ts

@@ -1,13 +1,26 @@
 import { AhkoError } from "./ahko.error.js";
+/**
+ * Options for constructing an AhkoTimeoutError.
+ */
+export interface IAhkoTimeoutErrorOptions extends ErrorOptions {
+    /**
+     * The timeout threshold in milliseconds that was exceeded.
+     */
+    timeoutMs?: number;
+}
 /**
  * Thrown when a task exceeds its allotted timeout duration.
  */
 export declare class AhkoTimeoutError extends AhkoError {
+    /**
+     * The timeout threshold in milliseconds that was exceeded, if configured.
+     */
+    readonly timeoutMs?: number;
     /**
      * Creates a new AhkoTimeoutError.
      *
      * @param message - Explanation of timeout expiry.
-     * @param options - Standard Error options including cause.
+     * @param options - Standard Error options including optional timeoutMs and cause.
      */
-    constructor(message?: string, options?: ErrorOptions);
+    constructor(message?: string, options?: IAhkoTimeoutErrorOptions);
 }