@mrjacket/ahko 0.6.0 → 1.1.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -22,17 +32,27 @@ var src_exports = {};
 __export(src_exports, {
   Ahko: () => Ahko,
   AhkoCancellationError: () => AhkoCancellationError,
+  AhkoCircuitBreakerOpenError: () => AhkoCircuitBreakerOpenError,
   AhkoConfigurationError: () => AhkoConfigurationError,
   AhkoError: () => AhkoError,
   AhkoQueueError: () => AhkoQueueError,
   AhkoTimeoutError: () => AhkoTimeoutError,
+  CircuitBreakerCoordinator: () => CircuitBreakerCoordinator,
   DEFAULT_BASE_DELAY: () => DEFAULT_BASE_DELAY,
   DEFAULT_MAX_DELAY: () => DEFAULT_MAX_DELAY,
+  ECircuitState: () => ECircuitState,
   EScheduleStrategy: () => EScheduleStrategy,
   ETaskState: () => ETaskState,
+  TASK_PRIORITY_WEIGHTS: () => TASK_PRIORITY_WEIGHTS,
   VERSION: () => VERSION,
   calculateBackoff: () => calculateBackoff,
-  combineSignals: () => combineSignals
+  combineSignals: () => combineSignals,
+  getActiveConfig: () => getActiveConfig,
+  getProfileConfig: () => getProfileConfig,
+  loadConfig: () => loadConfig,
+  loadConfigFile: () => loadConfigFile,
+  resetConfig: () => resetConfig,
+  resolvePriorityWeight: () => resolvePriorityWeight
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -66,6 +86,72 @@ var AhkoConfigurationError = class extends AhkoError {
   }
 };
 
+// src/config/config-loader.ts
+var activeConfig;
+function loadConfig(config) {
+  activeConfig = { ...config };
+}
+function resetConfig() {
+  activeConfig = void 0;
+}
+async function loadConfigFile(filePath = "config.ahko.json") {
+  if (typeof process === "undefined" || !process.versions?.node) {
+    return void 0;
+  }
+  try {
+    const { readFile } = await import("fs/promises");
+    const { resolve } = await import("path");
+    const resolvedPath = resolve(process.cwd(), filePath);
+    const content = await readFile(resolvedPath, "utf-8");
+    const parsed = JSON.parse(content);
+    activeConfig = parsed;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+function tryAutoDiscoverSync() {
+  if (activeConfig !== void 0 || typeof process === "undefined" || !process.versions?.node) {
+    return;
+  }
+  try {
+    let fs = null;
+    let path = null;
+    if (typeof process.getBuiltinModule === "function") {
+      const getBuiltin = process.getBuiltinModule;
+      fs = getBuiltin("node:fs");
+      path = getBuiltin("node:path");
+    } else if (typeof require === "function") {
+      fs = require("fs");
+      path = require("path");
+    }
+    if (fs && path) {
+      const configPath = path.resolve(process.cwd(), "config.ahko.json");
+      if (fs.existsSync(configPath)) {
+        const raw = fs.readFileSync(configPath, "utf-8");
+        activeConfig = JSON.parse(raw);
+      }
+    }
+  } catch {
+  }
+}
+function getActiveConfig() {
+  if (activeConfig === void 0) {
+    tryAutoDiscoverSync();
+  }
+  return activeConfig;
+}
+function getProfileConfig(profileName) {
+  const config = getActiveConfig();
+  if (!config) {
+    return void 0;
+  }
+  if (profileName) {
+    return config.profiles?.[profileName];
+  }
+  return config.default;
+}
+
 // src/models/strategy.model.ts
 var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
   EScheduleStrategy2["IMMEDIATE"] = "immediate";
@@ -76,6 +162,23 @@ var EScheduleStrategy = /* @__PURE__ */ ((EScheduleStrategy2) => {
   return EScheduleStrategy2;
 })(EScheduleStrategy || {});
 
+// src/errors/circuit-breaker.error.ts
+var AhkoCircuitBreakerOpenError = class extends AhkoError {
+  /** Time remaining in milliseconds before trial execution is allowed */
+  resetTimeoutMs;
+  /** Timestamp when the circuit tripped open */
+  trippedAt;
+  /** Total consecutive failures that caused the trip */
+  consecutiveFailures;
+  constructor(message = "Circuit breaker is open. Fast-failing task execution to protect downstream resources.", options) {
+    super(message);
+    this.name = "AhkoCircuitBreakerOpenError";
+    this.resetTimeoutMs = options?.resetTimeoutMs;
+    this.trippedAt = options?.trippedAt;
+    this.consecutiveFailures = options?.consecutiveFailures;
+  }
+};
+
 // src/errors/timeout.error.ts
 var AhkoTimeoutError = class extends AhkoError {
   /**
@@ -96,6 +199,28 @@ var AhkoTimeoutError = class extends AhkoError {
   }
 };
 
+// src/models/priority.model.ts
+var TASK_PRIORITY_WEIGHTS = {
+  high: 10,
+  normal: 0,
+  low: -10
+};
+function resolvePriorityWeight(priority) {
+  if (priority === void 0) {
+    return TASK_PRIORITY_WEIGHTS.normal;
+  }
+  if (typeof priority === "number") {
+    return Number.isFinite(priority) ? priority : TASK_PRIORITY_WEIGHTS.normal;
+  }
+  if (priority === "high") {
+    return TASK_PRIORITY_WEIGHTS.high;
+  }
+  if (priority === "low") {
+    return TASK_PRIORITY_WEIGHTS.low;
+  }
+  return TASK_PRIORITY_WEIGHTS.normal;
+}
+
 // src/models/state.model.ts
 var ETaskState = /* @__PURE__ */ ((ETaskState2) => {
   ETaskState2["PENDING"] = "pending";
@@ -132,6 +257,123 @@ function calculateBackoff(attempt, options, randomFn = Math.random) {
   return Math.floor(cappedDelay);
 }
 
+// src/models/circuit-breaker.model.ts
+var ECircuitState = /* @__PURE__ */ ((ECircuitState2) => {
+  ECircuitState2["CLOSED"] = "closed";
+  ECircuitState2["OPEN"] = "open";
+  ECircuitState2["HALF_OPEN"] = "half_open";
+  return ECircuitState2;
+})(ECircuitState || {});
+
+// src/scheduler/circuit-breaker.ts
+var CircuitBreakerCoordinator = class {
+  _state = "closed" /* CLOSED */;
+  _consecutiveFailures = 0;
+  _lastFailureTime;
+  failureThreshold;
+  resetTimeoutMs;
+  /**
+   * Initializes a new CircuitBreakerCoordinator.
+   *
+   * @param options - Configuration options for threshold and cool-down window.
+   * @throws {AhkoConfigurationError} If options are invalid.
+   */
+  constructor(options) {
+    if (typeof options.failureThreshold !== "number" || Number.isNaN(options.failureThreshold) || !Number.isInteger(options.failureThreshold) || options.failureThreshold < 1) {
+      throw new AhkoConfigurationError(
+        `Invalid failureThreshold "${options.failureThreshold}". failureThreshold must be an integer greater than or equal to 1.`
+      );
+    }
+    if (typeof options.resetTimeoutMs !== "number" || Number.isNaN(options.resetTimeoutMs) || !Number.isFinite(options.resetTimeoutMs) || options.resetTimeoutMs <= 0) {
+      throw new AhkoConfigurationError(
+        `Invalid resetTimeoutMs "${options.resetTimeoutMs}". resetTimeoutMs must be a positive finite number greater than 0.`
+      );
+    }
+    this.failureThreshold = options.failureThreshold;
+    this.resetTimeoutMs = options.resetTimeoutMs;
+  }
+  /** Current state of the circuit breaker */
+  get state() {
+    this.refreshState();
+    return this._state;
+  }
+  /**
+   * Checks whether an execution is currently allowed.
+   * If the circuit is OPEN and cool-down has not elapsed, fast-fails immediately.
+   *
+   * @throws {AhkoCircuitBreakerOpenError} If the circuit is currently OPEN.
+   */
+  checkAllowed() {
+    this.refreshState();
+    if (this._state === "open" /* OPEN */) {
+      const remainingMs = this._lastFailureTime ? Math.max(0, this.resetTimeoutMs - (Date.now() - this._lastFailureTime)) : this.resetTimeoutMs;
+      throw new AhkoCircuitBreakerOpenError(
+        `Circuit breaker is open. Fast-failing task execution. Remaining cool-down: ${remainingMs}ms.`,
+        {
+          resetTimeoutMs: remainingMs,
+          trippedAt: this._lastFailureTime,
+          consecutiveFailures: this._consecutiveFailures
+        }
+      );
+    }
+  }
+  /**
+   * Records a successful task execution.
+   * Heals HALF_OPEN state back to CLOSED and resets consecutive failure counters.
+   */
+  recordSuccess() {
+    this._consecutiveFailures = 0;
+    this._state = "closed" /* CLOSED */;
+  }
+  /**
+   * Records a failed task execution.
+   * Trips CLOSED to OPEN when threshold is met, or re-trips HALF_OPEN immediately.
+   *
+   * @param _error - Optional error that caused the failure.
+   */
+  recordFailure(_error) {
+    this._consecutiveFailures++;
+    this._lastFailureTime = Date.now();
+    if (this._state === "half_open" /* HALF_OPEN */) {
+      this._state = "open" /* OPEN */;
+      return;
+    }
+    if (this._consecutiveFailures >= this.failureThreshold) {
+      this._state = "open" /* OPEN */;
+    }
+  }
+  /**
+   * Evaluates if enough time has passed to transition from OPEN to HALF_OPEN.
+   */
+  refreshState() {
+    if (this._state === "open" /* OPEN */ && this._lastFailureTime !== void 0) {
+      const elapsed = Date.now() - this._lastFailureTime;
+      if (elapsed >= this.resetTimeoutMs) {
+        this._state = "half_open" /* HALF_OPEN */;
+      }
+    }
+  }
+  /**
+   * Resets the circuit breaker back to initial CLOSED state.
+   */
+  reset() {
+    this._state = "closed" /* CLOSED */;
+    this._consecutiveFailures = 0;
+    this._lastFailureTime = void 0;
+  }
+  /**
+   * Returns a snapshot of circuit breaker telemetry.
+   */
+  getStats() {
+    this.refreshState();
+    return {
+      state: this._state,
+      consecutiveFailures: this._consecutiveFailures,
+      lastFailureTime: this._lastFailureTime
+    };
+  }
+};
+
 // src/errors/cancellation.error.ts
 var AhkoCancellationError = class extends AhkoError {
   /**
@@ -150,6 +392,8 @@ var AhkoCancellationError = class extends AhkoError {
 // src/scheduler/debounce-coordinator.ts
 var DebounceCoordinator = class {
   entries = /* @__PURE__ */ new Map();
+  /** Optional callback invoked whenever entries are settled or removed from coordinator */
+  onSettled;
   /**
    * Schedules a task under the debounce strategy.
    *
@@ -236,6 +480,7 @@ var DebounceCoordinator = class {
       return;
     }
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.options?.signal && entry.abortListener) {
       entry.options.signal.removeEventListener("abort", entry.abortListener);
     }
@@ -259,6 +504,7 @@ var DebounceCoordinator = class {
     }
     clearTimeout(entry.timerId);
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.options?.signal && entry.abortListener) {
       entry.options.signal.removeEventListener("abort", entry.abortListener);
     }
@@ -286,6 +532,7 @@ var DebounceCoordinator = class {
       entry.reject(new AhkoCancellationError("Debounced tasks cleared"));
     }
     this.entries.clear();
+    this.onSettled?.();
   }
 };
 
@@ -331,6 +578,8 @@ var IdleScheduler = class {
 // src/scheduler/throttle-coordinator.ts
 var ThrottleCoordinator = class {
   entries = /* @__PURE__ */ new Map();
+  /** Optional callback invoked whenever entries are settled or removed from coordinator */
+  onSettled;
   /**
    * Schedules a task under the throttle strategy.
    *
@@ -416,6 +665,7 @@ var ThrottleCoordinator = class {
       return;
     }
     this.entries.delete(key);
+    this.onSettled?.();
   }
   /**
    * Cancels any pending trailing throttled task for a given key.
@@ -432,6 +682,7 @@ var ThrottleCoordinator = class {
       clearTimeout(entry.windowTimerId);
     }
     this.entries.delete(key);
+    this.onSettled?.();
     if (entry.trailingReject) {
       const cancelError = new AhkoCancellationError(
         typeof reason === "string" ? reason : "Throttled task was cancelled",
@@ -459,6 +710,7 @@ var ThrottleCoordinator = class {
       }
     }
     this.entries.clear();
+    this.onSettled?.();
   }
 };
 
@@ -556,6 +808,10 @@ var TaskQueue = class {
   throttleCoordinator = new ThrottleCoordinator();
   /** Lifecycle event emitter for task and scheduler events */
   emitter = new AhkoEventEmitter();
+  /** Circuit breaker coordinator if configured */
+  circuitBreakerCoordinator;
+  /** Pause state flag */
+  _isPaused = false;
   /** Set of pending resolvers awaiting scheduler idle transition */
   idleResolvers = /* @__PURE__ */ new Set();
   /** WeakMap associating task runners with their scheduling options */
@@ -577,9 +833,10 @@ var TaskQueue = class {
    *
    * @param concurrency - Maximum concurrent tasks (defaults to Infinity).
    * @param minIntervalMs - Minimum interval in milliseconds between task dispatches.
+   * @param circuitBreakerOptions - Optional circuit breaker policy configuration.
    * @throws {AhkoConfigurationError} If concurrency is less than 1 or minIntervalMs is invalid.
    */
-  constructor(concurrency = Infinity, minIntervalMs = 0) {
+  constructor(concurrency = Infinity, minIntervalMs = 0, circuitBreakerOptions) {
     if (Number.isNaN(concurrency) || concurrency < 1) {
       throw new AhkoConfigurationError(
         `Invalid concurrency "${concurrency}". Must be a number greater than or equal to 1.`
@@ -592,6 +849,50 @@ var TaskQueue = class {
     }
     this.concurrency = concurrency;
     this.minIntervalMs = minIntervalMs;
+    if (circuitBreakerOptions) {
+      this.circuitBreakerCoordinator = new CircuitBreakerCoordinator(circuitBreakerOptions);
+    }
+    this.debounceCoordinator.onSettled = () => this.checkIdle();
+    this.throttleCoordinator.onSettled = () => this.checkIdle();
+  }
+  /**
+   * Pauses queue execution. Running tasks will complete normally, but no new pending tasks will be dispatched.
+   */
+  pause() {
+    this._isPaused = true;
+  }
+  /**
+   * Resumes queue execution, immediately dispatching waiting tasks up to available concurrency.
+   */
+  resume() {
+    if (this._isPaused) {
+      this._isPaused = false;
+      this.pump();
+    }
+  }
+  /**
+   * Checks whether the task queue is currently paused.
+   */
+  isPaused() {
+    return this._isPaused;
+  }
+  /**
+   * Inserts a task runner into the queue based on priority weight (descending).
+   * Preserves FIFO ordering among tasks with identical priority.
+   */
+  insertIntoQueue(runner) {
+    const options = this.runnerOptions.get(runner);
+    const targetWeight = resolvePriorityWeight(options?.priority);
+    let insertIndex = this.queue.length;
+    for (let i = 0; i < this.queue.length; i++) {
+      const existingOptions = this.runnerOptions.get(this.queue[i]);
+      const existingWeight = resolvePriorityWeight(existingOptions?.priority);
+      if (existingWeight < targetWeight) {
+        insertIndex = i;
+        break;
+      }
+    }
+    this.queue.splice(insertIndex, 0, runner);
   }
   /**
    * Enqueues a task runner according to the specified schedule options.
@@ -646,6 +947,13 @@ var TaskQueue = class {
         );
       }
     }
+    if (options?.totalTimeoutMs !== void 0) {
+      if (typeof options.totalTimeoutMs !== "number" || Number.isNaN(options.totalTimeoutMs) || !Number.isFinite(options.totalTimeoutMs) || options.totalTimeoutMs <= 0) {
+        throw new AhkoConfigurationError(
+          `Invalid totalTimeoutMs "${options.totalTimeoutMs}". totalTimeoutMs must be a positive finite number greater than 0.`
+        );
+      }
+    }
     if (options) {
       this.runnerOptions.set(runner, options);
     }
@@ -653,6 +961,16 @@ var TaskQueue = class {
       this.cancelledTasks++;
       return runner.promise;
     }
+    if (options?.totalTimeoutMs !== void 0) {
+      const budgetMs = options.totalTimeoutMs;
+      const totalTimerId = setTimeout(() => {
+        runner.timeout(budgetMs, `Task total execution deadline exceeded after ${budgetMs}ms`);
+      }, budgetMs);
+      runner.promise.finally(() => {
+        clearTimeout(totalTimerId);
+      }).catch(() => {
+      });
+    }
     if (strategy === "delay" /* DELAY */) {
       const delayMs = options?.delay ?? 0;
       if (typeof delayMs !== "number" || Number.isNaN(delayMs) || delayMs < 0) {
@@ -676,15 +994,23 @@ var TaskQueue = class {
       const index = this.queue.indexOf(runner);
       if (index !== -1) {
         this.queue.splice(index, 1);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled while queued"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while queued"
+          });
+        }
         this.checkIdle();
       }
     };
-    this.queue.push(runner);
+    this.insertIntoQueue(runner);
     this.pump();
     return runner.promise;
   }
@@ -697,22 +1023,30 @@ var TaskQueue = class {
       runner,
       timerId: setTimeout(() => {
         this.delayedEntries.delete(delayedEntry);
-        if (runner.state === "cancelled" /* CANCELLED */) {
+        if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
           return;
         }
         runner.onCancel = () => {
           const index = this.queue.indexOf(runner);
           if (index !== -1) {
             this.queue.splice(index, 1);
-            this.cancelledTasks++;
-            this.emitter.emit("task:cancel", {
-              taskId: runner.taskId,
-              reason: "Task cancelled while queued"
-            });
+            if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+              this.timedOutTasks++;
+              this.emitter.emit("task:timeout", {
+                taskId: runner.taskId,
+                timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+              });
+            } else {
+              this.cancelledTasks++;
+              this.emitter.emit("task:cancel", {
+                taskId: runner.taskId,
+                reason: "Task cancelled while queued"
+              });
+            }
             this.checkIdle();
           }
         };
-        this.queue.push(runner);
+        this.insertIntoQueue(runner);
         this.pump();
       }, delayMs)
     };
@@ -721,11 +1055,19 @@ var TaskQueue = class {
       if (this.delayedEntries.has(delayedEntry)) {
         clearTimeout(delayedEntry.timerId);
         this.delayedEntries.delete(delayedEntry);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled while waiting in delay"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while waiting in delay"
+          });
+        }
         this.checkIdle();
       }
     };
@@ -738,22 +1080,30 @@ var TaskQueue = class {
     let idleEntry;
     const handle = IdleScheduler.schedule(() => {
       this.idleEntries.delete(idleEntry);
-      if (runner.state === "cancelled" /* CANCELLED */) {
+      if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
         return;
       }
       runner.onCancel = () => {
         const index = this.queue.indexOf(runner);
         if (index !== -1) {
           this.queue.splice(index, 1);
-          this.cancelledTasks++;
-          this.emitter.emit("task:cancel", {
-            taskId: runner.taskId,
-            reason: "Task cancelled while queued"
-          });
+          if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+            this.timedOutTasks++;
+            this.emitter.emit("task:timeout", {
+              taskId: runner.taskId,
+              timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+            });
+          } else {
+            this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+          }
           this.checkIdle();
         }
       };
-      this.queue.push(runner);
+      this.insertIntoQueue(runner);
       this.pump();
     }, idleTimeout);
     idleEntry = { runner, handle };
@@ -762,21 +1112,30 @@ var TaskQueue = class {
       if (this.idleEntries.has(idleEntry)) {
         handle.cancel();
         this.idleEntries.delete(idleEntry);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled while waiting for idle"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: this.runnerOptions.get(runner)?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled while waiting for idle"
+          });
+        }
         this.checkIdle();
       }
     };
   }
   /**
    * Pumps the queue by picking pending tasks and executing them
-   * as long as concurrency capacity is available and minIntervalMs is respected.
+   * as long as concurrency capacity is available, minIntervalMs is respected,
+   * and queue is not paused.
    */
   pump() {
-    if (this.queue.length === 0 || this.activeRunners.size >= this.concurrency) {
+    if (this._isPaused || this.queue.length === 0 || this.activeRunners.size >= this.concurrency) {
       return;
     }
     if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
@@ -793,7 +1152,7 @@ var TaskQueue = class {
         return;
       }
     }
-    while (this.activeRunners.size < this.concurrency && this.queue.length > 0) {
+    while (!this._isPaused && this.activeRunners.size < this.concurrency && this.queue.length > 0) {
       if (this.minIntervalMs > 0 && this.lastTaskStartTime > 0) {
         const now = Date.now();
         const elapsed = now - this.lastTaskStartTime;
@@ -812,9 +1171,25 @@ var TaskQueue = class {
       if (!runner) {
         break;
       }
-      if (runner.state === "cancelled" /* CANCELLED */) {
+      if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
         continue;
       }
+      if (this.circuitBreakerCoordinator) {
+        try {
+          this.circuitBreakerCoordinator.checkAllowed();
+        } catch (cbError) {
+          this.failedTasks++;
+          this.runnerOptions.delete(runner);
+          this.emitter.emit("task:fail", {
+            taskId: runner.taskId,
+            attempt: runner.attempt,
+            error: cbError,
+            willRetry: false
+          });
+          runner.reject(cbError);
+          continue;
+        }
+      }
       this.activeRunners.add(runner);
       this.lastTaskStartTime = Date.now();
       void this.executeRunner(runner);
@@ -843,6 +1218,7 @@ var TaskQueue = class {
     });
     try {
       const result = await runner.run();
+      this.circuitBreakerCoordinator?.recordSuccess();
       this.completedTasks++;
       this.activeRunners.delete(runner);
       this.runnerOptions.delete(runner);
@@ -878,11 +1254,14 @@ var TaskQueue = class {
         this.scheduleRetry(runner, options);
         return;
       }
+      if (this.circuitBreakerCoordinator && !(error instanceof AhkoCircuitBreakerOpenError)) {
+        this.circuitBreakerCoordinator.recordFailure(error);
+      }
       if (runner.state === "timed_out" /* TIMED_OUT */ || error instanceof AhkoTimeoutError) {
         this.timedOutTasks++;
         this.emitter.emit("task:timeout", {
           taskId: runner.taskId,
-          timeoutMs: runner.timeoutMs
+          timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
         });
       } else {
         this.failedTasks++;
@@ -912,15 +1291,23 @@ var TaskQueue = class {
         const index = this.queue.indexOf(runner);
         if (index !== -1) {
           this.queue.splice(index, 1);
-          this.cancelledTasks++;
-          this.emitter.emit("task:cancel", {
-            taskId: runner.taskId,
-            reason: "Task cancelled while queued"
-          });
+          if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+            this.timedOutTasks++;
+            this.emitter.emit("task:timeout", {
+              taskId: runner.taskId,
+              timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+            });
+          } else {
+            this.cancelledTasks++;
+            this.emitter.emit("task:cancel", {
+              taskId: runner.taskId,
+              reason: "Task cancelled while queued"
+            });
+          }
           this.checkIdle();
         }
       };
-      this.queue.push(runner);
+      this.insertIntoQueue(runner);
       this.pump();
       return;
     }
@@ -928,22 +1315,30 @@ var TaskQueue = class {
       runner,
       timerId: setTimeout(() => {
         this.retryEntries.delete(retryEntry);
-        if (runner.state === "cancelled" /* CANCELLED */) {
+        if (runner.state === "cancelled" /* CANCELLED */ || runner.state === "timed_out" /* TIMED_OUT */) {
           return;
         }
         runner.onCancel = () => {
           const index = this.queue.indexOf(runner);
           if (index !== -1) {
             this.queue.splice(index, 1);
-            this.cancelledTasks++;
-            this.emitter.emit("task:cancel", {
-              taskId: runner.taskId,
-              reason: "Task cancelled while queued"
-            });
+            if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+              this.timedOutTasks++;
+              this.emitter.emit("task:timeout", {
+                taskId: runner.taskId,
+                timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+              });
+            } else {
+              this.cancelledTasks++;
+              this.emitter.emit("task:cancel", {
+                taskId: runner.taskId,
+                reason: "Task cancelled while queued"
+              });
+            }
             this.checkIdle();
           }
         };
-        this.queue.push(runner);
+        this.insertIntoQueue(runner);
         this.pump();
       }, backoffDelay)
     };
@@ -952,11 +1347,19 @@ var TaskQueue = class {
       if (this.retryEntries.has(retryEntry)) {
         clearTimeout(retryEntry.timerId);
         this.retryEntries.delete(retryEntry);
-        this.cancelledTasks++;
-        this.emitter.emit("task:cancel", {
-          taskId: runner.taskId,
-          reason: "Task cancelled during retry backoff"
-        });
+        if (runner.totalTimedOut || runner.state === "timed_out" /* TIMED_OUT */) {
+          this.timedOutTasks++;
+          this.emitter.emit("task:timeout", {
+            taskId: runner.taskId,
+            timeoutMs: options?.totalTimeoutMs ?? runner.timeoutMs
+          });
+        } else {
+          this.cancelledTasks++;
+          this.emitter.emit("task:cancel", {
+            taskId: runner.taskId,
+            reason: "Task cancelled during retry backoff"
+          });
+        }
         this.checkIdle();
       }
     };
@@ -1003,7 +1406,7 @@ var TaskQueue = class {
   clear() {
     while (this.queue.length > 0) {
       const runner = this.queue.shift();
-      if (runner && runner.state !== "cancelled" /* CANCELLED */) {
+      if (runner && runner.state !== "cancelled" /* CANCELLED */ && runner.state !== "timed_out" /* TIMED_OUT */) {
         runner.cancel("Scheduler cleared");
         this.cancelledTasks++;
         this.emitter.emit("task:cancel", { taskId: runner.taskId, reason: "Scheduler cleared" });
@@ -1053,7 +1456,9 @@ var TaskQueue = class {
       timedOutTasks: this.timedOutTasks,
       retriedTasks: this.retriedTasks,
       totalDispatched: this.totalDispatched,
-      capacity: this.concurrency
+      capacity: this.concurrency,
+      isPaused: this._isPaused,
+      circuitState: this.circuitBreakerCoordinator?.state
     });
   }
 };
@@ -1124,6 +1529,8 @@ var TaskRunner = class {
       }
     }
   }
+  /** Flag indicating if runner was aborted by an overall total timeout deadline */
+  totalTimedOut = false;
   /**
    * Gets the current lifecycle state of the task.
    */
@@ -1156,7 +1563,7 @@ var TaskRunner = class {
    * @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)) {
+    if (this.totalTimedOut || this._state === "cancelled" /* CANCELLED */ || (this.externalSignal?.aborted ?? false)) {
       return false;
     }
     if (!retryOptions || typeof retryOptions.attempts !== "number") {
@@ -1197,15 +1604,16 @@ var TaskRunner = class {
     let abortListener;
     const abortPromise = new Promise((_, reject) => {
       abortListener = () => {
-        if (this._state === "timed_out" /* TIMED_OUT */) {
+        const reason = this.abortController.signal.reason;
+        if (this._state === "timed_out" /* TIMED_OUT */ || reason instanceof AhkoTimeoutError) {
+          this._state = "timed_out" /* TIMED_OUT */;
           reject(
-            new AhkoTimeoutError(
+            reason instanceof AhkoTimeoutError ? reason : 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
@@ -1240,6 +1648,10 @@ var TaskRunner = class {
     }
     taskExecutionPromise.catch(() => {
     });
+    abortPromise.catch(() => {
+    });
+    timeoutPromise?.catch(() => {
+    });
     const racePromises = [
       taskExecutionPromise,
       abortPromise
@@ -1331,6 +1743,31 @@ var TaskRunner = class {
       this.onCancel?.(this);
     }
   }
+  /**
+   * Times out the task, aborting pending or running execution with AhkoTimeoutError.
+   *
+   * @param timeoutMs - Timeout duration in milliseconds.
+   * @param message - Optional custom timeout message.
+   */
+  timeout(timeoutMs, message) {
+    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 = "timed_out" /* TIMED_OUT */;
+    this.totalTimedOut = true;
+    this.clearTimeoutTimer();
+    const timeoutError = new AhkoTimeoutError(
+      message ?? `Task execution timed out after ${timeoutMs}ms`,
+      { timeoutMs }
+    );
+    this.abortController.abort(timeoutError);
+    this.cleanup();
+    if (wasPending) {
+      this.rejectPromise(timeoutError);
+      this.onCancel?.(this);
+    }
+  }
   /**
    * Handles external AbortSignal trigger.
    */
@@ -1349,9 +1786,55 @@ var TaskRunner = class {
 };
 
 // src/ahko.ts
-var Ahko = class {
+var Ahko = class _Ahko {
   /** Internal queue and concurrency manager */
   queue;
+  /** Default schedule options inherited from profile if configured */
+  defaultScheduleOptions;
+  /**
+   * Programmatically loads a declarative configuration into memory.
+   * Works universally across Node.js, browsers, and edge runtimes.
+   *
+   * @param config - File configuration object containing default and named profiles.
+   */
+  static loadConfig(config) {
+    loadConfig(config);
+  }
+  /**
+   * Asynchronously loads a configuration file from disk (Node.js).
+   *
+   * @param filePath - Path to configuration file (default: "config.ahko.json").
+   */
+  static async loadConfigFile(filePath) {
+    return loadConfigFile(filePath);
+  }
+  /**
+   * Resets the active declarative configuration.
+   */
+  static resetConfig() {
+    resetConfig();
+  }
+  /**
+   * Retrieves the currently active declarative configuration.
+   */
+  static getActiveConfig() {
+    return getActiveConfig();
+  }
+  /**
+   * Instantiates an Ahko scheduler initialized with settings from a declarative profile.
+   *
+   * @param profileName - Optional name of the profile (e.g. "api", "background").
+   * @param overrides - Optional scheduler options overriding profile values.
+   * @returns A new configured Ahko instance.
+   */
+  static fromProfile(profileName, overrides) {
+    const profile = getProfileConfig(profileName);
+    return new _Ahko({
+      ...profile,
+      ...overrides,
+      circuitBreaker: overrides?.circuitBreaker ?? profile?.circuitBreaker
+    });
+  }
   /**
    * Initializes a new Ahko scheduler instance.
    *
@@ -1364,79 +1847,152 @@ var Ahko = class {
    * ```
    */
   constructor(options) {
-    this.queue = new TaskQueue(options?.concurrency, options?.minIntervalMs);
+    const profile = options?.profile ? getProfileConfig(options.profile) : getProfileConfig();
+    const mergedOptions = {
+      ...profile,
+      ...options,
+      circuitBreaker: options?.circuitBreaker ?? profile?.circuitBreaker
+    };
+    if (profile) {
+      this.defaultScheduleOptions = {
+        priority: profile.priority,
+        retry: profile.retry,
+        timeoutMs: profile.timeoutMs,
+        totalTimeoutMs: profile.totalTimeoutMs
+      };
+    }
+    this.queue = new TaskQueue(
+      mergedOptions.concurrency,
+      mergedOptions.minIntervalMs,
+      mergedOptions.circuitBreaker
+    );
+  }
+  /**
+   * Pauses scheduler dispatch. In-flight tasks run to completion, but pending tasks remain queued.
+   */
+  pause() {
+    this.queue.pause();
+  }
+  /**
+   * Resumes scheduler dispatch, immediately executing waiting tasks up to available concurrency.
+   */
+  resume() {
+    this.queue.resume();
+  }
+  /**
+   * Checks whether the scheduler is currently paused.
+   */
+  isPaused() {
+    return this.queue.isPaused();
+  }
+  /**
+   * Current circuit breaker state if circuit breaker protection is configured.
+   */
+  get circuitState() {
+    return this.queue.circuitBreakerCoordinator?.state;
+  }
+  /**
+   * Access to the underlying circuit breaker coordinator instance if configured.
+   */
+  get circuitBreaker() {
+    return this.queue.circuitBreakerCoordinator;
+  }
+  /**
+   * Wraps an async function so every execution is automatically routed through this Ahko scheduler.
+   *
+   * @template TArgs - Parameter types of the wrapped function.
+   * @template TReturn - Return type of the wrapped function.
+   * @param fn - The function to wrap.
+   * @param options - Optional scheduling options applied to every wrapped call.
+   * @returns A wrapped function returning a Promise.
+   *
+   * @example
+   * ```typescript
+   * const fetchUser = ahko.wrap(async (id: string) => api.getUser(id), { priority: "high" });
+   * const user = await fetchUser("usr_123");
+   * ```
+   */
+  wrap(fn, options) {
+    if (typeof fn !== "function") {
+      throw new AhkoConfigurationError("Target to wrap must be a valid function.");
+    }
+    return (...args) => {
+      return this.schedule(() => fn(...args), options);
+    };
   }
   /**
    * 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.
+   * @param options - Task-specific scheduling options such as strategy, priority, 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.
-   * @throws {AhkoTimeoutError} If task execution exceeds timeoutMs.
+   * @throws {AhkoTimeoutError} If task execution exceeds timeoutMs or totalTimeoutMs.
+   * @throws {AhkoCircuitBreakerOpenError} If the circuit breaker is OPEN and rejects the 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 }
-   * );
+   * // High priority task
+   * await ahko.schedule(doUrgentWork, { priority: "high" });
    * ```
    */
   schedule(task, options) {
     if (typeof task !== "function") {
       throw new AhkoConfigurationError("Task must be a valid function.");
     }
-    const strategy = options?.strategy ?? "immediate" /* IMMEDIATE */;
+    const mergedOptions = {
+      ...this.defaultScheduleOptions,
+      ...options
+    };
+    const strategy = mergedOptions.strategy ?? "immediate" /* IMMEDIATE */;
     if (strategy === "debounce" /* DEBOUNCE */) {
-      if (!options?.key || typeof options.key !== "string" && typeof options.key !== "symbol") {
+      if (!mergedOptions.key || typeof mergedOptions.key !== "string" && typeof mergedOptions.key !== "symbol") {
         throw new AhkoConfigurationError(
           `Strategy "debounce" requires a valid "key" of type string or symbol.`
         );
       }
-      const waitMs = options.waitMs ?? options.delay;
+      const waitMs = mergedOptions.waitMs ?? mergedOptions.delay;
       if (typeof waitMs !== "number" || Number.isNaN(waitMs) || !Number.isFinite(waitMs) || waitMs < 0) {
         throw new AhkoConfigurationError(
           `Strategy "debounce" requires a non-negative finite "waitMs" or "delay" in milliseconds.`
         );
       }
       return this.queue.debounceCoordinator.schedule(
-        options.key,
+        mergedOptions.key,
         task,
         waitMs,
-        options,
+        mergedOptions,
         (t, opts) => this.schedule(t, { ...opts, strategy: "immediate" /* IMMEDIATE */ })
       );
     }
     if (strategy === "throttle" /* THROTTLE */) {
-      if (!options?.key || typeof options.key !== "string" && typeof options.key !== "symbol") {
+      if (!mergedOptions.key || typeof mergedOptions.key !== "string" && typeof mergedOptions.key !== "symbol") {
         throw new AhkoConfigurationError(
           `Strategy "throttle" requires a valid "key" of type string or symbol.`
         );
       }
-      const waitMs = options.waitMs ?? options.delay;
+      const waitMs = mergedOptions.waitMs ?? mergedOptions.delay;
       if (typeof waitMs !== "number" || Number.isNaN(waitMs) || !Number.isFinite(waitMs) || waitMs < 0) {
         throw new AhkoConfigurationError(
           `Strategy "throttle" requires a non-negative finite "waitMs" or "delay" in milliseconds.`
         );
       }
       return this.queue.throttleCoordinator.schedule(
-        options.key,
+        mergedOptions.key,
         task,
         waitMs,
-        options,
+        mergedOptions,
         (t, opts) => this.schedule(t, { ...opts, strategy: "immediate" /* IMMEDIATE */ })
       );
     }
-    const runner = new TaskRunner(task, options?.signal, options?.timeoutMs);
-    return this.queue.enqueue(runner, options);
+    const runner = new TaskRunner(task, mergedOptions.signal, mergedOptions.timeoutMs);
+    return this.queue.enqueue(runner, mergedOptions);
   }
   /**
    * Convenience method to schedule a task during platform idle opportunities.
@@ -1499,12 +2055,12 @@ var Ahko = class {
   /**
    * Retrieves real-time telemetry metrics from the scheduler.
    *
-   * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, and timed out tasks.
+   * @returns An {@link IAhkoStats} snapshot of active, pending, completed, failed, cancelled, timed out tasks, pause status, and circuit state.
    *
    * @example
    * ```typescript
    * const stats = ahko.stats();
-   * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}`);
+   * console.log(`Active: ${stats.activeTasks}, Pending: ${stats.pendingTasks}, Paused: ${stats.isPaused}`);
    * ```
    */
   stats() {
@@ -1590,7 +2146,7 @@ var Ahko = class {
 };
 
 // src/version.ts
-var VERSION = "0.6.0";
+var VERSION = "1.1.0";
 
 // src/errors/queue.error.ts
 var AhkoQueueError = class extends AhkoError {
@@ -1665,16 +2221,26 @@ function combineSignals(signals) {
 0 && (module.exports = {
   Ahko,
   AhkoCancellationError,
+  AhkoCircuitBreakerOpenError,
   AhkoConfigurationError,
   AhkoError,
   AhkoQueueError,
   AhkoTimeoutError,
+  CircuitBreakerCoordinator,
   DEFAULT_BASE_DELAY,
   DEFAULT_MAX_DELAY,
+  ECircuitState,
   EScheduleStrategy,
   ETaskState,
+  TASK_PRIORITY_WEIGHTS,
   VERSION,
   calculateBackoff,
-  combineSignals
+  combineSignals,
+  getActiveConfig,
+  getProfileConfig,
+  loadConfig,
+  loadConfigFile,
+  resetConfig,
+  resolvePriorityWeight
 });
 //# sourceMappingURL=index.cjs.map