npm - @mrjacket/ahko - Versions diffs - 0.1.0 → 0.2.0 - Mend

@mrjacket/ahko 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/CHANGELOG.md +12 -0
package/README.md +43 -21
package/dist/ahko.d.ts +25 -1
package/dist/index.cjs +121 -10
package/dist/index.cjs.map +1 -1
package/dist/index.js +121 -10
package/dist/index.js.map +1 -1
package/dist/models/options.model.d.ts +6 -0
package/dist/models/strategy.model.d.ts +4 -2
package/dist/scheduler/idle-scheduler.d.ts +28 -0
package/dist/scheduler/task-queue.d.ts +7 -0
package/dist/version.d.ts +1 -1
package/package.json +4 -4

package/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,18 @@ 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.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 CHANGED Viewed

@@ -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
@@ -117,7 +137,7 @@ console.log(stats);
 ---
-## 📖 API Reference
+## API Reference
 ### `new Ahko(options?: IAhkoOptions)`
@@ -142,7 +162,7 @@ Returns a snapshot of current task counters and capacity.
 ---
-## 🛡️ Errors
+## Errors
 - `AhkoError`: Base class for all scheduler errors.
 - `AhkoCancellationError`: Thrown when a task is aborted.
@@ -152,6 +172,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 CHANGED Viewed

@@ -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.
      *

package/dist/index.cjs CHANGED Viewed

@@ -62,6 +62,14 @@ var AhkoConfigurationError = class extends AhkoError {
   }
 };
+// src/models/strategy.model.ts
+var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
+  EScheduleStrategy2["IMMEDIATE"] = "immediate";
+  EScheduleStrategy2["DELAY"] = "delay";
+  EScheduleStrategy2["IDLE"] = "idle";
+  return EScheduleStrategy2;
+})(EScheduleStrategy || {});
 // src/models/state.model.ts
 var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   ETaskState2["PENDING"] = "pending";
@@ -73,12 +81,44 @@ var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   return ETaskState2;
 })(ETaskState || {});
-// src/models/strategy.model.ts
-var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
-  EScheduleStrategy2["IMMEDIATE"] = "immediate";
-  EScheduleStrategy2["DELAY"] = "delay";
-  return EScheduleStrategy2;
-})(EScheduleStrategy || {});
+// src/scheduler/idle-scheduler.ts
+var IdleScheduler = class {
+  /**
+   * Schedules a callback to execute during the next idle opportunity.
+   *
+   * @param callback - Function to invoke when idle opportunity arises.
+   * @param timeout - Optional max deadline in milliseconds to wait before invoking (browser only).
+   * @param runtime - Target runtime scope providing scheduling primitives (defaults to globalThis).
+   * @returns An {@link IIdleHandle} with a `cancel()` method for cleanup.
+   */
+  static schedule(callback, timeout, runtime = globalThis) {
+    if (typeof runtime.requestIdleCallback === "function" && typeof runtime.cancelIdleCallback === "function") {
+      const requestFn = runtime.requestIdleCallback;
+      const cancelFn = runtime.cancelIdleCallback;
+      const id = requestFn(
+        () => callback(),
+        typeof timeout === "number" && !Number.isNaN(timeout) && timeout >= 0 ? { timeout } : void 0
+      );
+      return {
+        cancel: () => cancelFn(id)
+      };
+    }
+    if (typeof runtime.setImmediate === "function" && typeof runtime.clearImmediate === "function") {
+      const setImmFn = runtime.setImmediate;
+      const clearImmFn = runtime.clearImmediate;
+      const handle = setImmFn(() => callback());
+      return {
+        cancel: () => clearImmFn(handle)
+      };
+    }
+    const setTimerFn = runtime.setTimeout.bind(runtime);
+    const clearTimerFn = runtime.clearTimeout.bind(runtime);
+    const timerId = setTimerFn(() => callback(), 0);
+    return {
+      cancel: () => clearTimerFn(timerId)
+    };
+  }
+};
 // src/scheduler/task-queue.ts
 var TaskQueue = class {
@@ -90,6 +130,8 @@ var TaskQueue = class {
   activeRunners = /* @__PURE__ */ new Set();
   /** Set of tasks currently in delay phase */
   delayedEntries = /* @__PURE__ */ new Set();
+  /** Set of tasks currently awaiting an idle opportunity */
+  idleEntries = /* @__PURE__ */ new Set();
   /** Cumulative completed tasks counter */
   completedTasks = 0;
   /** Cumulative failed tasks counter */
@@ -123,9 +165,9 @@ var TaskQueue = class {
    */
   enqueue(runner, options) {
     const strategy = options?.strategy ?? "immediate" /* IMMEDIATE */;
-    if (strategy !== "immediate" /* IMMEDIATE */ && strategy !== "delay" /* DELAY */) {
+    if (strategy !== "immediate" /* IMMEDIATE */ && strategy !== "delay" /* DELAY */ && strategy !== "idle" /* IDLE */) {
       throw new AhkoConfigurationError(
-        `Unsupported schedule strategy "${String(strategy)}". Supported strategies in 0.1.0: "immediate", "delay".`
+        `Unsupported schedule strategy "${String(strategy)}". Supported strategies: "immediate", "delay", "idle".`
       );
     }
     if (runner.state === "cancelled" /* CANCELLED */) {
@@ -142,6 +184,15 @@ var TaskQueue = class {
       this.scheduleDelayed(runner, delayMs);
       return runner.promise;
     }
+    if (strategy === "idle" /* IDLE */) {
+      if (options?.idleTimeout !== void 0 && (typeof options.idleTimeout !== "number" || Number.isNaN(options.idleTimeout) || options.idleTimeout < 0)) {
+        throw new AhkoConfigurationError(
+          `Invalid idleTimeout "${options.idleTimeout}". idleTimeout must be a non-negative number in milliseconds.`
+        );
+      }
+      this.scheduleIdle(runner, options?.idleTimeout);
+      return runner.promise;
+    }
     runner.onCancel = () => {
       const index = this.queue.indexOf(runner);
       if (index !== -1) {
@@ -185,6 +236,37 @@ var TaskQueue = class {
       }
     };
   }
+  /**
+   * Schedules a task to be placed into the queue during an idle opportunity,
+   * handling early cancellation safely.
+   */
+  scheduleIdle(runner, idleTimeout) {
+    let idleEntry;
+    const handle = IdleScheduler.schedule(() => {
+      this.idleEntries.delete(idleEntry);
+      if (runner.state === "cancelled" /* CANCELLED */) {
+        return;
+      }
+      runner.onCancel = () => {
+        const index = this.queue.indexOf(runner);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+          this.cancelledTasks++;
+        }
+      };
+      this.queue.push(runner);
+      this.pump();
+    }, idleTimeout);
+    idleEntry = { runner, handle };
+    this.idleEntries.add(idleEntry);
+    runner.onCancel = () => {
+      if (this.idleEntries.has(idleEntry)) {
+        handle.cancel();
+        this.idleEntries.delete(idleEntry);
+        this.cancelledTasks++;
+      }
+    };
+  }
   /**
    * Pumps the queue by picking pending tasks and executing them
    * as long as concurrency capacity is available.
@@ -234,7 +316,7 @@ var TaskQueue = class {
   getStats() {
     return Object.freeze({
       activeTasks: this.activeRunners.size,
-      pendingTasks: this.queue.length + this.delayedEntries.size,
+      pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size,
       completedTasks: this.completedTasks,
       failedTasks: this.failedTasks,
       cancelledTasks: this.cancelledTasks,
@@ -454,6 +536,35 @@ var Ahko = class {
     const runner = new TaskRunner(task, options?.signal);
     return this.queue.enqueue(runner, options);
   }
+  /**
+   * 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(task, options) {
+    return this.schedule(task, {
+      ...options,
+      strategy: "idle" /* IDLE */
+    });
+  }
   /**
    * Retrieves real-time telemetry metrics from the scheduler.
    *
@@ -471,7 +582,7 @@ var Ahko = class {
 };
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {

package/dist/index.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/index.ts","../src/errors/ahko.error.ts","../src/errors/configuration.error.ts","../src/models/state.model.ts","../src/models/strategy.model.ts","../src/scheduler/task-queue.ts","../src/errors/cancellation.error.ts","../src/scheduler/task-runner.ts","../src/ahko.ts","../src/version.ts","../src/errors/queue.error.ts","../src/errors/timeout.error.ts"],"sourcesContent":["export { Ahko } from \"./ahko.js\";\nexport { VERSION } from \"./version.js\";\n\n// Errors\nexport {\n AhkoError,\n AhkoCancellationError,\n AhkoConfigurationError,\n AhkoQueueError,\n AhkoTimeoutError,\n} from \"./errors/index.js\";\n\n// Models and interfaces\nexport {\n ETaskState,\n EScheduleStrategy,\n} from \"./models/index.js\";\n\nexport type {\n ITask,\n ITaskContext,\n IScheduleOptions,\n IAhkoOptions,\n IAhkoStats,\n TScheduleStrategy,\n} from \"./models/index.js\";\n","/*\n Base error class for all errors originating from the Ahko scheduler.\n /\nexport class AhkoError extends Error {\n /\n Creates a new AhkoError instance.\n \n @param message - Descriptive error message.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when invalid configuration or scheduling options are provided.\n /\nexport class AhkoConfigurationError extends AhkoError {\n /\n Creates a new AhkoConfigurationError.\n \n @param message - Explanation of the invalid configuration parameter.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoConfigurationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","/\n Represents the discrete lifecycle states of an Ahko task.\n /\nexport enum ETaskState {\n /* Task has been scheduled and is awaiting execution in queue or timer /\n PENDING = \"pending\",\n /* Task is currently executing within an allocated concurrency slot /\n RUNNING = \"running\",\n /* Task successfully finished execution /\n COMPLETED = \"completed\",\n /* Task execution threw an error or rejected /\n FAILED = \"failed\",\n /* Task was cancelled via AbortSignal before or during execution /\n CANCELLED = \"cancelled\",\n /* Task was terminated because its execution exceeded the timeout /\n TIMED_OUT = \"timed_out\",\n}\n","/\n Fundamental scheduling strategies supported by the Ahko scheduler.\n /\nexport enum EScheduleStrategy {\n /* Execute as soon as a concurrency slot is available /\n IMMEDIATE = \"immediate\",\n /* Delay execution for a designated duration before queuing /\n DELAY = \"delay\",\n}\n\n/\n Union type representing valid scheduling strategy identifiers.\n /\nexport type TScheduleStrategy = EScheduleStrategy \| \"immediate\" \| \"delay\";\n","import { AhkoConfigurationError } from \"../errors/configuration.error.js\";\nimport type { IScheduleOptions } from \"../models/options.model.js\";\nimport type { IAhkoStats } from \"../models/stats.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport { EScheduleStrategy } from \"../models/strategy.model.js\";\nimport { TaskRunner } from \"./task-runner.js\";\n\n/\n Entry tracking delayed task timers for deterministic cancellation and memory cleanup.\n /\ninterface IDelayedEntry {\n runner: TaskRunner<unknown>;\n timerId: ReturnType<typeof setTimeout>;\n}\n\n/\n Memory-safe FIFO task queue managing concurrency allocation,\n * delayed scheduling, and task lifecycle counters.\n /\nexport class TaskQueue {\n /* Maximum concurrent active tasks /\n public readonly concurrency: number;\n\n /* Queue of pending task runners waiting for a concurrency slot /\n private readonly queue: TaskRunner<unknown>[] = [];\n\n /* Set of task runners currently executing /\n private readonly activeRunners = new Set<TaskRunner<unknown>>();\n\n /* Set of tasks currently in delay phase /\n private readonly delayedEntries = new Set<IDelayedEntry>();\n\n /* Cumulative completed tasks counter /\n private completedTasks = 0;\n\n /* Cumulative failed tasks counter /\n private failedTasks = 0;\n\n /* Cumulative cancelled tasks counter /\n private cancelledTasks = 0;\n\n /* Cumulative timed out tasks counter /\n private timedOutTasks = 0;\n\n /\n Creates a new TaskQueue.\n \n @param concurrency - Maximum concurrent tasks (defaults to Infinity).\n * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.\n /\n constructor(concurrency = Infinity) {\n if (Number.isNaN(concurrency) \|\| concurrency < 1) {\n throw new AhkoConfigurationError(\n `Invalid concurrency \"${concurrency}\". Must be a number greater than or equal to 1.`\n );\n }\n this.concurrency = concurrency;\n }\n\n /\n Enqueues a task runner according to the specified schedule options.\n \n @template T - The return type produced by the task.\n * @param runner - The task runner instance.\n * @param options - Scheduling options.\n * @returns The deferred promise associated with the task runner.\n * @throws {AhkoConfigurationError} If scheduling options are invalid.\n /\n public enqueue<T>(runner: TaskRunner<T>, options?: IScheduleOptions): Promise<T> {\n const strategy = options?.strategy ?? EScheduleStrategy.IMMEDIATE;\n\n if (strategy !== EScheduleStrategy.IMMEDIATE && strategy !== EScheduleStrategy.DELAY) {\n throw new AhkoConfigurationError(\n `Unsupported schedule strategy \"${String(strategy)}\". Supported strategies in 0.1.0: \"immediate\", \"delay\".`\n );\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n return runner.promise;\n }\n\n if (strategy === EScheduleStrategy.DELAY) {\n const delayMs = options?.delay ?? 0;\n if (typeof delayMs !== \"number\" \|\| Number.isNaN(delayMs) \|\| delayMs < 0) {\n throw new AhkoConfigurationError(\n `Invalid delay \"${delayMs}\". Delay must be a non-negative number in milliseconds.`\n );\n }\n\n this.scheduleDelayed(runner as TaskRunner<unknown>, delayMs);\n return runner.promise;\n }\n\n // Attach immediate onCancel handler to dequeue without consuming concurrency\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner as TaskRunner<unknown>);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n // Immediate strategy: add to pending queue and pump\n this.queue.push(runner as TaskRunner<unknown>);\n this.pump();\n\n return runner.promise;\n }\n\n /\n Schedules a task to be placed into the queue after a delay,\n * handling early cancellation safely.\n /\n private scheduleDelayed(runner: TaskRunner<unknown>, delayMs: number): void {\n const delayedEntry: IDelayedEntry = {\n runner,\n timerId: setTimeout(() => {\n this.delayedEntries.delete(delayedEntry);\n if (runner.state === ETaskState.CANCELLED) {\n return;\n }\n\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n this.queue.push(runner);\n this.pump();\n }, delayMs),\n };\n\n this.delayedEntries.add(delayedEntry);\n\n runner.onCancel = () => {\n if (this.delayedEntries.has(delayedEntry)) {\n clearTimeout(delayedEntry.timerId);\n this.delayedEntries.delete(delayedEntry);\n this.cancelledTasks++;\n }\n };\n }\n\n /\n Pumps the queue by picking pending tasks and executing them\n * as long as concurrency capacity is available.\n /\n private pump(): void {\n while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {\n const runner = this.queue.shift();\n if (!runner) {\n break;\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n continue;\n }\n\n this.activeRunners.add(runner);\n\n // Execute runner without unhandled rejection risk\n void this.executeRunner(runner);\n }\n }\n\n /\n Internal execution of an active task runner.\n * Settle caller promise strictly after stats and active status are updated.\n /\n private async executeRunner(runner: TaskRunner<unknown>): Promise<void> {\n try {\n const result = await runner.run();\n this.completedTasks++;\n this.activeRunners.delete(runner);\n runner.resolve(result);\n } catch (error) {\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n } else if (runner.state === ETaskState.TIMED_OUT) {\n this.timedOutTasks++;\n } else {\n this.failedTasks++;\n }\n this.activeRunners.delete(runner);\n runner.reject(error);\n } finally {\n this.pump();\n }\n }\n\n /\n Returns telemetry snapshot for the scheduler.\n \n @returns Frozen snapshot of current task metrics.\n /\n public getStats(): IAhkoStats {\n return Object.freeze({\n activeTasks: this.activeRunners.size,\n pendingTasks: this.queue.length + this.delayedEntries.size,\n completedTasks: this.completedTasks,\n failedTasks: this.failedTasks,\n cancelledTasks: this.cancelledTasks,\n timedOutTasks: this.timedOutTasks,\n capacity: this.concurrency,\n });\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task is cancelled before or during execution.\n /\nexport class AhkoCancellationError extends AhkoError {\n /\n Creates a new AhkoCancellationError.\n \n @param message - Reason for cancellation.\n * @param options - Standard Error options including cause.\n /\n constructor(message = \"Task was cancelled\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoCancellationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoCancellationError } from \"../errors/cancellation.error.js\";\nimport type { ITaskContext } from \"../models/context.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport type { ITask } from \"../models/task.model.js\";\n\nlet taskIdCounter = 0;\n\n/\n Internal task lifecycle manager responsible for execution, state transitions,\n * AbortSignal coordination, and deterministic resource cleanup.\n \n @template T - The return type produced by the underlying task.\n /\nexport class TaskRunner<T> {\n /* Unique task identifier /\n public readonly taskId: string;\n\n /* Current lifecycle state /\n private _state: ETaskState = ETaskState.PENDING;\n\n /* Internal AbortController whose signal is passed to the task context /\n private readonly abortController: AbortController;\n\n /* The user task function to execute /\n private readonly task: ITask<T>;\n\n /* User-supplied AbortSignal for external cancellation /\n private readonly externalSignal?: AbortSignal;\n\n /* Abort event listener reference for clean detachment /\n private readonly abortListener?: () => void;\n\n /* Promise resolve handler /\n private resolvePromise!: (value: T \| PromiseLike<T>) => void;\n\n /* Promise reject handler /\n private rejectPromise!: (reason?: unknown) => void;\n\n /* Deferred promise exposed to the caller /\n public readonly promise: Promise<T>;\n\n /* Callback invoked when runner is cancelled while pending /\n public onCancel?: (runner: TaskRunner<T>) => void;\n\n /\n Creates a new TaskRunner instance.\n \n @param task - The asynchronous work unit to run.\n * @param externalSignal - Optional external AbortSignal to propagate.\n /\n constructor(task: ITask<T>, externalSignal?: AbortSignal) {\n this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;\n this.task = task;\n this.externalSignal = externalSignal;\n this.abortController = new AbortController();\n\n this.promise = new Promise<T>((resolve, reject) => {\n this.resolvePromise = resolve;\n this.rejectPromise = reject;\n });\n\n if (this.externalSignal) {\n if (this.externalSignal.aborted) {\n this._state = ETaskState.CANCELLED;\n const reason = this.externalSignal.reason;\n const cancelError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancelError);\n } else {\n this.abortListener = () => {\n this.handleExternalAbort();\n };\n this.externalSignal.addEventListener(\"abort\", this.abortListener, { once: true });\n }\n }\n }\n\n /\n Gets the current lifecycle state of the task.\n /\n public get state(): ETaskState {\n return this._state;\n }\n\n /\n Resolves the deferred promise.\n \n @param value - Value to resolve with.\n /\n public resolve(value: T): void {\n this.resolvePromise(value);\n }\n\n /\n Rejects the deferred promise.\n \n @param reason - Reason to reject with.\n /\n public reject(reason: unknown): void {\n this.rejectPromise(reason);\n }\n\n /\n Executes the task within an allocated concurrency slot.\n \n @returns A promise resolving to the task result or rejecting on failure/cancellation.\n /\n public async run(): Promise<T> {\n if (this._state === ETaskState.CANCELLED) {\n throw new AhkoCancellationError(\"Task was cancelled prior to execution\");\n }\n\n this._state = ETaskState.RUNNING;\n\n const context: ITaskContext = {\n signal: this.abortController.signal,\n taskId: this.taskId,\n };\n\n try {\n const result = await this.task(context);\n this._state = ETaskState.COMPLETED;\n this.cleanup();\n return result;\n } catch (error) {\n this.cleanup();\n\n const isCancelled =\n (this._state as ETaskState) === ETaskState.CANCELLED \|\|\n this.abortController.signal.aborted;\n\n if (isCancelled) {\n this._state = ETaskState.CANCELLED;\n throw new AhkoCancellationError(\"Task was cancelled during execution\", {\n cause: error instanceof Error ? error : undefined,\n });\n }\n\n this._state = ETaskState.FAILED;\n throw error;\n }\n }\n\n /\n Cancels the task, aborting pending or running execution.\n \n @param reason - Optional cancellation reason.\n /\n public cancel(reason?: unknown): void {\n if (\n this._state === ETaskState.COMPLETED \|\|\n this._state === ETaskState.FAILED \|\|\n this._state === ETaskState.CANCELLED \|\|\n this._state === ETaskState.TIMED_OUT\n ) {\n return;\n }\n\n const wasPending = this._state === ETaskState.PENDING;\n this._state = ETaskState.CANCELLED;\n this.abortController.abort(reason);\n this.cleanup();\n\n if (wasPending) {\n const cancellationError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancellationError);\n this.onCancel?.(this);\n }\n }\n\n /\n Handles external AbortSignal trigger.\n /\n private handleExternalAbort(): void {\n this.cancel(this.externalSignal?.reason);\n }\n\n /\n Detaches event listeners from external signal to guarantee memory safety.\n /\n public cleanup(): void {\n if (this.externalSignal && this.abortListener) {\n this.externalSignal.removeEventListener(\"abort\", this.abortListener);\n }\n }\n}\n","import { AhkoConfigurationError } from \"./errors/configuration.error.js\";\nimport type { IAhkoOptions, IScheduleOptions } from \"./models/options.model.js\";\nimport type { IAhkoStats } from \"./models/stats.model.js\";\nimport type { ITask } from \"./models/task.model.js\";\nimport { TaskQueue } from \"./scheduler/task-queue.js\";\nimport { TaskRunner } from \"./scheduler/task-runner.js\";\n\n/\n Ahko — Low-energy, production-grade asynchronous task scheduler.\n \n Coordinates execution timing, enforces concurrency limits, and cooperates\n * natively with AbortSignal cancellation.\n \n @example\n * ```typescript\n * import { Ahko } from \"@mrjacket/ahko\";\n \n const ahko = new Ahko({ concurrency: 2 });\n \n const result = await ahko.schedule(async ({ signal, taskId }) => {\n * const res = await fetch(\"https://api.example.com\", { signal });\n * return res.json();\n * });\n * ```\n /\nexport class Ahko {\n /* Internal queue and concurrency manager /\n private readonly queue: TaskQueue;\n\n /\n Initializes a new Ahko scheduler instance.\n \n @param options - Optional scheduler configuration.\n * @throws {AhkoConfigurationError} If concurrency is invalid (less than 1 or NaN).\n \n @example\n * ```typescript\n * const ahko = new Ahko({ concurrency: 4 });\n * ```\n /\n constructor(options?: IAhkoOptions) {\n this.queue = new TaskQueue(options?.concurrency);\n }\n\n /\n Schedules a task for execution with full return type inference.\n \n @template T - Inferred return type of the task.\n * @param task - Asynchronous or synchronous task function accepting an {@link ITaskContext}.\n * @param options - Task-specific scheduling options such as strategy, delay, and cancellation signal.\n * @returns A promise that resolves with the task's return value.\n \n @throws {AhkoConfigurationError} If the task is not a function or options are invalid.\n * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.\n \n @example\n * ```typescript\n * // Immediate execution (subject to concurrency)\n * const count = await ahko.schedule(async () => 42);\n \n // Delayed execution\n * await ahko.schedule(\n * async ({ signal }) => doWork({ signal }),\n * { strategy: \"delay\", delay: 1000 }\n * );\n * ```\n /\n public schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T> {\n if (typeof task !== \"function\") {\n throw new AhkoConfigurationError(\"Task must be a valid function.\");\n }\n\n const runner = new TaskRunner<T>(task, options?.signal);\n return this.queue.enqueue(runner, options);\n }\n\n /\n Retrieves real-time telemetry metrics from the scheduler.\n \n @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.\n \n @example\n * ```typescript\n * const stats = ahko.stats();\n * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);\n * ```\n /\n public stats(): IAhkoStats {\n return this.queue.getStats();\n }\n}\n","/\n Current version of @mrjacket/ahko package.\n /\nexport const VERSION = \"0.1.0\";\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when an internal queue invariant is violated or queue limits are breached.\n /\nexport class AhkoQueueError extends AhkoError {\n /\n Creates a new AhkoQueueError.\n \n @param message - Explanation of the queue failure.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoQueueError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task exceeds its allotted timeout duration.\n /\nexport class AhkoTimeoutError extends AhkoError {\n /\n Creates a new AhkoTimeoutError.\n \n @param message - Explanation of timeout expiry.\n * @param options - Standard Error options including cause.\n */\n constructor(message = \"Task execution timed out\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoTimeoutError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n"],"mappings":"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","names":["ETaskState","EScheduleStrategy"]}
1	+ {"version":3,"sources":["../src/index.ts","../src/errors/ahko.error.ts","../src/errors/configuration.error.ts","../src/models/strategy.model.ts","../src/models/state.model.ts","../src/scheduler/idle-scheduler.ts","../src/scheduler/task-queue.ts","../src/errors/cancellation.error.ts","../src/scheduler/task-runner.ts","../src/ahko.ts","../src/version.ts","../src/errors/queue.error.ts","../src/errors/timeout.error.ts"],"sourcesContent":["export { Ahko } from \"./ahko.js\";\nexport { VERSION } from \"./version.js\";\n\n// Errors\nexport {\n AhkoError,\n AhkoCancellationError,\n AhkoConfigurationError,\n AhkoQueueError,\n AhkoTimeoutError,\n} from \"./errors/index.js\";\n\n// Models and interfaces\nexport {\n ETaskState,\n EScheduleStrategy,\n} from \"./models/index.js\";\n\nexport type {\n ITask,\n ITaskContext,\n IScheduleOptions,\n IAhkoOptions,\n IAhkoStats,\n TScheduleStrategy,\n} from \"./models/index.js\";\n","/*\n Base error class for all errors originating from the Ahko scheduler.\n /\nexport class AhkoError extends Error {\n /\n Creates a new AhkoError instance.\n \n @param message - Descriptive error message.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when invalid configuration or scheduling options are provided.\n /\nexport class AhkoConfigurationError extends AhkoError {\n /\n Creates a new AhkoConfigurationError.\n \n @param message - Explanation of the invalid configuration parameter.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoConfigurationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","/\n Fundamental scheduling strategies supported by the Ahko scheduler.\n /\nexport enum EScheduleStrategy {\n /* Execute as soon as a concurrency slot is available /\n IMMEDIATE = \"immediate\",\n /* Delay execution for a designated duration before queuing /\n DELAY = \"delay\",\n /* Execute during platform idle opportunities (requestIdleCallback in browser, setImmediate in Node.js) /\n IDLE = \"idle\",\n}\n\n/\n Union type representing valid scheduling strategy identifiers.\n /\nexport type TScheduleStrategy = EScheduleStrategy \| \"immediate\" \| \"delay\" \| \"idle\";\n","/\n Represents the discrete lifecycle states of an Ahko task.\n /\nexport enum ETaskState {\n /* Task has been scheduled and is awaiting execution in queue or timer /\n PENDING = \"pending\",\n /* Task is currently executing within an allocated concurrency slot /\n RUNNING = \"running\",\n /* Task successfully finished execution /\n COMPLETED = \"completed\",\n /* Task execution threw an error or rejected /\n FAILED = \"failed\",\n /* Task was cancelled via AbortSignal before or during execution /\n CANCELLED = \"cancelled\",\n /* Task was terminated because its execution exceeded the timeout /\n TIMED_OUT = \"timed_out\",\n}\n","/\n Handle returned by the IdleScheduler allowing cancellation of an idle request.\n /\nexport interface IIdleHandle {\n /\n Cancels the scheduled idle callback and cleans up platform resources.\n /\n cancel(): void;\n}\n\n/\n Platform-agnostic scheduler for opportunistic idle task execution.\n \n Automatically detects and selects platform capabilities:\n * 1. Browser: `requestIdleCallback` / `cancelIdleCallback` (with optional timeout)\n * 2. Node.js: `setImmediate` / `clearImmediate` as low-priority primitive\n * 3. Fallback: `setTimeout(..., 0)` / `clearTimeout`\n /\nexport class IdleScheduler {\n /\n Schedules a callback to execute during the next idle opportunity.\n \n @param callback - Function to invoke when idle opportunity arises.\n * @param timeout - Optional max deadline in milliseconds to wait before invoking (browser only).\n * @param runtime - Target runtime scope providing scheduling primitives (defaults to globalThis).\n * @returns An {@link IIdleHandle} with a `cancel()` method for cleanup.\n /\n public static schedule(\n callback: () => void,\n timeout?: number,\n runtime: typeof globalThis = globalThis\n ): IIdleHandle {\n // 1. Browser requestIdleCallback\n if (\n typeof (runtime as Record<string, unknown>).requestIdleCallback === \"function\" &&\n typeof (runtime as Record<string, unknown>).cancelIdleCallback === \"function\"\n ) {\n const requestFn = (runtime as Record<string, unknown>).requestIdleCallback as (\n cb: (deadline?: unknown) => void,\n opts?: { timeout?: number }\n ) => number;\n\n const cancelFn = (runtime as Record<string, unknown>).cancelIdleCallback as (\n handle: number\n ) => void;\n\n const id = requestFn(\n () => callback(),\n typeof timeout === \"number\" && !Number.isNaN(timeout) && timeout >= 0\n ? { timeout }\n : undefined\n );\n\n return {\n cancel: () => cancelFn(id),\n };\n }\n\n // 2. Node.js setImmediate\n if (\n typeof (runtime as Record<string, unknown>).setImmediate === \"function\" &&\n typeof (runtime as Record<string, unknown>).clearImmediate === \"function\"\n ) {\n const setImmFn = (runtime as Record<string, unknown>).setImmediate as (\n cb: () => void\n ) => ReturnType<typeof setImmediate>;\n\n const clearImmFn = (runtime as Record<string, unknown>).clearImmediate as (\n handle: ReturnType<typeof setImmediate>\n ) => void;\n\n const handle = setImmFn(() => callback());\n\n return {\n cancel: () => clearImmFn(handle),\n };\n }\n\n // 3. Universal fallback setTimeout(0)\n const setTimerFn = runtime.setTimeout.bind(runtime);\n const clearTimerFn = runtime.clearTimeout.bind(runtime);\n\n const timerId = setTimerFn(() => callback(), 0);\n\n return {\n cancel: () => clearTimerFn(timerId),\n };\n }\n}\n","import { AhkoConfigurationError } from \"../errors/configuration.error.js\";\nimport type { IScheduleOptions } from \"../models/options.model.js\";\nimport type { IAhkoStats } from \"../models/stats.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport { EScheduleStrategy } from \"../models/strategy.model.js\";\nimport { IdleScheduler, type IIdleHandle } from \"./idle-scheduler.js\";\nimport { TaskRunner } from \"./task-runner.js\";\n\n/\n Entry tracking delayed task timers for deterministic cancellation and memory cleanup.\n /\ninterface IDelayedEntry {\n runner: TaskRunner<unknown>;\n timerId: ReturnType<typeof setTimeout>;\n}\n\n/\n Entry tracking idle callback handles for deterministic cancellation and cleanup.\n /\ninterface IIdleEntry {\n runner: TaskRunner<unknown>;\n handle: IIdleHandle;\n}\n\n/\n Memory-safe FIFO task queue managing concurrency allocation,\n * delayed scheduling, and task lifecycle counters.\n /\nexport class TaskQueue {\n /* Maximum concurrent active tasks /\n public readonly concurrency: number;\n\n /* Queue of pending task runners waiting for a concurrency slot /\n private readonly queue: TaskRunner<unknown>[] = [];\n\n /* Set of task runners currently executing /\n private readonly activeRunners = new Set<TaskRunner<unknown>>();\n\n /* Set of tasks currently in delay phase /\n private readonly delayedEntries = new Set<IDelayedEntry>();\n\n /* Set of tasks currently awaiting an idle opportunity /\n private readonly idleEntries = new Set<IIdleEntry>();\n\n /* Cumulative completed tasks counter /\n private completedTasks = 0;\n\n /* Cumulative failed tasks counter /\n private failedTasks = 0;\n\n /* Cumulative cancelled tasks counter /\n private cancelledTasks = 0;\n\n /* Cumulative timed out tasks counter /\n private timedOutTasks = 0;\n\n /\n Creates a new TaskQueue.\n \n @param concurrency - Maximum concurrent tasks (defaults to Infinity).\n * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.\n /\n constructor(concurrency = Infinity) {\n if (Number.isNaN(concurrency) \|\| concurrency < 1) {\n throw new AhkoConfigurationError(\n `Invalid concurrency \"${concurrency}\". Must be a number greater than or equal to 1.`\n );\n }\n this.concurrency = concurrency;\n }\n\n /\n Enqueues a task runner according to the specified schedule options.\n \n @template T - The return type produced by the task.\n * @param runner - The task runner instance.\n * @param options - Scheduling options.\n * @returns The deferred promise associated with the task runner.\n * @throws {AhkoConfigurationError} If scheduling options are invalid.\n /\n public enqueue<T>(runner: TaskRunner<T>, options?: IScheduleOptions): Promise<T> {\n const strategy = options?.strategy ?? EScheduleStrategy.IMMEDIATE;\n\n if (\n strategy !== EScheduleStrategy.IMMEDIATE &&\n strategy !== EScheduleStrategy.DELAY &&\n strategy !== EScheduleStrategy.IDLE\n ) {\n throw new AhkoConfigurationError(\n `Unsupported schedule strategy \"${String(strategy)}\". Supported strategies: \"immediate\", \"delay\", \"idle\".`\n );\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n return runner.promise;\n }\n\n if (strategy === EScheduleStrategy.DELAY) {\n const delayMs = options?.delay ?? 0;\n if (typeof delayMs !== \"number\" \|\| Number.isNaN(delayMs) \|\| delayMs < 0) {\n throw new AhkoConfigurationError(\n `Invalid delay \"${delayMs}\". Delay must be a non-negative number in milliseconds.`\n );\n }\n\n this.scheduleDelayed(runner as TaskRunner<unknown>, delayMs);\n return runner.promise;\n }\n\n if (strategy === EScheduleStrategy.IDLE) {\n if (\n options?.idleTimeout !== undefined &&\n (typeof options.idleTimeout !== \"number\" \|\|\n Number.isNaN(options.idleTimeout) \|\|\n options.idleTimeout < 0)\n ) {\n throw new AhkoConfigurationError(\n `Invalid idleTimeout \"${options.idleTimeout}\". idleTimeout must be a non-negative number in milliseconds.`\n );\n }\n\n this.scheduleIdle(runner as TaskRunner<unknown>, options?.idleTimeout);\n return runner.promise;\n }\n\n // Attach immediate onCancel handler to dequeue without consuming concurrency\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner as TaskRunner<unknown>);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n // Immediate strategy: add to pending queue and pump\n this.queue.push(runner as TaskRunner<unknown>);\n this.pump();\n\n return runner.promise;\n }\n\n /\n Schedules a task to be placed into the queue after a delay,\n * handling early cancellation safely.\n /\n private scheduleDelayed(runner: TaskRunner<unknown>, delayMs: number): void {\n const delayedEntry: IDelayedEntry = {\n runner,\n timerId: setTimeout(() => {\n this.delayedEntries.delete(delayedEntry);\n if (runner.state === ETaskState.CANCELLED) {\n return;\n }\n\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n this.queue.push(runner);\n this.pump();\n }, delayMs),\n };\n\n this.delayedEntries.add(delayedEntry);\n\n runner.onCancel = () => {\n if (this.delayedEntries.has(delayedEntry)) {\n clearTimeout(delayedEntry.timerId);\n this.delayedEntries.delete(delayedEntry);\n this.cancelledTasks++;\n }\n };\n }\n\n /\n Schedules a task to be placed into the queue during an idle opportunity,\n * handling early cancellation safely.\n /\n private scheduleIdle(runner: TaskRunner<unknown>, idleTimeout?: number): void {\n let idleEntry!: IIdleEntry;\n\n const handle = IdleScheduler.schedule(() => {\n this.idleEntries.delete(idleEntry);\n if (runner.state === ETaskState.CANCELLED) {\n return;\n }\n\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n this.queue.push(runner);\n this.pump();\n }, idleTimeout);\n\n idleEntry = { runner, handle };\n this.idleEntries.add(idleEntry);\n\n runner.onCancel = () => {\n if (this.idleEntries.has(idleEntry)) {\n handle.cancel();\n this.idleEntries.delete(idleEntry);\n this.cancelledTasks++;\n }\n };\n }\n\n /\n Pumps the queue by picking pending tasks and executing them\n * as long as concurrency capacity is available.\n /\n private pump(): void {\n while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {\n const runner = this.queue.shift();\n if (!runner) {\n break;\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n continue;\n }\n\n this.activeRunners.add(runner);\n\n // Execute runner without unhandled rejection risk\n void this.executeRunner(runner);\n }\n }\n\n /\n Internal execution of an active task runner.\n * Settle caller promise strictly after stats and active status are updated.\n /\n private async executeRunner(runner: TaskRunner<unknown>): Promise<void> {\n try {\n const result = await runner.run();\n this.completedTasks++;\n this.activeRunners.delete(runner);\n runner.resolve(result);\n } catch (error) {\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n } else if (runner.state === ETaskState.TIMED_OUT) {\n this.timedOutTasks++;\n } else {\n this.failedTasks++;\n }\n this.activeRunners.delete(runner);\n runner.reject(error);\n } finally {\n this.pump();\n }\n }\n\n /\n Returns telemetry snapshot for the scheduler.\n \n @returns Frozen snapshot of current task metrics.\n /\n public getStats(): IAhkoStats {\n return Object.freeze({\n activeTasks: this.activeRunners.size,\n pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size,\n completedTasks: this.completedTasks,\n failedTasks: this.failedTasks,\n cancelledTasks: this.cancelledTasks,\n timedOutTasks: this.timedOutTasks,\n capacity: this.concurrency,\n });\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task is cancelled before or during execution.\n /\nexport class AhkoCancellationError extends AhkoError {\n /\n Creates a new AhkoCancellationError.\n \n @param message - Reason for cancellation.\n * @param options - Standard Error options including cause.\n /\n constructor(message = \"Task was cancelled\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoCancellationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoCancellationError } from \"../errors/cancellation.error.js\";\nimport type { ITaskContext } from \"../models/context.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport type { ITask } from \"../models/task.model.js\";\n\nlet taskIdCounter = 0;\n\n/\n Internal task lifecycle manager responsible for execution, state transitions,\n * AbortSignal coordination, and deterministic resource cleanup.\n \n @template T - The return type produced by the underlying task.\n /\nexport class TaskRunner<T> {\n /* Unique task identifier /\n public readonly taskId: string;\n\n /* Current lifecycle state /\n private _state: ETaskState = ETaskState.PENDING;\n\n /* Internal AbortController whose signal is passed to the task context /\n private readonly abortController: AbortController;\n\n /* The user task function to execute /\n private readonly task: ITask<T>;\n\n /* User-supplied AbortSignal for external cancellation /\n private readonly externalSignal?: AbortSignal;\n\n /* Abort event listener reference for clean detachment /\n private readonly abortListener?: () => void;\n\n /* Promise resolve handler /\n private resolvePromise!: (value: T \| PromiseLike<T>) => void;\n\n /* Promise reject handler /\n private rejectPromise!: (reason?: unknown) => void;\n\n /* Deferred promise exposed to the caller /\n public readonly promise: Promise<T>;\n\n /* Callback invoked when runner is cancelled while pending /\n public onCancel?: (runner: TaskRunner<T>) => void;\n\n /\n Creates a new TaskRunner instance.\n \n @param task - The asynchronous work unit to run.\n * @param externalSignal - Optional external AbortSignal to propagate.\n /\n constructor(task: ITask<T>, externalSignal?: AbortSignal) {\n this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;\n this.task = task;\n this.externalSignal = externalSignal;\n this.abortController = new AbortController();\n\n this.promise = new Promise<T>((resolve, reject) => {\n this.resolvePromise = resolve;\n this.rejectPromise = reject;\n });\n\n if (this.externalSignal) {\n if (this.externalSignal.aborted) {\n this._state = ETaskState.CANCELLED;\n const reason = this.externalSignal.reason;\n const cancelError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancelError);\n } else {\n this.abortListener = () => {\n this.handleExternalAbort();\n };\n this.externalSignal.addEventListener(\"abort\", this.abortListener, { once: true });\n }\n }\n }\n\n /\n Gets the current lifecycle state of the task.\n /\n public get state(): ETaskState {\n return this._state;\n }\n\n /\n Resolves the deferred promise.\n \n @param value - Value to resolve with.\n /\n public resolve(value: T): void {\n this.resolvePromise(value);\n }\n\n /\n Rejects the deferred promise.\n \n @param reason - Reason to reject with.\n /\n public reject(reason: unknown): void {\n this.rejectPromise(reason);\n }\n\n /\n Executes the task within an allocated concurrency slot.\n \n @returns A promise resolving to the task result or rejecting on failure/cancellation.\n /\n public async run(): Promise<T> {\n if (this._state === ETaskState.CANCELLED) {\n throw new AhkoCancellationError(\"Task was cancelled prior to execution\");\n }\n\n this._state = ETaskState.RUNNING;\n\n const context: ITaskContext = {\n signal: this.abortController.signal,\n taskId: this.taskId,\n };\n\n try {\n const result = await this.task(context);\n this._state = ETaskState.COMPLETED;\n this.cleanup();\n return result;\n } catch (error) {\n this.cleanup();\n\n const isCancelled =\n (this._state as ETaskState) === ETaskState.CANCELLED \|\|\n this.abortController.signal.aborted;\n\n if (isCancelled) {\n this._state = ETaskState.CANCELLED;\n throw new AhkoCancellationError(\"Task was cancelled during execution\", {\n cause: error instanceof Error ? error : undefined,\n });\n }\n\n this._state = ETaskState.FAILED;\n throw error;\n }\n }\n\n /\n Cancels the task, aborting pending or running execution.\n \n @param reason - Optional cancellation reason.\n /\n public cancel(reason?: unknown): void {\n if (\n this._state === ETaskState.COMPLETED \|\|\n this._state === ETaskState.FAILED \|\|\n this._state === ETaskState.CANCELLED \|\|\n this._state === ETaskState.TIMED_OUT\n ) {\n return;\n }\n\n const wasPending = this._state === ETaskState.PENDING;\n this._state = ETaskState.CANCELLED;\n this.abortController.abort(reason);\n this.cleanup();\n\n if (wasPending) {\n const cancellationError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancellationError);\n this.onCancel?.(this);\n }\n }\n\n /\n Handles external AbortSignal trigger.\n /\n private handleExternalAbort(): void {\n this.cancel(this.externalSignal?.reason);\n }\n\n /\n Detaches event listeners from external signal to guarantee memory safety.\n /\n public cleanup(): void {\n if (this.externalSignal && this.abortListener) {\n this.externalSignal.removeEventListener(\"abort\", this.abortListener);\n }\n }\n}\n","import { AhkoConfigurationError } from \"./errors/configuration.error.js\";\nimport type { IAhkoOptions, IScheduleOptions } from \"./models/options.model.js\";\nimport type { IAhkoStats } from \"./models/stats.model.js\";\nimport { EScheduleStrategy } from \"./models/strategy.model.js\";\nimport type { ITask } from \"./models/task.model.js\";\nimport { TaskQueue } from \"./scheduler/task-queue.js\";\nimport { TaskRunner } from \"./scheduler/task-runner.js\";\n\n/\n Ahko — Low-energy asynchronous task scheduler.\n \n Coordinates execution timing, enforces concurrency limits, and cooperates\n * natively with AbortSignal cancellation.\n \n @example\n * ```typescript\n * import { Ahko } from \"@mrjacket/ahko\";\n \n const ahko = new Ahko({ concurrency: 2 });\n \n const result = await ahko.schedule(async ({ signal, taskId }) => {\n * const res = await fetch(\"https://api.example.com\", { signal });\n * return res.json();\n * });\n * ```\n /\nexport class Ahko {\n /* Internal queue and concurrency manager /\n private readonly queue: TaskQueue;\n\n /\n Initializes a new Ahko scheduler instance.\n \n @param options - Optional scheduler configuration.\n * @throws {AhkoConfigurationError} If concurrency is invalid (less than 1 or NaN).\n \n @example\n * ```typescript\n * const ahko = new Ahko({ concurrency: 4 });\n * ```\n /\n constructor(options?: IAhkoOptions) {\n this.queue = new TaskQueue(options?.concurrency);\n }\n\n /\n Schedules a task for execution with full return type inference.\n \n @template T - Inferred return type of the task.\n * @param task - Asynchronous or synchronous task function accepting an {@link ITaskContext}.\n * @param options - Task-specific scheduling options such as strategy, delay, and cancellation signal.\n * @returns A promise that resolves with the task's return value.\n \n @throws {AhkoConfigurationError} If the task is not a function or options are invalid.\n * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.\n \n @example\n * ```typescript\n * // Immediate execution (subject to concurrency)\n * const count = await ahko.schedule(async () => 42);\n \n // Delayed execution\n * await ahko.schedule(\n * async ({ signal }) => doWork({ signal }),\n * { strategy: \"delay\", delay: 1000 }\n * );\n * ```\n /\n public schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T> {\n if (typeof task !== \"function\") {\n throw new AhkoConfigurationError(\"Task must be a valid function.\");\n }\n\n const runner = new TaskRunner<T>(task, options?.signal);\n return this.queue.enqueue(runner, options);\n }\n\n /\n Convenience method to schedule a task during platform idle opportunities.\n \n Equivalent to calling `schedule(task, { ...options, strategy: \"idle\" })`.\n * In browsers, uses `requestIdleCallback` when available.\n * In Node.js, uses `setImmediate`.\n * Falls back to `setTimeout(..., 0)` if neither is available.\n \n @template T - Inferred return type of the task.\n * @param task - Task function to run when idle.\n * @param options - Scheduling options (excluding strategy).\n * @returns A promise resolving to the task's return value.\n \n @throws {AhkoConfigurationError} If the task is not a function or options are invalid.\n * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.\n \n @example\n * ```typescript\n * const result = await ahko.idle(async ({ signal }) => {\n * return computeAnalytics();\n * });\n * ```\n /\n public idle<T>(\n task: ITask<T>,\n options?: Omit<IScheduleOptions, \"strategy\">\n ): Promise<T> {\n return this.schedule(task, {\n ...options,\n strategy: EScheduleStrategy.IDLE,\n });\n }\n\n /\n Retrieves real-time telemetry metrics from the scheduler.\n \n @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.\n \n @example\n * ```typescript\n * const stats = ahko.stats();\n * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);\n * ```\n /\n public stats(): IAhkoStats {\n return this.queue.getStats();\n }\n}\n","/\n Current version of @mrjacket/ahko package.\n /\nexport const VERSION = \"0.2.0\";\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when an internal queue invariant is violated or queue limits are breached.\n /\nexport class AhkoQueueError extends AhkoError {\n /\n Creates a new AhkoQueueError.\n \n @param message - Explanation of the queue failure.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoQueueError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task exceeds its allotted timeout duration.\n /\nexport class AhkoTimeoutError extends AhkoError {\n /\n Creates a new AhkoTimeoutError.\n \n @param message - Explanation of timeout expiry.\n * @param options - Standard Error options including cause.\n */\n constructor(message = \"Task execution timed out\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoTimeoutError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n"],"mappings":"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","names":["EScheduleStrategy","ETaskState"]}

package/dist/index.js CHANGED Viewed

@@ -28,6 +28,14 @@ var AhkoConfigurationError = class extends AhkoError {
   }
 };
+// src/models/strategy.model.ts
+var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
+  EScheduleStrategy2["IMMEDIATE"] = "immediate";
+  EScheduleStrategy2["DELAY"] = "delay";
+  EScheduleStrategy2["IDLE"] = "idle";
+  return EScheduleStrategy2;
+})(EScheduleStrategy || {});
 // src/models/state.model.ts
 var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   ETaskState2["PENDING"] = "pending";
@@ -39,12 +47,44 @@ var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   return ETaskState2;
 })(ETaskState || {});
-// src/models/strategy.model.ts
-var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
-  EScheduleStrategy2["IMMEDIATE"] = "immediate";
-  EScheduleStrategy2["DELAY"] = "delay";
-  return EScheduleStrategy2;
-})(EScheduleStrategy || {});
+// src/scheduler/idle-scheduler.ts
+var IdleScheduler = class {
+  /**
+   * Schedules a callback to execute during the next idle opportunity.
+   *
+   * @param callback - Function to invoke when idle opportunity arises.
+   * @param timeout - Optional max deadline in milliseconds to wait before invoking (browser only).
+   * @param runtime - Target runtime scope providing scheduling primitives (defaults to globalThis).
+   * @returns An {@link IIdleHandle} with a `cancel()` method for cleanup.
+   */
+  static schedule(callback, timeout, runtime = globalThis) {
+    if (typeof runtime.requestIdleCallback === "function" && typeof runtime.cancelIdleCallback === "function") {
+      const requestFn = runtime.requestIdleCallback;
+      const cancelFn = runtime.cancelIdleCallback;
+      const id = requestFn(
+        () => callback(),
+        typeof timeout === "number" && !Number.isNaN(timeout) && timeout >= 0 ? { timeout } : void 0
+      );
+      return {
+        cancel: () => cancelFn(id)
+      };
+    }
+    if (typeof runtime.setImmediate === "function" && typeof runtime.clearImmediate === "function") {
+      const setImmFn = runtime.setImmediate;
+      const clearImmFn = runtime.clearImmediate;
+      const handle = setImmFn(() => callback());
+      return {
+        cancel: () => clearImmFn(handle)
+      };
+    }
+    const setTimerFn = runtime.setTimeout.bind(runtime);
+    const clearTimerFn = runtime.clearTimeout.bind(runtime);
+    const timerId = setTimerFn(() => callback(), 0);
+    return {
+      cancel: () => clearTimerFn(timerId)
+    };
+  }
+};
 // src/scheduler/task-queue.ts
 var TaskQueue = class {
@@ -56,6 +96,8 @@ var TaskQueue = class {
   activeRunners = /* @__PURE__ */ new Set();
   /** Set of tasks currently in delay phase */
   delayedEntries = /* @__PURE__ */ new Set();
+  /** Set of tasks currently awaiting an idle opportunity */
+  idleEntries = /* @__PURE__ */ new Set();
   /** Cumulative completed tasks counter */
   completedTasks = 0;
   /** Cumulative failed tasks counter */
@@ -89,9 +131,9 @@ var TaskQueue = class {
    */
   enqueue(runner, options) {
     const strategy = options?.strategy ?? "immediate" /* IMMEDIATE */;
-    if (strategy !== "immediate" /* IMMEDIATE */ && strategy !== "delay" /* DELAY */) {
+    if (strategy !== "immediate" /* IMMEDIATE */ && strategy !== "delay" /* DELAY */ && strategy !== "idle" /* IDLE */) {
       throw new AhkoConfigurationError(
-        `Unsupported schedule strategy "${String(strategy)}". Supported strategies in 0.1.0: "immediate", "delay".`
+        `Unsupported schedule strategy "${String(strategy)}". Supported strategies: "immediate", "delay", "idle".`
       );
     }
     if (runner.state === "cancelled" /* CANCELLED */) {
@@ -108,6 +150,15 @@ var TaskQueue = class {
       this.scheduleDelayed(runner, delayMs);
       return runner.promise;
     }
+    if (strategy === "idle" /* IDLE */) {
+      if (options?.idleTimeout !== void 0 && (typeof options.idleTimeout !== "number" || Number.isNaN(options.idleTimeout) || options.idleTimeout < 0)) {
+        throw new AhkoConfigurationError(
+          `Invalid idleTimeout "${options.idleTimeout}". idleTimeout must be a non-negative number in milliseconds.`
+        );
+      }
+      this.scheduleIdle(runner, options?.idleTimeout);
+      return runner.promise;
+    }
     runner.onCancel = () => {
       const index = this.queue.indexOf(runner);
       if (index !== -1) {
@@ -151,6 +202,37 @@ var TaskQueue = class {
       }
     };
   }
+  /**
+   * Schedules a task to be placed into the queue during an idle opportunity,
+   * handling early cancellation safely.
+   */
+  scheduleIdle(runner, idleTimeout) {
+    let idleEntry;
+    const handle = IdleScheduler.schedule(() => {
+      this.idleEntries.delete(idleEntry);
+      if (runner.state === "cancelled" /* CANCELLED */) {
+        return;
+      }
+      runner.onCancel = () => {
+        const index = this.queue.indexOf(runner);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+          this.cancelledTasks++;
+        }
+      };
+      this.queue.push(runner);
+      this.pump();
+    }, idleTimeout);
+    idleEntry = { runner, handle };
+    this.idleEntries.add(idleEntry);
+    runner.onCancel = () => {
+      if (this.idleEntries.has(idleEntry)) {
+        handle.cancel();
+        this.idleEntries.delete(idleEntry);
+        this.cancelledTasks++;
+      }
+    };
+  }
   /**
    * Pumps the queue by picking pending tasks and executing them
    * as long as concurrency capacity is available.
@@ -200,7 +282,7 @@ var TaskQueue = class {
   getStats() {
     return Object.freeze({
       activeTasks: this.activeRunners.size,
-      pendingTasks: this.queue.length + this.delayedEntries.size,
+      pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size,
       completedTasks: this.completedTasks,
       failedTasks: this.failedTasks,
       cancelledTasks: this.cancelledTasks,
@@ -420,6 +502,35 @@ var Ahko = class {
     const runner = new TaskRunner(task, options?.signal);
     return this.queue.enqueue(runner, options);
   }
+  /**
+   * 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(task, options) {
+    return this.schedule(task, {
+      ...options,
+      strategy: "idle" /* IDLE */
+    });
+  }
   /**
    * Retrieves real-time telemetry metrics from the scheduler.
    *
@@ -437,7 +548,7 @@ var Ahko = class {
 };
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/errors/ahko.error.ts","../src/errors/configuration.error.ts","../src/models/state.model.ts","../src/models/strategy.model.ts","../src/scheduler/task-queue.ts","../src/errors/cancellation.error.ts","../src/scheduler/task-runner.ts","../src/ahko.ts","../src/version.ts","../src/errors/queue.error.ts","../src/errors/timeout.error.ts"],"sourcesContent":["/*\n Base error class for all errors originating from the Ahko scheduler.\n /\nexport class AhkoError extends Error {\n /\n Creates a new AhkoError instance.\n \n @param message - Descriptive error message.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when invalid configuration or scheduling options are provided.\n /\nexport class AhkoConfigurationError extends AhkoError {\n /\n Creates a new AhkoConfigurationError.\n \n @param message - Explanation of the invalid configuration parameter.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoConfigurationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","/\n Represents the discrete lifecycle states of an Ahko task.\n /\nexport enum ETaskState {\n /* Task has been scheduled and is awaiting execution in queue or timer /\n PENDING = \"pending\",\n /* Task is currently executing within an allocated concurrency slot /\n RUNNING = \"running\",\n /* Task successfully finished execution /\n COMPLETED = \"completed\",\n /* Task execution threw an error or rejected /\n FAILED = \"failed\",\n /* Task was cancelled via AbortSignal before or during execution /\n CANCELLED = \"cancelled\",\n /* Task was terminated because its execution exceeded the timeout /\n TIMED_OUT = \"timed_out\",\n}\n","/\n Fundamental scheduling strategies supported by the Ahko scheduler.\n /\nexport enum EScheduleStrategy {\n /* Execute as soon as a concurrency slot is available /\n IMMEDIATE = \"immediate\",\n /* Delay execution for a designated duration before queuing /\n DELAY = \"delay\",\n}\n\n/\n Union type representing valid scheduling strategy identifiers.\n /\nexport type TScheduleStrategy = EScheduleStrategy \| \"immediate\" \| \"delay\";\n","import { AhkoConfigurationError } from \"../errors/configuration.error.js\";\nimport type { IScheduleOptions } from \"../models/options.model.js\";\nimport type { IAhkoStats } from \"../models/stats.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport { EScheduleStrategy } from \"../models/strategy.model.js\";\nimport { TaskRunner } from \"./task-runner.js\";\n\n/\n Entry tracking delayed task timers for deterministic cancellation and memory cleanup.\n /\ninterface IDelayedEntry {\n runner: TaskRunner<unknown>;\n timerId: ReturnType<typeof setTimeout>;\n}\n\n/\n Memory-safe FIFO task queue managing concurrency allocation,\n * delayed scheduling, and task lifecycle counters.\n /\nexport class TaskQueue {\n /* Maximum concurrent active tasks /\n public readonly concurrency: number;\n\n /* Queue of pending task runners waiting for a concurrency slot /\n private readonly queue: TaskRunner<unknown>[] = [];\n\n /* Set of task runners currently executing /\n private readonly activeRunners = new Set<TaskRunner<unknown>>();\n\n /* Set of tasks currently in delay phase /\n private readonly delayedEntries = new Set<IDelayedEntry>();\n\n /* Cumulative completed tasks counter /\n private completedTasks = 0;\n\n /* Cumulative failed tasks counter /\n private failedTasks = 0;\n\n /* Cumulative cancelled tasks counter /\n private cancelledTasks = 0;\n\n /* Cumulative timed out tasks counter /\n private timedOutTasks = 0;\n\n /\n Creates a new TaskQueue.\n \n @param concurrency - Maximum concurrent tasks (defaults to Infinity).\n * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.\n /\n constructor(concurrency = Infinity) {\n if (Number.isNaN(concurrency) \|\| concurrency < 1) {\n throw new AhkoConfigurationError(\n `Invalid concurrency \"${concurrency}\". Must be a number greater than or equal to 1.`\n );\n }\n this.concurrency = concurrency;\n }\n\n /\n Enqueues a task runner according to the specified schedule options.\n \n @template T - The return type produced by the task.\n * @param runner - The task runner instance.\n * @param options - Scheduling options.\n * @returns The deferred promise associated with the task runner.\n * @throws {AhkoConfigurationError} If scheduling options are invalid.\n /\n public enqueue<T>(runner: TaskRunner<T>, options?: IScheduleOptions): Promise<T> {\n const strategy = options?.strategy ?? EScheduleStrategy.IMMEDIATE;\n\n if (strategy !== EScheduleStrategy.IMMEDIATE && strategy !== EScheduleStrategy.DELAY) {\n throw new AhkoConfigurationError(\n `Unsupported schedule strategy \"${String(strategy)}\". Supported strategies in 0.1.0: \"immediate\", \"delay\".`\n );\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n return runner.promise;\n }\n\n if (strategy === EScheduleStrategy.DELAY) {\n const delayMs = options?.delay ?? 0;\n if (typeof delayMs !== \"number\" \|\| Number.isNaN(delayMs) \|\| delayMs < 0) {\n throw new AhkoConfigurationError(\n `Invalid delay \"${delayMs}\". Delay must be a non-negative number in milliseconds.`\n );\n }\n\n this.scheduleDelayed(runner as TaskRunner<unknown>, delayMs);\n return runner.promise;\n }\n\n // Attach immediate onCancel handler to dequeue without consuming concurrency\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner as TaskRunner<unknown>);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n // Immediate strategy: add to pending queue and pump\n this.queue.push(runner as TaskRunner<unknown>);\n this.pump();\n\n return runner.promise;\n }\n\n /\n Schedules a task to be placed into the queue after a delay,\n * handling early cancellation safely.\n /\n private scheduleDelayed(runner: TaskRunner<unknown>, delayMs: number): void {\n const delayedEntry: IDelayedEntry = {\n runner,\n timerId: setTimeout(() => {\n this.delayedEntries.delete(delayedEntry);\n if (runner.state === ETaskState.CANCELLED) {\n return;\n }\n\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n this.queue.push(runner);\n this.pump();\n }, delayMs),\n };\n\n this.delayedEntries.add(delayedEntry);\n\n runner.onCancel = () => {\n if (this.delayedEntries.has(delayedEntry)) {\n clearTimeout(delayedEntry.timerId);\n this.delayedEntries.delete(delayedEntry);\n this.cancelledTasks++;\n }\n };\n }\n\n /\n Pumps the queue by picking pending tasks and executing them\n * as long as concurrency capacity is available.\n /\n private pump(): void {\n while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {\n const runner = this.queue.shift();\n if (!runner) {\n break;\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n continue;\n }\n\n this.activeRunners.add(runner);\n\n // Execute runner without unhandled rejection risk\n void this.executeRunner(runner);\n }\n }\n\n /\n Internal execution of an active task runner.\n * Settle caller promise strictly after stats and active status are updated.\n /\n private async executeRunner(runner: TaskRunner<unknown>): Promise<void> {\n try {\n const result = await runner.run();\n this.completedTasks++;\n this.activeRunners.delete(runner);\n runner.resolve(result);\n } catch (error) {\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n } else if (runner.state === ETaskState.TIMED_OUT) {\n this.timedOutTasks++;\n } else {\n this.failedTasks++;\n }\n this.activeRunners.delete(runner);\n runner.reject(error);\n } finally {\n this.pump();\n }\n }\n\n /\n Returns telemetry snapshot for the scheduler.\n \n @returns Frozen snapshot of current task metrics.\n /\n public getStats(): IAhkoStats {\n return Object.freeze({\n activeTasks: this.activeRunners.size,\n pendingTasks: this.queue.length + this.delayedEntries.size,\n completedTasks: this.completedTasks,\n failedTasks: this.failedTasks,\n cancelledTasks: this.cancelledTasks,\n timedOutTasks: this.timedOutTasks,\n capacity: this.concurrency,\n });\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task is cancelled before or during execution.\n /\nexport class AhkoCancellationError extends AhkoError {\n /\n Creates a new AhkoCancellationError.\n \n @param message - Reason for cancellation.\n * @param options - Standard Error options including cause.\n /\n constructor(message = \"Task was cancelled\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoCancellationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoCancellationError } from \"../errors/cancellation.error.js\";\nimport type { ITaskContext } from \"../models/context.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport type { ITask } from \"../models/task.model.js\";\n\nlet taskIdCounter = 0;\n\n/\n Internal task lifecycle manager responsible for execution, state transitions,\n * AbortSignal coordination, and deterministic resource cleanup.\n \n @template T - The return type produced by the underlying task.\n /\nexport class TaskRunner<T> {\n /* Unique task identifier /\n public readonly taskId: string;\n\n /* Current lifecycle state /\n private _state: ETaskState = ETaskState.PENDING;\n\n /* Internal AbortController whose signal is passed to the task context /\n private readonly abortController: AbortController;\n\n /* The user task function to execute /\n private readonly task: ITask<T>;\n\n /* User-supplied AbortSignal for external cancellation /\n private readonly externalSignal?: AbortSignal;\n\n /* Abort event listener reference for clean detachment /\n private readonly abortListener?: () => void;\n\n /* Promise resolve handler /\n private resolvePromise!: (value: T \| PromiseLike<T>) => void;\n\n /* Promise reject handler /\n private rejectPromise!: (reason?: unknown) => void;\n\n /* Deferred promise exposed to the caller /\n public readonly promise: Promise<T>;\n\n /* Callback invoked when runner is cancelled while pending /\n public onCancel?: (runner: TaskRunner<T>) => void;\n\n /\n Creates a new TaskRunner instance.\n \n @param task - The asynchronous work unit to run.\n * @param externalSignal - Optional external AbortSignal to propagate.\n /\n constructor(task: ITask<T>, externalSignal?: AbortSignal) {\n this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;\n this.task = task;\n this.externalSignal = externalSignal;\n this.abortController = new AbortController();\n\n this.promise = new Promise<T>((resolve, reject) => {\n this.resolvePromise = resolve;\n this.rejectPromise = reject;\n });\n\n if (this.externalSignal) {\n if (this.externalSignal.aborted) {\n this._state = ETaskState.CANCELLED;\n const reason = this.externalSignal.reason;\n const cancelError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancelError);\n } else {\n this.abortListener = () => {\n this.handleExternalAbort();\n };\n this.externalSignal.addEventListener(\"abort\", this.abortListener, { once: true });\n }\n }\n }\n\n /\n Gets the current lifecycle state of the task.\n /\n public get state(): ETaskState {\n return this._state;\n }\n\n /\n Resolves the deferred promise.\n \n @param value - Value to resolve with.\n /\n public resolve(value: T): void {\n this.resolvePromise(value);\n }\n\n /\n Rejects the deferred promise.\n \n @param reason - Reason to reject with.\n /\n public reject(reason: unknown): void {\n this.rejectPromise(reason);\n }\n\n /\n Executes the task within an allocated concurrency slot.\n \n @returns A promise resolving to the task result or rejecting on failure/cancellation.\n /\n public async run(): Promise<T> {\n if (this._state === ETaskState.CANCELLED) {\n throw new AhkoCancellationError(\"Task was cancelled prior to execution\");\n }\n\n this._state = ETaskState.RUNNING;\n\n const context: ITaskContext = {\n signal: this.abortController.signal,\n taskId: this.taskId,\n };\n\n try {\n const result = await this.task(context);\n this._state = ETaskState.COMPLETED;\n this.cleanup();\n return result;\n } catch (error) {\n this.cleanup();\n\n const isCancelled =\n (this._state as ETaskState) === ETaskState.CANCELLED \|\|\n this.abortController.signal.aborted;\n\n if (isCancelled) {\n this._state = ETaskState.CANCELLED;\n throw new AhkoCancellationError(\"Task was cancelled during execution\", {\n cause: error instanceof Error ? error : undefined,\n });\n }\n\n this._state = ETaskState.FAILED;\n throw error;\n }\n }\n\n /\n Cancels the task, aborting pending or running execution.\n \n @param reason - Optional cancellation reason.\n /\n public cancel(reason?: unknown): void {\n if (\n this._state === ETaskState.COMPLETED \|\|\n this._state === ETaskState.FAILED \|\|\n this._state === ETaskState.CANCELLED \|\|\n this._state === ETaskState.TIMED_OUT\n ) {\n return;\n }\n\n const wasPending = this._state === ETaskState.PENDING;\n this._state = ETaskState.CANCELLED;\n this.abortController.abort(reason);\n this.cleanup();\n\n if (wasPending) {\n const cancellationError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancellationError);\n this.onCancel?.(this);\n }\n }\n\n /\n Handles external AbortSignal trigger.\n /\n private handleExternalAbort(): void {\n this.cancel(this.externalSignal?.reason);\n }\n\n /\n Detaches event listeners from external signal to guarantee memory safety.\n /\n public cleanup(): void {\n if (this.externalSignal && this.abortListener) {\n this.externalSignal.removeEventListener(\"abort\", this.abortListener);\n }\n }\n}\n","import { AhkoConfigurationError } from \"./errors/configuration.error.js\";\nimport type { IAhkoOptions, IScheduleOptions } from \"./models/options.model.js\";\nimport type { IAhkoStats } from \"./models/stats.model.js\";\nimport type { ITask } from \"./models/task.model.js\";\nimport { TaskQueue } from \"./scheduler/task-queue.js\";\nimport { TaskRunner } from \"./scheduler/task-runner.js\";\n\n/\n Ahko — Low-energy, production-grade asynchronous task scheduler.\n \n Coordinates execution timing, enforces concurrency limits, and cooperates\n * natively with AbortSignal cancellation.\n \n @example\n * ```typescript\n * import { Ahko } from \"@mrjacket/ahko\";\n \n const ahko = new Ahko({ concurrency: 2 });\n \n const result = await ahko.schedule(async ({ signal, taskId }) => {\n * const res = await fetch(\"https://api.example.com\", { signal });\n * return res.json();\n * });\n * ```\n /\nexport class Ahko {\n /* Internal queue and concurrency manager /\n private readonly queue: TaskQueue;\n\n /\n Initializes a new Ahko scheduler instance.\n \n @param options - Optional scheduler configuration.\n * @throws {AhkoConfigurationError} If concurrency is invalid (less than 1 or NaN).\n \n @example\n * ```typescript\n * const ahko = new Ahko({ concurrency: 4 });\n * ```\n /\n constructor(options?: IAhkoOptions) {\n this.queue = new TaskQueue(options?.concurrency);\n }\n\n /\n Schedules a task for execution with full return type inference.\n \n @template T - Inferred return type of the task.\n * @param task - Asynchronous or synchronous task function accepting an {@link ITaskContext}.\n * @param options - Task-specific scheduling options such as strategy, delay, and cancellation signal.\n * @returns A promise that resolves with the task's return value.\n \n @throws {AhkoConfigurationError} If the task is not a function or options are invalid.\n * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.\n \n @example\n * ```typescript\n * // Immediate execution (subject to concurrency)\n * const count = await ahko.schedule(async () => 42);\n \n // Delayed execution\n * await ahko.schedule(\n * async ({ signal }) => doWork({ signal }),\n * { strategy: \"delay\", delay: 1000 }\n * );\n * ```\n /\n public schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T> {\n if (typeof task !== \"function\") {\n throw new AhkoConfigurationError(\"Task must be a valid function.\");\n }\n\n const runner = new TaskRunner<T>(task, options?.signal);\n return this.queue.enqueue(runner, options);\n }\n\n /\n Retrieves real-time telemetry metrics from the scheduler.\n \n @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.\n \n @example\n * ```typescript\n * const stats = ahko.stats();\n * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);\n * ```\n /\n public stats(): IAhkoStats {\n return this.queue.getStats();\n }\n}\n","/\n Current version of @mrjacket/ahko package.\n /\nexport const VERSION = \"0.1.0\";\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when an internal queue invariant is violated or queue limits are breached.\n /\nexport class AhkoQueueError extends AhkoError {\n /\n Creates a new AhkoQueueError.\n \n @param message - Explanation of the queue failure.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoQueueError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task exceeds its allotted timeout duration.\n /\nexport class AhkoTimeoutError extends AhkoError {\n /\n Creates a new AhkoTimeoutError.\n \n @param message - Explanation of timeout expiry.\n * @param options - Standard Error options including cause.\n */\n constructor(message = \"Task execution timed out\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoTimeoutError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n"],"mappings":";AAGO,IAAM,YAAN,cAAwB,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOnC,YAAY,SAAiB,SAAwB;AACnD,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;;;ACVO,IAAM,yBAAN,cAAqC,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOpD,YAAY,SAAiB,SAAwB;AACnD,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;;;ACdO,IAAK,aAAL,kBAAKA,gBAAL;AAEL,EAAAA,YAAA,aAAU;AAEV,EAAAA,YAAA,aAAU;AAEV,EAAAA,YAAA,eAAY;AAEZ,EAAAA,YAAA,YAAS;AAET,EAAAA,YAAA,eAAY;AAEZ,EAAAA,YAAA,eAAY;AAZF,SAAAA;AAAA,GAAA;;;ACAL,IAAK,oBAAL,kBAAKC,uBAAL;AAEL,EAAAA,mBAAA,eAAY;AAEZ,EAAAA,mBAAA,WAAQ;AAJE,SAAAA;AAAA,GAAA;;;ACgBL,IAAM,YAAN,MAAgB;AAAA;AAAA,EAEL;AAAA;AAAA,EAGC,QAA+B,CAAC;AAAA;AAAA,EAGhC,gBAAgB,oBAAI,IAAyB;AAAA;AAAA,EAG7C,iBAAiB,oBAAI,IAAmB;AAAA;AAAA,EAGjD,iBAAiB;AAAA;AAAA,EAGjB,cAAc;AAAA;AAAA,EAGd,iBAAiB;AAAA;AAAA,EAGjB,gBAAgB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQxB,YAAY,cAAc,UAAU;AAClC,QAAI,OAAO,MAAM,WAAW,KAAK,cAAc,GAAG;AAChD,YAAM,IAAI;AAAA,QACR,wBAAwB,WAAW;AAAA,MACrC;AAAA,IACF;AACA,SAAK,cAAc;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWO,QAAW,QAAuB,SAAwC;AAC/E,UAAM,WAAW,SAAS;AAE1B,QAAI,4CAA4C,kCAAsC;AACpF,YAAM,IAAI;AAAA,QACR,kCAAkC,OAAO,QAAQ,CAAC;AAAA,MACpD;AAAA,IACF;AAEA,QAAI,OAAO,uCAAgC;AACzC,WAAK;AACL,aAAO,OAAO;AAAA,IAChB;AAEA,QAAI,kCAAsC;AACxC,YAAM,UAAU,SAAS,SAAS;AAClC,UAAI,OAAO,YAAY,YAAY,OAAO,MAAM,OAAO,KAAK,UAAU,GAAG;AACvE,cAAM,IAAI;AAAA,UACR,kBAAkB,OAAO;AAAA,QAC3B;AAAA,MACF;AAEA,WAAK,gBAAgB,QAA+B,OAAO;AAC3D,aAAO,OAAO;AAAA,IAChB;AAGA,WAAO,WAAW,MAAM;AACtB,YAAM,QAAQ,KAAK,MAAM,QAAQ,MAA6B;AAC9D,UAAI,UAAU,IAAI;AAChB,aAAK,MAAM,OAAO,OAAO,CAAC;AAC1B,aAAK;AAAA,MACP;AAAA,IACF;AAGA,SAAK,MAAM,KAAK,MAA6B;AAC7C,SAAK,KAAK;AAEV,WAAO,OAAO;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMQ,gBAAgB,QAA6B,SAAuB;AAC1E,UAAM,eAA8B;AAAA,MAClC;AAAA,MACA,SAAS,WAAW,MAAM;AACxB,aAAK,eAAe,OAAO,YAAY;AACvC,YAAI,OAAO,uCAAgC;AACzC;AAAA,QACF;AAEA,eAAO,WAAW,MAAM;AACtB,gBAAM,QAAQ,KAAK,MAAM,QAAQ,MAAM;AACvC,cAAI,UAAU,IAAI;AAChB,iBAAK,MAAM,OAAO,OAAO,CAAC;AAC1B,iBAAK;AAAA,UACP;AAAA,QACF;AAEA,aAAK,MAAM,KAAK,MAAM;AACtB,aAAK,KAAK;AAAA,MACZ,GAAG,OAAO;AAAA,IACZ;AAEA,SAAK,eAAe,IAAI,YAAY;AAEpC,WAAO,WAAW,MAAM;AACtB,UAAI,KAAK,eAAe,IAAI,YAAY,GAAG;AACzC,qBAAa,aAAa,OAAO;AACjC,aAAK,eAAe,OAAO,YAAY;AACvC,aAAK;AAAA,MACP;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMQ,OAAa;AACnB,WAAO,KAAK,cAAc,OAAO,KAAK,eAAe,KAAK,MAAM,SAAS,GAAG;AAC1E,YAAM,SAAS,KAAK,MAAM,MAAM;AAChC,UAAI,CAAC,QAAQ;AACX;AAAA,MACF;AAEA,UAAI,OAAO,uCAAgC;AACzC;AAAA,MACF;AAEA,WAAK,cAAc,IAAI,MAAM;AAG7B,WAAK,KAAK,cAAc,MAAM;AAAA,IAChC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAc,cAAc,QAA4C;AACtE,QAAI;AACF,YAAM,SAAS,MAAM,OAAO,IAAI;AAChC,WAAK;AACL,WAAK,cAAc,OAAO,MAAM;AAChC,aAAO,QAAQ,MAAM;AAAA,IACvB,SAAS,OAAO;AACd,UAAI,OAAO,uCAAgC;AACzC,aAAK;AAAA,MACP,WAAW,OAAO,uCAAgC;AAChD,aAAK;AAAA,MACP,OAAO;AACL,aAAK;AAAA,MACP;AACA,WAAK,cAAc,OAAO,MAAM;AAChC,aAAO,OAAO,KAAK;AAAA,IACrB,UAAE;AACA,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,WAAuB;AAC5B,WAAO,OAAO,OAAO;AAAA,MACnB,aAAa,KAAK,cAAc;AAAA,MAChC,cAAc,KAAK,MAAM,SAAS,KAAK,eAAe;AAAA,MACtD,gBAAgB,KAAK;AAAA,MACrB,aAAa,KAAK;AAAA,MAClB,gBAAgB,KAAK;AAAA,MACrB,eAAe,KAAK;AAAA,MACpB,UAAU,KAAK;AAAA,IACjB,CAAC;AAAA,EACH;AACF;;;AC7MO,IAAM,wBAAN,cAAoC,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOnD,YAAY,UAAU,sBAAsB,SAAwB;AAClE,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;;;ACZA,IAAI,gBAAgB;AAQb,IAAM,aAAN,MAAoB;AAAA;AAAA,EAET;AAAA;AAAA,EAGR;AAAA;AAAA,EAGS;AAAA;AAAA,EAGA;AAAA;AAAA,EAGA;AAAA;AAAA,EAGA;AAAA;AAAA,EAGT;AAAA;AAAA,EAGA;AAAA;AAAA,EAGQ;AAAA;AAAA,EAGT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQP,YAAY,MAAgB,gBAA8B;AACxD,SAAK,SAAS,QAAQ,KAAK,IAAI,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,eAAe,SAAS,EAAE,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AACzH,SAAK,OAAO;AACZ,SAAK,iBAAiB;AACtB,SAAK,kBAAkB,IAAI,gBAAgB;AAE3C,SAAK,UAAU,IAAI,QAAW,CAAC,SAAS,WAAW;AACjD,WAAK,iBAAiB;AACtB,WAAK,gBAAgB;AAAA,IACvB,CAAC;AAED,QAAI,KAAK,gBAAgB;AACvB,UAAI,KAAK,eAAe,SAAS;AAC/B,aAAK;AACL,cAAM,SAAS,KAAK,eAAe;AACnC,cAAM,cAAc,IAAI;AAAA,UACtB,OAAO,WAAW,WAAW,SAAS;AAAA,UACtC,EAAE,OAAO,kBAAkB,QAAQ,SAAS,OAAU;AAAA,QACxD;AACA,aAAK,cAAc,WAAW;AAAA,MAChC,OAAO;AACL,aAAK,gBAAgB,MAAM;AACzB,eAAK,oBAAoB;AAAA,QAC3B;AACA,aAAK,eAAe,iBAAiB,SAAS,KAAK,eAAe,EAAE,MAAM,KAAK,CAAC;AAAA,MAClF;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,IAAW,QAAoB;AAC7B,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,QAAQ,OAAgB;AAC7B,SAAK,eAAe,KAAK;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,OAAO,QAAuB;AACnC,SAAK,cAAc,MAAM;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAa,MAAkB;AAC7B,QAAI,KAAK,wCAAiC;AACxC,YAAM,IAAI,sBAAsB,uCAAuC;AAAA,IACzE;AAEA,SAAK;AAEL,UAAM,UAAwB;AAAA,MAC5B,QAAQ,KAAK,gBAAgB;AAAA,MAC7B,QAAQ,KAAK;AAAA,IACf;AAEA,QAAI;AACF,YAAM,SAAS,MAAM,KAAK,KAAK,OAAO;AACtC,WAAK;AACL,WAAK,QAAQ;AACb,aAAO;AAAA,IACT,SAAS,OAAO;AACd,WAAK,QAAQ;AAEb,YAAM,cACH,KAAK,0CACN,KAAK,gBAAgB,OAAO;AAE9B,UAAI,aAAa;AACf,aAAK;AACL,cAAM,IAAI,sBAAsB,uCAAuC;AAAA,UACrE,OAAO,iBAAiB,QAAQ,QAAQ;AAAA,QAC1C,CAAC;AAAA,MACH;AAEA,WAAK;AACL,YAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,OAAO,QAAwB;AACpC,QACE,KAAK,0CACL,KAAK,oCACL,KAAK,0CACL,KAAK,wCACL;AACA;AAAA,IACF;AAEA,UAAM,aAAa,KAAK;AACxB,SAAK;AACL,SAAK,gBAAgB,MAAM,MAAM;AACjC,SAAK,QAAQ;AAEb,QAAI,YAAY;AACd,YAAM,oBAAoB,IAAI;AAAA,QAC5B,OAAO,WAAW,WAAW,SAAS;AAAA,QACtC,EAAE,OAAO,kBAAkB,QAAQ,SAAS,OAAU;AAAA,MACxD;AACA,WAAK,cAAc,iBAAiB;AACpC,WAAK,WAAW,IAAI;AAAA,IACtB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,sBAA4B;AAClC,SAAK,OAAO,KAAK,gBAAgB,MAAM;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA,EAKO,UAAgB;AACrB,QAAI,KAAK,kBAAkB,KAAK,eAAe;AAC7C,WAAK,eAAe,oBAAoB,SAAS,KAAK,aAAa;AAAA,IACrE;AAAA,EACF;AACF;;;ACrKO,IAAM,OAAN,MAAW;AAAA;AAAA,EAEC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAajB,YAAY,SAAwB;AAClC,SAAK,QAAQ,IAAI,UAAU,SAAS,WAAW;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAyBO,SAAY,MAAgB,SAAwC;AACzE,QAAI,OAAO,SAAS,YAAY;AAC9B,YAAM,IAAI,uBAAuB,gCAAgC;AAAA,IACnE;AAEA,UAAM,SAAS,IAAI,WAAc,MAAM,SAAS,MAAM;AACtD,WAAO,KAAK,MAAM,QAAQ,QAAQ,OAAO;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaO,QAAoB;AACzB,WAAO,KAAK,MAAM,SAAS;AAAA,EAC7B;AACF;;;ACvFO,IAAM,UAAU;;;ACEhB,IAAM,iBAAN,cAA6B,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO5C,YAAY,SAAiB,SAAwB;AACnD,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;;;ACZO,IAAM,mBAAN,cAA+B,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO9C,YAAY,UAAU,4BAA4B,SAAwB;AACxE,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;","names":["ETaskState","EScheduleStrategy"]}
1	+ {"version":3,"sources":["../src/errors/ahko.error.ts","../src/errors/configuration.error.ts","../src/models/strategy.model.ts","../src/models/state.model.ts","../src/scheduler/idle-scheduler.ts","../src/scheduler/task-queue.ts","../src/errors/cancellation.error.ts","../src/scheduler/task-runner.ts","../src/ahko.ts","../src/version.ts","../src/errors/queue.error.ts","../src/errors/timeout.error.ts"],"sourcesContent":["/*\n Base error class for all errors originating from the Ahko scheduler.\n /\nexport class AhkoError extends Error {\n /\n Creates a new AhkoError instance.\n \n @param message - Descriptive error message.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when invalid configuration or scheduling options are provided.\n /\nexport class AhkoConfigurationError extends AhkoError {\n /\n Creates a new AhkoConfigurationError.\n \n @param message - Explanation of the invalid configuration parameter.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoConfigurationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","/\n Fundamental scheduling strategies supported by the Ahko scheduler.\n /\nexport enum EScheduleStrategy {\n /* Execute as soon as a concurrency slot is available /\n IMMEDIATE = \"immediate\",\n /* Delay execution for a designated duration before queuing /\n DELAY = \"delay\",\n /* Execute during platform idle opportunities (requestIdleCallback in browser, setImmediate in Node.js) /\n IDLE = \"idle\",\n}\n\n/\n Union type representing valid scheduling strategy identifiers.\n /\nexport type TScheduleStrategy = EScheduleStrategy \| \"immediate\" \| \"delay\" \| \"idle\";\n","/\n Represents the discrete lifecycle states of an Ahko task.\n /\nexport enum ETaskState {\n /* Task has been scheduled and is awaiting execution in queue or timer /\n PENDING = \"pending\",\n /* Task is currently executing within an allocated concurrency slot /\n RUNNING = \"running\",\n /* Task successfully finished execution /\n COMPLETED = \"completed\",\n /* Task execution threw an error or rejected /\n FAILED = \"failed\",\n /* Task was cancelled via AbortSignal before or during execution /\n CANCELLED = \"cancelled\",\n /* Task was terminated because its execution exceeded the timeout /\n TIMED_OUT = \"timed_out\",\n}\n","/\n Handle returned by the IdleScheduler allowing cancellation of an idle request.\n /\nexport interface IIdleHandle {\n /\n Cancels the scheduled idle callback and cleans up platform resources.\n /\n cancel(): void;\n}\n\n/\n Platform-agnostic scheduler for opportunistic idle task execution.\n \n Automatically detects and selects platform capabilities:\n * 1. Browser: `requestIdleCallback` / `cancelIdleCallback` (with optional timeout)\n * 2. Node.js: `setImmediate` / `clearImmediate` as low-priority primitive\n * 3. Fallback: `setTimeout(..., 0)` / `clearTimeout`\n /\nexport class IdleScheduler {\n /\n Schedules a callback to execute during the next idle opportunity.\n \n @param callback - Function to invoke when idle opportunity arises.\n * @param timeout - Optional max deadline in milliseconds to wait before invoking (browser only).\n * @param runtime - Target runtime scope providing scheduling primitives (defaults to globalThis).\n * @returns An {@link IIdleHandle} with a `cancel()` method for cleanup.\n /\n public static schedule(\n callback: () => void,\n timeout?: number,\n runtime: typeof globalThis = globalThis\n ): IIdleHandle {\n // 1. Browser requestIdleCallback\n if (\n typeof (runtime as Record<string, unknown>).requestIdleCallback === \"function\" &&\n typeof (runtime as Record<string, unknown>).cancelIdleCallback === \"function\"\n ) {\n const requestFn = (runtime as Record<string, unknown>).requestIdleCallback as (\n cb: (deadline?: unknown) => void,\n opts?: { timeout?: number }\n ) => number;\n\n const cancelFn = (runtime as Record<string, unknown>).cancelIdleCallback as (\n handle: number\n ) => void;\n\n const id = requestFn(\n () => callback(),\n typeof timeout === \"number\" && !Number.isNaN(timeout) && timeout >= 0\n ? { timeout }\n : undefined\n );\n\n return {\n cancel: () => cancelFn(id),\n };\n }\n\n // 2. Node.js setImmediate\n if (\n typeof (runtime as Record<string, unknown>).setImmediate === \"function\" &&\n typeof (runtime as Record<string, unknown>).clearImmediate === \"function\"\n ) {\n const setImmFn = (runtime as Record<string, unknown>).setImmediate as (\n cb: () => void\n ) => ReturnType<typeof setImmediate>;\n\n const clearImmFn = (runtime as Record<string, unknown>).clearImmediate as (\n handle: ReturnType<typeof setImmediate>\n ) => void;\n\n const handle = setImmFn(() => callback());\n\n return {\n cancel: () => clearImmFn(handle),\n };\n }\n\n // 3. Universal fallback setTimeout(0)\n const setTimerFn = runtime.setTimeout.bind(runtime);\n const clearTimerFn = runtime.clearTimeout.bind(runtime);\n\n const timerId = setTimerFn(() => callback(), 0);\n\n return {\n cancel: () => clearTimerFn(timerId),\n };\n }\n}\n","import { AhkoConfigurationError } from \"../errors/configuration.error.js\";\nimport type { IScheduleOptions } from \"../models/options.model.js\";\nimport type { IAhkoStats } from \"../models/stats.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport { EScheduleStrategy } from \"../models/strategy.model.js\";\nimport { IdleScheduler, type IIdleHandle } from \"./idle-scheduler.js\";\nimport { TaskRunner } from \"./task-runner.js\";\n\n/\n Entry tracking delayed task timers for deterministic cancellation and memory cleanup.\n /\ninterface IDelayedEntry {\n runner: TaskRunner<unknown>;\n timerId: ReturnType<typeof setTimeout>;\n}\n\n/\n Entry tracking idle callback handles for deterministic cancellation and cleanup.\n /\ninterface IIdleEntry {\n runner: TaskRunner<unknown>;\n handle: IIdleHandle;\n}\n\n/\n Memory-safe FIFO task queue managing concurrency allocation,\n * delayed scheduling, and task lifecycle counters.\n /\nexport class TaskQueue {\n /* Maximum concurrent active tasks /\n public readonly concurrency: number;\n\n /* Queue of pending task runners waiting for a concurrency slot /\n private readonly queue: TaskRunner<unknown>[] = [];\n\n /* Set of task runners currently executing /\n private readonly activeRunners = new Set<TaskRunner<unknown>>();\n\n /* Set of tasks currently in delay phase /\n private readonly delayedEntries = new Set<IDelayedEntry>();\n\n /* Set of tasks currently awaiting an idle opportunity /\n private readonly idleEntries = new Set<IIdleEntry>();\n\n /* Cumulative completed tasks counter /\n private completedTasks = 0;\n\n /* Cumulative failed tasks counter /\n private failedTasks = 0;\n\n /* Cumulative cancelled tasks counter /\n private cancelledTasks = 0;\n\n /* Cumulative timed out tasks counter /\n private timedOutTasks = 0;\n\n /\n Creates a new TaskQueue.\n \n @param concurrency - Maximum concurrent tasks (defaults to Infinity).\n * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.\n /\n constructor(concurrency = Infinity) {\n if (Number.isNaN(concurrency) \|\| concurrency < 1) {\n throw new AhkoConfigurationError(\n `Invalid concurrency \"${concurrency}\". Must be a number greater than or equal to 1.`\n );\n }\n this.concurrency = concurrency;\n }\n\n /\n Enqueues a task runner according to the specified schedule options.\n \n @template T - The return type produced by the task.\n * @param runner - The task runner instance.\n * @param options - Scheduling options.\n * @returns The deferred promise associated with the task runner.\n * @throws {AhkoConfigurationError} If scheduling options are invalid.\n /\n public enqueue<T>(runner: TaskRunner<T>, options?: IScheduleOptions): Promise<T> {\n const strategy = options?.strategy ?? EScheduleStrategy.IMMEDIATE;\n\n if (\n strategy !== EScheduleStrategy.IMMEDIATE &&\n strategy !== EScheduleStrategy.DELAY &&\n strategy !== EScheduleStrategy.IDLE\n ) {\n throw new AhkoConfigurationError(\n `Unsupported schedule strategy \"${String(strategy)}\". Supported strategies: \"immediate\", \"delay\", \"idle\".`\n );\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n return runner.promise;\n }\n\n if (strategy === EScheduleStrategy.DELAY) {\n const delayMs = options?.delay ?? 0;\n if (typeof delayMs !== \"number\" \|\| Number.isNaN(delayMs) \|\| delayMs < 0) {\n throw new AhkoConfigurationError(\n `Invalid delay \"${delayMs}\". Delay must be a non-negative number in milliseconds.`\n );\n }\n\n this.scheduleDelayed(runner as TaskRunner<unknown>, delayMs);\n return runner.promise;\n }\n\n if (strategy === EScheduleStrategy.IDLE) {\n if (\n options?.idleTimeout !== undefined &&\n (typeof options.idleTimeout !== \"number\" \|\|\n Number.isNaN(options.idleTimeout) \|\|\n options.idleTimeout < 0)\n ) {\n throw new AhkoConfigurationError(\n `Invalid idleTimeout \"${options.idleTimeout}\". idleTimeout must be a non-negative number in milliseconds.`\n );\n }\n\n this.scheduleIdle(runner as TaskRunner<unknown>, options?.idleTimeout);\n return runner.promise;\n }\n\n // Attach immediate onCancel handler to dequeue without consuming concurrency\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner as TaskRunner<unknown>);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n // Immediate strategy: add to pending queue and pump\n this.queue.push(runner as TaskRunner<unknown>);\n this.pump();\n\n return runner.promise;\n }\n\n /\n Schedules a task to be placed into the queue after a delay,\n * handling early cancellation safely.\n /\n private scheduleDelayed(runner: TaskRunner<unknown>, delayMs: number): void {\n const delayedEntry: IDelayedEntry = {\n runner,\n timerId: setTimeout(() => {\n this.delayedEntries.delete(delayedEntry);\n if (runner.state === ETaskState.CANCELLED) {\n return;\n }\n\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n this.queue.push(runner);\n this.pump();\n }, delayMs),\n };\n\n this.delayedEntries.add(delayedEntry);\n\n runner.onCancel = () => {\n if (this.delayedEntries.has(delayedEntry)) {\n clearTimeout(delayedEntry.timerId);\n this.delayedEntries.delete(delayedEntry);\n this.cancelledTasks++;\n }\n };\n }\n\n /\n Schedules a task to be placed into the queue during an idle opportunity,\n * handling early cancellation safely.\n /\n private scheduleIdle(runner: TaskRunner<unknown>, idleTimeout?: number): void {\n let idleEntry!: IIdleEntry;\n\n const handle = IdleScheduler.schedule(() => {\n this.idleEntries.delete(idleEntry);\n if (runner.state === ETaskState.CANCELLED) {\n return;\n }\n\n runner.onCancel = () => {\n const index = this.queue.indexOf(runner);\n if (index !== -1) {\n this.queue.splice(index, 1);\n this.cancelledTasks++;\n }\n };\n\n this.queue.push(runner);\n this.pump();\n }, idleTimeout);\n\n idleEntry = { runner, handle };\n this.idleEntries.add(idleEntry);\n\n runner.onCancel = () => {\n if (this.idleEntries.has(idleEntry)) {\n handle.cancel();\n this.idleEntries.delete(idleEntry);\n this.cancelledTasks++;\n }\n };\n }\n\n /\n Pumps the queue by picking pending tasks and executing them\n * as long as concurrency capacity is available.\n /\n private pump(): void {\n while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {\n const runner = this.queue.shift();\n if (!runner) {\n break;\n }\n\n if (runner.state === ETaskState.CANCELLED) {\n continue;\n }\n\n this.activeRunners.add(runner);\n\n // Execute runner without unhandled rejection risk\n void this.executeRunner(runner);\n }\n }\n\n /\n Internal execution of an active task runner.\n * Settle caller promise strictly after stats and active status are updated.\n /\n private async executeRunner(runner: TaskRunner<unknown>): Promise<void> {\n try {\n const result = await runner.run();\n this.completedTasks++;\n this.activeRunners.delete(runner);\n runner.resolve(result);\n } catch (error) {\n if (runner.state === ETaskState.CANCELLED) {\n this.cancelledTasks++;\n } else if (runner.state === ETaskState.TIMED_OUT) {\n this.timedOutTasks++;\n } else {\n this.failedTasks++;\n }\n this.activeRunners.delete(runner);\n runner.reject(error);\n } finally {\n this.pump();\n }\n }\n\n /\n Returns telemetry snapshot for the scheduler.\n \n @returns Frozen snapshot of current task metrics.\n /\n public getStats(): IAhkoStats {\n return Object.freeze({\n activeTasks: this.activeRunners.size,\n pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size,\n completedTasks: this.completedTasks,\n failedTasks: this.failedTasks,\n cancelledTasks: this.cancelledTasks,\n timedOutTasks: this.timedOutTasks,\n capacity: this.concurrency,\n });\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task is cancelled before or during execution.\n /\nexport class AhkoCancellationError extends AhkoError {\n /\n Creates a new AhkoCancellationError.\n \n @param message - Reason for cancellation.\n * @param options - Standard Error options including cause.\n /\n constructor(message = \"Task was cancelled\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoCancellationError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoCancellationError } from \"../errors/cancellation.error.js\";\nimport type { ITaskContext } from \"../models/context.model.js\";\nimport { ETaskState } from \"../models/state.model.js\";\nimport type { ITask } from \"../models/task.model.js\";\n\nlet taskIdCounter = 0;\n\n/\n Internal task lifecycle manager responsible for execution, state transitions,\n * AbortSignal coordination, and deterministic resource cleanup.\n \n @template T - The return type produced by the underlying task.\n /\nexport class TaskRunner<T> {\n /* Unique task identifier /\n public readonly taskId: string;\n\n /* Current lifecycle state /\n private _state: ETaskState = ETaskState.PENDING;\n\n /* Internal AbortController whose signal is passed to the task context /\n private readonly abortController: AbortController;\n\n /* The user task function to execute /\n private readonly task: ITask<T>;\n\n /* User-supplied AbortSignal for external cancellation /\n private readonly externalSignal?: AbortSignal;\n\n /* Abort event listener reference for clean detachment /\n private readonly abortListener?: () => void;\n\n /* Promise resolve handler /\n private resolvePromise!: (value: T \| PromiseLike<T>) => void;\n\n /* Promise reject handler /\n private rejectPromise!: (reason?: unknown) => void;\n\n /* Deferred promise exposed to the caller /\n public readonly promise: Promise<T>;\n\n /* Callback invoked when runner is cancelled while pending /\n public onCancel?: (runner: TaskRunner<T>) => void;\n\n /\n Creates a new TaskRunner instance.\n \n @param task - The asynchronous work unit to run.\n * @param externalSignal - Optional external AbortSignal to propagate.\n /\n constructor(task: ITask<T>, externalSignal?: AbortSignal) {\n this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;\n this.task = task;\n this.externalSignal = externalSignal;\n this.abortController = new AbortController();\n\n this.promise = new Promise<T>((resolve, reject) => {\n this.resolvePromise = resolve;\n this.rejectPromise = reject;\n });\n\n if (this.externalSignal) {\n if (this.externalSignal.aborted) {\n this._state = ETaskState.CANCELLED;\n const reason = this.externalSignal.reason;\n const cancelError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancelError);\n } else {\n this.abortListener = () => {\n this.handleExternalAbort();\n };\n this.externalSignal.addEventListener(\"abort\", this.abortListener, { once: true });\n }\n }\n }\n\n /\n Gets the current lifecycle state of the task.\n /\n public get state(): ETaskState {\n return this._state;\n }\n\n /\n Resolves the deferred promise.\n \n @param value - Value to resolve with.\n /\n public resolve(value: T): void {\n this.resolvePromise(value);\n }\n\n /\n Rejects the deferred promise.\n \n @param reason - Reason to reject with.\n /\n public reject(reason: unknown): void {\n this.rejectPromise(reason);\n }\n\n /\n Executes the task within an allocated concurrency slot.\n \n @returns A promise resolving to the task result or rejecting on failure/cancellation.\n /\n public async run(): Promise<T> {\n if (this._state === ETaskState.CANCELLED) {\n throw new AhkoCancellationError(\"Task was cancelled prior to execution\");\n }\n\n this._state = ETaskState.RUNNING;\n\n const context: ITaskContext = {\n signal: this.abortController.signal,\n taskId: this.taskId,\n };\n\n try {\n const result = await this.task(context);\n this._state = ETaskState.COMPLETED;\n this.cleanup();\n return result;\n } catch (error) {\n this.cleanup();\n\n const isCancelled =\n (this._state as ETaskState) === ETaskState.CANCELLED \|\|\n this.abortController.signal.aborted;\n\n if (isCancelled) {\n this._state = ETaskState.CANCELLED;\n throw new AhkoCancellationError(\"Task was cancelled during execution\", {\n cause: error instanceof Error ? error : undefined,\n });\n }\n\n this._state = ETaskState.FAILED;\n throw error;\n }\n }\n\n /\n Cancels the task, aborting pending or running execution.\n \n @param reason - Optional cancellation reason.\n /\n public cancel(reason?: unknown): void {\n if (\n this._state === ETaskState.COMPLETED \|\|\n this._state === ETaskState.FAILED \|\|\n this._state === ETaskState.CANCELLED \|\|\n this._state === ETaskState.TIMED_OUT\n ) {\n return;\n }\n\n const wasPending = this._state === ETaskState.PENDING;\n this._state = ETaskState.CANCELLED;\n this.abortController.abort(reason);\n this.cleanup();\n\n if (wasPending) {\n const cancellationError = new AhkoCancellationError(\n typeof reason === \"string\" ? reason : \"Task was cancelled prior to execution\",\n { cause: reason instanceof Error ? reason : undefined }\n );\n this.rejectPromise(cancellationError);\n this.onCancel?.(this);\n }\n }\n\n /\n Handles external AbortSignal trigger.\n /\n private handleExternalAbort(): void {\n this.cancel(this.externalSignal?.reason);\n }\n\n /\n Detaches event listeners from external signal to guarantee memory safety.\n /\n public cleanup(): void {\n if (this.externalSignal && this.abortListener) {\n this.externalSignal.removeEventListener(\"abort\", this.abortListener);\n }\n }\n}\n","import { AhkoConfigurationError } from \"./errors/configuration.error.js\";\nimport type { IAhkoOptions, IScheduleOptions } from \"./models/options.model.js\";\nimport type { IAhkoStats } from \"./models/stats.model.js\";\nimport { EScheduleStrategy } from \"./models/strategy.model.js\";\nimport type { ITask } from \"./models/task.model.js\";\nimport { TaskQueue } from \"./scheduler/task-queue.js\";\nimport { TaskRunner } from \"./scheduler/task-runner.js\";\n\n/\n Ahko — Low-energy asynchronous task scheduler.\n \n Coordinates execution timing, enforces concurrency limits, and cooperates\n * natively with AbortSignal cancellation.\n \n @example\n * ```typescript\n * import { Ahko } from \"@mrjacket/ahko\";\n \n const ahko = new Ahko({ concurrency: 2 });\n \n const result = await ahko.schedule(async ({ signal, taskId }) => {\n * const res = await fetch(\"https://api.example.com\", { signal });\n * return res.json();\n * });\n * ```\n /\nexport class Ahko {\n /* Internal queue and concurrency manager /\n private readonly queue: TaskQueue;\n\n /\n Initializes a new Ahko scheduler instance.\n \n @param options - Optional scheduler configuration.\n * @throws {AhkoConfigurationError} If concurrency is invalid (less than 1 or NaN).\n \n @example\n * ```typescript\n * const ahko = new Ahko({ concurrency: 4 });\n * ```\n /\n constructor(options?: IAhkoOptions) {\n this.queue = new TaskQueue(options?.concurrency);\n }\n\n /\n Schedules a task for execution with full return type inference.\n \n @template T - Inferred return type of the task.\n * @param task - Asynchronous or synchronous task function accepting an {@link ITaskContext}.\n * @param options - Task-specific scheduling options such as strategy, delay, and cancellation signal.\n * @returns A promise that resolves with the task's return value.\n \n @throws {AhkoConfigurationError} If the task is not a function or options are invalid.\n * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.\n \n @example\n * ```typescript\n * // Immediate execution (subject to concurrency)\n * const count = await ahko.schedule(async () => 42);\n \n // Delayed execution\n * await ahko.schedule(\n * async ({ signal }) => doWork({ signal }),\n * { strategy: \"delay\", delay: 1000 }\n * );\n * ```\n /\n public schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T> {\n if (typeof task !== \"function\") {\n throw new AhkoConfigurationError(\"Task must be a valid function.\");\n }\n\n const runner = new TaskRunner<T>(task, options?.signal);\n return this.queue.enqueue(runner, options);\n }\n\n /\n Convenience method to schedule a task during platform idle opportunities.\n \n Equivalent to calling `schedule(task, { ...options, strategy: \"idle\" })`.\n * In browsers, uses `requestIdleCallback` when available.\n * In Node.js, uses `setImmediate`.\n * Falls back to `setTimeout(..., 0)` if neither is available.\n \n @template T - Inferred return type of the task.\n * @param task - Task function to run when idle.\n * @param options - Scheduling options (excluding strategy).\n * @returns A promise resolving to the task's return value.\n \n @throws {AhkoConfigurationError} If the task is not a function or options are invalid.\n * @throws {AhkoCancellationError} If the task is cancelled prior to or during execution.\n \n @example\n * ```typescript\n * const result = await ahko.idle(async ({ signal }) => {\n * return computeAnalytics();\n * });\n * ```\n /\n public idle<T>(\n task: ITask<T>,\n options?: Omit<IScheduleOptions, \"strategy\">\n ): Promise<T> {\n return this.schedule(task, {\n ...options,\n strategy: EScheduleStrategy.IDLE,\n });\n }\n\n /\n Retrieves real-time telemetry metrics from the scheduler.\n \n @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.\n \n @example\n * ```typescript\n * const stats = ahko.stats();\n * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);\n * ```\n /\n public stats(): IAhkoStats {\n return this.queue.getStats();\n }\n}\n","/\n Current version of @mrjacket/ahko package.\n /\nexport const VERSION = \"0.2.0\";\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when an internal queue invariant is violated or queue limits are breached.\n /\nexport class AhkoQueueError extends AhkoError {\n /\n Creates a new AhkoQueueError.\n \n @param message - Explanation of the queue failure.\n * @param options - Standard Error options including cause.\n /\n constructor(message: string, options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoQueueError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n","import { AhkoError } from \"./ahko.error.js\";\n\n/\n Thrown when a task exceeds its allotted timeout duration.\n /\nexport class AhkoTimeoutError extends AhkoError {\n /\n Creates a new AhkoTimeoutError.\n \n @param message - Explanation of timeout expiry.\n * @param options - Standard Error options including cause.\n */\n constructor(message = \"Task execution timed out\", options?: ErrorOptions) {\n super(message, options);\n this.name = \"AhkoTimeoutError\";\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n"],"mappings":"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","names":["EScheduleStrategy","ETaskState"]}

package/dist/models/options.model.d.ts CHANGED Viewed

@@ -13,6 +13,12 @@ export interface IScheduleOptions {
      * Applicable when strategy is "delay".
      */
     delay?: number;
+    /**
+     * Maximum time in milliseconds to wait for an idle opportunity before
+     * forcing execution into the queue. Applicable when strategy is "idle".
+     * Forwards to requestIdleCallback({ timeout }) when running in browser runtimes.
+     */
+    idleTimeout?: number;
     /**
      * External cancellation signal.
      * If aborted before start, the task is removed from the queue without execution.

package/dist/models/strategy.model.d.ts CHANGED Viewed

@@ -5,9 +5,11 @@ export declare enum EScheduleStrategy {
     /** Execute as soon as a concurrency slot is available */
     IMMEDIATE = "immediate",
     /** Delay execution for a designated duration before queuing */
-    DELAY = "delay"
+    DELAY = "delay",
+    /** Execute during platform idle opportunities (requestIdleCallback in browser, setImmediate in Node.js) */
+    IDLE = "idle"
 }
 /**
  * Union type representing valid scheduling strategy identifiers.
  */
-export type TScheduleStrategy = EScheduleStrategy | "immediate" | "delay";
+export type TScheduleStrategy = EScheduleStrategy | "immediate" | "delay" | "idle";

package/dist/scheduler/idle-scheduler.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * Handle returned by the IdleScheduler allowing cancellation of an idle request.
+ */
+export interface IIdleHandle {
+    /**
+     * Cancels the scheduled idle callback and cleans up platform resources.
+     */
+    cancel(): void;
+}
+/**
+ * Platform-agnostic scheduler for opportunistic idle task execution.
+ *
+ * Automatically detects and selects platform capabilities:
+ * 1. Browser: `requestIdleCallback` / `cancelIdleCallback` (with optional timeout)
+ * 2. Node.js: `setImmediate` / `clearImmediate` as low-priority primitive
+ * 3. Fallback: `setTimeout(..., 0)` / `clearTimeout`
+ */
+export declare class IdleScheduler {
+    /**
+     * Schedules a callback to execute during the next idle opportunity.
+     *
+     * @param callback - Function to invoke when idle opportunity arises.
+     * @param timeout - Optional max deadline in milliseconds to wait before invoking (browser only).
+     * @param runtime - Target runtime scope providing scheduling primitives (defaults to globalThis).
+     * @returns An {@link IIdleHandle} with a `cancel()` method for cleanup.
+     */
+    static schedule(callback: () => void, timeout?: number, runtime?: typeof globalThis): IIdleHandle;
+}

package/dist/scheduler/task-queue.d.ts CHANGED Viewed

@@ -14,6 +14,8 @@ export declare class TaskQueue {
     private readonly activeRunners;
     /** Set of tasks currently in delay phase */
     private readonly delayedEntries;
+    /** Set of tasks currently awaiting an idle opportunity */
+    private readonly idleEntries;
     /** Cumulative completed tasks counter */
     private completedTasks;
     /** Cumulative failed tasks counter */
@@ -44,6 +46,11 @@ export declare class TaskQueue {
      * handling early cancellation safely.
      */
     private scheduleDelayed;
+    /**
+     * Schedules a task to be placed into the queue during an idle opportunity,
+     * handling early cancellation safely.
+     */
+    private scheduleIdle;
     /**
      * Pumps the queue by picking pending tasks and executing them
      * as long as concurrency capacity is available.

package/dist/version.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
 /**
  * Current version of @mrjacket/ahko package.
  */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mrjacket/ahko",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A low-energy task scheduler for JavaScript and TypeScript. Let your code chill.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -54,9 +54,9 @@
     "async"
   ],
   "devDependencies": {
-    "@types/node": "^22.13.0",
+    "@types/node": "^26.6.2",
     "tsup": "^8.3.6",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
   }
 }