@xyph3r/circuit-breaker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xyph3r
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# `@xyph3r/circuit-breaker`
+
+Wrap any async function with circuit breaker semantics.
+
+When a dependency starts failing, the circuit breaker stops calling it. Your service degrades gracefully instead of piling up timeouts. When the dependency recovers, traffic resumes automatically.
+
+Three states:
+
+- **Closed** — normal operation. Calls go through. Failures are tracked.
+- **Open** — the dependency is considered down. Calls are rejected immediately or routed to a fallback. No traffic reaches the dependency.
+- **Half-open** — a probe call is allowed through to test recovery. Success closes the circuit. Failure reopens it.
+
+## Install
+
+```bash
+npm install @xyph3r/circuit-breaker
+```
+
+or
+
+```bash
+bun add @xyph3r/circuit-breaker
+```
+
+## When to use it
+
+Use a circuit breaker when:
+
+- you call an external API, database, or service that can go down
+- slow responses from a dependency can exhaust your connection pool or threads
+- you want automatic recovery detection without manual intervention
+- you need a fallback path when a dependency is unavailable
+
+Do not use it when:
+
+- the call is purely in-memory with no external dependency
+- failures are expected and handled by business logic (e.g. validation errors)
+- you need per-request rate limiting (use `@xyph3r/rate-limiter` instead)
+
+## Quick start
+
+```ts
+import { CircuitBreakerBuilder } from "@xyph3r/circuit-breaker";
+
+const breaker = new CircuitBreakerBuilder()
+  .forConsecutiveFailures({ threshold: 5 })
+  .withResetTimeout(30_000)
+  .build();
+
+const result = await breaker.fire(() => fetch("https://api.example.com/data"));
+```
+
+## Failure detection strategies
+
+### Consecutive failures
+
+Open the circuit after N consecutive failures. A single success resets the count.
+
+```ts
+const breaker = new CircuitBreakerBuilder()
+  .forConsecutiveFailures({ threshold: 5 })
+  .withResetTimeout(30_000)
+  .build();
+```
+
+Use this when:
+
+- a dependency is either up or down
+- intermittent errors should not trip the breaker
+- you want the simplest possible configuration
+
+### Failure rate
+
+Open the circuit when the failure rate exceeds a threshold within a sliding time window. Requires a minimum number of samples before the rate is evaluated.
+
+```ts
+const breaker = new CircuitBreakerBuilder()
+  .forFailureRate({
+    threshold: 0.5,
+    windowMs: 60_000,
+    minSamples: 10,
+  })
+  .withResetTimeout(30_000)
+  .build();
+```
+
+Use this when:
+
+- a low background error rate is acceptable
+- you want to react to sustained degradation, not a single burst
+- the dependency handles mixed traffic with different reliability profiles
+
+## Fallback
+
+Provide a fallback function when you want graceful degradation instead of errors.
+
+```ts
+const result = await breaker.fire(
+  () => fetch("https://api.example.com/data"),
+  () => ({ cached: true, data: getCachedData() }),
+);
+```
+
+The fallback runs when the circuit is open or when all half-open probe slots are occupied.
+
+## Wrapping a function
+
+Use `wrap()` to create a permanently protected version of a function.
+
+```ts
+async function fetchUser(id: string): Promise<User> {
+  const response = await fetch(`https://api.example.com/users/${id}`);
+  return response.json();
+}
+
+const safeFetchUser = breaker.wrap(fetchUser);
+
+const user = await safeFetchUser("42");
+```
+
+With a fallback:
+
+```ts
+const safeFetchUser = breaker.wrap(
+  fetchUser,
+  async (id) => ({ id, name: "Unknown", cached: true }),
+);
+```
+
+## Filtering failures
+
+By default, every thrown error counts as a failure. Use `isFailure()` to control which errors trip the breaker.
+
+```ts
+const breaker = new CircuitBreakerBuilder()
+  .forConsecutiveFailures({ threshold: 5 })
+  .withResetTimeout(30_000)
+  .isFailure((error) => {
+    if (error instanceof HttpError && error.status === 404) return false;
+    if (error instanceof HttpError && error.status === 400) return false;
+    return true;
+  })
+  .build();
+```
+
+Errors that `isFailure` returns `false` for are still thrown to the caller — they just don't affect the circuit state.
+
+## Events
+
+Subscribe to lifecycle events for logging, metrics, or alerting.
+
+```ts
+breaker.on("stateChange", (info) => {
+  console.log(`Circuit ${info.previousState} → ${info.state}`);
+});
+
+breaker.on("success", (info) => {
+  metrics.increment("circuit.success");
+});
+
+breaker.on("failure", (info) => {
+  metrics.increment("circuit.failure");
+  logger.warn("dependency failure", { error: info.error });
+});
+
+breaker.on("reject", (info) => {
+  metrics.increment("circuit.reject");
+});
+```
+
+Remove a listener with `off()`:
+
+```ts
+breaker.off("stateChange", handler);
+```
+
+## Half-open probes
+
+When the circuit is open and the reset timeout elapses, the next call transitions to half-open. One probe call (configurable with `withHalfOpenMax()`) is allowed through:
+
+- If the probe succeeds, the circuit closes and normal traffic resumes.
+- If the probe fails, the circuit reopens and the reset timeout restarts.
+- Additional calls while the probe slot is occupied are rejected.
+
+```ts
+const breaker = new CircuitBreakerBuilder()
+  .forConsecutiveFailures({ threshold: 5 })
+  .withResetTimeout(30_000)
+  .withHalfOpenMax(1)
+  .build();
+```
+
+## Factory vs Builder
+
+Use the Builder when you want readability and progressive configuration.
+
+```ts
+const breaker = new CircuitBreakerBuilder()
+  .forConsecutiveFailures({ threshold: 5 })
+  .withResetTimeout(30_000)
+  .withHalfOpenMax(1)
+  .isFailure((error) => error.message !== "not-a-real-error")
+  .build();
+```
+
+Use `createCircuitBreaker()` when a plain config object is enough.
+
+```ts
+import { createCircuitBreaker } from "@xyph3r/circuit-breaker";
+
+const breaker = createCircuitBreaker({
+  strategy: "consecutive",
+  threshold: 5,
+  resetTimeoutMs: 30_000,
+});
+```
+
+## Custom strategies
+
+Implement `FailureDetectionStrategy` to plug in your own failure detection logic.
+
+```ts
+import type { FailureDetectionStrategy } from "@xyph3r/circuit-breaker";
+
+class JitteredFailureStrategy implements FailureDetectionStrategy {
+  recordSuccess(): void { /* ... */ }
+  recordFailure(): void { /* ... */ }
+  shouldOpen(): boolean { /* ... */ }
+  reset(): void { /* ... */ }
+}
+
+const breaker = new CircuitBreakerBuilder()
+  .useStrategy(new JitteredFailureStrategy())
+  .withResetTimeout(30_000)
+  .build();
+```
+
+## Public API
+
+### `CircuitBreakerBuilder`
+
+- `.forConsecutiveFailures({ threshold })`
+- `.forFailureRate({ threshold, windowMs, minSamples })`
+- `.useStrategy(strategy)`
+- `.withResetTimeout(ms)`
+- `.withHalfOpenMax(max)`
+- `.isFailure(predicate)`
+- `.withClock(now)`
+- `.build()`
+
+### `CircuitBreaker`
+
+- `fire(fn, fallback?)`
+- `wrap(fn, fallback?)`
+- `state` — current state: `"closed"`, `"open"`, or `"half-open"`
+- `on(event, handler)`
+- `off(event, handler)`
+- `reset()`
+
+### Events
+
+- `stateChange` — `{ state, previousState, timestamp }`
+- `success` — `{ state, timestamp }`
+- `failure` — `{ state, error, timestamp }`
+- `reject` — `{ state, error, timestamp }`
+
+### Errors
+
+- `CircuitBreakerOpenError` — thrown when the circuit is open and no fallback is provided
+- `CircuitBreakerConfigurationError` — thrown by the builder on invalid configuration
+
+## Publishing
+
+The package is set up so `npm publish` builds `dist/` during `prepack` and runs tests during `prepublishOnly`.
+
+Release flow:
+
+1. Install dependencies with `bun install` or `npm install`.
+2. Verify with `bun run test` and `bun run build`.
+3. Inspect the tarball with `npm pack --dry-run`.
+4. Log in with `npm login` if needed.
+5. Publish with `npm publish --access public --provenance`.
+
+## License
+
+MIT

package/dist/core/circuit-breaker-builder.d.ts

@@ -0,0 +1,30 @@
+import type { FailureDetectionStrategy } from "../strategies/failure-detection-strategy.js";
+import { CircuitBreaker } from "./circuit-breaker.js";
+/**
+ * Pattern: Builder
+ * Problem: Construction spans strategy selection, timeouts, failure predicates, and probe limits.
+ * Solution: The builder makes each choice explicit and validates the combination at build time.
+ * Trade-off: More ceremony than a constructor; justified because the config surface is non-trivial.
+ */
+export declare class CircuitBreakerBuilder {
+    private strategy;
+    private resetTimeoutMs;
+    private halfOpenMax;
+    private failurePredicate;
+    private clock;
+    forConsecutiveFailures(options: {
+        threshold: number;
+    }): this;
+    forFailureRate(options: {
+        threshold: number;
+        windowMs: number;
+        minSamples: number;
+    }): this;
+    useStrategy(strategy: FailureDetectionStrategy): this;
+    withResetTimeout(ms: number): this;
+    withHalfOpenMax(max: number): this;
+    isFailure(predicate: (error: Error) => boolean): this;
+    withClock(now: () => number): this;
+    build(): CircuitBreaker;
+}
+//# sourceMappingURL=circuit-breaker-builder.d.ts.map

package/dist/core/circuit-breaker-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker-builder.d.ts","sourceRoot":"","sources":["../../src/core/circuit-breaker-builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAG5F,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,gBAAgB,CAA0C;IAClE,OAAO,CAAC,KAAK,CAA6B;IAE1C,sBAAsB,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAM5D,cAAc,CAAC,OAAO,EAAE;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI;IAuBR,WAAW,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAKrD,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMlC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMlC,SAAS,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,GAAG,IAAI;IAKrD,SAAS,CAAC,GAAG,EAAE,MAAM,MAAM,GAAG,IAAI;IAKlC,KAAK,IAAI,cAAc;CAgBxB"}

package/dist/core/circuit-breaker-builder.js

@@ -0,0 +1,79 @@
+import { CircuitBreakerConfigurationError } from "../errors.js";
+import { ConsecutiveFailureStrategy } from "../strategies/consecutive-failure-strategy.js";
+import { FailureRateStrategy } from "../strategies/failure-rate-strategy.js";
+import { CircuitBreaker } from "./circuit-breaker.js";
+/**
+ * Pattern: Builder
+ * Problem: Construction spans strategy selection, timeouts, failure predicates, and probe limits.
+ * Solution: The builder makes each choice explicit and validates the combination at build time.
+ * Trade-off: More ceremony than a constructor; justified because the config surface is non-trivial.
+ */
+export class CircuitBreakerBuilder {
+    strategy;
+    resetTimeoutMs = 30_000;
+    halfOpenMax = 1;
+    failurePredicate;
+    clock;
+    forConsecutiveFailures(options) {
+        validatePositiveInteger(options.threshold, "forConsecutiveFailures()");
+        this.strategy = new ConsecutiveFailureStrategy(options.threshold);
+        return this;
+    }
+    forFailureRate(options) {
+        if (!Number.isFinite(options.threshold) ||
+            options.threshold <= 0 ||
+            options.threshold > 1) {
+            throw new CircuitBreakerConfigurationError("forFailureRate() threshold must be between 0 (exclusive) and 1 (inclusive).");
+        }
+        validatePositiveNumber(options.windowMs, "forFailureRate() windowMs");
+        validatePositiveInteger(options.minSamples, "forFailureRate() minSamples");
+        this.strategy = new FailureRateStrategy(options.threshold, options.windowMs, options.minSamples, this.clock ?? (() => Date.now()));
+        return this;
+    }
+    useStrategy(strategy) {
+        this.strategy = strategy;
+        return this;
+    }
+    withResetTimeout(ms) {
+        validatePositiveNumber(ms, "withResetTimeout()");
+        this.resetTimeoutMs = ms;
+        return this;
+    }
+    withHalfOpenMax(max) {
+        validatePositiveInteger(max, "withHalfOpenMax()");
+        this.halfOpenMax = max;
+        return this;
+    }
+    isFailure(predicate) {
+        this.failurePredicate = predicate;
+        return this;
+    }
+    withClock(now) {
+        this.clock = now;
+        return this;
+    }
+    build() {
+        if (!this.strategy) {
+            throw new CircuitBreakerConfigurationError("A failure detection strategy is required. " +
+                "Call forConsecutiveFailures(), forFailureRate(), or useStrategy().");
+        }
+        return new CircuitBreaker({
+            strategy: this.strategy,
+            resetTimeoutMs: this.resetTimeoutMs,
+            halfOpenMax: this.halfOpenMax,
+            isFailure: this.failurePredicate ?? (() => true),
+            now: this.clock ?? (() => Date.now()),
+        });
+    }
+}
+function validatePositiveNumber(value, label) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new CircuitBreakerConfigurationError(`${label} requires a positive number.`);
+    }
+}
+function validatePositiveInteger(value, label) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new CircuitBreakerConfigurationError(`${label} requires a positive integer.`);
+    }
+}
+//# sourceMappingURL=circuit-breaker-builder.js.map

package/dist/core/circuit-breaker-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker-builder.js","sourceRoot":"","sources":["../../src/core/circuit-breaker-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,OAAO,qBAAqB;IACxB,QAAQ,CAAuC;IAC/C,cAAc,GAAG,MAAM,CAAC;IACxB,WAAW,GAAG,CAAC,CAAC;IAChB,gBAAgB,CAA0C;IAC1D,KAAK,CAA6B;IAE1C,sBAAsB,CAAC,OAA8B;QACnD,uBAAuB,CAAC,OAAO,CAAC,SAAS,EAAE,0BAA0B,CAAC,CAAC;QACvE,IAAI,CAAC,QAAQ,GAAG,IAAI,0BAA0B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,OAId;QACC,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;YACnC,OAAO,CAAC,SAAS,IAAI,CAAC;YACtB,OAAO,CAAC,SAAS,GAAG,CAAC,EACrB,CAAC;YACD,MAAM,IAAI,gCAAgC,CACxC,6EAA6E,CAC9E,CAAC;QACJ,CAAC;QAED,sBAAsB,CAAC,OAAO,CAAC,QAAQ,EAAE,2BAA2B,CAAC,CAAC;QACtE,uBAAuB,CAAC,OAAO,CAAC,UAAU,EAAE,6BAA6B,CAAC,CAAC;QAE3E,IAAI,CAAC,QAAQ,GAAG,IAAI,mBAAmB,CACrC,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,UAAU,EAClB,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CACjC,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,WAAW,CAAC,QAAkC;QAC5C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gBAAgB,CAAC,EAAU;QACzB,sBAAsB,CAAC,EAAE,EAAE,oBAAoB,CAAC,CAAC;QACjD,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,eAAe,CAAC,GAAW;QACzB,uBAAuB,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,SAAS,CAAC,SAAoC;QAC5C,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,SAAS,CAAC,GAAiB;QACzB,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,gCAAgC,CACxC,4CAA4C;gBAC1C,oEAAoE,CACvE,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,cAAc,CAAC;YACxB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,IAAI,CAAC,gBAAgB,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YAChD,GAAG,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;SACtC,CAAC,CAAC;IACL,CAAC;CACF;AAED,SAAS,sBAAsB,CAAC,KAAa,EAAE,KAAa;IAC1D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,gCAAgC,CACxC,GAAG,KAAK,8BAA8B,CACvC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAa,EAAE,KAAa;IAC3D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,gCAAgC,CACxC,GAAG,KAAK,+BAA+B,CACxC,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/circuit-breaker.d.ts

@@ -0,0 +1,38 @@
+import type { FailureDetectionStrategy } from "../strategies/failure-detection-strategy.js";
+import type { CircuitBreakerEventHandler, CircuitBreakerEventType, CircuitBreakerState } from "../types.js";
+import type { CircuitBreakerContext, CircuitState } from "../states/circuit-state.js";
+export interface CircuitBreakerOptions {
+    strategy: FailureDetectionStrategy;
+    resetTimeoutMs: number;
+    halfOpenMax: number;
+    isFailure: (error: Error) => boolean;
+    now: () => number;
+}
+/**
+ * Pattern: Proxy
+ * Problem: Callers should not manage failure tracking, timeouts, or state transitions themselves.
+ * Solution: CircuitBreaker.fire(fn) wraps fn transparently — sometimes calling through, sometimes short-circuiting.
+ * Trade-off: One wrapper per dependency call; justified because the alternative is scattered failure handling.
+ */
+export declare class CircuitBreaker implements CircuitBreakerContext {
+    readonly resetTimeoutMs: number;
+    readonly halfOpenMax: number;
+    readonly now: () => number;
+    readonly isFailure: (error: Error) => boolean;
+    readonly strategy: FailureDetectionStrategy;
+    private currentState;
+    private readonly emitter;
+    constructor(options: CircuitBreakerOptions);
+    get state(): CircuitBreakerState;
+    fire<T>(fn: () => Promise<T>, fallback?: () => T | Promise<T>): Promise<T>;
+    wrap<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, fallback?: (...args: TArgs) => TResult | Promise<TResult>): (...args: TArgs) => Promise<TResult>;
+    on(event: CircuitBreakerEventType, handler: CircuitBreakerEventHandler): void;
+    off(event: CircuitBreakerEventType, handler: CircuitBreakerEventHandler): void;
+    reset(): void;
+    transition(state: CircuitState): void;
+    emitStateChange(from: CircuitBreakerState, to: CircuitBreakerState): void;
+    emitSuccess(): void;
+    emitFailure(error: Error): void;
+    emitReject(error: Error): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/core/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAC5F,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,qBAAqB,EACrB,YAAY,EACb,MAAM,4BAA4B,CAAC;AAIpC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,wBAAwB,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACrC,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,qBAAqB;IAC1D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAE5C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;gBAEhD,OAAO,EAAE,qBAAqB;IAU1C,IAAI,KAAK,IAAI,mBAAmB,CAE/B;IAEK,IAAI,CAAC,CAAC,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC;IAIb,IAAI,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EACnC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACxD,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC;IAQvC,EAAE,CACA,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI;IAIP,GAAG,CACD,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI;IAIP,KAAK,IAAI,IAAI;IASb,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAKrC,eAAe,CACb,IAAI,EAAE,mBAAmB,EACzB,EAAE,EAAE,mBAAmB,GACtB,IAAI;IAQP,WAAW,IAAI,IAAI;IAOnB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAQ/B,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAO/B"}

package/dist/core/circuit-breaker.js

@@ -0,0 +1,80 @@
+import { ClosedState } from "../states/closed-state.js";
+import { CircuitBreakerEventEmitter } from "./event-emitter.js";
+/**
+ * Pattern: Proxy
+ * Problem: Callers should not manage failure tracking, timeouts, or state transitions themselves.
+ * Solution: CircuitBreaker.fire(fn) wraps fn transparently — sometimes calling through, sometimes short-circuiting.
+ * Trade-off: One wrapper per dependency call; justified because the alternative is scattered failure handling.
+ */
+export class CircuitBreaker {
+    resetTimeoutMs;
+    halfOpenMax;
+    now;
+    isFailure;
+    strategy;
+    currentState;
+    emitter = new CircuitBreakerEventEmitter();
+    constructor(options) {
+        this.strategy = options.strategy;
+        this.resetTimeoutMs = options.resetTimeoutMs;
+        this.halfOpenMax = options.halfOpenMax;
+        this.isFailure = options.isFailure;
+        this.now = options.now;
+        this.currentState = new ClosedState(this);
+    }
+    get state() {
+        return this.currentState.name;
+    }
+    async fire(fn, fallback) {
+        return this.currentState.fire(fn, fallback);
+    }
+    wrap(fn, fallback) {
+        return (...args) => this.fire(() => fn(...args), fallback ? () => fallback(...args) : undefined);
+    }
+    on(event, handler) {
+        this.emitter.on(event, handler);
+    }
+    off(event, handler) {
+        this.emitter.off(event, handler);
+    }
+    reset() {
+        this.strategy.reset();
+        const closed = new ClosedState(this);
+        if (this.currentState.name !== "closed") {
+            this.emitStateChange(this.currentState.name, "closed");
+        }
+        this.currentState = closed;
+    }
+    transition(state) {
+        this.currentState = state;
+        state.onEntry();
+    }
+    emitStateChange(from, to) {
+        this.emitter.emit("stateChange", {
+            state: to,
+            previousState: from,
+            timestamp: this.now(),
+        });
+    }
+    emitSuccess() {
+        this.emitter.emit("success", {
+            state: this.currentState.name,
+            timestamp: this.now(),
+        });
+    }
+    emitFailure(error) {
+        this.emitter.emit("failure", {
+            state: this.currentState.name,
+            error,
+            timestamp: this.now(),
+        });
+    }
+    emitReject(error) {
+        this.emitter.emit("reject", {
+            state: this.currentState.name,
+            error,
+            timestamp: this.now(),
+        });
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/core/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"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"}

package/dist/core/create-circuit-breaker.d.ts

@@ -0,0 +1,4 @@
+import type { CreateCircuitBreakerOptions } from "../types.js";
+import type { CircuitBreaker } from "./circuit-breaker.js";
+export declare function createCircuitBreaker(options?: CreateCircuitBreakerOptions): CircuitBreaker;
+//# sourceMappingURL=create-circuit-breaker.d.ts.map

package/dist/core/create-circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/core/create-circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,cAAc,CAgChB"}

package/dist/core/create-circuit-breaker.js

@@ -0,0 +1,30 @@
+import { CircuitBreakerBuilder } from "./circuit-breaker-builder.js";
+export function createCircuitBreaker(options = {}) {
+    const builder = new CircuitBreakerBuilder();
+    if (options.now) {
+        builder.withClock(options.now);
+    }
+    if (options.strategy === "failure-rate") {
+        builder.forFailureRate({
+            threshold: options.threshold ?? 0.5,
+            windowMs: options.windowMs ?? 60_000,
+            minSamples: options.minSamples ?? 10,
+        });
+    }
+    else {
+        builder.forConsecutiveFailures({
+            threshold: options.threshold ?? 5,
+        });
+    }
+    if (options.resetTimeoutMs !== undefined) {
+        builder.withResetTimeout(options.resetTimeoutMs);
+    }
+    if (options.halfOpenMax !== undefined) {
+        builder.withHalfOpenMax(options.halfOpenMax);
+    }
+    if (options.isFailure) {
+        builder.isFailure(options.isFailure);
+    }
+    return builder.build();
+}
+//# sourceMappingURL=create-circuit-breaker.js.map

package/dist/core/create-circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-circuit-breaker.js","sourceRoot":"","sources":["../../src/core/create-circuit-breaker.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,MAAM,UAAU,oBAAoB,CAClC,UAAuC,EAAE;IAEzC,MAAM,OAAO,GAAG,IAAI,qBAAqB,EAAE,CAAC;IAE5C,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QACxC,OAAO,CAAC,cAAc,CAAC;YACrB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,GAAG;YACnC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM;YACpC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE;SACrC,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,sBAAsB,CAAC;YAC7B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACzC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/core/event-emitter.d.ts

@@ -0,0 +1,8 @@
+import type { CircuitBreakerEventHandler, CircuitBreakerEventType } from "../types.js";
+export declare class CircuitBreakerEventEmitter {
+    private readonly listeners;
+    on(event: CircuitBreakerEventType, handler: CircuitBreakerEventHandler): void;
+    off(event: CircuitBreakerEventType, handler: CircuitBreakerEventHandler): void;
+    emit(event: CircuitBreakerEventType, ...args: Parameters<CircuitBreakerEventHandler>): void;
+}
+//# sourceMappingURL=event-emitter.d.ts.map

package/dist/core/event-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-emitter.d.ts","sourceRoot":"","sources":["../../src/core/event-emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAErB,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGtB;IAEJ,EAAE,CACA,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI;IASP,GAAG,CACD,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI;IAIP,IAAI,CACF,KAAK,EAAE,uBAAuB,EAC9B,GAAG,IAAI,EAAE,UAAU,CAAC,0BAA0B,CAAC,GAC9C,IAAI;CAUR"}

package/dist/core/event-emitter.js

@@ -0,0 +1,24 @@
+export class CircuitBreakerEventEmitter {
+    listeners = new Map();
+    on(event, handler) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+    }
+    off(event, handler) {
+        this.listeners.get(event)?.delete(handler);
+    }
+    emit(event, ...args) {
+        const set = this.listeners.get(event);
+        if (!set) {
+            return;
+        }
+        for (const handler of set) {
+            handler(...args);
+        }
+    }
+}
+//# sourceMappingURL=event-emitter.js.map

package/dist/core/event-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-emitter.js","sourceRoot":"","sources":["../../src/core/event-emitter.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,0BAA0B;IACpB,SAAS,GAAG,IAAI,GAAG,EAGjC,CAAC;IAEJ,EAAE,CACA,KAA8B,EAC9B,OAAmC;QAEnC,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnB,CAAC;IAED,GAAG,CACD,KAA8B,EAC9B,OAAmC;QAEnC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,CACF,KAA8B,EAC9B,GAAG,IAA4C;QAE/C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QAED,KAAK,MAAM,OAAO,IAAI,GAAG,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export declare class CircuitBreakerConfigurationError extends Error {
+    constructor(message: string);
+}
+export declare class CircuitBreakerOpenError extends Error {
+    readonly remainingMs: number;
+    constructor(message: string, remainingMs: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,gCAAiC,SAAQ,KAAK;gBAC7C,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aAG9B,WAAW,EAAE,MAAM;gBADnC,OAAO,EAAE,MAAM,EACC,WAAW,EAAE,MAAM;CAKtC"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+export class CircuitBreakerConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CircuitBreakerConfigurationError";
+    }
+}
+export class CircuitBreakerOpenError extends Error {
+    remainingMs;
+    constructor(message, remainingMs) {
+        super(message);
+        this.remainingMs = remainingMs;
+        this.name = "CircuitBreakerOpenError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,gCAAiC,SAAQ,KAAK;IACzD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;IACjD,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAG9B;IAFlB,YACE,OAAe,EACC,WAAmB;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,gBAAW,GAAX,WAAW,CAAQ;QAGnC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { CircuitBreaker } from "./core/circuit-breaker.js";
+export { CircuitBreakerBuilder } from "./core/circuit-breaker-builder.js";
+export { createCircuitBreaker, } from "./core/create-circuit-breaker.js";
+export { ConsecutiveFailureStrategy } from "./strategies/consecutive-failure-strategy.js";
+export { FailureRateStrategy } from "./strategies/failure-rate-strategy.js";
+export type { FailureDetectionStrategy } from "./strategies/failure-detection-strategy.js";
+export { CircuitBreakerConfigurationError, CircuitBreakerOpenError, } from "./errors.js";
+export type { CircuitBreakerEventHandler, CircuitBreakerEventInfo, CircuitBreakerEventType, CircuitBreakerLike, CircuitBreakerState, CreateCircuitBreakerOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EACL,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EAAE,MAAM,8CAA8C,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAC5E,YAAY,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AAC3F,OAAO,EACL,gCAAgC,EAChC,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { CircuitBreaker } from "./core/circuit-breaker.js";
+export { CircuitBreakerBuilder } from "./core/circuit-breaker-builder.js";
+export { createCircuitBreaker, } from "./core/create-circuit-breaker.js";
+export { ConsecutiveFailureStrategy } from "./strategies/consecutive-failure-strategy.js";
+export { FailureRateStrategy } from "./strategies/failure-rate-strategy.js";
+export { CircuitBreakerConfigurationError, CircuitBreakerOpenError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EACL,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,0BAA0B,EAAE,MAAM,8CAA8C,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAE5E,OAAO,EACL,gCAAgC,EAChC,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/states/circuit-state.d.ts

@@ -0,0 +1,26 @@
+import type { CircuitBreakerState } from "../types.js";
+import type { FailureDetectionStrategy } from "../strategies/failure-detection-strategy.js";
+export interface CircuitBreakerContext {
+    readonly resetTimeoutMs: number;
+    readonly halfOpenMax: number;
+    readonly now: () => number;
+    readonly isFailure: (error: Error) => boolean;
+    readonly strategy: FailureDetectionStrategy;
+    transition(state: CircuitState): void;
+    emitStateChange(from: CircuitBreakerState, to: CircuitBreakerState): void;
+    emitSuccess(): void;
+    emitFailure(error: Error): void;
+    emitReject(error: Error): void;
+}
+/**
+ * Pattern: State
+ * Problem: fire() behaves completely differently depending on circuit state.
+ * Solution: Each state is a class that implements CircuitState; the breaker delegates to the current state.
+ * Trade-off: Three classes instead of if/else; justified because state transitions are the core logic.
+ */
+export interface CircuitState {
+    readonly name: CircuitBreakerState;
+    onEntry(): void;
+    fire<T>(fn: () => Promise<T>, fallback: (() => T | Promise<T>) | undefined): Promise<T>;
+}
+//# sourceMappingURL=circuit-state.d.ts.map

package/dist/states/circuit-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-state.d.ts","sourceRoot":"","sources":["../../src/states/circuit-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAE5F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACtC,eAAe,CACb,IAAI,EAAE,mBAAmB,EACzB,EAAE,EAAE,mBAAmB,GACtB,IAAI,CAAC;IACR,WAAW,IAAI,IAAI,CAAC;IACpB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAChC,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,OAAO,IAAI,IAAI,CAAC;IAChB,IAAI,CAAC,CAAC,EACJ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,EAAE,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GAC3C,OAAO,CAAC,CAAC,CAAC,CAAC;CACf"}

package/dist/states/circuit-state.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=circuit-state.js.map

package/dist/states/circuit-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-state.js","sourceRoot":"","sources":["../../src/states/circuit-state.ts"],"names":[],"mappings":""}

package/dist/states/closed-state.d.ts

@@ -0,0 +1,9 @@
+import type { CircuitBreakerContext, CircuitState } from "./circuit-state.js";
+export declare class ClosedState implements CircuitState {
+    private readonly context;
+    readonly name: "closed";
+    constructor(context: CircuitBreakerContext);
+    onEntry(): void;
+    fire<T>(fn: () => Promise<T>, _fallback: (() => T | Promise<T>) | undefined): Promise<T>;
+}
+//# sourceMappingURL=closed-state.d.ts.map

package/dist/states/closed-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closed-state.d.ts","sourceRoot":"","sources":["../../src/states/closed-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG9E,qBAAa,WAAY,YAAW,YAAY;IAGlC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;gBAEL,OAAO,EAAE,qBAAqB;IAE3D,OAAO,IAAI,IAAI;IAIT,IAAI,CAAC,CAAC,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GAC5C,OAAO,CAAC,CAAC,CAAC;CA0Bd"}

package/dist/states/closed-state.js

@@ -0,0 +1,34 @@
+import { OpenState } from "./open-state.js";
+export class ClosedState {
+    context;
+    name = "closed";
+    constructor(context) {
+        this.context = context;
+    }
+    onEntry() {
+        this.context.strategy.reset();
+    }
+    async fire(fn, _fallback) {
+        try {
+            const result = await fn();
+            this.context.strategy.recordSuccess();
+            this.context.emitSuccess();
+            return result;
+        }
+        catch (error) {
+            const asError = error instanceof Error ? error : new Error(String(error));
+            if (!this.context.isFailure(asError)) {
+                throw error;
+            }
+            this.context.strategy.recordFailure();
+            this.context.emitFailure(asError);
+            if (this.context.strategy.shouldOpen()) {
+                const next = new OpenState(this.context);
+                this.context.emitStateChange("closed", "open");
+                this.context.transition(next);
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=closed-state.js.map

package/dist/states/closed-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closed-state.js","sourceRoot":"","sources":["../../src/states/closed-state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,OAAO,WAAW;IAGO;IAFpB,IAAI,GAAG,QAAiB,CAAC;IAElC,YAA6B,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;IAAG,CAAC;IAE/D,OAAO;QACL,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,IAAI,CACR,EAAoB,EACpB,SAA6C;QAE7C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAE5D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrC,MAAM,KAAK,CAAC;YACd,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAElC,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC;gBACvC,MAAM,IAAI,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAC/C,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;YAED,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/states/half-open-state.d.ts

@@ -0,0 +1,10 @@
+import type { CircuitBreakerContext, CircuitState } from "./circuit-state.js";
+export declare class HalfOpenState implements CircuitState {
+    private readonly context;
+    readonly name: "half-open";
+    private activeProbes;
+    constructor(context: CircuitBreakerContext);
+    onEntry(): void;
+    fire<T>(fn: () => Promise<T>, fallback: (() => T | Promise<T>) | undefined): Promise<T>;
+}
+//# sourceMappingURL=half-open-state.d.ts.map

package/dist/states/half-open-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"half-open-state.d.ts","sourceRoot":"","sources":["../../src/states/half-open-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI9E,qBAAa,aAAc,YAAW,YAAY;IAIpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IACrC,OAAO,CAAC,YAAY,CAAK;gBAEI,OAAO,EAAE,qBAAqB;IAE3D,OAAO,IAAI,IAAI;IAIT,IAAI,CAAC,CAAC,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,EAAE,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GAC3C,OAAO,CAAC,CAAC,CAAC;CA2Cd"}

package/dist/states/half-open-state.js

@@ -0,0 +1,45 @@
+import { CircuitBreakerOpenError } from "../errors.js";
+import { ClosedState } from "./closed-state.js";
+import { OpenState } from "./open-state.js";
+export class HalfOpenState {
+    context;
+    name = "half-open";
+    activeProbes = 0;
+    constructor(context) {
+        this.context = context;
+    }
+    onEntry() {
+        this.activeProbes = 0;
+    }
+    async fire(fn, fallback) {
+        if (this.activeProbes >= this.context.halfOpenMax) {
+            const error = new CircuitBreakerOpenError("Circuit breaker is half-open and all probe slots are occupied.", 0);
+            this.context.emitReject(error);
+            if (fallback) {
+                return fallback();
+            }
+            throw error;
+        }
+        this.activeProbes += 1;
+        try {
+            const result = await fn();
+            this.context.emitSuccess();
+            const next = new ClosedState(this.context);
+            this.context.emitStateChange("half-open", "closed");
+            this.context.transition(next);
+            return result;
+        }
+        catch (error) {
+            const asError = error instanceof Error ? error : new Error(String(error));
+            if (!this.context.isFailure(asError)) {
+                throw error;
+            }
+            this.context.emitFailure(asError);
+            const next = new OpenState(this.context);
+            this.context.emitStateChange("half-open", "open");
+            this.context.transition(next);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=half-open-state.js.map

package/dist/states/half-open-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"half-open-state.js","sourceRoot":"","sources":["../../src/states/half-open-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,OAAO,aAAa;IAIK;IAHpB,IAAI,GAAG,WAAoB,CAAC;IAC7B,YAAY,GAAG,CAAC,CAAC;IAEzB,YAA6B,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;IAAG,CAAC;IAE/D,OAAO;QACL,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,IAAI,CACR,EAAoB,EACpB,QAA4C;QAE5C,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,IAAI,uBAAuB,CACvC,gEAAgE,EAChE,CAAC,CACF,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAE/B,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,QAAQ,EAAE,CAAC;YACpB,CAAC;YAED,MAAM,KAAK,CAAC;QACd,CAAC;QAED,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QAEvB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAE3B,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;YACpD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAE9B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAE5D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrC,MAAM,KAAK,CAAC;YACd,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAElC,MAAM,IAAI,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;YAClD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAE9B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/states/open-state.d.ts

@@ -0,0 +1,10 @@
+import type { CircuitBreakerContext, CircuitState } from "./circuit-state.js";
+export declare class OpenState implements CircuitState {
+    private readonly context;
+    readonly name: "open";
+    private openedAt;
+    constructor(context: CircuitBreakerContext);
+    onEntry(): void;
+    fire<T>(fn: () => Promise<T>, fallback: (() => T | Promise<T>) | undefined): Promise<T>;
+}
+//# sourceMappingURL=open-state.d.ts.map

package/dist/states/open-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-state.d.ts","sourceRoot":"","sources":["../../src/states/open-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG9E,qBAAa,SAAU,YAAW,YAAY;IAIhC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAK;gBAEQ,OAAO,EAAE,qBAAqB;IAE3D,OAAO,IAAI,IAAI;IAIT,IAAI,CAAC,CAAC,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,EAAE,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GAC3C,OAAO,CAAC,CAAC,CAAC;CAwBd"}

package/dist/states/open-state.js

@@ -0,0 +1,30 @@
+import { CircuitBreakerOpenError } from "../errors.js";
+import { HalfOpenState } from "./half-open-state.js";
+export class OpenState {
+    context;
+    name = "open";
+    openedAt = 0;
+    constructor(context) {
+        this.context = context;
+    }
+    onEntry() {
+        this.openedAt = this.context.now();
+    }
+    async fire(fn, fallback) {
+        const elapsed = this.context.now() - this.openedAt;
+        if (elapsed >= this.context.resetTimeoutMs) {
+            const next = new HalfOpenState(this.context);
+            this.context.emitStateChange("open", "half-open");
+            this.context.transition(next);
+            return next.fire(fn, fallback);
+        }
+        const remainingMs = this.context.resetTimeoutMs - elapsed;
+        const error = new CircuitBreakerOpenError("Circuit breaker is open.", remainingMs);
+        this.context.emitReject(error);
+        if (fallback) {
+            return fallback();
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=open-state.js.map

package/dist/states/open-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-state.js","sourceRoot":"","sources":["../../src/states/open-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,MAAM,OAAO,SAAS;IAIS;IAHpB,IAAI,GAAG,MAAe,CAAC;IACxB,QAAQ,GAAG,CAAC,CAAC;IAErB,YAA6B,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;IAAG,CAAC;IAE/D,OAAO;QACL,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,IAAI,CACR,EAAoB,EACpB,QAA4C;QAE5C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QAEnD,IAAI,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC7C,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;YAClD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC;QAC1D,MAAM,KAAK,GAAG,IAAI,uBAAuB,CACvC,0BAA0B,EAC1B,WAAW,CACZ,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAE/B,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,EAAE,CAAC;QACpB,CAAC;QAED,MAAM,KAAK,CAAC;IACd,CAAC;CACF"}

package/dist/strategies/consecutive-failure-strategy.d.ts

@@ -0,0 +1,11 @@
+import type { FailureDetectionStrategy } from "./failure-detection-strategy.js";
+export declare class ConsecutiveFailureStrategy implements FailureDetectionStrategy {
+    private readonly threshold;
+    private consecutiveFailures;
+    constructor(threshold: number);
+    recordSuccess(): void;
+    recordFailure(): void;
+    shouldOpen(): boolean;
+    reset(): void;
+}
+//# sourceMappingURL=consecutive-failure-strategy.d.ts.map

package/dist/strategies/consecutive-failure-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consecutive-failure-strategy.d.ts","sourceRoot":"","sources":["../../src/strategies/consecutive-failure-strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAEhF,qBAAa,0BAA2B,YAAW,wBAAwB;IAG7D,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,mBAAmB,CAAK;gBAEH,SAAS,EAAE,MAAM;IAE9C,aAAa,IAAI,IAAI;IAIrB,aAAa,IAAI,IAAI;IAIrB,UAAU,IAAI,OAAO;IAIrB,KAAK,IAAI,IAAI;CAGd"}

package/dist/strategies/consecutive-failure-strategy.js

@@ -0,0 +1,20 @@
+export class ConsecutiveFailureStrategy {
+    threshold;
+    consecutiveFailures = 0;
+    constructor(threshold) {
+        this.threshold = threshold;
+    }
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+    }
+    recordFailure() {
+        this.consecutiveFailures += 1;
+    }
+    shouldOpen() {
+        return this.consecutiveFailures >= this.threshold;
+    }
+    reset() {
+        this.consecutiveFailures = 0;
+    }
+}
+//# sourceMappingURL=consecutive-failure-strategy.js.map

package/dist/strategies/consecutive-failure-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consecutive-failure-strategy.js","sourceRoot":"","sources":["../../src/strategies/consecutive-failure-strategy.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,0BAA0B;IAGR;IAFrB,mBAAmB,GAAG,CAAC,CAAC;IAEhC,YAA6B,SAAiB;QAAjB,cAAS,GAAT,SAAS,CAAQ;IAAG,CAAC;IAElD,aAAa;QACX,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,aAAa;QACX,IAAI,CAAC,mBAAmB,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,SAAS,CAAC;IACpD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/strategies/failure-detection-strategy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pattern: Strategy
+ * Problem: Failure detection logic differs between consecutive-count and failure-rate approaches.
+ * Solution: Both implement FailureDetectionStrategy; the circuit breaker delegates without knowing which.
+ * Trade-off: One extra indirection; justified because strategies diverge significantly.
+ */
+export interface FailureDetectionStrategy {
+    recordSuccess(): void;
+    recordFailure(): void;
+    shouldOpen(): boolean;
+    reset(): void;
+}
+//# sourceMappingURL=failure-detection-strategy.d.ts.map

package/dist/strategies/failure-detection-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-detection-strategy.d.ts","sourceRoot":"","sources":["../../src/strategies/failure-detection-strategy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,aAAa,IAAI,IAAI,CAAC;IACtB,aAAa,IAAI,IAAI,CAAC;IACtB,UAAU,IAAI,OAAO,CAAC;IACtB,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/strategies/failure-detection-strategy.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=failure-detection-strategy.js.map

package/dist/strategies/failure-detection-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-detection-strategy.js","sourceRoot":"","sources":["../../src/strategies/failure-detection-strategy.ts"],"names":[],"mappings":""}

package/dist/strategies/failure-rate-strategy.d.ts

@@ -0,0 +1,15 @@
+import type { FailureDetectionStrategy } from "./failure-detection-strategy.js";
+export declare class FailureRateStrategy implements FailureDetectionStrategy {
+    private readonly threshold;
+    private readonly windowMs;
+    private readonly minSamples;
+    private readonly now;
+    private samples;
+    constructor(threshold: number, windowMs: number, minSamples: number, now: () => number);
+    recordSuccess(): void;
+    recordFailure(): void;
+    shouldOpen(): boolean;
+    reset(): void;
+    private prune;
+}
+//# sourceMappingURL=failure-rate-strategy.d.ts.map

package/dist/strategies/failure-rate-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-rate-strategy.d.ts","sourceRoot":"","sources":["../../src/strategies/failure-rate-strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAOhF,qBAAa,mBAAoB,YAAW,wBAAwB;IAIhE,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IANtB,OAAO,CAAC,OAAO,CAAgB;gBAGZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,MAAM;IAGpC,aAAa,IAAI,IAAI;IAKrB,aAAa,IAAI,IAAI;IAKrB,UAAU,IAAI,OAAO;IAUrB,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,KAAK;CAId"}

package/dist/strategies/failure-rate-strategy.js

@@ -0,0 +1,37 @@
+export class FailureRateStrategy {
+    threshold;
+    windowMs;
+    minSamples;
+    now;
+    samples = [];
+    constructor(threshold, windowMs, minSamples, now) {
+        this.threshold = threshold;
+        this.windowMs = windowMs;
+        this.minSamples = minSamples;
+        this.now = now;
+    }
+    recordSuccess() {
+        this.prune();
+        this.samples.push({ timestamp: this.now(), success: true });
+    }
+    recordFailure() {
+        this.prune();
+        this.samples.push({ timestamp: this.now(), success: false });
+    }
+    shouldOpen() {
+        this.prune();
+        if (this.samples.length < this.minSamples) {
+            return false;
+        }
+        const failures = this.samples.filter((s) => !s.success).length;
+        return failures / this.samples.length >= this.threshold;
+    }
+    reset() {
+        this.samples = [];
+    }
+    prune() {
+        const cutoff = this.now() - this.windowMs;
+        this.samples = this.samples.filter((s) => s.timestamp > cutoff);
+    }
+}
+//# sourceMappingURL=failure-rate-strategy.js.map

package/dist/strategies/failure-rate-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-rate-strategy.js","sourceRoot":"","sources":["../../src/strategies/failure-rate-strategy.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,mBAAmB;IAIX;IACA;IACA;IACA;IANX,OAAO,GAAa,EAAE,CAAC;IAE/B,YACmB,SAAiB,EACjB,QAAgB,EAChB,UAAkB,EAClB,GAAiB;QAHjB,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,eAAU,GAAV,UAAU,CAAQ;QAClB,QAAG,GAAH,GAAG,CAAc;IACjC,CAAC;IAEJ,aAAa;QACX,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,aAAa;QACX,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QAC/D,OAAO,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC;IAC1D,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAEO,KAAK;QACX,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC1C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export type CircuitBreakerState = "closed" | "open" | "half-open";
+export type CircuitBreakerEventType = "stateChange" | "success" | "failure" | "reject";
+export interface CircuitBreakerEventInfo {
+    state: CircuitBreakerState;
+    previousState?: CircuitBreakerState;
+    error?: Error;
+    timestamp: number;
+}
+export type CircuitBreakerEventHandler = (info: CircuitBreakerEventInfo) => void;
+export interface CircuitBreakerLike {
+    readonly state: CircuitBreakerState;
+    fire<T>(fn: () => Promise<T>, fallback?: () => T | Promise<T>): Promise<T>;
+    wrap<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, fallback?: (...args: TArgs) => TResult | Promise<TResult>): (...args: TArgs) => Promise<TResult>;
+    on(event: CircuitBreakerEventType, handler: CircuitBreakerEventHandler): void;
+    off(event: CircuitBreakerEventType, handler: CircuitBreakerEventHandler): void;
+    reset(): void;
+}
+export interface CreateCircuitBreakerOptions {
+    strategy?: "consecutive" | "failure-rate";
+    threshold?: number;
+    windowMs?: number;
+    minSamples?: number;
+    resetTimeoutMs?: number;
+    halfOpenMax?: number;
+    isFailure?: (error: Error) => boolean;
+    now?: () => number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAElE,MAAM,MAAM,uBAAuB,GAC/B,aAAa,GACb,SAAS,GACT,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,0BAA0B,GAAG,CACvC,IAAI,EAAE,uBAAuB,KAC1B,IAAI,CAAC;AAEV,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IAEpC,IAAI,CAAC,CAAC,EACJ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,CAAC;IAEd,IAAI,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EACnC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACxD,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAExC,EAAE,CACA,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI,CAAC;IAER,GAAG,CACD,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,0BAA0B,GAClC,IAAI,CAAC;IAER,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@xyph3r/circuit-breaker",
+  "version": "0.1.0",
+  "description": "Wrap any async function with circuit breaker semantics — closed, open, half-open.",
+  "author": "xyph3r",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/faisalahmedsifat/circuit-breaker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/faisalahmedsifat/circuit-breaker/issues"
+  },
+  "homepage": "https://github.com/faisalahmedsifat/circuit-breaker#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "bun test test/*.test.ts",
+    "test:node": "rm -rf .test-dist && tsc -p tsconfig.test.json && node --test .test-dist/test/*.test.js",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run test:node"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "keywords": [
+    "circuit-breaker",
+    "resilience",
+    "fault-tolerance",
+    "retry",
+    "fallback",
+    "state-machine",
+    "proxy"
+  ]
+}