@mrjacket/ahko 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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

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.
@@ -219,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
@@ -231,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. |
 
 ---
 
@@ -276,9 +346,37 @@ Convenience method scheduling a throttled task with leading execution and coales
 
 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";
@@ -110,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";