{"_id":"@chaisser/circuit-breaker","name":"@chaisser/circuit-breaker","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@chaisser/circuit-breaker","version":"1.0.0","description":"Circuit breaker pattern implementation","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["circuit","breaker","resilience","fault","tolerance","typescript"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Chaisser/circuit-breaker.git"},"homepage":"https://github.com/Chaisser/circuit-breaker#readme","bugs":{"url":"https://github.com/Chaisser/circuit-breaker/issues"},"devDependencies":{"@types/node":"^22.10.2","tsup":"^8.3.5","typescript":"^5.7.2","vitest":"^2.1.8"},"engines":{"node":">=16.0.0"},"publishConfig":{"access":"public"},"gitHead":"f885559b9af7756aa6b19920c0aaed1092c1ed98","_id":"@chaisser/circuit-breaker@1.0.0","_nodeVersion":"26.1.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-p1+y8K2l3lxMxfQRTTRel68TzmkKeKL7x4QekltL+9BsNeU9AEag++6lGr6hXqYXF00yAaGKoOBSEZwHnANlkA==","shasum":"8f0da76a196d4100d7d84aeb447da59d958b244e","tarball":"https://registry.npmjs.org/@chaisser/circuit-breaker/-/circuit-breaker-1.0.0.tgz","fileCount":8,"unpackedSize":41219,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDTZA7u9c3PetdO1hwswrrZjbxtYZcDGtprwjFhofT11gIhAKxghsLtAODwgE7HUIMeMDeDsklzih6BrkYNE3Xbs2ym"}]},"_npmUser":{"name":"chaisser","email":"doruk.karaboncuk@gmail.com"},"directories":{},"maintainers":[{"name":"chaisser","email":"doruk.karaboncuk@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/circuit-breaker_1.0.0_1778660633810_0.5884796314737117"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T08:23:53.721Z","1.0.0":"2026-05-13T08:23:54.000Z","modified":"2026-05-13T08:23:54.223Z"},"maintainers":[{"name":"chaisser","email":"doruk.karaboncuk@gmail.com"}],"description":"Circuit breaker pattern implementation","homepage":"https://github.com/Chaisser/circuit-breaker#readme","keywords":["circuit","breaker","resilience","fault","tolerance","typescript"],"repository":{"type":"git","url":"git+https://github.com/Chaisser/circuit-breaker.git"},"bugs":{"url":"https://github.com/Chaisser/circuit-breaker/issues"},"license":"MIT","readme":"# ⚡ @chaisser/circuit-breaker\n\n> **Circuit breaker pattern implementation for resilient async operations**\n\n---\n\n## ✨ Features\n\n- ⚡ **Circuit breaker pattern** - Protect your services from cascading failures\n- 🔄 **Automatic state transitions** - CLOSED → OPEN → HALF_OPEN cycle\n- 🎯 **Type-safe** - Full TypeScript support with generics\n- 📊 **Statistics tracking** - Monitor successes, failures, and rejections\n- 🔔 **State change callbacks** - React to circuit state transitions\n- 🛠️ **Manual control** - Force reset or trip the circuit\n- ⏱️ **Configurable thresholds** - Custom failure threshold, reset timeout, and half-open requests\n- 📈 **Monitor interval** - Optional background state monitoring\n- 🪶 **Zero dependencies** - Lightweight and tree-shakeable\n- 🏎️ **ESM + CJS** - Dual module format support\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @chaisser/circuit-breaker\n# or\nyarn add @chaisser/circuit-breaker\n# or\npnpm add @chaisser/circuit-breaker\n```\n\n---\n\n## 🚀 Quick Start\n\n```typescript\nimport { createCircuitBreaker } from '@chaisser/circuit-breaker';\n\nconst breaker = createCircuitBreaker({\n  failureThreshold: 5,\n  resetTimeout: 30000,\n});\n\nconst data = await breaker.execute(() => fetch('/api/data').then(r => r.json()));\n```\n\n---\n\n## 📖 What It Does\n\nThis package provides a circuit breaker implementation for JavaScript and TypeScript. It wraps async operations and tracks failures, automatically opening the circuit when the failure threshold is reached. After a configurable timeout, it transitions to a half-open state to test recovery. Supports state change callbacks, statistics tracking, manual control, and configurable thresholds.\n\n---\n\n## 💡 Usage Examples\n\n### Basic Circuit Breaker\n\n```typescript\nimport { createCircuitBreaker } from '@chaisser/circuit-breaker';\n\nconst breaker = createCircuitBreaker({\n  failureThreshold: 5,\n  resetTimeout: 30000,\n});\n\ntry {\n  const result = await breaker.execute(() => fetchData());\n} catch (error) {\n  if (error instanceof CircuitOpenError) {\n    console.log('Circuit is open, service unavailable');\n  }\n}\n```\n\n### With State Change Callback\n\n```typescript\nimport { CircuitBreaker, CircuitState } from '@chaisser/circuit-breaker';\n\nconst breaker = new CircuitBreaker({\n  failureThreshold: 3,\n  resetTimeout: 10000,\n});\n\nbreaker.onStateChange((oldState, newState) => {\n  console.log(`Circuit: ${oldState} → ${newState}`);\n  if (newState === CircuitState.OPEN) {\n    alertTeam('Service is down!');\n  }\n});\n```\n\n### Checking Circuit State\n\n```typescript\nif (breaker.isCallAllowed()) {\n  const result = await breaker.execute(() => fetchData());\n} else {\n  // Use fallback\n  return cachedData;\n}\n```\n\n### Monitoring Statistics\n\n```typescript\nconst stats = breaker.getStats();\nconsole.log(`Successes: ${stats.successes}`);\nconsole.log(`Failures: ${stats.failures}`);\nconsole.log(`Rejections: ${stats.rejections}`);\nconsole.log(`Last failure: ${new Date(stats.lastFailureTime!)}`);\n```\n\n### Manual Control\n\n```typescript\n// Force open the circuit\nbreaker.trip();\n\n// Force close the circuit\nbreaker.reset();\n```\n\n### With Monitor Interval\n\n```typescript\nconst breaker = new CircuitBreaker({\n  failureThreshold: 5,\n  resetTimeout: 30000,\n  monitorInterval: 5000, // check every 5 seconds\n});\n\n// Clean up when done\nbreaker.shutdown();\n```\n\n### Half-Open Configuration\n\n```typescript\nconst breaker = new CircuitBreaker({\n  failureThreshold: 5,\n  resetTimeout: 30000,\n  halfOpenRequests: 3, // allow 3 test requests in half-open\n});\n```\n\n---\n\n## 📚 API Reference\n\n### Classes\n\n| Class | Description |\n|---|---|\n| `CircuitBreaker` | Main circuit breaker class |\n| `CircuitOpenError` | Error thrown when circuit is open |\n\n### CircuitBreakerOptions\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `failureThreshold` | `number` | *(required)* | Consecutive failures before opening |\n| `resetTimeout` | `number` | *(required)* | Ms before OPEN → HALF_OPEN |\n| `halfOpenRequests` | `number` | `1` | Test requests allowed in HALF_OPEN |\n| `monitorInterval` | `number` | — | Optional background check interval (ms) |\n\n### CircuitBreaker Methods\n\n| Method | Signature | Description |\n|---|---|---|\n| `execute(fn)` | `(fn: () => Promise<T>) → Promise<T>` | Execute fn through the circuit breaker |\n| `getState()` | `() → CircuitState` | Get current circuit state |\n| `getStats()` | `() → CircuitStats` | Get success/failure/rejection counts |\n| `reset()` | `() → void` | Force close the circuit |\n| `trip()` | `() → void` | Force open the circuit |\n| `onStateChange(cb)` | `(cb) → void` | Register state change callback |\n| `isCallAllowed()` | `() → boolean` | Check if a call would be allowed |\n| `shutdown()` | `() → void` | Stop monitor interval |\n\n### CircuitState Enum\n\n| Value | Description |\n|---|---|\n| `CLOSED` | Normal operation — calls pass through |\n| `OPEN` | Circuit tripped — calls are rejected |\n| `HALF_OPEN` | Testing recovery — limited calls allowed |\n\n### CircuitStats\n\n| Field | Type | Description |\n|---|---|---|\n| `successes` | `number` | Total successful calls |\n| `failures` | `number` | Total failed calls |\n| `rejections` | `number` | Calls rejected while OPEN |\n| `lastFailureTime` | `number \\| null` | Timestamp of last failure |\n\n### Factory Function\n\n| Function | Signature | Description |\n|---|---|---|\n| `createCircuitBreaker(options)` | `(CircuitBreakerOptions) → CircuitBreaker` | Create a new circuit breaker |\n\n---\n\n## 🔗 Related Packages\n\nExplore our other utility packages in the @chaisser namespace:\n\n- **@chaisser/circuit-breaker** (this package) - Circuit breaker pattern implementation\n- [@chaisser/retry-async](https://www.npmjs.com/package/@chaisser/retry-async) - Retry async functions with exponential backoff\n- [@chaisser/chunk-array](https://www.npmjs.com/package/@chaisser/chunk-array) - Split arrays into chunks\n- [@chaisser/string-wizard](https://www.npmjs.com/package/@chaisser/string-wizard) - Advanced string manipulation\n- [@chaisser/type-guard](https://www.npmjs.com/package/@chaisser/type-guard) - Runtime type guards and validators\n- [@chaisser/uuid-v7](https://www.npmjs.com/package/@chaisser/uuid-v7) - Time-ordered UUID v7 generator\n- [@chaisser/wait-for](https://www.npmjs.com/package/@chaisser/wait-for) - Promise-based wait utilities\n- [@chaisser/regex-humanizer](https://www.npmjs.com/package/@chaisser/regex-humanizer) - Regex to human-readable descriptions\n- [@chaisser/password-strength](https://www.npmjs.com/package/@chaisser/password-strength) - Password strength checker\n- [@chaisser/human-time](https://www.npmjs.com/package/@chaisser/human-time) - Human-readable time formatting\n- [@chaisser/obj-path](https://www.npmjs.com/package/@chaisser/obj-path) - Safe dot-notation object access\n- [@chaisser/debounce-throttle](https://www.npmjs.com/package/@chaisser/debounce-throttle) - Rate limiting utilities\n- [@chaisser/color-utils](https://www.npmjs.com/package/@chaisser/color-utils) - Color conversion utilities\n- [@chaisser/deep-clone](https://www.npmjs.com/package/@chaisser/deep-clone) - Deep cloning functions\n- [@chaisser/array-group-by](https://www.npmjs.com/package/@chaisser/array-group-by) - Array grouping utilities\n- [@chaisser/merge-objects](https://www.npmjs.com/package/@chaisser/merge-objects) - Object merge utilities\n- [@chaisser/event-emitter](https://www.npmjs.com/package/@chaisser/event-emitter) - Typed event emitter\n- [@chaisser/unique-by](https://www.npmjs.com/package/@chaisser/unique-by) - Array uniqueness utilities\n- [@chaisser/memoize](https://www.npmjs.com/package/@chaisser/memoize) - Function memoization\n- [@chaisser/base64-url](https://www.npmjs.com/package/@chaisser/base64-url) - URL-safe base64 encoding\n- [@chaisser/ip-regex](https://www.npmjs.com/package/@chaisser/ip-regex) - IP address validation\n\n---\n\n## 🔒 License\n\n**MIT** - Free to use in personal and commercial projects\n\n---\n\n## 👨 Developed by\n\n**Doruk Karaboncuk** <doruk.karaboncuk@interaktifis.com>\n\n---\n\n## 📄 Repository\n\n- **GitHub:** [@Chaisser](https://github.com/Chaisser)\n- **NPM:** [@chaisser/circuit-breaker](https://www.npmjs.com/package/@chaisser/circuit-breaker)\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Feel free to:\n- Report bugs\n- Suggest new features\n- Submit pull requests\n- Improve documentation\n\n---\n\n## 📞 Support\n\nFor issues, questions, or suggestions, please reach out through:\n- **Email:** doruk.karaboncuk@interaktifis.com\n- **GitHub Issues:** [Create an issue](https://github.com/Chaisser/circuit-breaker/issues)\n\n---\n\n<div align=\"center\">\n\nMade with ❤️ by [@chaisser](https://www.npmjs.com/~chaisser)\n\n</div>\n","readmeFilename":"README.md","_rev":"1-391e9e2e59d6b0575beb80fb45f166f9"}