{"id":15043915,"url":"https://github.com/socketsomeone/nestjs-resilience","last_synced_at":"2025-05-15T18:11:18.032Z","repository":{"id":153095384,"uuid":"628131248","full_name":"SocketSomeone/nestjs-resilience","owner":"SocketSomeone","description":"🛡️ A module for improving the reliability and fault-tolerance of your NestJS applications","archived":false,"fork":false,"pushed_at":"2025-05-14T23:03:52.000Z","size":3405,"stargazers_count":236,"open_issues_count":2,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-15T01:41:20.927Z","etag":null,"topics":["circuit-breaker","hystrix","nest","nestjs","reliability","retry","timeout","typescript"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/nestjs-resilience","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/SocketSomeone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["SocketSomeone"]}},"created_at":"2023-04-15T02:10:57.000Z","updated_at":"2025-05-14T23:03:56.000Z","dependencies_parsed_at":"2023-12-25T23:20:20.250Z","dependency_job_id":"bdb13cf7-969b-4f07-ae44-1ba6b993e2c7","html_url":"https://github.com/SocketSomeone/nestjs-resilience","commit_stats":{"total_commits":700,"total_committers":4,"mean_commits":175.0,"dds":"0.14142857142857146","last_synced_commit":"0648611fee6fde0569c4e7d96bf3ef848cba348d"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":"SocketSomeone/nestjs-open-source-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocketSomeone%2Fnestjs-resilience","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocketSomeone%2Fnestjs-resilience/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocketSomeone%2Fnestjs-resilience/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SocketSomeone%2Fnestjs-resilience/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SocketSomeone","download_url":"https://codeload.github.com/SocketSomeone/nestjs-resilience/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254394724,"owners_count":22063984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["circuit-breaker","hystrix","nest","nestjs","reliability","retry","timeout","typescript"],"created_at":"2024-09-24T20:49:49.150Z","updated_at":"2025-05-15T18:11:17.999Z","avatar_url":"https://github.com/SocketSomeone.png","language":"TypeScript","funding_links":["https://github.com/sponsors/SocketSomeone"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"http://nestjs.com/\" target=\"blank\"\u003e\u003cimg src=\"https://nestjs.com/img/logo-small.svg\" width=\"120\" alt=\"Nest Logo\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    A module for improving the reliability and fault-tolerance of your \u003ca href=\"https://nestjs.com/\" target=\"_blank\"\u003eNestJS\u003c/a\u003e applications\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href='https://img.shields.io/npm/v/nestjs-resilience'\u003e\u003cimg src=\"https://img.shields.io/npm/v/nestjs-resilience\" alt=\"NPM Version\" /\u003e\u003c/a\u003e\n    \u003ca href='https://img.shields.io/npm/l/nestjs-resilience'\u003e\u003cimg src=\"https://img.shields.io/npm/l/nestjs-resilience\" alt=\"NPM License\" /\u003e\u003c/a\u003e\n    \u003ca href='https://img.shields.io/npm/dm/nestjs-resilience'\u003e\u003cimg src=\"https://img.shields.io/npm/dm/nestjs-resilience\" alt=\"NPM Downloads\" /\u003e\u003c/a\u003e\n    \u003ca href='https://img.shields.io/github/last-commit/SocketSomeone/nestjs-resilience'\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/SocketSomeone/nestjs-resilience\" alt=\"Last commit\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\nNestJS Resilience is an open-source library that provides a set of reliable patterns for building resilient applications on top of NestJS.\nThe library includes several key features, including retry, circuit breaker, and timeout patterns, which help to ensure that your\napplication can handle failures and recover quickly from them.\n\nWith NestJS Resilience, you can easily configure these patterns for your application, allowing you to improve the reliability and\nfault-tolerance of your services. Whether you're building a high-traffic web application or a distributed system, NestJS Resilience provides\nthe tools you need to build robust, failure-resistant services that can withstand even the most challenging environments.\n\n**Features**\n\n- **Circuit Breaker** - Automatically fail fast when a service is unavailable\n- **Retry** - Automatically retry failed requests\n- **Timeout** - Automatically fail fast when a service is taking too long to respond\n- **Bulkhead** - Limit the number of concurrent requests to a service\n- **Fallback** - Provide a fallback response when a service is unavailable\n- **Rate Limiting** - Limit the number of requests to a service\n- **De duplicate** - Prevent duplicate requests from being processed\n\n## Installation\n\n```bash\n$ npm install nestjs-resilience\n$ yarn add nestjs-resilience\n$ pnpm add nestjs-resilience\n```\n\n## Usage\n\n### Import the module\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { ResilienceModule } from 'nestjs-resilience';\n\n@Module({\n    imports: [ResilienceModule.forRoot()]\n})\nexport class AppModule {}\n```\n\nUse `store` field to configure cache (e.x. `store: new RedisStore({ host: 'localhost', port: 6379 })`).\nWe use `memory` from `cache-manager` store by default.\n\n### Ways to use\n\nYou can use it in three ways:\n\n#### 1. Use `ResilienceCommand`\n\nYou can create a command by extending the `ResilienceCommand` class. You can also use the `ResilienceFactory` to create a command with a set\nof policies.\n\n```typescript\nimport { Injectable } from '@nestjs/common';\nimport { ResilienceCommand, ResilienceFactory } from 'nestjs-resilience';\nimport { UsersService } from './user.service';\nimport { User, NullUserObject } from './user.entity';\n\n@Injectable()\nexport class GetUserByIdCommand extends ResilienceCommand {\n    constructor(\n        private readonly factory: ResilienceFactory,\n        private readonly userService: UsersService\n    ) {\n        super([\n            // You can use the injected factory to create a strategy\n            factory.createTimeout(1000),\n            // Or you can create a strategy directly\n            ResilienceFactory.createFallback((id) =\u003e new NullUserObject(id))\n            // You can also use mannually created strategies\n            // new TimeoutStrategy(1000),\n        ]);\n    }\n\n    async run(id: number): User {\n        return this.usersService.getUser(id);\n    }\n}\n```\n\nThis way supports DI, just what you need add `@Injectable()` decorator to your command and to providers of your module. Inject your\ncommand in the constructor or use `resilienceService.getCommand(GetUserByIdCommand)`.\n\nFAQ:\n\n- Can I use `@Inject()` decorator? Yes, you can. But you need to add `@Injectable()` decorator to your command.\n- Can I use w/o DI? Yes, you can. Just create a command with `new` operator.\n\n#### 2. Use the `@UseResilience()` decorator\n\nYou can use `@UseResilience()` decorator to wrap your **service** methods.\n\n```typescript\nimport { Injectable } from '@nestjs/common';\nimport { TimeoutStrategy } from \"./timeout.strategy\";\nimport { NullUserObject, User } from './user.entity';\n\n@Injectable()\nexport class UsersService {\n    @UseResilience(new TimeoutStrategy(1000), ResilienceFactory.createFallback((id) =\u003e new NullUserObject(id)))\n    async getUser(id: number): User {\n        return this.httpService.get(`https://example.com/users/${id}`).toPromise();\n    }\n}\n```\n\n\u003e Not the best way to use in controller methods. `@UseResilience` rewrite your method. \n\n#### 3. Interceptors\n\nYou also can wrap your controller methods with `ResilienceInterceptor` and use all the features of the library.\n\n```typescript\nimport { Controller, Get, UseInterceptors } from '@nestjs/common';\nimport { ResilienceInterceptor } from 'nestjs-resilience';\nimport { UsersService } from './users.service';\n\n@Controller('users')\nexport class UsersController {\n    constructor(private readonly usersService: UsersService) {\n    }\n\n    @Get()\n    @UseInterceptors(ResilienceInterceptor(new TimeoutStrategy(1000), ResilienceFactory.createFallback(() =\u003e [])))\n    async getUsers(): User[] {\n        return this.usersService.getUsers();\n    }\n}\n```\n\n#### Observables\n\nWe also support `Observable` as a return type. You can use it with `@UseResilienceObservable()` decorator or `ResilienceCommandObservable`.\n\n```typescript\nimport { Injectable } from '@nestjs/common';\nimport { TimeoutStrategy } from \"./timeout.strategy\";\nimport { NullUserObject, User } from './user.entity';\nimport { Observable, of } from 'rxjs';\n\n@Injectable()\nexport class UsersService {\n    @UseResilienceObservable(new TimeoutStrategy(1000), ResilienceFactory.createFallback((id) =\u003e new NullUserObject(id)))\n    getUser(id: number): Observable\u003cUser\u003e {\n        return of(new User(id, 'John Doe'));\n    }\n}\n```\n\n#### Order of execution\n\nStrategies processing in order which you pass them to the `ResilienceCommand` or `ResilienceInterceptor`.\n\nWhat it means? Let's take a look at the example:\n\n**Timeout before Retry:**\n\n- If the command is executed successfully, the result will be returned.\n- If the command is executed with an error or timed out, the command will be retried.\n- If the command is executed with an error or timed out and the number of retries is exceeded, the error will be thrown.\n\n**Retry after Timeout:**\n\n- If the command is executed successfully, the result will be returned.\n- If the command is executed with an error, the command will be retried.\n- If the command is executed with an error and the number of retries is exceeded, the error will be thrown.\n- If the command is executed with an error and the number of retries is exceeded or timed out, the error will be thrown.\n\n### Strategies\n\n| Strategy                 | Description                                                          |\n|--------------------------|----------------------------------------------------------------------|\n| `TimeoutStrategy`        | Automatically fail fast when a service is taking too long to respond |\n| `RetryStrategy`          | Automatically retry failed requests                                  |\n| `CircuitBreakerStrategy` | Automatically fail fast when a service is unavailable                |\n| `BulkheadStrategy`       | Limit the number of concurrent requests to a service                 |\n| `FallbackStrategy`       | Provide a fallback response when a service is unavailable            |\n| `ThrottleStrategy`       | Limit the number of requests to a service                            |\n| `HealthCheckStrategy`    | Check the health of a service                                        |\n| `CacheStrategy`          | Cache the result of a service call                                   |\n| `DeduplicateStrategy`    | Prevent duplicate requests from being processed                      |\n\n\n\n## Stay in touch\n\n* Author - [Alexey Filippov](https://t.me/socketsomeone)\n* Twitter - [@SocketSomeone](https://twitter.com/SocketSomeone)\n\n## License\n\n[MIT](https://github.com/SocketSomeone/nestjs-resilience/blob/master/LICENSE) © [Alexey Filippov](https://github.com/SocketSomeone)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocketsomeone%2Fnestjs-resilience","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocketsomeone%2Fnestjs-resilience","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocketsomeone%2Fnestjs-resilience/lists"}