{"id":49820220,"url":"https://github.com/silent-watcher/resilia","last_synced_at":"2026-05-13T10:05:47.098Z","repository":{"id":330774257,"uuid":"1122880600","full_name":"Silent-Watcher/resilia","owner":"Silent-Watcher","description":"A lightweight, decorator-based resilience stack for TypeScript: Circuit Breaker, Bulkhead, and Retry","archived":false,"fork":false,"pushed_at":"2026-01-01T02:57:15.000Z","size":58,"stargazers_count":8,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-29T01:56:46.935Z","etag":null,"topics":["bulkhead","circuit-breaker","resilience","retry-pattern","stability"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/resilia","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Silent-Watcher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-25T18:13:50.000Z","updated_at":"2026-01-01T02:57:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Silent-Watcher/resilia","commit_stats":null,"previous_names":["silent-watcher/resilia"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Silent-Watcher/resilia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silent-Watcher%2Fresilia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silent-Watcher%2Fresilia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silent-Watcher%2Fresilia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silent-Watcher%2Fresilia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Silent-Watcher","download_url":"https://codeload.github.com/Silent-Watcher/resilia/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silent-Watcher%2Fresilia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32977329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T06:31:55.726Z","status":"ssl_error","status_checked_at":"2026-05-13T06:31:51.336Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bulkhead","circuit-breaker","resilience","retry-pattern","stability"],"created_at":"2026-05-13T10:05:46.142Z","updated_at":"2026-05-13T10:05:47.089Z","avatar_url":"https://github.com/Silent-Watcher.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Resilia\n\n**The zero-dependency, decorator-based resilience stack for TypeScript.**\n\n**Resilia** helps you build \"unbreakable\" Node.js applications by wrapping your critical methods in a professional-grade resilience stack. With a single `@Resilient` decorator, you gain a **Circuit Breaker**, **Bulkhead**, and **Exponential Retry** strategy—all pre-configured and fully observable.\n\n---\n\n## Features\n\n* **Decorator-First DX:** Protect any class method with one line of code.\n* **Circuit Breaker:** Prevent cascading failures with a sliding-window state machine (Closed, Open, Half-Open).\n* **Bulkhead:** Limit concurrency and manage overflow queues to protect system resources.\n* **Smart Retries:** Automatic retries with **Exponential Backoff** and **Jitter** to prevent \"thundering herd\" issues.\n* **Full Observability:** Event-driven architecture with built-in counters and gauges for Prometheus/Grafana integration.\n* **Zero Dependencies:** Extremely lightweight and fast.\n\n---\n\n## Installation\n\n```bash\nnpm install resilia reflect-metadata\n\n```\n\nMake sure you have these flags enabled in your `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"experimentalDecorators\": true,\n    \"emitDecoratorMetadata\": true\n  }\n}\n\n```\n\n---\n\n## Quick Start\n\nSimply tag your database calls or external API requests. Resilia handles the rest.\n\n```typescript\nimport { Resilient } from 'resilia';\n\nclass PaymentService {\n  @Resilient({\n    concurrency: 5,        // Max 5 simultaneous requests\n    queue: 10,             // Max 10 waiting in line\n    maxRetries: 3,         // Try 3 times before failing\n    errorThreshold: 0.5,   // Trip circuit if \u003e50% fail\n    sleepWindowMs: 30000   // Rest for 30s when tripped\n  })\n  async processTransaction(id: string) {\n    return await db.payments.create({ id });\n  }\n}\n\n```\n\n---\n\n## The Resilience Stack\n\nResilia executes your code through a three-layer \"Matryoshka\" security model:\n\n### 1. The Circuit Breaker (Outer Layer)\n\nActs as a safety switch. If your service starts failing (e.g., the database is down), the circuit flips to **OPEN**.\n\n* **Closed**: Everything is healthy.\n* **Open**: Requests are \"short-circuited\" immediately to save resources.\n* **Half-Open**: One \"test\" request is allowed through to check if the system recovered.\n\n### 2. The Retry Strategy (Middle Layer)\n\nHandles transient glitches. If a request fails, Resilia waits using **Exponential Backoff** (delaying longer each time) before trying again. It adds **Jitter** (randomness) to ensure multiple retrying services don't hit your server at the exact same millisecond.\n\n### 3. The Bulkhead (Inner Layer)\n\nIsolates resources. Even if one part of your app is slow, it won't crash the whole process. It limits how many copies of a specific function can run at once and provides a waiting room (queue) for the overflow.\n\n---\n\n## Observability \u0026 Events\n\nResilia is designed to be monitored. Every component is an `EventEmitter`, allowing you to hook into the system health in real-time.\n\n```typescript\nimport { resilienceRegistry } from 'resilia';\n\nresilienceRegistry.forEach(({ breaker, bulkhead }, key) =\u003e {\n    // Alert when a circuit trips\n    breaker.on('state:changed', (event) =\u003e {\n        console.error(`🚨 ALERT: ${key} changed from ${event.from} to ${event.to}`);\n    });\n\n    // Send metrics to your dashboard\n    bulkhead.on('request:rejected', () =\u003e {\n        metrics.increment(`bulkhead_overflow_${key}`);\n    });\n});\n\n```\n\n### Metrics Snapshot\n\nYou can also grab a health snapshot at any time:\n\n```typescript\nconst stats = bulkhead.getMetrics();\n// { activeCount: 5, queueLength: 2, totalAccepted: 100, totalRejected: 1 }\n\n```\n\n---\n\n## Configuration Reference\n\n| Property | Type | Default | Description |\n| --- | --- | --- | --- |\n| `concurrency` | `number` | `10` | Max concurrent executions allowed for this method. |\n| `queue` | `number` | `20` | Max requests that can wait if concurrency is full. |\n| `maxRetries` | `number` | `3` | Number of retry attempts for transient errors. |\n| `backoffMs` | `number` | `1000` | Initial delay for the exponential backoff. |\n| `errorThreshold` | `number` | `0.5` | Percentage of failures (0.0 to 1.0) that trips the circuit. |\n| `sleepWindowMs` | `number` | `30000` | How long the circuit stays OPEN before testing recovery. |\n\n---\n\n## Contributing\n\nContributions are welcome! If you have ideas for new resilience patterns (like Rate Limiting or Timeouts), feel free to open an issue or a PR.\n\n---\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n---\n\n**Built with ❤️ for the Node.js community.** *Star this repo if it helped you sleep better at night!* ⭐\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilent-watcher%2Fresilia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsilent-watcher%2Fresilia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilent-watcher%2Fresilia/lists"}