@mrjacket/ahko 0.6.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@ 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).
 
+## [1.1.0] - 2026-09-23 — Declarative Config, Circuit Breaker & Priority Queue
+
+### Added
+- Declarative configuration file support via `config.ahko.json` with multi-profile support (e.g. `default`, `crawler`, `critical-gateway`).
+- Static configuration loaders: `Ahko.loadConfig(config)` for universal programmatic profile loading (Node.js & browser), `Ahko.loadConfigFile(path?)` for asynchronous filesystem loading, and `Ahko.fromProfile(name, overrides?)`.
+- Martin Fowler Circuit Breaker pattern with `ECircuitState` (`CLOSED`, `OPEN`, `HALF_OPEN`), `CircuitBreakerCoordinator`, and `AhkoCircuitBreakerOpenError`:
+  - Protects downstream services by tracking consecutive failures against a `failureThreshold`.
+  - Fast-fails pending and incoming tasks without execution when OPEN.
+  - Automatically transitions to HALF_OPEN after `resetTimeoutMs` cooldown to allow a recovery trial.
+  - Heals to CLOSED on trial success or immediately re-trips to OPEN on trial failure.
+- Priority queue scheduling with stable FIFO ordering:
+  - Supports named priorities (`"high"`, `"normal"`, `"low"`) and arbitrary numerical weights (e.g. `100`, `-5`).
+  - Tasks with higher priority preempt lower priority tasks in the queue; tasks with identical priority preserve strict FIFO ordering.
+- Queue flow control via `ahko.pause()`, `ahko.resume()`, and `ahko.isPaused()`:
+  - Halts dispatching pending tasks without interrupting currently executing tasks.
+  - Immediately dispatches accumulated tasks upon resume up to concurrency limits.
+- Total Timeout Budget (`totalTimeoutMs`):
+  - Sets an overarching execution deadline spanning queue wait time, execution, and retry delays.
+  - Cancels task runners cleanly with `AhkoTimeoutError` when the budget expires.
+- Ergonomic function wrapping via `ahko.wrap(fn, options)`:
+  - Wraps any sync or async function returning a decorated function routed through the scheduler with pre-configured priorities and options.
+- New runnable examples:
+  - `examples/07-circuit-breaker.mjs`: circuit breaker tripping, fast-failing, and cooldown recovery.
+  - `examples/08-priority-queue.mjs`: priority queue ordering and pause/resume flow control.
+  - `config.ahko.example.json`: reference declarative schema configuration file.
+- Extended telemetry in `ahko.stats()`: `isPaused` boolean and `circuitState` indicator.
+
+### Fixed
+- Remediated 2 CodeQL static analysis security alerts:
+  - Alert #4: Removed unused `externalController` declaration in `src/__tests__/e2e.test.ts`.
+  - Alert #3: Removed unused `sleep` helper declaration in `examples/04-retry-backoff-jitter.mjs`.
+
+---
+
+## [1.0.0] - 2026-09-23 — Stable Scheduler Release
+
+### Added
+- Comprehensive End-to-End stress and integration test suite (`src/__tests__/e2e.test.ts`) verifying:
+  - High-concurrency bursts under rate-limited temporal pacing (`minIntervalMs`) and jittered backoff retries.
+  - Interleaved interactive debounce and throttle streams under queue contention.
+  - Cooperative cancellation waves simulating document switches or build cancellations (VS Code / CLI scenarios).
+  - Graceful shutdown workflows clearing pending queues while allowing in-flight tasks to settle cleanly (`ahko.chill()`).
+  - Full lifecycle telemetry stream validation and microservice uncooperative timeout handling.
+- Standalone runnable examples suite (`examples/`) with dedicated `examples/README.md`:
+  - `01-concurrency-and-pacing.mjs`: concurrency limits and temporal pacing.
+  - `02-debounce-search.mjs`: debounced interactive search with Promise coalescing.
+  - `03-throttle-events.mjs`: high-frequency event stream throttling.
+  - `04-retry-backoff-jitter.mjs`: resilient retries with exponential backoff and full jitter.
+  - `05-idle-telemetry.mjs`: non-blocking background tasks and lifecycle event logging.
+  - `06-graceful-shutdown.mjs`: safe process termination sequence.
+- Dedicated npm script `"test:e2e"` for focused integration testing.
+- Documentation restructuring into domain guides (`docs/guides/`) and specifications (`docs/architecture/`), including production architectural recipes (`recipes.md`).
+
+### Changed
+- Connected `DebounceCoordinator` and `ThrottleCoordinator` settlement lifecycles directly to `TaskQueue.checkIdle()`, ensuring that window expirations and coordinator deletions deterministically resolve idle promises and emit `"idle"` events.
+- Transitioned version to stable 1.0.0 baseline with frozen zero-dependency architecture.
+
+---
+
 ## [0.6.0] - 2026-09-23 — Telemetry & DX
 
 ### Added

package/README.md

@@ -13,10 +13,10 @@
     <img src="https://img.shields.io/npm/v/@mrjacket/ahko.svg?color=success" alt="npm version">
   </a>
   <a href="https://www.npmjs.com/package/@mrjacket/ahko">
-    <img src="https://img.shields.io/npm/dm/@mrjacket/ahko.svg" alt="npm downloads">
+    <img src="https://img.shields.io/node/v/@mrjacket/ahko.svg" alt="node">
   </a>
   <a href="https://www.npmjs.com/package/@mrjacket/ahko">
-    <img src="https://img.shields.io/node/v/@mrjacket/ahko.svg" alt="node">
+    <img src="https://img.shields.io/npm/dm/@mrjacket/ahko.svg" alt="npm downloads">
   </a>
   <a href="https://github.com/x-name15/ahko/actions/workflows/ci.yml">
     <img src="https://github.com/x-name15/ahko/actions/workflows/ci.yml/badge.svg" alt="ci">
@@ -30,12 +30,6 @@
   <a href="https://www.npmjs.com/package/@mrjacket/ahko">
     <img src="https://img.shields.io/badge/dependencies-0-success" alt="zero dependencies">
   </a>
-  <a href="https://bundlephobia.com/package/@mrjacket/ahko">
-    <img src="https://img.shields.io/bundlephobia/minzip/@mrjacket/ahko?color=purple" alt="bundle size">
-  </a>
-  <a href="https://github.com/x-name15/ahko">
-    <img src="https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
-  </a>
   <a href="https://github.com/x-name15/ahko/issues">
     <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
   </a>
@@ -290,6 +284,119 @@ console.log(ahko.battery());
 // { level: 3, chill: true, status: "low-energy", quote: "Mwee... my battery is low, but all your tasks are handled completely chill." }
 ```
 
+### 12. Priority-Aware Scheduling
+
+Ensure critical tasks jump ahead of normal or background work while preserving strict FIFO ordering among peers:
+
+```typescript
+// Named priorities: "high" (10), "normal" (0), "low" (-10), or custom numeric weights
+await ahko.schedule(criticalTask, { priority: "high" });
+await ahko.schedule(backgroundSync, { priority: "low" });
+await ahko.schedule(superUrgent, { priority: 100 });
+```
+
+### 13. Circuit Breaker Protection
+
+Protect fragile downstream services and databases from cascading failures. When consecutive failures meet `failureThreshold`, the circuit trips to `OPEN` and fast-fails tasks immediately without execution:
+
+```typescript
+const ahko = new Ahko({
+  concurrency: 2,
+  circuitBreaker: {
+    failureThreshold: 3, // trip after 3 consecutive failures
+    resetTimeoutMs: 15000, // wait 15s before attempting recovery probe
+  },
+});
+
+try {
+  await ahko.schedule(callFlakyService);
+} catch (err) {
+  if (err instanceof AhkoCircuitBreakerOpenError) {
+    console.warn("Fast-failed: Circuit breaker is OPEN!");
+  }
+}
+```
+
+### 14. Pause & Resume Flow Control
+
+Temporarily halt queue dispatching without aborting in-flight tasks. Resuming immediately pumps accumulated tasks up to capacity:
+
+```typescript
+// Stop dispatching new tasks
+ahko.pause();
+console.log(ahko.isPaused()); // true
+
+// In-flight tasks finish peacefully...
+
+// Resume dispatching
+ahko.resume();
+```
+
+### 15. Total Timeout Budget
+
+Enforce an overarching deadline spanning queue wait time, execution, and retries:
+
+```typescript
+// Task will abort with AhkoTimeoutError if total elapsed time exceeds 5000ms
+await ahko.schedule(fetchWithRetries, {
+  totalTimeoutMs: 5000,
+  retry: { attempts: 3, baseDelay: 1000 },
+});
+```
+
+### 16. Function Wrapping (`ahko.wrap`)
+
+Decorate any async function to automatically route every invocation through Ahko:
+
+```typescript
+const fetchUser = ahko.wrap(
+  async (userId: string) => {
+    const res = await fetch(`https://api.example.com/users/${userId}`);
+    return res.json();
+  },
+  { priority: "high", retry: { attempts: 2 } }
+);
+
+// Seamlessly executed via scheduler
+const user = await fetchUser("usr_42");
+```
+
+### 17. Declarative Configuration (`config.ahko.json`)
+
+Define scheduler defaults and workload profiles cleanly in JSON:
+
+```json
+{
+  "default": {
+    "concurrency": 2,
+    "minIntervalMs": 50,
+    "priority": "normal"
+  },
+  "profiles": {
+    "crawler": {
+      "concurrency": 4,
+      "minIntervalMs": 200,
+      "priority": "low"
+    },
+    "critical-gateway": {
+      "concurrency": 1,
+      "circuitBreaker": {
+        "failureThreshold": 3,
+        "resetTimeoutMs": 10000
+      }
+    }
+  }
+}
+```
+
+```typescript
+// Programmatically or from config file:
+Ahko.loadConfig(config);
+
+// Instantiate configured scheduler from profile
+const gateway = Ahko.fromProfile("critical-gateway");
+```
+
 ---
 
 ## Documentation
@@ -300,24 +407,29 @@ Comprehensive guides and technical documentation are available in the [`docs/`](
 |---|---|
 | [**Documentation Portal**](./docs/README.md) | Master overview and index of all guides and specifications. |
 | [**Getting Started**](./docs/guides/getting-started.md) | Quickstart guide, installation, and fundamental usage patterns. |
+| [**Declarative Configuration**](./docs/guides/configuration.md) | Centralizing limits in `config.ahko.json`, `$schema` validation, named profiles, and fallback rules. |
 | [**Library API**](./docs/guides/library.md) | Complete programmatic API reference, TypeScript interfaces, and options. |
 | [**Production Recipes**](./docs/guides/recipes.md) | Battle-tested recipes (paced API client, debounced search, throttled scroll, graceful shutdown). |
 | [**Architecture**](./docs/architecture/ARCHITECTURE.md) | Architectural specifications, lifecycle state machine, and design decisions. |
-| [**Roadmap**](./docs/architecture/ROADMAP.md) | Milestone progression from 0.1.0 through 1.0.0. |
+| [**Roadmap**](./docs/architecture/ROADMAP.md) | Milestone progression from 0.1.0 through 1.1.0. |
 | [**Engineering Log**](./docs/architecture/LOG.md) | Chronological log of engineering decisions and ADRs. |
 
+> **Runnable Examples:** A comprehensive suite of standalone, runnable Node.js scripts is available in the [`examples/`](./examples/) folder. See [`examples/README.md`](./examples/README.md) for details.
+
 ---
 
 ## API Reference
 
 ### `new Ahko(options?: IAhkoOptions)`
 
-Creates an AHKO scheduler instance.
+Creates an ahko scheduler instance.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `concurrency` | `number` | `Infinity` | Maximum concurrent tasks allowed to run simultaneously. Must be $\ge 1$. |
 | `minIntervalMs` | `number` | `0` | Minimum interval in milliseconds between consecutive task starts. Must be $\ge 0$. |
+| `circuitBreaker` | `ICircuitBreakerOptions` | `undefined` | Optional failure threshold and cooldown reset configuration. |
+| `profile` | `string` | `undefined` | Name of declarative profile to inherit settings from. |
 
 ### `ahko.schedule<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>`
 
@@ -326,23 +438,37 @@ Schedules an asynchronous task with full return type inference.
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `strategy` | `"immediate" \| "delay" \| "idle" \| "throttle" \| "debounce"` | `"immediate"` | Scheduling execution strategy. |
+| `priority` | `"high" \| "normal" \| "low" \| number` | `"normal"` | Task priority weight for queue ordering. |
 | `delay` | `number` | `0` | Delay in milliseconds when strategy is `"delay"`. |
 | `key` | `string \| symbol` | `undefined` | Explicit identity key for `"debounce"` and `"throttle"`. |
 | `waitMs` | `number` | `undefined` | Window duration in ms for debounce quiet period or throttle interval. |
 | `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`. |
+| `totalTimeoutMs` | `number` | `undefined` | Total execution budget across wait time, retries, and execution. |
 | `signal` | `AbortSignal` | `undefined` | Optional external `AbortSignal` for cooperative cancellation. |
 
-### `ahko.debounce<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: IScheduleOptions): Promise<T>`
+### `ahko.wrap(fn, options?)`
+
+Returns a wrapped version of `fn` routed through the scheduler.
+
+### `ahko.pause() / ahko.resume() / ahko.isPaused()`
+
+Pauses and resumes task dispatching.
+
+### `ahko.circuitState`
+
+Returns current circuit breaker state (`"closed" | "open" | "half_open"` or `undefined`).
+
+### `ahko.debounce<T>(key, task, waitMs, options?): Promise<T>`
 
 Convenience method scheduling a debounced task with key-based Promise coalescing.
 
-### `ahko.throttle<T>(key: string | symbol, task: ITask<T>, waitMs: number, options?: IScheduleOptions): Promise<T>`
+### `ahko.throttle<T>(key, task, waitMs, options?): Promise<T>`
 
 Convenience method scheduling a throttled task with leading execution and coalesced trailing run.
 
-### `ahko.idle<T>(task: ITask<T>, options?: Omit<IScheduleOptions, "strategy">): Promise<T>`
+### `ahko.idle<T>(task, options?): Promise<T>`
 
 Convenience method scheduling a task under `strategy: "idle"`.
 
@@ -376,7 +502,7 @@ Returns mascot battery status and quote.
 
 ### `ahko.stats(): IAhkoStats`
 
-Returns a snapshot of current task counters, retry counts, total dispatches, and queue capacity.
+Returns a snapshot of current task counters, retry counts, total dispatches, pause status, circuit state, and queue capacity.
 
 ---
 
@@ -388,7 +514,8 @@ All scheduler errors inherit from `AhkoError`:
 - `AhkoCancellationError`: Thrown when a task is aborted.
 - `AhkoConfigurationError`: Thrown when invalid options are provided.
 - `AhkoQueueError`: Thrown when queue constraints are violated.
-- `AhkoTimeoutError`: Thrown when a task exceeds its configured duration.
+- `AhkoTimeoutError`: Thrown when a task exceeds its configured duration or totalTimeoutMs.
+- `AhkoCircuitBreakerOpenError`: Thrown when task execution is fast-failed because the circuit breaker is OPEN.
 
 ---
 

package/dist/ahko.d.ts

@@ -1,12 +1,16 @@
+import type { ECircuitState } from "./models/circuit-breaker.model.js";
+import type { IAhkoFileConfig } from "./models/config.model.js";
 import type { TAhkoEventName, TAhkoEventHandler, TAhkoUnsubscribe } from "./models/events.model.js";
 import type { IAhkoOptions, IScheduleOptions } from "./models/options.model.js";
 import type { IAhkoStats } from "./models/stats.model.js";
 import type { ITask } from "./models/task.model.js";
+import type { CircuitBreakerCoordinator } from "./scheduler/circuit-breaker.js";
 /**
  * Ahko — Low-energy asynchronous task scheduler.
  *
- * Coordinates execution timing, enforces concurrency limits, and cooperates
- * natively with AbortSignal cancellation.
+ * Coordinates execution timing, enforces concurrency limits, manages priorities,
+ * provides circuit-breaker stability, supports pause/resume flow control,
+ * and cooperates natively with AbortSignal cancellation.
  *
  * @example
  * ```typescript
@@ -23,6 +27,37 @@ import type { ITask } from "./models/task.model.js";
 export declare class Ahko {
     /** Internal queue and concurrency manager */
     private readonly queue;
+    /** Default schedule options inherited from profile if configured */
+    private readonly 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: IAhkoFileConfig): void;
+    /**
+     * Asynchronously loads a configuration file from disk (Node.js).
+     *
+     * @param filePath - Path to configuration file (default: "config.ahko.json").
+     */
+    static loadConfigFile(filePath?: string): Promise<IAhkoFileConfig | undefined>;
+    /**
+     * Resets the active declarative configuration.
+     */
+    static resetConfig(): void;
+    /**
+     * Retrieves the currently active declarative configuration.
+     */
+    static getActiveConfig(): IAhkoFileConfig | undefined;
+    /**
+     * 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?: string, overrides?: IAhkoOptions): Ahko;
     /**
      * Initializes a new Ahko scheduler instance.
      *
@@ -35,28 +70,62 @@ export declare class Ahko {
      * ```
      */
     constructor(options?: IAhkoOptions);
+    /**
+     * Pauses scheduler dispatch. In-flight tasks run to completion, but pending tasks remain queued.
+     */
+    pause(): void;
+    /**
+     * Resumes scheduler dispatch, immediately executing waiting tasks up to available concurrency.
+     */
+    resume(): void;
+    /**
+     * Checks whether the scheduler is currently paused.
+     */
+    isPaused(): boolean;
+    /**
+     * Current circuit breaker state if circuit breaker protection is configured.
+     */
+    get circuitState(): ECircuitState | undefined;
+    /**
+     * Access to the underlying circuit breaker coordinator instance if configured.
+     */
+    get circuitBreaker(): CircuitBreakerCoordinator | undefined;
+    /**
+     * 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<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn> | TReturn, options?: IScheduleOptions): (...args: TArgs) => Promise<TReturn>;
     /**
      * 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<T>(task: ITask<T>, options?: IScheduleOptions): Promise<T>;
@@ -102,12 +171,12 @@ export declare class Ahko {
     /**
      * 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(): IAhkoStats;

package/dist/config/config-loader.d.ts

@@ -0,0 +1,31 @@
+import type { IAhkoFileConfig, IAhkoProfileConfig } from "../models/config.model.js";
+/**
+ * Programmatically loads and activates a declarative configuration.
+ * Universal across Node.js, browsers, and edge environments.
+ *
+ * @param config - Complete configuration object conforming to `IAhkoFileConfig`.
+ */
+export declare function loadConfig(config: IAhkoFileConfig): void;
+/**
+ * Resets the currently active configuration in memory to undefined.
+ */
+export declare function resetConfig(): void;
+/**
+ * Asynchronously loads a `config.ahko.json` or custom config file from the filesystem in Node.js.
+ * Sets the active configuration in memory upon successful read and parse.
+ *
+ * @param filePath - Optional relative or absolute path to the configuration file (default: "config.ahko.json").
+ * @returns The parsed configuration object, or `undefined` if not running in Node.js or if file cannot be read.
+ */
+export declare function loadConfigFile(filePath?: string): Promise<IAhkoFileConfig | undefined>;
+/**
+ * Returns the currently active declarative configuration, attempting auto-discovery if in Node.js.
+ */
+export declare function getActiveConfig(): IAhkoFileConfig | undefined;
+/**
+ * Retrieves a specific profile configuration by name, or the default profile if no name is provided.
+ *
+ * @param profileName - Optional name of the profile (e.g. "api", "background").
+ * @returns The profile configuration if defined, or undefined.
+ */
+export declare function getProfileConfig(profileName?: string): IAhkoProfileConfig | undefined;

package/dist/config/index.d.ts

@@ -0,0 +1 @@
+export { loadConfig, resetConfig, loadConfigFile, getActiveConfig, getProfileConfig, } from "./config-loader.js";

package/dist/errors/circuit-breaker.error.d.ts

@@ -0,0 +1,24 @@
+import { AhkoError } from "./ahko.error.js";
+/**
+ * Options describing the circuit breaker open state.
+ */
+export interface IAhkoCircuitBreakerErrorOptions {
+    /** Time remaining in milliseconds before the circuit attempts half-open trial */
+    resetTimeoutMs?: number;
+    /** Timestamp when the circuit tripped open */
+    trippedAt?: number;
+    /** Consecutive failures that caused the trip */
+    consecutiveFailures?: number;
+}
+/**
+ * Thrown when attempting to execute a task while the scheduler's circuit breaker is in OPEN state.
+ */
+export declare class AhkoCircuitBreakerOpenError extends AhkoError {
+    /** Time remaining in milliseconds before trial execution is allowed */
+    readonly resetTimeoutMs?: number;
+    /** Timestamp when the circuit tripped open */
+    readonly trippedAt?: number;
+    /** Total consecutive failures that caused the trip */
+    readonly consecutiveFailures?: number;
+    constructor(message?: string, options?: IAhkoCircuitBreakerErrorOptions);
+}

package/dist/errors/index.d.ts

@@ -3,3 +3,4 @@ export * from "./cancellation.error.js";
 export * from "./configuration.error.js";
 export * from "./queue.error.js";
 export * from "./timeout.error.js";
+export * from "./circuit-breaker.error.js";