@mrjacket/ahko 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.6.0] - 2026-09-23 — Telemetry & DX
+
+### Added
+- Type-safe lifecycle event emitter (`AhkoEventEmitter`) with dedicated `IAhkoEventMap` events:
+  - `task:start`: emitted when a task begins execution with `taskId` and `attempt`.
+  - `task:complete`: emitted on task success with `taskId`, `attempt`, `durationMs`, and `result`.
+  - `task:fail`: emitted on failure with `taskId`, `attempt`, `error`, and `willRetry` boolean indicator.
+  - `task:cancel`: emitted on task cancellation with `taskId` and `reason`.
+  - `task:timeout`: emitted when execution exceeds configured deadline with `taskId` and `timeoutMs`.
+  - `idle`: emitted when all tasks settle and queue reaches idle state with `timestamp`.
+- Event subscription methods `ahko.on(event, handler)` returning an unsubscribe function, and `ahko.off(event, handler)`.
+- Listener error containment: listener exceptions are safely isolated without crashing the scheduler loop or sibling listeners.
+- Idle lifecycle promises via `ahko.isIdle()`, `ahko.onIdle()`, and chill alias `ahko.chill()`.
+- Queue clearance method `ahko.clear()` to cancel queued, delayed, and coalesced tasks cleanly.
+- Ahko mascot battery telemetry via `ahko.battery()` reporting chill status.
+- Extended telemetry snapshot in `ahko.stats()` with `retriedTasks` and `totalDispatched`.
+
+### Fixed
+- Fixed 2 CodeQL security alerts by iterating over map values (`this.entries.values()`) in `DebounceCoordinator.clear()` and `ThrottleCoordinator.clear()`.
+
+---
+
+## [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

@@ -27,6 +27,18 @@
   <a href="https://github.com/x-name15/ahko/blob/main/LICENSE">
     <img src="https://img.shields.io/npm/l/@mrjacket/ahko.svg" alt="license">
   </a>
+  <a href="https://www.npmjs.com/package/@mrjacket/ahko">
+    <img src="https://img.shields.io/badge/dependencies-0-success" alt="zero dependencies">
+  </a>
+  <a href="https://bundlephobia.com/package/@mrjacket/ahko">
+    <img src="https://img.shields.io/bundlephobia/minzip/@mrjacket/ahko?color=purple" alt="bundle size">
+  </a>
+  <a href="https://github.com/x-name15/ahko">
+    <img src="https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
+  </a>
+  <a href="https://github.com/x-name15/ahko/issues">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
+  </a>
 </p>
 
 `ahko` is a low-energy task scheduler for JavaScript and TypeScript.
@@ -179,7 +191,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:
 
@@ -194,10 +231,65 @@ console.log(stats);
 //   failedTasks: 1,
 //   cancelledTasks: 2,
 //   timedOutTasks: 1,
+//   retriedTasks: 3,
+//   totalDispatched: 45,
 //   capacity: 3
 // }
 ```
 
+### 10. Lifecycle Events (`on` / `off`)
+
+Listen to typed lifecycle events with isolated callback safety:
+
+```typescript
+const unsubscribe = ahko.on("task:start", ({ taskId, attempt }) => {
+  console.log(`Task ${taskId} started attempt #${attempt}`);
+});
+
+ahko.on("task:complete", ({ taskId, durationMs, result }) => {
+  console.log(`Task ${taskId} completed in ${durationMs}ms:`, result);
+});
+
+ahko.on("task:fail", ({ taskId, attempt, error, willRetry }) => {
+  console.warn(`Task ${taskId} attempt #${attempt} failed (willRetry: ${willRetry})`, error);
+});
+
+ahko.on("task:timeout", ({ taskId, timeoutMs }) => {
+  console.warn(`Task ${taskId} exceeded ${timeoutMs}ms deadline`);
+});
+
+ahko.on("task:cancel", ({ taskId, reason }) => {
+  console.info(`Task ${taskId} was cancelled:`, reason);
+});
+
+ahko.on("idle", ({ timestamp }) => {
+  console.log("Scheduler transitioned to idle at", timestamp);
+});
+```
+
+### 11. Idle & Chill Developer Experience
+
+Wait for all work to settle or clear the queue cleanly:
+
+```typescript
+// Wait for all active and pending tasks to finish
+await ahko.onIdle();
+// Or use the completely chill alias:
+await ahko.chill();
+
+// Check if scheduler is currently idle
+if (ahko.isIdle()) {
+  console.log("Completely chill. No tasks running or queued.");
+}
+
+// Clear all queued, delayed, and coalesced tasks
+ahko.clear();
+
+// Check Ahko mascot battery telemetry
+console.log(ahko.battery());
+// { level: 3, chill: true, status: "low-energy", quote: "Mwee... my battery is low, but all your tasks are handled completely chill." }
+```
+
 ---
 
 ## Documentation
@@ -206,10 +298,13 @@ Comprehensive guides and technical documentation are available in the [`docs/`](
 
 | Document | Description |
 |---|---|
-| [**Getting Started**](./docs/getting-started.md) | Quickstart guide, installation, and fundamental usage patterns. |
-| [**Library API**](./docs/library.md) | Complete programmatic API reference, TypeScript interfaces, and options. |
-| [**Architecture**](./docs/architecture.md) | Architectural specifications, lifecycle state machine, and design decisions. |
-| [**Roadmap**](./docs/roadmap.md) | Milestone progression from 0.1.0 through 1.0.0. |
+| [**Documentation Portal**](./docs/README.md) | Master overview and index of all guides and specifications. |
+| [**Getting Started**](./docs/guides/getting-started.md) | Quickstart guide, installation, and fundamental usage patterns. |
+| [**Library API**](./docs/guides/library.md) | Complete programmatic API reference, TypeScript interfaces, and options. |
+| [**Production Recipes**](./docs/guides/recipes.md) | Battle-tested recipes (paced API client, debounced search, throttled scroll, graceful shutdown). |
+| [**Architecture**](./docs/architecture/ARCHITECTURE.md) | Architectural specifications, lifecycle state machine, and design decisions. |
+| [**Roadmap**](./docs/architecture/ROADMAP.md) | Milestone progression from 0.1.0 through 1.0.0. |
+| [**Engineering Log**](./docs/architecture/LOG.md) | Chronological log of engineering decisions and ADRs. |
 
 ---
 
@@ -222,6 +317,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,20 +325,58 @@ 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"`.
 
+### `ahko.on(event, handler)`
+
+Subscribes to scheduler lifecycle events (`task:start`, `task:complete`, `task:fail`, `task:cancel`, `task:timeout`, `idle`). Returns an unsubscribe function.
+
+### `ahko.off(event, handler)`
+
+Unsubscribes an event listener callback.
+
+### `ahko.isIdle(): boolean`
+
+Returns whether the scheduler is currently idle (no active or pending tasks).
+
+### `ahko.onIdle(): Promise<void>`
+
+Returns a Promise that resolves when all active and pending tasks have settled.
+
+### `ahko.chill(): Promise<void>`
+
+Alias for `ahko.onIdle()`.
+
+### `ahko.clear(): void`
+
+Cancels all pending, delayed, and throttled/debounced tasks cleanly.
+
+### `ahko.battery()`
+
+Returns mascot battery status and quote.
+
 ### `ahko.stats(): IAhkoStats`
 
-Returns a snapshot of current task counters and queue capacity.
+Returns a snapshot of current task counters, retry counts, total dispatches, and queue capacity.
 
 ---
 

package/dist/ahko.d.ts

@@ -1,3 +1,4 @@
+import type { TAhkoEventName, TAhkoEventHandler, TAhkoUnsubscribe } from "./models/events.model.js";
 import type { IAhkoOptions, IScheduleOptions } from "./models/options.model.js";
 import type { IAhkoStats } from "./models/stats.model.js";
 import type { ITask } from "./models/task.model.js";
@@ -44,6 +45,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 +75,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.
      *
@@ -94,4 +111,67 @@ export declare class Ahko {
      * ```
      */
     stats(): IAhkoStats;
+    /**
+     * 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<K extends TAhkoEventName>(event: K, handler: TAhkoEventHandler<K>): TAhkoUnsubscribe;
+    /**
+     * Unsubscribes an event listener from a scheduler lifecycle event.
+     *
+     * @param event - Event name.
+     * @param handler - The exact listener callback to remove.
+     */
+    off<K extends TAhkoEventName>(event: K, handler: TAhkoEventHandler<K>): void;
+    /**
+     * Checks whether the scheduler is currently idle (no active runners and no pending tasks).
+     *
+     * @returns True if completely idle, false otherwise.
+     */
+    isIdle(): boolean;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * Returns the delightful Ahko mascot battery telemetry status.
+     *
+     * Low energy, completely chill.
+     */
+    battery(): {
+        level: number;
+        chill: boolean;
+        status: string;
+        quote: string;
+    };
+    /**
+     * Delightful alias for `onIdle()`: wait for all tasks to settle chill and relaxed.
+     *
+     * @returns Promise resolving when all tasks have finished.
+     */
+    chill(): Promise<void>;
 }

package/dist/events/event-emitter.d.ts

@@ -0,0 +1,34 @@
+import type { IAhkoEventMap, TAhkoEventHandler, TAhkoEventName, TAhkoUnsubscribe } from "../models/events.model.js";
+/**
+ * Lightweight, zero-dependency typed event emitter with safe error containment.
+ */
+export declare class AhkoEventEmitter {
+    private readonly listeners;
+    /**
+     * 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<K extends TAhkoEventName>(event: K, handler: TAhkoEventHandler<K>): TAhkoUnsubscribe;
+    /**
+     * Unsubscribes a listener from a specific Ahko lifecycle event.
+     *
+     * @param event - The event name.
+     * @param handler - The callback function to remove.
+     */
+    off<K extends TAhkoEventName>(event: K, handler: TAhkoEventHandler<K>): void;
+    /**
+     * 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<K extends TAhkoEventName>(event: K, payload: IAhkoEventMap[K]): void;
+    /**
+     * Removes all registered event listeners.
+     */
+    clear(): void;
+}

package/dist/events/index.d.ts

@@ -0,0 +1 @@
+export * from "./event-emitter.js";