@mrjacket/ahko 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.3.0] - 2026-09-22 — Retry & Backoff
+
+### Added
+- Automatic retry engine supporting `attempts`, exponential/linear backoff, and full jitter.
+- Retry filtering via `shouldRetry` predicate `(error, attempt) => boolean | Promise<boolean>`.
+- Concurrency slot release during backoff delay to prevent capacity starvation.
+- Cancellation safety during backoff delay (clears timers immediately, rejects with `AhkoCancellationError`, and halts remaining retries).
+- Public retry models (`IRetryOptions`, `TRetryBackoff`, `TRetryPredicate`) and backoff calculation utilities.
+- Comprehensive unit test suite covering backoff calculations, jitter, slot release, predicates, and cancellations.
+
+---
+
+## [0.2.0] - 2026-09-22 — Idle Scheduling
+
+### Added
+- Platform-agnostic `IdleScheduler` supporting browser `requestIdleCallback`, Node.js `setImmediate`, and universal fallback `setTimeout(..., 0)`.
+- Support for `idle` strategy (`EScheduleStrategy.IDLE`).
+- Optional `idleTimeout` parameter in `IScheduleOptions` forwarding to `requestIdleCallback({ timeout })`.
+- Convenience method `ahko.idle(task, options)`.
+- Immediate resource cleanup and handle cancellation when idle tasks are cancelled prior to callback execution.
+- Comprehensive unit test suite covering cross-runtime execution, fallback paths, cancellation, and concurrency.
+
+---
+
 ## [0.1.0] - 2026-09-22 — Core Scheduler
 
 ### Added

package/README.md

@@ -1,21 +1,41 @@
-<h1><img src=".github/images/ahko.png" width="80" height="80"> ahko</h1>
-
-[![npm version](https://img.shields.io/npm/v/@mrjacket/ahko.svg?color=success)](https://www.npmjs.com/package/@mrjacket/ahko)
-[![npm downloads](https://img.shields.io/npm/dm/@mrjacket/ahko.svg)](https://www.npmjs.com/package/@mrjacket/ahko)
-[![node](https://img.shields.io/node/v/@mrjacket/ahko.svg)](https://www.npmjs.com/package/@mrjacket/ahko)
-[![ci](https://github.com/x-name15/ahko/actions/workflows/ci.yml/badge.svg)](https://github.com/x-name15/ahko/actions/workflows/ci.yml)
-[![types](https://img.shields.io/npm/types/@mrjacket/ahko.svg)](https://www.npmjs.com/package/@mrjacket/ahko)
-[![license](https://img.shields.io/npm/l/@mrjacket/ahko.svg)](https://github.com/x-name15/ahko/blob/main/LICENSE)
-
-> Let your code chill.
-
-`@mrjacket/ahko` is a low-energy, production-grade task scheduler for JavaScript and TypeScript.
-
-Inspired by Aashii Kedarui / Ahko from *"The 100 Girlfriends Who Really, Really, Really, Really, Really Love You"*, AHKO brings calm, controlled execution to asynchronous workflows without rush, bursts, or unnecessary complexity.
+<p align="center">
+  <img src=".github/images/ahko.png" width="120" height="120" alt="ahko">
+</p>
+
+<h1 align="center">ahko</h1>
+
+<p align="center">
+  <strong>Let your code chill.</strong>
+</p>
+
+<p align="center">
+  <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>
+  <a href="https://github.com/x-name15/ahko/actions/workflows/ci.yml">
+    <img src="https://github.com/x-name15/ahko/actions/workflows/ci.yml/badge.svg" alt="ci">
+  </a>
+  <a href="https://www.npmjs.com/package/@mrjacket/ahko">
+    <img src="https://img.shields.io/npm/types/@mrjacket/ahko.svg" alt="types">
+  </a>
+  <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>
+</p>
+
+`ahko` is a low-energy task scheduler for JavaScript and TypeScript.
+
+Inspired by Aashii Kedarui / Ahko from *"The 100 Girlfriends Who Really, Really, Really, Really, Really Love You"*, @mrjacket/ahko brings calm, controlled execution to asynchronous workflows without rush, bursts, or unnecessary complexity.
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @mrjacket/ahko
@@ -25,7 +45,7 @@ Requires **Node.js >= 22.12.0** or a modern browser environment. Zero external d
 
 ---
 
-## ⚡ Quick Start
+## Quick Start
 
 ```typescript
 import { Ahko } from "@mrjacket/ahko";
@@ -41,7 +61,7 @@ const data = await ahko.schedule(async ({ signal, taskId }) => {
 
 ---
 
-## 🧘 Core Capabilities
+## Core Capabilities
 
 ### 1. Concurrency Control
 
@@ -77,7 +97,51 @@ await ahko.schedule(
 );
 ```
 
-### 3. First-Class Cancellation (`AbortSignal`)
+### 3. Opportunistic Idle Execution
+
+Schedule work to run when the runtime is idle (using browser `requestIdleCallback`, Node.js `setImmediate`, or universal fallback):
+
+```typescript
+// Dedicated convenience method
+await ahko.idle(async ({ signal }) => {
+  await computeBackgroundAnalytics({ signal });
+});
+
+// Or via schedule options with maximum wait timeout
+await ahko.schedule(
+  async ({ signal }) => {
+    await performLowPriorityWork({ signal });
+  },
+  {
+    strategy: "idle",
+    idleTimeout: 5000, // Forces execution if idle window doesn't appear in 5s
+  }
+);
+```
+
+### 4. Resilient Retries & Backoff
+
+Automatically retry failed tasks with configurable exponential or linear backoff and full jitter:
+
+```typescript
+const result = await ahko.schedule(
+  async ({ signal }) => {
+    return callExternalService({ signal });
+  },
+  {
+    retry: {
+      attempts: 3,            // 1 initial run + up to 2 retries
+      backoff: "exponential", // "exponential" | "linear" | "none"
+      baseDelay: 250,         // starting delay in ms
+      maxDelay: 5000,         // maximum delay cap in ms
+      jitter: true,           // randomize backoff to prevent thundering herds
+      shouldRetry: (error) => isNetworkError(error),
+    },
+  }
+);
+```
+
+### 5. First-Class Cancellation (`AbortSignal`)
 
 AHKO provides native, cooperative cancellation:
 
@@ -96,7 +160,7 @@ const taskPromise = ahko.schedule(
 controller.abort();
 ```
 
-### 4. Telemetry (`stats`)
+### 6. Telemetry (`stats`)
 
 Inspect real-time scheduler state without synthetic metrics:
 
@@ -117,7 +181,20 @@ console.log(stats);
 
 ---
 
-## 📖 API Reference
+## Documentation
+
+Comprehensive guides and technical documentation are available in the [`docs/`](./docs) directory:
+
+| 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. |
+
+---
+
+## API Reference
 
 ### `new Ahko(options?: IAhkoOptions)`
 
@@ -131,18 +208,27 @@ Creates an AHKO scheduler instance.
 
 Schedules an asynchronous task with full return type inference.
 
-- `task`: `(context: ITaskContext) => Promise<T> | T`
-- `options.strategy`: `"immediate"` (default) or `"delay"`.
-- `options.delay`: Delay in milliseconds when strategy is `"delay"`.
-- `options.signal`: Optional `AbortSignal` for cancellation.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `strategy` | `"immediate" \| "delay" \| "idle"` | `"immediate"` | Scheduling execution strategy. |
+| `delay` | `number` | `0` | Delay in milliseconds when strategy is `"delay"`. |
+| `idleTimeout` | `number` | `undefined` | Maximum time to wait for idle window before forcing queue entry. |
+| `retry` | `IRetryOptions` | `undefined` | Automatic retry policy (attempts, backoff, jitter, predicate). |
+| `signal` | `AbortSignal` | `undefined` | Optional external `AbortSignal` for cooperative cancellation. |
+
+### `ahko.idle<T>(task: ITask<T>, options?: Omit<IScheduleOptions, "strategy">): Promise<T>`
+
+Convenience method scheduling a task under `strategy: "idle"`.
 
 ### `ahko.stats(): IAhkoStats`
 
-Returns a snapshot of current task counters and capacity.
+Returns a snapshot of current task counters and queue capacity.
 
 ---
 
-## 🛡️ Errors
+## Errors
+
+All scheduler errors inherit from `AhkoError`:
 
 - `AhkoError`: Base class for all scheduler errors.
 - `AhkoCancellationError`: Thrown when a task is aborted.
@@ -152,6 +238,8 @@ Returns a snapshot of current task counters and capacity.
 
 ---
 
-## 📜 License
+## License
+[GNU General Public License v3.0 (GPL-3.0-only)](LICENSE) 
 
-[GNU General Public License v3.0 (GPL-3.0-only)](LICENSE) © [x-name15](https://github.com/x-name15)
+### Credits
+**Author:** Mr Jacket / Felix Manrique / x-name15 (we are all the same person)

package/dist/ahko.d.ts

@@ -2,7 +2,7 @@ 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";
 /**
- * Ahko — Low-energy, production-grade asynchronous task scheduler.
+ * Ahko — Low-energy asynchronous task scheduler.
  *
  * Coordinates execution timing, enforces concurrency limits, and cooperates
  * natively with AbortSignal cancellation.
@@ -58,6 +58,30 @@ export declare class Ahko {
      * ```
      */
     schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>;
+    /**
+     * Convenience method to schedule a task during platform idle opportunities.
+     *
+     * Equivalent to calling `schedule(task, { ...options, strategy: "idle" })`.
+     * In browsers, uses `requestIdleCallback` when available.
+     * In Node.js, uses `setImmediate`.
+     * Falls back to `setTimeout(..., 0)` if neither is available.
+     *
+     * @template T - Inferred return type of the task.
+     * @param task - Task function to run when idle.
+     * @param options - Scheduling options (excluding strategy).
+     * @returns A promise resolving to the task's return value.
+     *
+     * @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>;
     /**
      * Retrieves real-time telemetry metrics from the scheduler.
      *