@prash0029/circuit-breaker 0.1.0

package/dist/index.js

@@ -0,0 +1,544 @@
+// src/types.ts
+var BreakerState = /* @__PURE__ */ ((BreakerState2) => {
+  BreakerState2["CLOSED"] = "CLOSED";
+  BreakerState2["OPEN"] = "OPEN";
+  BreakerState2["HALF_OPEN"] = "HALF_OPEN";
+  return BreakerState2;
+})(BreakerState || {});
+
+// src/breaker.ts
+var Breaker = class {
+  constructor(tuning, now = Date.now, onTransition) {
+    this.tuning = tuning;
+    this.now = now;
+    this.onTransition = onTransition;
+  }
+  tuning;
+  now;
+  onTransition;
+  state = "CLOSED" /* CLOSED */;
+  count = 0;
+  halfOpenSuccesses = 0;
+  openedAt = null;
+  /**
+   * 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() {
+    this.maybeHalfOpen();
+    return this.state !== "OPEN" /* OPEN */;
+  }
+  /** Record a successful guarded call. */
+  onSuccess() {
+    if (this.state === "HALF_OPEN" /* HALF_OPEN */) {
+      this.halfOpenSuccesses += 1;
+      if (this.halfOpenSuccesses >= this.tuning.successThreshold) {
+        this.close();
+      }
+      return;
+    }
+    if (this.state === "CLOSED" /* CLOSED */ && this.count > 0) {
+      this.count -= 1;
+    }
+  }
+  /** Record a failed guarded call. */
+  onFailure() {
+    if (this.state === "HALF_OPEN" /* HALF_OPEN */) {
+      this.open();
+      return;
+    }
+    if (this.state === "CLOSED" /* CLOSED */) {
+      this.count += 1;
+      if (this.count >= this.tuning.failureThreshold) {
+        this.open();
+      }
+    }
+  }
+  /** Earliest epoch ms a rejected caller may retry (cooldown end). */
+  retryAt() {
+    if (this.openedAt === null) {
+      return this.now();
+    }
+    return this.openedAt + this.tuning.cooldownMs;
+  }
+  snapshot() {
+    return { state: this.state, count: this.count, openedAt: this.openedAt };
+  }
+  /** Force back to CLOSED (manual operator reset). */
+  reset() {
+    this.close();
+  }
+  maybeHalfOpen() {
+    if (this.state === "OPEN" /* OPEN */ && this.openedAt !== null && this.now() - this.openedAt >= this.tuning.cooldownMs) {
+      this.halfOpenSuccesses = 0;
+      this.transition("HALF_OPEN" /* HALF_OPEN */);
+    }
+  }
+  open() {
+    this.openedAt = this.now();
+    this.halfOpenSuccesses = 0;
+    this.transition("OPEN" /* OPEN */);
+  }
+  close() {
+    this.count = 0;
+    this.halfOpenSuccesses = 0;
+    this.openedAt = null;
+    this.transition("CLOSED" /* CLOSED */);
+  }
+  transition(to) {
+    const from = this.state;
+    if (from === to) {
+      return;
+    }
+    this.state = to;
+    this.onTransition?.(from, to);
+  }
+};
+
+// src/classify.ts
+function defaultIsSuccess(status) {
+  return status >= 200 && status < 300;
+}
+function classifyStatus(status, rule, isSuccess) {
+  if (status === void 0) {
+    return "failure";
+  }
+  if (rule.failedServerResStatus?.includes(status)) {
+    return "failure";
+  }
+  if (rule.successServerStatus?.includes(status)) {
+    return "success";
+  }
+  return isSuccess(status) ? "success" : "failure";
+}
+function statusOf(value, isError) {
+  if (value == null || typeof value !== "object") {
+    return void 0;
+  }
+  const record = value;
+  if (isError) {
+    const response = record["response"];
+    const fromResponse = readStatus(response);
+    if (fromResponse !== void 0) {
+      return fromResponse;
+    }
+  }
+  return readStatus(record);
+}
+function readStatus(value) {
+  if (value == null || typeof value !== "object") {
+    return void 0;
+  }
+  const status = value["status"];
+  return typeof status === "number" ? status : void 0;
+}
+
+// src/errors.ts
+var CircuitOpenError = class extends Error {
+  level;
+  /** The rule `match` string keying the open breaker. Not the raw URL. */
+  key;
+  /** Epoch ms when callers may retry (breaker eligible for HALF_OPEN trial). */
+  retryAt;
+  constructor(args) {
+    super(`Circuit open for ${args.level} "${args.key}"; request not sent`);
+    this.name = "CircuitOpenError";
+    this.level = args.level;
+    this.key = args.key;
+    this.retryAt = args.retryAt;
+  }
+};
+function isCircuitOpenError(error) {
+  return error instanceof CircuitOpenError;
+}
+
+// src/matcher.ts
+function matchTarget(url, matchOn) {
+  if (matchOn === "url") {
+    return url;
+  }
+  try {
+    const parsed = new URL(url, "http://placeholder.invalid");
+    return parsed.pathname;
+  } catch {
+    const queryStart = url.indexOf("?");
+    return queryStart === -1 ? url : url.slice(0, queryStart);
+  }
+}
+function resolveRules(fullUrl2, target, rules) {
+  const result = {};
+  for (const rule of rules) {
+    if (rule.type === "service") {
+      if (!result.service && target.includes(rule.match) && !isSkipped(target, fullUrl2, rule)) {
+        result.service = rule;
+      }
+    } else if (!result.endpoint && target.includes(rule.match)) {
+      result.endpoint = rule;
+    }
+    if (result.service && result.endpoint) {
+      break;
+    }
+  }
+  return result;
+}
+function isSkipped(target, fullUrl2, rule) {
+  if (!rule.skipList || rule.skipList.length === 0) {
+    return false;
+  }
+  return rule.skipList.some(
+    (skip) => target.includes(skip) || fullUrl2.includes(skip)
+  );
+}
+
+// src/registry.ts
+var BUILT_IN_TUNING = {
+  failureThreshold: 5,
+  cooldownMs: 3e4,
+  successThreshold: 2
+};
+var CircuitBreaker = class {
+  constructor(config, now = Date.now) {
+    this.config = config;
+    this.now = now;
+    this.matchOn = config.matchOn ?? "path";
+    this.isSuccess = config.defaultIsSuccess ?? defaultIsSuccess;
+  }
+  config;
+  now;
+  matchOn;
+  isSuccess;
+  serviceBreakers = /* @__PURE__ */ new Map();
+  endpointBreakers = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  async guard(req, fn) {
+    const matched = this.resolve(req);
+    const open = this.checkOpen(matched);
+    if (open) {
+      throw open;
+    }
+    let response;
+    let thrown;
+    let isError = false;
+    try {
+      response = await fn();
+    } catch (error) {
+      thrown = error;
+      isError = true;
+    }
+    this.settle(matched, statusOf(isError ? thrown : response, isError));
+    if (isError) {
+      throw thrown;
+    }
+    return response;
+  }
+  /**
+   * Resolve which service/endpoint breakers apply to a request. Low-level seam
+   * for adapters; most callers should use {@link guard}.
+   */
+  resolve(req) {
+    const target = matchTarget(req.url, this.matchOn);
+    const { service, endpoint } = resolveRules(
+      req.url,
+      target,
+      this.config.rules
+    );
+    return {
+      service: service ? { rule: service, breaker: this.breakerFor("service", service) } : void 0,
+      endpoint: endpoint ? { rule: endpoint, breaker: this.breakerFor("endpoint", endpoint) } : void 0
+    };
+  }
+  /**
+   * 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) {
+    if (matched.service && !matched.service.breaker.canRequest()) {
+      return new CircuitOpenError({
+        level: "service",
+        key: matched.service.rule.match,
+        retryAt: matched.service.breaker.retryAt()
+      });
+    }
+    if (matched.endpoint && !matched.endpoint.breaker.canRequest()) {
+      return new CircuitOpenError({
+        level: "endpoint",
+        key: matched.endpoint.rule.match,
+        retryAt: matched.endpoint.breaker.retryAt()
+      });
+    }
+    return null;
+  }
+  /** Record the outcome of a completed request on its matched breakers. */
+  settle(matched, status) {
+    if (matched.service) {
+      this.record(
+        matched.service.breaker,
+        classifyStatus(status, matched.service.rule, this.isSuccess)
+      );
+    }
+    if (matched.endpoint) {
+      this.record(
+        matched.endpoint.breaker,
+        classifyStatus(status, matched.endpoint.rule, this.isSuccess)
+      );
+    }
+  }
+  /**
+   * 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(req, fn) {
+    return (...args) => {
+      const resolved = typeof req === "function" ? req(...args) : req;
+      return this.guard(resolved, () => fn(...args));
+    };
+  }
+  /** Inspect a breaker by level and rule-match key. Null if not yet created. */
+  stateOf(level, key) {
+    const map = level === "service" ? this.serviceBreakers : this.endpointBreakers;
+    return map.get(key)?.snapshot() ?? null;
+  }
+  /** Force a single breaker back to CLOSED. */
+  reset(level, key) {
+    const map = level === "service" ? this.serviceBreakers : this.endpointBreakers;
+    map.get(key)?.reset();
+  }
+  /** Force every breaker back to CLOSED. */
+  resetAll() {
+    for (const breaker of this.serviceBreakers.values()) breaker.reset();
+    for (const breaker of this.endpointBreakers.values()) breaker.reset();
+  }
+  /**
+   * Snapshot every live breaker, grouped by level and keyed by rule `match`.
+   * Only breakers that have seen at least one request appear.
+   */
+  snapshots() {
+    const dump = (map) => {
+      const out = {};
+      for (const [key, breaker] of map) {
+        out[key] = breaker.snapshot();
+      }
+      return out;
+    };
+    return {
+      service: dump(this.serviceBreakers),
+      endpoint: dump(this.endpointBreakers)
+    };
+  }
+  /**
+   * 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 = console.log) {
+    const lines = [];
+    const collect = (level, map) => {
+      for (const [key, breaker] of map) {
+        const snap = breaker.snapshot();
+        lines.push(
+          `[${level}] ${key} :: ${snap.state} count=${snap.count}` + (snap.openedAt === null ? "" : ` openedAt=${snap.openedAt}`)
+        );
+      }
+    };
+    collect("service", this.serviceBreakers);
+    collect("endpoint", this.endpointBreakers);
+    if (lines.length === 0) {
+      log("circuit-breaker: no breakers active yet");
+      return;
+    }
+    log(`circuit-breaker status (${lines.length}):`);
+    for (const line of lines) log(`  ${line}`);
+  }
+  record(breaker, outcome) {
+    if (outcome === "success") {
+      breaker.onSuccess();
+    } else {
+      breaker.onFailure();
+    }
+  }
+  breakerFor(level, rule) {
+    const map = level === "service" ? this.serviceBreakers : this.endpointBreakers;
+    let breaker = map.get(rule.match);
+    if (!breaker) {
+      breaker = new Breaker(this.resolveTuning(rule), this.now, (from, to) => {
+        const event = {
+          level,
+          key: rule.match,
+          from,
+          to,
+          at: this.now(),
+          alertEmails: rule.alertEmails
+        };
+        rule.onStateChange?.(event);
+        this.config.onStateChange?.(event);
+      });
+      map.set(rule.match, breaker);
+    }
+    return breaker;
+  }
+  resolveTuning(rule) {
+    const defaults = this.config.defaults ?? {};
+    return {
+      failureThreshold: rule.failureThreshold ?? defaults.failureThreshold ?? BUILT_IN_TUNING.failureThreshold,
+      cooldownMs: rule.cooldownMs ?? defaults.cooldownMs ?? BUILT_IN_TUNING.cooldownMs,
+      successThreshold: rule.successThreshold ?? defaults.successThreshold ?? BUILT_IN_TUNING.successThreshold
+    };
+  }
+};
+
+// src/adapters/fetch.ts
+function urlOf(input) {
+  if (typeof input === "string") {
+    return input;
+  }
+  if (input && typeof input === "object") {
+    const url = input["url"];
+    if (typeof url === "string") {
+      return url;
+    }
+  }
+  return String(input);
+}
+function methodOf(input, init) {
+  const fromInit = init && typeof init === "object" ? init["method"] : void 0;
+  if (typeof fromInit === "string") {
+    return fromInit;
+  }
+  const fromReq = input && typeof input === "object" ? input["method"] : void 0;
+  return typeof fromReq === "string" ? fromReq : void 0;
+}
+function wrapFetch(breaker, fetchImpl) {
+  const impl = fetchImpl ?? globalThis.fetch;
+  if (typeof impl !== "function") {
+    throw new Error(
+      "wrapFetch: no fetch implementation available; pass one explicitly"
+    );
+  }
+  return (input, init) => breaker.guard(
+    { url: urlOf(input), method: methodOf(input, init) },
+    () => impl(input, init)
+  );
+}
+
+// src/adapters/axios.ts
+var MATCHED = /* @__PURE__ */ Symbol("circuit-breaker:matched");
+function fullUrl(config) {
+  const base = config.baseURL ?? "";
+  const url = config.url ?? "";
+  if (!base) {
+    return url;
+  }
+  if (!url) {
+    return base;
+  }
+  return `${base.replace(/\/+$/, "")}/${url.replace(/^\/+/, "")}`;
+}
+function attachAxios(client, breaker) {
+  client.interceptors.request.use((config) => {
+    const matched = breaker.resolve({
+      url: fullUrl(config),
+      method: config.method
+    });
+    const openError = breaker.checkOpen(matched);
+    if (openError) {
+      return Promise.reject(openError);
+    }
+    config[MATCHED] = matched;
+    return config;
+  });
+  client.interceptors.response.use(
+    (response) => {
+      const matched = readMatched(response.config);
+      if (matched) {
+        breaker.settle(matched, statusOf(response, false));
+      }
+      return response;
+    },
+    (error) => {
+      if (isCircuitOpenError(error)) {
+        return Promise.reject(error);
+      }
+      const axiosError = error;
+      const matched = readMatched(axiosError.config);
+      if (matched) {
+        breaker.settle(matched, statusOf(axiosError, true));
+      }
+      return Promise.reject(error);
+    }
+  );
+  return client;
+}
+function readMatched(config) {
+  if (!config) {
+    return void 0;
+  }
+  const value = config[MATCHED];
+  return value;
+}
+
+// src/adapters/email.ts
+function defaultSubject(event) {
+  return `[circuit-breaker] ${event.level} "${event.key}" -> ${event.to}`;
+}
+function defaultText(event) {
+  return [
+    `Circuit breaker state change.`,
+    `level: ${event.level}`,
+    `key:   ${event.key}`,
+    `from:  ${event.from}`,
+    `to:    ${event.to}`,
+    `at:    ${new Date(event.at).toISOString()}`
+  ].join("\n");
+}
+function emailAlerter(options) {
+  const when = options.when ?? ["OPEN" /* OPEN */];
+  const log = options.log ?? ((message, error) => console.error(message, error));
+  return (event) => {
+    if (!when.includes(event.to)) {
+      return;
+    }
+    const recipients = event.alertEmails && event.alertEmails.length > 0 ? event.alertEmails : options.to ?? [];
+    if (recipients.length === 0) {
+      return;
+    }
+    const subject = options.subject ? options.subject(event) : defaultSubject(event);
+    const parts = options.body ? options.body(event) : { text: defaultText(event) };
+    Promise.resolve().then(
+      () => options.transporter.sendMail({
+        from: options.from,
+        to: recipients,
+        subject,
+        ...parts
+      })
+    ).catch(
+      (error) => log(`circuit-breaker: alert email failed for "${event.key}"`, error)
+    );
+  };
+}
+
+// src/index.ts
+function createBreaker(config, now) {
+  return new CircuitBreaker(config, now);
+}
+export {
+  Breaker,
+  BreakerState,
+  CircuitBreaker,
+  CircuitOpenError,
+  attachAxios,
+  classifyStatus,
+  createBreaker,
+  defaultIsSuccess,
+  emailAlerter,
+  isCircuitOpenError,
+  matchTarget,
+  resolveRules,
+  statusOf,
+  wrapFetch
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@prash0029/circuit-breaker",
+  "version": "0.1.0",
+  "description": "Two-level, config-driven in-memory circuit breaker for guarding outbound server API calls (per-service + per-endpoint).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "keywords": [
+    "circuit-breaker",
+    "resilience",
+    "fault-tolerance",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Sai Prashanth",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prash-29/circuit-breaker.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}