@mrjacket/ahko 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-09-22 — Timeout & Robust Cancellation
+
+### Added
+- Execution timeout control via `timeoutMs` in `IScheduleOptions`.
+- Rejection with `AhkoTimeoutError` containing exceeded `timeoutMs` threshold and descriptive message.
+- Immediate rejection and slot recovery for hanging, uncooperative tasks via `Promise.race`.
+- Active execution timeout isolation (queued waiting time and backoff delays do not consume execution timeout).
+- Fresh `timeoutMs` window allocation on retry attempts.
+- Unified signal coordination via `combineSignals` utility with deterministic listener detachment.
+- Strict configuration validation for `timeoutMs` (positive finite numbers).
+- Comprehensive unit test suite covering execution timeouts, cancellation precedence, uncooperative tasks, retries, and signal combination.
+
+---
+
 ## [0.3.0] - 2026-09-22 — Retry & Backoff
 
 ### Added

package/README.md

@@ -160,7 +160,26 @@ const taskPromise = ahko.schedule(
 controller.abort();
 ```
 
-### 6. Telemetry (`stats`)
+### 6. Execution Deadlines & Timeouts (`timeoutMs`)
+
+Enforce deadlines per attempt. If a task exceeds `timeoutMs`, its context signal is aborted and the task rejects with `AhkoTimeoutError`:
+
+```typescript
+try {
+  await ahko.schedule(
+    async ({ signal }) => {
+      return callLongRunningApi({ signal });
+    },
+    { timeoutMs: 3000 } // aborts and rejects if running longer than 3 seconds
+  );
+} catch (error) {
+  if (error instanceof AhkoTimeoutError) {
+    console.error(`Timed out after ${error.timeoutMs}ms`);
+  }
+}
+```
+
+### 7. Telemetry (`stats`)
 
 Inspect real-time scheduler state without synthetic metrics:
 
@@ -174,7 +193,7 @@ console.log(stats);
 //   completedTasks: 42,
 //   failedTasks: 1,
 //   cancelledTasks: 2,
-//   timedOutTasks: 0,
+//   timedOutTasks: 1,
 //   capacity: 3
 // }
 ```
@@ -214,6 +233,7 @@ Schedules an asynchronous task with full return type inference.
 | `delay` | `number` | `0` | Delay in milliseconds when strategy is `"delay"`. |
 | `idleTimeout` | `number` | `undefined` | Maximum time to wait for idle window before forcing queue entry. |
 | `retry` | `IRetryOptions` | `undefined` | Automatic retry policy (attempts, backoff, jitter, predicate). |
+| `timeoutMs` | `number` | `undefined` | Maximum execution duration in milliseconds per attempt before aborting with `AhkoTimeoutError`. |
 | `signal` | `AbortSignal` | `undefined` | Optional external `AbortSignal` for cooperative cancellation. |
 
 ### `ahko.idle<T>(task: ITask<T>, options?: Omit<IScheduleOptions, "strategy">): Promise<T>`

package/dist/errors/timeout.error.d.ts

@@ -1,13 +1,26 @@
 import { AhkoError } from "./ahko.error.js";
+/**
+ * Options for constructing an AhkoTimeoutError.
+ */
+export interface IAhkoTimeoutErrorOptions extends ErrorOptions {
+    /**
+     * The timeout threshold in milliseconds that was exceeded.
+     */
+    timeoutMs?: number;
+}
 /**
  * Thrown when a task exceeds its allotted timeout duration.
  */
 export declare class AhkoTimeoutError extends AhkoError {
+    /**
+     * The timeout threshold in milliseconds that was exceeded, if configured.
+     */
+    readonly timeoutMs?: number;
     /**
      * Creates a new AhkoTimeoutError.
      *
      * @param message - Explanation of timeout expiry.
-     * @param options - Standard Error options including cause.
+     * @param options - Standard Error options including optional timeoutMs and cause.
      */
-    constructor(message?: string, options?: ErrorOptions);
+    constructor(message?: string, options?: IAhkoTimeoutErrorOptions);
 }

package/dist/index.cjs

@@ -31,7 +31,8 @@ __export(src_exports, {
   EScheduleStrategy: () => EScheduleStrategy,
   ETaskState: () => ETaskState,
   VERSION: () => VERSION,
-  calculateBackoff: () => calculateBackoff
+  calculateBackoff: () => calculateBackoff,
+  combineSignals: () => combineSignals
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -73,6 +74,26 @@ var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
   return EScheduleStrategy2;
 })(EScheduleStrategy || {});
 
+// src/errors/timeout.error.ts
+var AhkoTimeoutError = class extends AhkoError {
+  /**
+   * The timeout threshold in milliseconds that was exceeded, if configured.
+   */
+  timeoutMs;
+  /**
+   * Creates a new AhkoTimeoutError.
+   *
+   * @param message - Explanation of timeout expiry.
+   * @param options - Standard Error options including optional timeoutMs and cause.
+   */
+  constructor(message = "Task execution timed out", options) {
+    super(message, options);
+    this.name = "AhkoTimeoutError";
+    this.timeoutMs = options?.timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
 // src/models/state.model.ts
 var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   ETaskState2["PENDING"] = "pending";
@@ -219,6 +240,13 @@ var TaskQueue = class {
         );
       }
     }
+    if (options?.timeoutMs !== void 0) {
+      if (typeof options.timeoutMs !== "number" || Number.isNaN(options.timeoutMs) || !Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        throw new AhkoConfigurationError(
+          `Invalid timeoutMs "${options.timeoutMs}". timeoutMs must be a positive finite number greater than 0.`
+        );
+      }
+    }
     if (options) {
       this.runnerOptions.set(runner, options);
     }
@@ -361,7 +389,7 @@ var TaskQueue = class {
         this.scheduleRetry(runner, options);
         return;
       }
-      if (runner.state === "timed_out" /* TIMED_OUT */) {
+      if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
       } else {
         this.failedTasks++;
@@ -464,6 +492,10 @@ var TaskRunner = class {
   task;
   /** User-supplied AbortSignal for external cancellation */
   externalSignal;
+  /** Maximum execution duration allowed in milliseconds */
+  timeoutMs;
+  /** Active timeout timer identifier */
+  timeoutTimerId;
   /** Abort event listener reference for clean detachment */
   abortListener;
   /** Promise resolve handler */
@@ -474,16 +506,20 @@ var TaskRunner = class {
   promise;
   /** Callback invoked when runner is cancelled while pending */
   onCancel;
+  /** Current execution attempt count (1-indexed) */
+  attempt = 1;
   /**
    * Creates a new TaskRunner instance.
    *
    * @param task - The asynchronous work unit to run.
    * @param externalSignal - Optional external AbortSignal to propagate.
+   * @param timeoutMs - Optional maximum execution time in milliseconds.
    */
-  constructor(task, externalSignal) {
+  constructor(task, externalSignal, timeoutMs) {
     this.taskId = `task_${Date.now().toString(36)}_${(++taskIdCounter).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
     this.task = task;
     this.externalSignal = externalSignal;
+    this.timeoutMs = timeoutMs;
     this.abortController = new AbortController();
     this.promise = new Promise((resolve, reject) => {
       this.resolvePromise = resolve;
@@ -497,6 +533,7 @@ var TaskRunner = class {
           typeof reason === "string" ? reason : "Task was cancelled prior to execution",
           { cause: reason instanceof Error ? reason : void 0 }
         );
+        this.abortController.abort(cancelError);
         this.rejectPromise(cancelError);
       } else {
         this.abortListener = () => {
@@ -512,8 +549,6 @@ var TaskRunner = class {
   get state() {
     return this._state;
   }
-  /** Current execution attempt count (1-indexed) */
-  attempt = 1;
   /**
    * Resolves the deferred promise.
    *
@@ -533,14 +568,14 @@ var TaskRunner = class {
     this.rejectPromise(reason);
   }
   /**
-   * Evaluates if the task should be retried following an execution failure.
+   * Evaluates if the task should be retried following an execution failure or timeout.
    *
    * @param error - The error encountered during the attempt.
    * @param retryOptions - Configured retry policy.
    * @returns A promise resolving to true if retry should proceed, false otherwise.
    */
   async canRetry(error, retryOptions) {
-    if (this._state === "cancelled" /* CANCELLED */ || this.abortController.signal.aborted) {
+    if (this._state === "cancelled" /* CANCELLED */ || (this.externalSignal?.aborted ?? false)) {
       return false;
     }
     if (!retryOptions || typeof retryOptions.attempts !== "number") {
@@ -561,12 +596,13 @@ var TaskRunner = class {
     }
     this.attempt++;
     this._state = "pending" /* PENDING */;
+    this.abortController = new AbortController();
     return true;
   }
   /**
    * Executes the task within an allocated concurrency slot.
    *
-   * @returns A promise resolving to the task result or rejecting on failure/cancellation.
+   * @returns A promise resolving to the task result or rejecting on failure/cancellation/timeout.
    */
   async run() {
     if (this._state === "cancelled" /* CANCELLED */) {
@@ -577,14 +613,100 @@ var TaskRunner = class {
       signal: this.abortController.signal,
       taskId: this.taskId
     };
+    let abortListener;
+    const abortPromise = new Promise((_, reject) => {
+      abortListener = () => {
+        if (this._state === "timed_out" /* TIMED_OUT */) {
+          reject(
+            new AhkoTimeoutError(
+              `Task execution timed out after ${this.timeoutMs}ms`,
+              { timeoutMs: this.timeoutMs }
+            )
+          );
+        } else {
+          const reason = this.abortController.signal.reason;
+          reject(
+            new AhkoCancellationError("Task was cancelled during execution", {
+              cause: reason instanceof Error ? reason : void 0
+            })
+          );
+        }
+      };
+      this.abortController.signal.addEventListener("abort", abortListener, { once: true });
+    });
+    let timeoutPromise;
+    if (this.timeoutMs !== void 0) {
+      timeoutPromise = new Promise((_, reject) => {
+        this.timeoutTimerId = setTimeout(() => {
+          if (this._state !== "running" /* RUNNING */) {
+            return;
+          }
+          this._state = "timed_out" /* TIMED_OUT */;
+          const timeoutError = new AhkoTimeoutError(
+            `Task execution timed out after ${this.timeoutMs}ms`,
+            { timeoutMs: this.timeoutMs }
+          );
+          this.abortController.abort(timeoutError);
+          reject(timeoutError);
+        }, this.timeoutMs);
+      });
+    }
+    let taskExecutionPromise;
+    try {
+      taskExecutionPromise = Promise.resolve(this.task(context));
+    } catch (syncError) {
+      taskExecutionPromise = Promise.reject(syncError);
+    }
+    taskExecutionPromise.catch(() => {
+    });
+    const racePromises = [
+      taskExecutionPromise,
+      abortPromise
+    ];
+    if (timeoutPromise) {
+      racePromises.push(timeoutPromise);
+    }
     try {
-      const result = await this.task(context);
+      const result = await Promise.race(racePromises);
+      this.clearTimeoutTimer();
+      if (abortListener) {
+        this.abortController.signal.removeEventListener("abort", abortListener);
+      }
+      if (this._state === "timed_out" /* TIMED_OUT */) {
+        throw new AhkoTimeoutError(
+          `Task execution timed out after ${this.timeoutMs}ms`,
+          { timeoutMs: this.timeoutMs }
+        );
+      }
+      if (this._state === "cancelled" /* CANCELLED */) {
+        throw new AhkoCancellationError("Task was cancelled during execution");
+      }
       this._state = "completed" /* COMPLETED */;
       return result;
     } catch (error) {
-      const isCancelled = this._state === "cancelled" /* CANCELLED */ || this.abortController.signal.aborted;
+      this.clearTimeoutTimer();
+      if (abortListener) {
+        this.abortController.signal.removeEventListener("abort", abortListener);
+      }
+      if (this._state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
+        this._state = "timed_out" /* TIMED_OUT */;
+        if (error instanceof AhkoTimeoutError) {
+          throw error;
+        }
+        throw new AhkoTimeoutError(
+          `Task execution timed out after ${this.timeoutMs}ms`,
+          {
+            timeoutMs: this.timeoutMs,
+            cause: error instanceof Error ? error : void 0
+          }
+        );
+      }
+      const isCancelled = this._state === "cancelled" /* CANCELLED */ || this.abortController.signal.aborted || (this.externalSignal?.aborted ?? false);
       if (isCancelled) {
         this._state = "cancelled" /* CANCELLED */;
+        if (error instanceof AhkoCancellationError) {
+          throw error;
+        }
         throw new AhkoCancellationError("Task was cancelled during execution", {
           cause: error instanceof Error ? error : void 0
         });
@@ -593,6 +715,15 @@ var TaskRunner = class {
       throw error;
     }
   }
+  /**
+   * Clears the active timeout timer.
+   */
+  clearTimeoutTimer() {
+    if (this.timeoutTimerId !== void 0) {
+      clearTimeout(this.timeoutTimerId);
+      this.timeoutTimerId = void 0;
+    }
+  }
   /**
    * Cancels the task, aborting pending or running execution.
    *
@@ -604,6 +735,7 @@ var TaskRunner = class {
     }
     const wasPending = this._state === "pending" /* PENDING */;
     this._state = "cancelled" /* CANCELLED */;
+    this.clearTimeoutTimer();
     this.abortController.abort(reason);
     this.cleanup();
     if (wasPending) {
@@ -625,6 +757,7 @@ var TaskRunner = class {
    * Detaches event listeners from external signal to guarantee memory safety.
    */
   cleanup() {
+    this.clearTimeoutTimer();
     if (this.externalSignal && this.abortListener) {
       this.externalSignal.removeEventListener("abort", this.abortListener);
     }
@@ -676,7 +809,7 @@ var Ahko = class {
     if (typeof task !== "function") {
       throw new AhkoConfigurationError("Task must be a valid function.");
     }
-    const runner = new TaskRunner(task, options?.signal);
+    const runner = new TaskRunner(task, options?.signal, options?.timeoutMs);
     return this.queue.enqueue(runner, options);
   }
   /**
@@ -725,7 +858,7 @@ var Ahko = class {
 };
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {
@@ -742,20 +875,60 @@ var AhkoQueueError = class extends AhkoError {
   }
 };
 
-// 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);
+// src/scheduler/signal.ts
+function combineSignals(signals) {
+  const activeSignals = signals.filter(
+    (signal) => signal !== void 0
+  );
+  if (activeSignals.length === 0) {
+    const controller2 = new AbortController();
+    return {
+      signal: controller2.signal,
+      cleanup: () => {
+      }
+    };
   }
-};
+  const alreadyAborted = activeSignals.find((s) => s.aborted);
+  if (alreadyAborted) {
+    const controller2 = new AbortController();
+    controller2.abort(alreadyAborted.reason);
+    return {
+      signal: controller2.signal,
+      cleanup: () => {
+      }
+    };
+  }
+  if (activeSignals.length === 1) {
+    return {
+      signal: activeSignals[0],
+      cleanup: () => {
+      }
+    };
+  }
+  const controller = new AbortController();
+  const cleanupFns = [];
+  const onAbort = (event) => {
+    const target = event.target;
+    cleanup();
+    controller.abort(target.reason);
+  };
+  for (const sig of activeSignals) {
+    sig.addEventListener("abort", onAbort, { once: true });
+    cleanupFns.push(() => {
+      sig.removeEventListener("abort", onAbort);
+    });
+  }
+  const cleanup = () => {
+    for (const fn of cleanupFns) {
+      fn();
+    }
+    cleanupFns.length = 0;
+  };
+  return {
+    signal: controller.signal,
+    cleanup
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Ahko,
@@ -769,6 +942,7 @@ var AhkoTimeoutError = class extends AhkoError {
   EScheduleStrategy,
   ETaskState,
   VERSION,
-  calculateBackoff
+  calculateBackoff,
+  combineSignals
 });
 //# sourceMappingURL=index.cjs.map