@mrjacket/ahko 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -26,9 +26,13 @@ __export(src_exports, {
   AhkoError: () => AhkoError,
   AhkoQueueError: () => AhkoQueueError,
   AhkoTimeoutError: () => AhkoTimeoutError,
+  DEFAULT_BASE_DELAY: () => DEFAULT_BASE_DELAY,
+  DEFAULT_MAX_DELAY: () => DEFAULT_MAX_DELAY,
   EScheduleStrategy: () => EScheduleStrategy,
   ETaskState: () => ETaskState,
-  VERSION: () => VERSION
+  VERSION: () => VERSION,
+  calculateBackoff: () => calculateBackoff,
+  combineSignals: () => combineSignals
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -70,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";
@@ -81,6 +105,31 @@ var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   return ETaskState2;
 })(ETaskState || {});
 
+// src/retry/backoff.ts
+var DEFAULT_BASE_DELAY = 250;
+var DEFAULT_MAX_DELAY = 1e4;
+function calculateBackoff(attempt, options, randomFn = Math.random) {
+  const backoff = options?.backoff ?? "exponential";
+  if (backoff === "none") {
+    return 0;
+  }
+  const baseDelay = typeof options?.baseDelay === "number" && !Number.isNaN(options.baseDelay) && options.baseDelay >= 0 ? options.baseDelay : DEFAULT_BASE_DELAY;
+  const maxDelay = typeof options?.maxDelay === "number" && !Number.isNaN(options.maxDelay) && options.maxDelay >= baseDelay ? options.maxDelay : Math.max(DEFAULT_MAX_DELAY, baseDelay);
+  let calculatedDelay;
+  if (backoff === "linear") {
+    calculatedDelay = baseDelay * Math.max(1, attempt);
+  } else {
+    const exponent = Math.max(0, attempt - 1);
+    const factor = exponent > 30 ? 2 ** 30 : 2 ** exponent;
+    calculatedDelay = baseDelay * factor;
+  }
+  const cappedDelay = Math.min(calculatedDelay, maxDelay);
+  if (options?.jitter) {
+    return Math.floor(randomFn() * (cappedDelay + 1));
+  }
+  return Math.floor(cappedDelay);
+}
+
 // src/scheduler/idle-scheduler.ts
 var IdleScheduler = class {
   /**
@@ -132,6 +181,10 @@ var TaskQueue = class {
   delayedEntries = /* @__PURE__ */ new Set();
   /** Set of tasks currently awaiting an idle opportunity */
   idleEntries = /* @__PURE__ */ new Set();
+  /** Set of tasks currently awaiting a retry backoff timer */
+  retryEntries = /* @__PURE__ */ new Set();
+  /** WeakMap associating task runners with their scheduling options */
+  runnerOptions = /* @__PURE__ */ new WeakMap();
   /** Cumulative completed tasks counter */
   completedTasks = 0;
   /** Cumulative failed tasks counter */
@@ -170,6 +223,33 @@ var TaskQueue = class {
         `Unsupported schedule strategy "${String(strategy)}". Supported strategies: "immediate", "delay", "idle".`
       );
     }
+    if (options?.retry) {
+      if (typeof options.retry.attempts !== "number" || Number.isNaN(options.retry.attempts) || options.retry.attempts < 1 || !Number.isInteger(options.retry.attempts)) {
+        throw new AhkoConfigurationError(
+          `Invalid retry attempts "${options.retry.attempts}". attempts must be an integer greater than or equal to 1.`
+        );
+      }
+      if (options.retry.baseDelay !== void 0 && (typeof options.retry.baseDelay !== "number" || Number.isNaN(options.retry.baseDelay) || options.retry.baseDelay < 0)) {
+        throw new AhkoConfigurationError(
+          `Invalid retry baseDelay "${options.retry.baseDelay}". baseDelay must be a non-negative number in milliseconds.`
+        );
+      }
+      if (options.retry.maxDelay !== void 0 && (typeof options.retry.maxDelay !== "number" || Number.isNaN(options.retry.maxDelay) || options.retry.maxDelay < 0)) {
+        throw new AhkoConfigurationError(
+          `Invalid retry maxDelay "${options.retry.maxDelay}". maxDelay must be a non-negative number in milliseconds.`
+        );
+      }
+    }
+    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);
+    }
     if (runner.state === "cancelled" /* CANCELLED */) {
       this.cancelledTasks++;
       return runner.promise;
@@ -286,28 +366,86 @@ var TaskQueue = class {
   }
   /**
    * Internal execution of an active task runner.
-   * Settle caller promise strictly after stats and active status are updated.
    */
   async executeRunner(runner) {
+    const options = this.runnerOptions.get(runner);
     try {
       const result = await runner.run();
       this.completedTasks++;
       this.activeRunners.delete(runner);
+      this.runnerOptions.delete(runner);
       runner.resolve(result);
     } catch (error) {
       if (runner.state === "cancelled" /* CANCELLED */) {
         this.cancelledTasks++;
-      } else if (runner.state === "timed_out" /* TIMED_OUT */) {
+        this.activeRunners.delete(runner);
+        this.runnerOptions.delete(runner);
+        runner.reject(error);
+        return;
+      }
+      const shouldRetry = await runner.canRetry(error, options?.retry);
+      if (shouldRetry) {
+        this.activeRunners.delete(runner);
+        this.scheduleRetry(runner, options);
+        return;
+      }
+      if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
       } else {
         this.failedTasks++;
       }
       this.activeRunners.delete(runner);
+      this.runnerOptions.delete(runner);
       runner.reject(error);
     } finally {
       this.pump();
     }
   }
+  /**
+   * Schedules a retry attempt following backoff delay,
+   * without holding a concurrency slot.
+   */
+  scheduleRetry(runner, options) {
+    const backoffDelay = calculateBackoff(runner.attempt - 1, options?.retry);
+    if (backoffDelay === 0) {
+      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;
+    }
+    const retryEntry = {
+      runner,
+      timerId: setTimeout(() => {
+        this.retryEntries.delete(retryEntry);
+        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();
+      }, backoffDelay)
+    };
+    this.retryEntries.add(retryEntry);
+    runner.onCancel = () => {
+      if (this.retryEntries.has(retryEntry)) {
+        clearTimeout(retryEntry.timerId);
+        this.retryEntries.delete(retryEntry);
+        this.cancelledTasks++;
+      }
+    };
+  }
   /**
    * Returns telemetry snapshot for the scheduler.
    *
@@ -316,7 +454,7 @@ var TaskQueue = class {
   getStats() {
     return Object.freeze({
       activeTasks: this.activeRunners.size,
-      pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size,
+      pendingTasks: this.queue.length + this.delayedEntries.size + this.idleEntries.size + this.retryEntries.size,
       completedTasks: this.completedTasks,
       failedTasks: this.failedTasks,
       cancelledTasks: this.cancelledTasks,
@@ -354,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 */
@@ -364,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;
@@ -387,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 = () => {
@@ -408,6 +555,7 @@ var TaskRunner = class {
    * @param value - Value to resolve with.
    */
   resolve(value) {
+    this.cleanup();
     this.resolvePromise(value);
   }
   /**
@@ -416,12 +564,45 @@ var TaskRunner = class {
    * @param reason - Reason to reject with.
    */
   reject(reason) {
+    this.cleanup();
     this.rejectPromise(reason);
   }
+  /**
+   * 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.externalSignal?.aborted ?? false)) {
+      return false;
+    }
+    if (!retryOptions || typeof retryOptions.attempts !== "number") {
+      return false;
+    }
+    if (this.attempt >= retryOptions.attempts) {
+      return false;
+    }
+    if (typeof retryOptions.shouldRetry === "function") {
+      try {
+        const allowed = await retryOptions.shouldRetry(error, this.attempt);
+        if (!allowed) {
+          return false;
+        }
+      } catch {
+        return false;
+      }
+    }
+    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 */) {
@@ -432,16 +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 */;
-      this.cleanup();
       return result;
     } catch (error) {
-      this.cleanup();
-      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
         });
@@ -450,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.
    *
@@ -461,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) {
@@ -482,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);
     }
@@ -533,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);
   }
   /**
@@ -582,7 +858,7 @@ var Ahko = class {
 };
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {
@@ -599,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,
@@ -621,8 +937,12 @@ var AhkoTimeoutError = class extends AhkoError {
   AhkoError,
   AhkoQueueError,
   AhkoTimeoutError,
+  DEFAULT_BASE_DELAY,
+  DEFAULT_MAX_DELAY,
   EScheduleStrategy,
   ETaskState,
-  VERSION
+  VERSION,
+  calculateBackoff,
+  combineSignals
 });
 //# sourceMappingURL=index.cjs.map