@mrjacket/ahko 0.1.0

package/dist/index.js

@@ -0,0 +1,482 @@
+// src/errors/ahko.error.ts
+var AhkoError = class extends Error {
+  /**
+   * Creates a new AhkoError instance.
+   *
+   * @param message - Descriptive error message.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AhkoError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/configuration.error.ts
+var AhkoConfigurationError = class extends AhkoError {
+  /**
+   * Creates a new AhkoConfigurationError.
+   *
+   * @param message - Explanation of the invalid configuration parameter.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AhkoConfigurationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/models/state.model.ts
+var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
+  ETaskState2["PENDING"] = "pending";
+  ETaskState2["RUNNING"] = "running";
+  ETaskState2["COMPLETED"] = "completed";
+  ETaskState2["FAILED"] = "failed";
+  ETaskState2["CANCELLED"] = "cancelled";
+  ETaskState2["TIMED_OUT"] = "timed_out";
+  return ETaskState2;
+})(ETaskState || {});
+
+// src/models/strategy.model.ts
+var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
+  EScheduleStrategy2["IMMEDIATE"] = "immediate";
+  EScheduleStrategy2["DELAY"] = "delay";
+  return EScheduleStrategy2;
+})(EScheduleStrategy || {});
+
+// src/scheduler/task-queue.ts
+var TaskQueue = class {
+  /** Maximum concurrent active tasks */
+  concurrency;
+  /** Queue of pending task runners waiting for a concurrency slot */
+  queue = [];
+  /** Set of task runners currently executing */
+  activeRunners = /* @__PURE__ */ new Set();
+  /** Set of tasks currently in delay phase */
+  delayedEntries = /* @__PURE__ */ new Set();
+  /** Cumulative completed tasks counter */
+  completedTasks = 0;
+  /** Cumulative failed tasks counter */
+  failedTasks = 0;
+  /** Cumulative cancelled tasks counter */
+  cancelledTasks = 0;
+  /** Cumulative timed out tasks counter */
+  timedOutTasks = 0;
+  /**
+   * Creates a new TaskQueue.
+   *
+   * @param concurrency - Maximum concurrent tasks (defaults to Infinity).
+   * @throws {AhkoConfigurationError} If concurrency is less than 1 or not a valid number.
+   */
+  constructor(concurrency = Infinity) {
+    if (Number.isNaN(concurrency) || concurrency < 1) {
+      throw new AhkoConfigurationError(
+        `Invalid concurrency "${concurrency}". Must be a number greater than or equal to 1.`
+      );
+    }
+    this.concurrency = concurrency;
+  }
+  /**
+   * Enqueues a task runner according to the specified schedule options.
+   *
+   * @template T - The return type produced by the task.
+   * @param runner - The task runner instance.
+   * @param options - Scheduling options.
+   * @returns The deferred promise associated with the task runner.
+   * @throws {AhkoConfigurationError} If scheduling options are invalid.
+   */
+  enqueue(runner, options) {
+    const strategy = options?.strategy ?? "immediate" /* IMMEDIATE */;
+    if (strategy !== "immediate" /* IMMEDIATE */ && strategy !== "delay" /* DELAY */) {
+      throw new AhkoConfigurationError(
+        `Unsupported schedule strategy "${String(strategy)}". Supported strategies in 0.1.0: "immediate", "delay".`
+      );
+    }
+    if (runner.state === "cancelled" /* CANCELLED */) {
+      this.cancelledTasks++;
+      return runner.promise;
+    }
+    if (strategy === "delay" /* DELAY */) {
+      const delayMs = options?.delay ?? 0;
+      if (typeof delayMs !== "number" || Number.isNaN(delayMs) || delayMs < 0) {
+        throw new AhkoConfigurationError(
+          `Invalid delay "${delayMs}". Delay must be a non-negative number in milliseconds.`
+        );
+      }
+      this.scheduleDelayed(runner, delayMs);
+      return runner.promise;
+    }
+    runner.onCancel = () => {
+      const index = this.queue.indexOf(runner);
+      if (index !== -1) {
+        this.queue.splice(index, 1);
+        this.cancelledTasks++;
+      }
+    };
+    this.queue.push(runner);
+    this.pump();
+    return runner.promise;
+  }
+  /**
+   * Schedules a task to be placed into the queue after a delay,
+   * handling early cancellation safely.
+   */
+  scheduleDelayed(runner, delayMs) {
+    const delayedEntry = {
+      runner,
+      timerId: setTimeout(() => {
+        this.delayedEntries.delete(delayedEntry);
+        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();
+      }, delayMs)
+    };
+    this.delayedEntries.add(delayedEntry);
+    runner.onCancel = () => {
+      if (this.delayedEntries.has(delayedEntry)) {
+        clearTimeout(delayedEntry.timerId);
+        this.delayedEntries.delete(delayedEntry);
+        this.cancelledTasks++;
+      }
+    };
+  }
+  /**
+   * Pumps the queue by picking pending tasks and executing them
+   * as long as concurrency capacity is available.
+   */
+  pump() {
+    while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {
+      const runner = this.queue.shift();
+      if (!runner) {
+        break;
+      }
+      if (runner.state === "cancelled" /* CANCELLED */) {
+        continue;
+      }
+      this.activeRunners.add(runner);
+      void this.executeRunner(runner);
+    }
+  }
+  /**
+   * Internal execution of an active task runner.
+   * Settle caller promise strictly after stats and active status are updated.
+   */
+  async executeRunner(runner) {
+    try {
+      const result = await runner.run();
+      this.completedTasks++;
+      this.activeRunners.delete(runner);
+      runner.resolve(result);
+    } catch (error) {
+      if (runner.state === "cancelled" /* CANCELLED */) {
+        this.cancelledTasks++;
+      } else if (runner.state === "timed_out" /* TIMED_OUT */) {
+        this.timedOutTasks++;
+      } else {
+        this.failedTasks++;
+      }
+      this.activeRunners.delete(runner);
+      runner.reject(error);
+    } finally {
+      this.pump();
+    }
+  }
+  /**
+   * Returns telemetry snapshot for the scheduler.
+   *
+   * @returns Frozen snapshot of current task metrics.
+   */
+  getStats() {
+    return Object.freeze({
+      activeTasks: this.activeRunners.size,
+      pendingTasks: this.queue.length + this.delayedEntries.size,
+      completedTasks: this.completedTasks,
+      failedTasks: this.failedTasks,
+      cancelledTasks: this.cancelledTasks,
+      timedOutTasks: this.timedOutTasks,
+      capacity: this.concurrency
+    });
+  }
+};
+
+// src/errors/cancellation.error.ts
+var AhkoCancellationError = class extends AhkoError {
+  /**
+   * Creates a new AhkoCancellationError.
+   *
+   * @param message - Reason for cancellation.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message = "Task was cancelled", options) {
+    super(message, options);
+    this.name = "AhkoCancellationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/scheduler/task-runner.ts
+var taskIdCounter = 0;
+var TaskRunner = class {
+  /** Unique task identifier */
+  taskId;
+  /** Current lifecycle state */
+  _state = "pending" /* PENDING */;
+  /** Internal AbortController whose signal is passed to the task context */
+  abortController;
+  /** The user task function to execute */
+  task;
+  /** User-supplied AbortSignal for external cancellation */
+  externalSignal;
+  /** Abort event listener reference for clean detachment */
+  abortListener;
+  /** Promise resolve handler */
+  resolvePromise;
+  /** Promise reject handler */
+  rejectPromise;
+  /** Deferred promise exposed to the caller */
+  promise;
+  /** Callback invoked when runner is cancelled while pending */
+  onCancel;
+  /**
+   * Creates a new TaskRunner instance.
+   *
+   * @param task - The asynchronous work unit to run.
+   * @param externalSignal - Optional external AbortSignal to propagate.
+   */
+  constructor(task, externalSignal) {
+    this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+    this.task = task;
+    this.externalSignal = externalSignal;
+    this.abortController = new AbortController();
+    this.promise = new Promise((resolve, reject) => {
+      this.resolvePromise = resolve;
+      this.rejectPromise = reject;
+    });
+    if (this.externalSignal) {
+      if (this.externalSignal.aborted) {
+        this._state = "cancelled" /* CANCELLED */;
+        const reason = this.externalSignal.reason;
+        const cancelError = new AhkoCancellationError(
+          typeof reason === "string" ? reason : "Task was cancelled prior to execution",
+          { cause: reason instanceof Error ? reason : void 0 }
+        );
+        this.rejectPromise(cancelError);
+      } else {
+        this.abortListener = () => {
+          this.handleExternalAbort();
+        };
+        this.externalSignal.addEventListener("abort", this.abortListener, { once: true });
+      }
+    }
+  }
+  /**
+   * Gets the current lifecycle state of the task.
+   */
+  get state() {
+    return this._state;
+  }
+  /**
+   * Resolves the deferred promise.
+   *
+   * @param value - Value to resolve with.
+   */
+  resolve(value) {
+    this.resolvePromise(value);
+  }
+  /**
+   * Rejects the deferred promise.
+   *
+   * @param reason - Reason to reject with.
+   */
+  reject(reason) {
+    this.rejectPromise(reason);
+  }
+  /**
+   * Executes the task within an allocated concurrency slot.
+   *
+   * @returns A promise resolving to the task result or rejecting on failure/cancellation.
+   */
+  async run() {
+    if (this._state === "cancelled" /* CANCELLED */) {
+      throw new AhkoCancellationError("Task was cancelled prior to execution");
+    }
+    this._state = "running" /* RUNNING */;
+    const context = {
+      signal: this.abortController.signal,
+      taskId: this.taskId
+    };
+    try {
+      const result = await this.task(context);
+      this._state = "completed" /* COMPLETED */;
+      this.cleanup();
+      return result;
+    } catch (error) {
+      this.cleanup();
+      const isCancelled = this._state === "cancelled" /* CANCELLED */ || this.abortController.signal.aborted;
+      if (isCancelled) {
+        this._state = "cancelled" /* CANCELLED */;
+        throw new AhkoCancellationError("Task was cancelled during execution", {
+          cause: error instanceof Error ? error : void 0
+        });
+      }
+      this._state = "failed" /* FAILED */;
+      throw error;
+    }
+  }
+  /**
+   * Cancels the task, aborting pending or running execution.
+   *
+   * @param reason - Optional cancellation reason.
+   */
+  cancel(reason) {
+    if (this._state === "completed" /* COMPLETED */ || this._state === "failed" /* FAILED */ || this._state === "cancelled" /* CANCELLED */ || this._state === "timed_out" /* TIMED_OUT */) {
+      return;
+    }
+    const wasPending = this._state === "pending" /* PENDING */;
+    this._state = "cancelled" /* CANCELLED */;
+    this.abortController.abort(reason);
+    this.cleanup();
+    if (wasPending) {
+      const cancellationError = new AhkoCancellationError(
+        typeof reason === "string" ? reason : "Task was cancelled prior to execution",
+        { cause: reason instanceof Error ? reason : void 0 }
+      );
+      this.rejectPromise(cancellationError);
+      this.onCancel?.(this);
+    }
+  }
+  /**
+   * Handles external AbortSignal trigger.
+   */
+  handleExternalAbort() {
+    this.cancel(this.externalSignal?.reason);
+  }
+  /**
+   * Detaches event listeners from external signal to guarantee memory safety.
+   */
+  cleanup() {
+    if (this.externalSignal && this.abortListener) {
+      this.externalSignal.removeEventListener("abort", this.abortListener);
+    }
+  }
+};
+
+// src/ahko.ts
+var Ahko = class {
+  /** Internal queue and concurrency manager */
+  queue;
+  /**
+   * Initializes a new Ahko scheduler instance.
+   *
+   * @param options - Optional scheduler configuration.
+   * @throws {AhkoConfigurationError} If concurrency is invalid (less than 1 or NaN).
+   *
+   * @example
+   * ```typescript
+   * const ahko = new Ahko({ concurrency: 4 });
+   * ```
+   */
+  constructor(options) {
+    this.queue = new TaskQueue(options?.concurrency);
+  }
+  /**
+   * Schedules a task for execution with full return type inference.
+   *
+   * @template T - Inferred return type of the task.
+   * @param task - Asynchronous or synchronous task function accepting an {@link ITaskContext}.
+   * @param options - Task-specific scheduling options such as strategy, delay, and cancellation signal.
+   * @returns A promise that resolves with 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
+   * // Immediate execution (subject to concurrency)
+   * const count = await ahko.schedule(async () => 42);
+   *
+   * // Delayed execution
+   * await ahko.schedule(
+   *   async ({ signal }) => doWork({ signal }),
+   *   { strategy: "delay", delay: 1000 }
+   * );
+   * ```
+   */
+  schedule(task, options) {
+    if (typeof task !== "function") {
+      throw new AhkoConfigurationError("Task must be a valid function.");
+    }
+    const runner = new TaskRunner(task, options?.signal);
+    return this.queue.enqueue(runner, options);
+  }
+  /**
+   * Retrieves real-time telemetry metrics from the scheduler.
+   *
+   * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.
+   *
+   * @example
+   * ```typescript
+   * const stats = ahko.stats();
+   * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);
+   * ```
+   */
+  stats() {
+    return this.queue.getStats();
+  }
+};
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/errors/queue.error.ts
+var AhkoQueueError = class extends AhkoError {
+  /**
+   * Creates a new AhkoQueueError.
+   *
+   * @param message - Explanation of the queue failure.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AhkoQueueError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/timeout.error.ts
+var AhkoTimeoutError = class extends AhkoError {
+  /**
+   * Creates a new AhkoTimeoutError.
+   *
+   * @param message - Explanation of timeout expiry.
+   * @param options - Standard Error options including cause.
+   */
+  constructor(message = "Task execution timed out", options) {
+    super(message, options);
+    this.name = "AhkoTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+export {
+  Ahko,
+  AhkoCancellationError,
+  AhkoConfigurationError,
+  AhkoError,
+  AhkoQueueError,
+  AhkoTimeoutError,
+  EScheduleStrategy,
+  ETaskState,
+  VERSION
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":"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","names":["ETaskState","EScheduleStrategy"]}

package/dist/models/context.model.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Execution context supplied to every scheduled Ahko task.
+ */
+export interface ITaskContext {
+    /**
+     * Cooperative cancellation signal for the task.
+     * Listeners should be attached to this signal to gracefully abort asynchronous operations.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Unique identifier assigned to the task by the scheduler.
+     */
+    readonly taskId: string;
+}

package/dist/models/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./context.model.js";
+export * from "./options.model.js";
+export * from "./state.model.js";
+export * from "./stats.model.js";
+export * from "./strategy.model.js";
+export * from "./task.model.js";

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

@@ -0,0 +1,33 @@
+import type { TScheduleStrategy } from "./strategy.model.js";
+/**
+ * Options to configure a specific scheduled task.
+ */
+export interface IScheduleOptions {
+    /**
+     * Scheduling strategy to use.
+     * @default "immediate"
+     */
+    strategy?: TScheduleStrategy;
+    /**
+     * Delay in milliseconds before queuing or executing the task.
+     * Applicable when strategy is "delay".
+     */
+    delay?: number;
+    /**
+     * External cancellation signal.
+     * If aborted before start, the task is removed from the queue without execution.
+     * If aborted while running, the abort event is propagated to the task context signal.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Global configuration options for the Ahko scheduler instance.
+ */
+export interface IAhkoOptions {
+    /**
+     * Maximum number of tasks allowed to execute concurrently.
+     * Must be an integer greater than or equal to 1, or Infinity.
+     * @default Infinity
+     */
+    concurrency?: number;
+}

package/dist/models/state.model.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents the discrete lifecycle states of an Ahko task.
+ */
+export declare enum ETaskState {
+    /** Task has been scheduled and is awaiting execution in queue or timer */
+    PENDING = "pending",
+    /** Task is currently executing within an allocated concurrency slot */
+    RUNNING = "running",
+    /** Task successfully finished execution */
+    COMPLETED = "completed",
+    /** Task execution threw an error or rejected */
+    FAILED = "failed",
+    /** Task was cancelled via AbortSignal before or during execution */
+    CANCELLED = "cancelled",
+    /** Task was terminated because its execution exceeded the timeout */
+    TIMED_OUT = "timed_out"
+}

package/dist/models/stats.model.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Telemetry snapshot of the Ahko scheduler.
+ */
+export interface IAhkoStats {
+    /** Number of tasks currently executing in a concurrency slot */
+    activeTasks: number;
+    /** Number of tasks waiting in queue or in delay phase */
+    pendingTasks: number;
+    /** Cumulative count of successfully completed tasks */
+    completedTasks: number;
+    /** Cumulative count of failed tasks */
+    failedTasks: number;
+    /** Cumulative count of cancelled tasks */
+    cancelledTasks: number;
+    /** Cumulative count of timed out tasks */
+    timedOutTasks: number;
+    /** Maximum concurrent execution capacity */
+    capacity: number;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Fundamental scheduling strategies supported by the Ahko scheduler.
+ */
+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"
+}
+/**
+ * Union type representing valid scheduling strategy identifiers.
+ */
+export type TScheduleStrategy = EScheduleStrategy | "immediate" | "delay";

package/dist/models/task.model.d.ts

@@ -0,0 +1,9 @@
+import type { ITaskContext } from "./context.model.js";
+/**
+ * Represents an asynchronous or synchronous unit of work managed by Ahko.
+ *
+ * @template T - The return type produced by the task.
+ * @param context - The execution context including cancellation signal and task ID.
+ * @returns The resolved value or a Promise resolving to the value.
+ */
+export type ITask<T> = (context: ITaskContext) => Promise<T> | T;

package/dist/scheduler/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./task-runner.js";
+export * from "./task-queue.js";