@prash0029/circuit-breaker 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,392 @@
+/** Circuit breaker states. */
+declare enum BreakerState {
+    /** Normal operation. Calls pass through. Failures raise the count. */
+    CLOSED = "CLOSED",
+    /** Tripped. Calls are rejected immediately without invoking the wrapped fn. */
+    OPEN = "OPEN",
+    /** Trial window. Calls are allowed to probe recovery. */
+    HALF_OPEN = "HALF_OPEN"
+}
+/** Which level of the two-level breaker rejected a call. */
+type BreakerLevel = "service" | "endpoint";
+/** Per-breaker tuning. Any field omitted falls back to registry defaults. */
+interface RuleTuning {
+    /** Count value that trips a CLOSED breaker to OPEN. */
+    failureThreshold?: number;
+    /** Time (ms) a breaker stays OPEN before allowing a trial call (HALF_OPEN). */
+    cooldownMs?: number;
+    /** Consecutive trial successes required in HALF_OPEN to close. */
+    successThreshold?: number;
+}
+/** Status-code classification shared by both rule types. */
+interface StatusClassification {
+    /** Response statuses counted as success (count -1). */
+    successServerStatus?: number[];
+    /** Response statuses counted as failure (count +1). */
+    failedServerResStatus?: number[];
+}
+/** Hooks a rule can carry. */
+interface RuleHooks {
+    /**
+     * Called when THIS rule's breaker changes state. Runs in addition to the
+     * registry-wide `onStateChange`. Use it to react per endpoint/service:
+     * alert, flip a feature flag, warm a fallback, etc.
+     */
+    onStateChange?: (event: StateChangeEvent) => void;
+    /**
+     * Recipients to alert for THIS rule's transitions. Surfaced on the
+     * StateChangeEvent so an alerter (e.g. {@link emailAlerter}) can mail the
+     * right people per route. Does not send anything on its own.
+     */
+    alertEmails?: string[];
+}
+/** A rule scoped to a single endpoint (one outgoing route). */
+interface EndpointRule extends RuleTuning, StatusClassification, RuleHooks {
+    type: "endpoint";
+    /** Substring searched in the outgoing request path; rule applies if found. */
+    match: string;
+}
+/** A rule scoped to a whole service (aggregates its non-skipped endpoints). */
+interface ServiceRule extends RuleTuning, StatusClassification, RuleHooks {
+    type: "service";
+    /** Substring identifying the service (e.g. host) in the outgoing path. */
+    match: string;
+    /** Endpoint substrings under this service that must NOT count toward it. */
+    skipList?: string[];
+}
+type Rule = EndpointRule | ServiceRule;
+/** Resolved, fully-populated tuning used by a live breaker. */
+interface ResolvedTuning {
+    failureThreshold: number;
+    cooldownMs: number;
+    successThreshold: number;
+}
+interface RegistryConfig {
+    /** Route checklist evaluated against every outgoing request, in order. */
+    rules: Rule[];
+    /** Tuning applied to any rule that omits a field. */
+    defaults?: RuleTuning;
+    /**
+     * Decides success/failure when a matched rule gives no status lists.
+     * Default: 2xx is success, everything else failure.
+     */
+    defaultIsSuccess?: (status: number) => boolean;
+    /**
+     * What part of the URL the `match`/`skipList` substrings test against.
+     * "path" (default) strips the query string — avoids matching/logging tokens
+     * or PII carried in query params.
+     */
+    matchOn?: "path" | "url";
+    /** Called whenever any breaker changes state. For logging/metrics. */
+    onStateChange?: (event: StateChangeEvent) => void;
+}
+interface StateChangeEvent {
+    level: BreakerLevel;
+    /** The rule `match` string that keys this breaker. Never the raw URL. */
+    key: string;
+    from: BreakerState;
+    to: BreakerState;
+    at: number;
+    /** Recipients configured on the rule (`alertEmails`), if any. */
+    alertEmails?: string[];
+}
+/** Identifies an outgoing request to guard. */
+interface GuardRequest {
+    url: string;
+    method?: string;
+}
+/** Snapshot of a single breaker for inspection. */
+interface BreakerSnapshot {
+    state: BreakerState;
+    /** Current leaky-bucket count. */
+    count: number;
+    openedAt: number | null;
+}
+/** Outcome of classifying a response/error against a rule. */
+type Outcome = "success" | "failure";
+
+/** Injectable clock so tests need not sleep. */
+type Clock = () => number;
+/**
+ * A single in-memory leaky-bucket circuit breaker.
+ *
+ * - failure raises `count` by 1; success lowers it by 1 (floored at 0)
+ * - `count >= failureThreshold` trips CLOSED -> OPEN
+ * - after `cooldownMs` an OPEN breaker allows trial calls (HALF_OPEN)
+ * - `successThreshold` consecutive trial successes close it; any trial failure
+ *   re-opens it
+ *
+ * Knows nothing about service/endpoint keys; the registry composes two per call.
+ * HALF_OPEN admits concurrent probes (no in-flight reservation) by design.
+ */
+declare class Breaker {
+    private readonly tuning;
+    private readonly now;
+    private readonly onTransition?;
+    private state;
+    private count;
+    private halfOpenSuccesses;
+    private openedAt;
+    constructor(tuning: ResolvedTuning, now?: Clock, onTransition?: ((from: BreakerState, to: BreakerState) => void) | undefined);
+    /**
+     * Whether a call may proceed. Performs the OPEN -> HALF_OPEN transition when
+     * the cooldown has elapsed. Does not mutate counts. Call once per guarded
+     * call, before invoking the wrapped fn.
+     */
+    canRequest(): boolean;
+    /** Record a successful guarded call. */
+    onSuccess(): void;
+    /** Record a failed guarded call. */
+    onFailure(): void;
+    /** Earliest epoch ms a rejected caller may retry (cooldown end). */
+    retryAt(): number;
+    snapshot(): BreakerSnapshot;
+    /** Force back to CLOSED (manual operator reset). */
+    reset(): void;
+    private maybeHalfOpen;
+    private open;
+    private close;
+    private transition;
+}
+
+/**
+ * Thrown when a request is rejected because its service- or endpoint-level
+ * breaker is OPEN. The wrapped request was never sent.
+ */
+declare class CircuitOpenError extends Error {
+    readonly level: BreakerLevel;
+    /** The rule `match` string keying the open breaker. Not the raw URL. */
+    readonly key: string;
+    /** Epoch ms when callers may retry (breaker eligible for HALF_OPEN trial). */
+    readonly retryAt: number;
+    constructor(args: {
+        level: BreakerLevel;
+        key: string;
+        retryAt: number;
+    });
+}
+/** Type guard for catch blocks. */
+declare function isCircuitOpenError(error: unknown): error is CircuitOpenError;
+
+/** A request's resolved breakers, returned by {@link CircuitBreaker.resolve}. */
+interface Matched {
+    service?: {
+        rule: Rule;
+        breaker: Breaker;
+    };
+    endpoint?: {
+        rule: Rule;
+        breaker: Breaker;
+    };
+}
+/**
+ * Config-driven, two-level circuit breaker. Built once per process from a rule
+ * checklist, then placed in front of every outgoing request (directly via
+ * {@link guard} or through the axios/fetch adapters).
+ *
+ * Each request is matched against the rules to find its service rule and its
+ * endpoint rule. The request passes only if both matched breakers are non-open;
+ * the response status then classifies the call as success (count -1) or failure
+ * (count +1) on each level. Requests matching no rule pass through untouched.
+ *
+ * State is in process memory only; each replica trips independently.
+ */
+declare class CircuitBreaker {
+    private readonly config;
+    private readonly now;
+    private readonly matchOn;
+    private readonly isSuccess;
+    private readonly serviceBreakers;
+    private readonly endpointBreakers;
+    constructor(config: RegistryConfig, now?: Clock);
+    /**
+     * Guard an outgoing request. Resolves the rules for `req.url`, rejects with
+     * {@link CircuitOpenError} (without sending) when either matched breaker is
+     * open, otherwise runs `fn`, classifies the result by status, and records the
+     * outcome on both levels. The response is returned as-is even when its status
+     * counts as a failure; network errors are recorded then re-thrown.
+     */
+    guard<T>(req: GuardRequest, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Resolve which service/endpoint breakers apply to a request. Low-level seam
+     * for adapters; most callers should use {@link guard}.
+     */
+    resolve(req: GuardRequest): Matched;
+    /**
+     * Return a {@link CircuitOpenError} if either matched breaker is open (and
+     * advance OPEN -> HALF_OPEN when due), else null. Does not send anything.
+     */
+    checkOpen(matched: Matched): CircuitOpenError | null;
+    /** Record the outcome of a completed request on its matched breakers. */
+    settle(matched: Matched, status: number | undefined): void;
+    /**
+     * Wrap a request function once and get back a guarded function with the same
+     * signature. `req` may be static or derived per call from the arguments.
+     */
+    wrap<Args extends unknown[], T>(req: GuardRequest | ((...args: Args) => GuardRequest), fn: (...args: Args) => Promise<T>): (...args: Args) => Promise<T>;
+    /** Inspect a breaker by level and rule-match key. Null if not yet created. */
+    stateOf(level: BreakerLevel, key: string): BreakerSnapshot | null;
+    /** Force a single breaker back to CLOSED. */
+    reset(level: BreakerLevel, key: string): void;
+    /** Force every breaker back to CLOSED. */
+    resetAll(): void;
+    /**
+     * Snapshot every live breaker, grouped by level and keyed by rule `match`.
+     * Only breakers that have seen at least one request appear.
+     */
+    snapshots(): {
+        service: Record<string, BreakerSnapshot>;
+        endpoint: Record<string, BreakerSnapshot>;
+    };
+    /**
+     * Print the state of every live breaker, one line each. Pass a custom sink
+     * (e.g. a logger) instead of the default `console.log`.
+     */
+    printStatus(log?: (line: string) => void): void;
+    private record;
+    private breakerFor;
+    private resolveTuning;
+}
+
+/** Default success predicate: any 2xx. */
+declare function defaultIsSuccess(status: number): boolean;
+/**
+ * Classify a response status against a rule.
+ *
+ * Precedence:
+ *  1. status in `failedServerResStatus` -> failure
+ *  2. status in `successServerStatus`   -> success
+ *  3. otherwise -> `isSuccess(status)` (registry default, 2xx)
+ *
+ * `status === undefined` (network error, no response) is always a failure.
+ */
+declare function classifyStatus(status: number | undefined, rule: StatusClassification, isSuccess: (status: number) => boolean): Outcome;
+/**
+ * Best-effort status extraction for both fetch (`Response.status`) and axios
+ * (`response.status`, error `err.response.status`) shapes.
+ */
+declare function statusOf(value: unknown, isError: boolean): number | undefined;
+
+interface MatchResult {
+    /** First service rule whose match is in the path and not excluded by skipList. */
+    service?: ServiceRule;
+    /** First endpoint rule whose match is in the path. */
+    endpoint?: EndpointRule;
+}
+/**
+ * Reduce a URL to the string the rules test against. With matchOn "path" the
+ * query string is dropped so tokens/PII in query params are never matched or
+ * surfaced. Falls back to the raw input when it is not a parseable URL (e.g. a
+ * relative path passed to a client with a baseURL).
+ */
+declare function matchTarget(url: string, matchOn: "path" | "url"): string;
+/**
+ * Resolve which service and endpoint rules apply to an outgoing target.
+ * First match wins for each level (rules are evaluated in declared order).
+ */
+declare function resolveRules(fullUrl: string, target: string, rules: Rule[]): MatchResult;
+
+/** Minimal structural type for a fetch implementation (no DOM lib needed). */
+type FetchLike = (input: unknown, init?: unknown) => Promise<unknown>;
+/**
+ * Wrap a fetch implementation so every call is guarded by the breaker. The
+ * returned function has the same signature as `fetch`. A non-2xx Response is
+ * still returned to the caller (fetch does not throw on HTTP errors); the
+ * breaker classifies it by status. Network rejections are recorded then
+ * re-thrown. A request whose breaker is open rejects with CircuitOpenError and
+ * is never sent.
+ *
+ * Defaults to the global `fetch` (Node 18+). Pass `fetchImpl` to use a custom
+ * client or a per-instance fetch.
+ */
+declare function wrapFetch(breaker: CircuitBreaker, fetchImpl?: FetchLike): FetchLike;
+
+interface AxiosConfigLike {
+    url?: string;
+    baseURL?: string;
+    method?: string;
+    [key: string]: unknown;
+}
+interface InterceptorManagerLike<V> {
+    use(onFulfilled?: (value: V) => V | Promise<V>, onRejected?: (error: unknown) => unknown): number;
+}
+/** Structural subset of an axios instance: just the interceptor managers. */
+interface AxiosInstanceLike {
+    interceptors: {
+        request: InterceptorManagerLike<AxiosConfigLike>;
+        response: InterceptorManagerLike<{
+            status?: number;
+            config?: AxiosConfigLike;
+        }>;
+    };
+}
+/**
+ * Attach the breaker to an axios instance via interceptors so every request
+ * through it is guarded. Open breakers reject the request before it is sent;
+ * responses and errors are classified by status and recorded.
+ *
+ * Works against any object shaped like an axios instance (axios, an
+ * axios.create() instance, or a compatible client). Returns the same instance.
+ *
+ * Known limitation: a request that is cancelled after passing the open check
+ * records no outcome (neither success nor failure).
+ */
+declare function attachAxios<T extends AxiosInstanceLike>(client: T, breaker: CircuitBreaker): T;
+
+/**
+ * Structural subset of a nodemailer transporter. Any object with a compatible
+ * `sendMail` works (nodemailer's `createTransport(...)` result, a mock, etc.).
+ * The transporter is injected so SMTP credentials live in your env / secrets
+ * manager, never in this package or its config.
+ */
+interface MailTransporter {
+    sendMail(message: {
+        from?: string;
+        to: string | string[];
+        subject: string;
+        text?: string;
+        html?: string;
+    }): Promise<unknown>;
+}
+interface EmailAlertOptions {
+    /** Your nodemailer transporter (or anything matching MailTransporter). */
+    transporter: MailTransporter;
+    /** From address. Required by most SMTP servers. */
+    from?: string;
+    /**
+     * Which transitions send mail. Default: only OPEN (a breaker tripped).
+     */
+    when?: BreakerState[];
+    /** Recipients used when a rule has no `alertEmails` of its own. */
+    to?: string[];
+    /** Override the subject line. */
+    subject?: (event: StateChangeEvent) => string;
+    /** Override the body. Return `text` and/or `html`. */
+    body?: (event: StateChangeEvent) => {
+        text?: string;
+        html?: string;
+    };
+    /** Sink for send failures. Defaults to console.error. */
+    log?: (message: string, error: unknown) => void;
+}
+/**
+ * Build an `onStateChange` handler that emails an alert when a breaker
+ * transitions into one of `when` (default: OPEN only). Recipients come from the
+ * rule's `alertEmails`, falling back to `options.to`. If no recipients resolve,
+ * nothing is sent.
+ *
+ * Sending is non-blocking and never throws into the breaker: a sendMail failure
+ * is caught and logged so alerting can never affect guarded traffic.
+ *
+ * Attach it registry-wide (fires for every rule) or per rule.
+ */
+declare function emailAlerter(options: EmailAlertOptions): (event: StateChangeEvent) => void;
+
+/**
+ * Build a circuit breaker from a rule checklist. Create one per process at
+ * startup, then place it in front of outgoing requests via the axios/fetch
+ * adapters or {@link CircuitBreaker.guard} / {@link CircuitBreaker.wrap}.
+ */
+declare function createBreaker(config: RegistryConfig, now?: Clock): CircuitBreaker;
+
+export { type AxiosInstanceLike, Breaker, type BreakerLevel, type BreakerSnapshot, BreakerState, CircuitBreaker, CircuitOpenError, type Clock, type EmailAlertOptions, type EndpointRule, type FetchLike, type GuardRequest, type MailTransporter, type MatchResult, type Matched, type Outcome, type RegistryConfig, type ResolvedTuning, type Rule, type RuleHooks, type RuleTuning, type ServiceRule, type StateChangeEvent, type StatusClassification, attachAxios, classifyStatus, createBreaker, defaultIsSuccess, emailAlerter, isCircuitOpenError, matchTarget, resolveRules, statusOf, wrapFetch };