@mrjacket/ahko 0.6.0 → 1.0.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [1.0.0] - 2026-09-23 — Stable Scheduler Release
+
+### Added
+- Comprehensive End-to-End stress and integration test suite (`src/__tests__/e2e.test.ts`) verifying:
+  - High-concurrency bursts under rate-limited temporal pacing (`minIntervalMs`) and jittered backoff retries.
+  - Interleaved interactive debounce and throttle streams under queue contention.
+  - Cooperative cancellation waves simulating document switches or build cancellations (VS Code / CLI scenarios).
+  - Graceful shutdown workflows clearing pending queues while allowing in-flight tasks to settle cleanly (`ahko.chill()`).
+  - Full lifecycle telemetry stream validation and microservice uncooperative timeout handling.
+- Standalone runnable examples suite (`examples/`) with dedicated `examples/README.md`:
+  - `01-concurrency-and-pacing.mjs`: concurrency limits and temporal pacing.
+  - `02-debounce-search.mjs`: debounced interactive search with Promise coalescing.
+  - `03-throttle-events.mjs`: high-frequency event stream throttling.
+  - `04-retry-backoff-jitter.mjs`: resilient retries with exponential backoff and full jitter.
+  - `05-idle-telemetry.mjs`: non-blocking background tasks and lifecycle event logging.
+  - `06-graceful-shutdown.mjs`: safe process termination sequence.
+- Dedicated npm script `"test:e2e"` for focused integration testing.
+- Documentation restructuring into domain guides (`docs/guides/`) and specifications (`docs/architecture/`), including production architectural recipes (`recipes.md`).
+
+### Changed
+- Connected `DebounceCoordinator` and `ThrottleCoordinator` settlement lifecycles directly to `TaskQueue.checkIdle()`, ensuring that window expirations and coordinator deletions deterministically resolve idle promises and emit `"idle"` events.
+- Transitioned version to stable 1.0.0 baseline with frozen zero-dependency architecture.
+
+---
+
 ## [0.6.0] - 2026-09-23 — Telemetry & DX
 
 ### Added

package/README.md

@@ -12,9 +12,6 @@
   <a href="https://www.npmjs.com/package/@mrjacket/ahko">
     <img src="https://img.shields.io/npm/v/@mrjacket/ahko.svg?color=success" alt="npm version">
   </a>
-  <a href="https://www.npmjs.com/package/@mrjacket/ahko">
-    <img src="https://img.shields.io/npm/dm/@mrjacket/ahko.svg" alt="npm downloads">
-  </a>
   <a href="https://www.npmjs.com/package/@mrjacket/ahko">
     <img src="https://img.shields.io/node/v/@mrjacket/ahko.svg" alt="node">
   </a>
@@ -30,12 +27,6 @@
   <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>
@@ -306,13 +297,15 @@ Comprehensive guides and technical documentation are available in the [`docs/`](
 | [**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. |
 
+> **Runnable Examples:** A comprehensive suite of standalone, runnable Node.js scripts is available in the [`examples/`](./examples/) folder. See [`examples/README.md`](./examples/README.md) for details.
+
 ---
 
 ## API Reference
 
 ### `new Ahko(options?: IAhkoOptions)`
 
-Creates an AHKO scheduler instance.
+Creates an ahko scheduler instance.
 
 | Option | Type | Default | Description |
 |---|---|---|---|

package/dist/index.cjs

@@ -150,6 +150,8 @@ var AhkoCancellationError = class extends AhkoError {
 // src/scheduler/debounce-coordinator.ts
 var DebounceCoordinator = class {
   entries = /* @__PURE__ */ new Map();
+  /** Optional callback invoked whenever entries are settled or removed from coordinator */
+  onSettled;
   /**
    * Schedules a task under the debounce strategy.
    *
@@ -236,6 +238,7 @@ var DebounceCoordinator = class {
       return;
     }
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.options?.signal && entry.abortListener) {
       entry.options.signal.removeEventListener("abort", entry.abortListener);
     }
@@ -259,6 +262,7 @@ var DebounceCoordinator = class {
     }
     clearTimeout(entry.timerId);
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.options?.signal && entry.abortListener) {
       entry.options.signal.removeEventListener("abort", entry.abortListener);
     }
@@ -286,6 +290,7 @@ var DebounceCoordinator = class {
       entry.reject(new AhkoCancellationError("Debounced tasks cleared"));
     }
     this.entries.clear();
+    this.onSettled?.();
   }
 };
 
@@ -331,6 +336,8 @@ var IdleScheduler = class {
 // src/scheduler/throttle-coordinator.ts
 var ThrottleCoordinator = class {
   entries = /* @__PURE__ */ new Map();
+  /** Optional callback invoked whenever entries are settled or removed from coordinator */
+  onSettled;
   /**
    * Schedules a task under the throttle strategy.
    *
@@ -416,6 +423,7 @@ var ThrottleCoordinator = class {
       return;
     }
     this.entries.delete(key);
+    this.onSettled?.();
   }
   /**
    * Cancels any pending trailing throttled task for a given key.
@@ -432,6 +440,7 @@ var ThrottleCoordinator = class {
       clearTimeout(entry.windowTimerId);
     }
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.trailingReject) {
       const cancelError = new AhkoCancellationError(
         typeof reason === "string" ? reason : "Throttled task was cancelled",
@@ -459,6 +468,7 @@ var ThrottleCoordinator = class {
       }
     }
     this.entries.clear();
+    this.onSettled?.();
   }
 };
 
@@ -592,6 +602,8 @@ var TaskQueue = class {
     }
     this.concurrency = concurrency;
     this.minIntervalMs = minIntervalMs;
+    this.debounceCoordinator.onSettled = () => this.checkIdle();
+    this.throttleCoordinator.onSettled = () => this.checkIdle();
   }
   /**
    * Enqueues a task runner according to the specified schedule options.
@@ -1590,7 +1602,7 @@ var Ahko = class {
 };
 
 // src/version.ts
-var VERSION = "0.6.0";
+var VERSION = "1.0.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {