@mrjacket/ahko 0.2.0 → 0.4.0

package/CHANGELOG.md

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

package/README.md

@@ -97,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:
 
@@ -116,7 +160,26 @@ const taskPromise = ahko.schedule(
 controller.abort();
 ```
 
-### 4. 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. Telemetry (`stats`)
 
 Inspect real-time scheduler state without synthetic metrics:
 
@@ -130,13 +193,26 @@ console.log(stats);
 //   completedTasks: 42,
 //   failedTasks: 1,
 //   cancelledTasks: 2,
-//   timedOutTasks: 0,
+//   timedOutTasks: 1,
 //   capacity: 3
 // }
 ```
 
 ---
 
+## 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)`
@@ -151,19 +227,29 @@ 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). |
+| `timeoutMs` | `number` | `undefined` | Maximum execution duration in milliseconds per attempt before aborting with `AhkoTimeoutError`. |
+| `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
 
+All scheduler errors inherit from `AhkoError`:
+
 - `AhkoError`: Base class for all scheduler errors.
 - `AhkoCancellationError`: Thrown when a task is aborted.
 - `AhkoConfigurationError`: Thrown when invalid options are provided.

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);
 }