{"id":19479212,"url":"https://github.com/pmb0/nestjs-unleash","last_synced_at":"2025-04-05T10:08:56.138Z","repository":{"id":37890362,"uuid":"317338911","full_name":"pmb0/nestjs-unleash","owner":"pmb0","description":"Unleash feature toggle support for NestJS","archived":false,"fork":false,"pushed_at":"2025-03-17T12:54:18.000Z","size":2898,"stargazers_count":51,"open_issues_count":21,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T09:11:36.864Z","etag":null,"topics":["feature-toggle","nestjs","unleash"],"latest_commit_sha":null,"homepage":"","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/pmb0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-30T20:32:52.000Z","updated_at":"2025-02-28T10:39:31.000Z","dependencies_parsed_at":"2024-04-19T10:55:33.210Z","dependency_job_id":"b86ead29-c11b-45ce-b817-8fd38ba1835b","html_url":"https://github.com/pmb0/nestjs-unleash","commit_stats":{"total_commits":562,"total_committers":9,"mean_commits":62.44444444444444,"dds":0.3861209964412812,"last_synced_commit":"d070dab4cbfc55d56ffe806eaf1c9696c401323a"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fnestjs-unleash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fnestjs-unleash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fnestjs-unleash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fnestjs-unleash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmb0","download_url":"https://codeload.github.com/pmb0/nestjs-unleash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247318744,"owners_count":20919484,"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":["feature-toggle","nestjs","unleash"],"created_at":"2024-11-10T19:53:22.282Z","updated_at":"2025-04-05T10:08:56.108Z","avatar_url":"https://github.com/pmb0.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eNestJS-Unleash\u003c/h1\u003e\n  \u003ca href=\"https://www.npmjs.com/package/nestjs-unleash\"\u003e\n    \u003cimg src=\"https://badge.fury.io/js/nestjs-unleash.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/r/pmb0/nestjs-unleash?branch=master\"\u003e\n    \u003cimg src=\"https://img.shields.io/coveralls/pmb0/nestjs-unleash/master.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/pmb0/nestjs-unleash/actions?query=workflow%3ATests\"\u003e\n    \u003cimg src=\"https://github.com/pmb0/nestjs-unleash/workflows/Tests/badge.svg\"\u003e\n  \u003c/a\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/Unleash/unleash\"\u003eUnleash\u003c/a\u003e module for \u003ca href=\"https://nestjs.com/\"\u003eNestJS\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n# Table of contents \u003c!-- omit in toc --\u003e\n\n- [Setup](#setup)\n  - [Synchronous configuration](#synchronous-configuration)\n  - [Asynchronous configuration](#asynchronous-configuration)\n- [Usage in controllers or providers](#usage-in-controllers-or-providers)\n  - [Custom context](#custom-context)\n  - [Configuration](#configuration)\n  - [Default strategies](#default-strategies)\n  - [Custom strategies](#custom-strategies)\n- [License](#license)\n\n# Setup\n\n```sh\n$ npm install --save nestjs-unleash\n```\n\nImport the module with `UnleashModule.forRoot(...)` or `UnleashModule.forRootAsync(...)`.\n\n## Synchronous configuration\n\nUse `UnleashModule.forRoot()`. Available options are described in the [UnleashModuleOptions interface](#configuration).\n\n```ts\n@Module({\n  imports: [\n    UnleashModule.forRoot({\n      url: \"https://example.com/unleash\",\n      appName: \"my-app-name\",\n      instanceId: \"my-unique-instance\",\n    }),\n  ],\n})\nexport class MyModule {}\n```\n\n## Asynchronous configuration\n\nIf you want to use your [Unleash options](#configuration) dynamically, use `UnleashModule.forRootAsync()`. Use `useFactory` and `inject` to import your dependencies. Example using the `ConfigService`:\n\n```ts\n@Module({\n  imports: [\n    UnleashModule.forRootAsync({\n      useFactory: (config: ConfigService) =\u003e ({\n        url: config.get(\"UNLEASH_URL\"),\n        appName: config.get(\"UNLEASH_APP_NAME\"),\n        instanceId: config.get(\"UNLEASH_INSTANCE_ID\"),\n        refreshInterval: config.get(\"UNLEASH_REFRESH_INTERVAL\"),\n        metricsInterval: config.get(\"UNLEASH_METRICS_INTERVAL\"),\n      }),\n      inject: [ConfigService],\n    }),\n  ],\n})\nexport class MyModule {}\n```\n\n# Usage in controllers or providers\n\nIn your controller use the `UnleashService` or the `@IfEnabled(...)` route decorator:\n\n```ts\nimport { UnleashService } from \"nestjs-unleash\";\n\n@Controller()\n@UseGuards(UserGuard)\nexport class AppController {\n  constructor(private readonly unleash: UnleashService) {}\n\n  @Get(\"/\")\n  index(): string {\n    // the UnleashService can be used in all controllerrs and provideers\n    return this.unleash.isEnabled(\"test\")\n      ? \"feature is active\"\n      : \"feature is not active\";\n  }\n\n  // Throws a NotFoundException if the feature is not enabled\n  @IfEnabled(\"test\")\n  @Get(\"/foo\")\n  getFoo(): string {\n    return \"my foo\";\n  }\n}\n```\n\n## Custom context\n\nThe `UnleashContext` grants access to request related information like user ID or IP address.\n\nIn addition, the context can be dynamically enriched with further information and subsequently used in a separate strategy:\n\n```ts\nexport interface MyCustomData {\n  foo: string;\n  bar: number;\n}\n\n@Injectable()\nclass SomeProvider {\n  constructor(private readonly unleash: UnleashService\u003cMyCustomData\u003e) {}\n\n  someMethod() {\n    return this.unleash.isEnabled(\"someToggleName\", undefined, {\n      foo: \"bar\",\n      bar: 123,\n    })\n      ? \"feature is active\"\n      : \"feature is not active\";\n  }\n}\n\n// Custom strategy with custom data:\n@Injectable()\nexport class MyCustomStrategy implements UnleashStrategy {\n  name = \"MyCustomStrategy\";\n\n  isEnabled(\n    _parameters: unknown,\n    context: UnleashContext\u003cMyCustomData\u003e\n  ): boolean {\n    return context.customData?.foo === \"bar\";\n  }\n}\n```\n\n## Configuration\n\nNestJS-Unleash can be configured with the following options:\n\n```ts\ninterface UnleashModuleOptions {\n  /**\n   * If \"true\", registers `UnleashModule` as a global module.\n   * See: https://docs.nestjs.com/modules#global-modules\n   *\n   * @default true\n   */\n  global?: boolean;\n\n  /**\n   * URL of your Unleash server\n   *\n   * @example http://unleash.herokuapp.com/api/client\n   */\n  url: string;\n\n  /**\n   * Name of the application seen by unleash-server\n   */\n  appName: string;\n\n  /**\n   * Instance id for this application (typically hostname, podId or similar)\n   */\n  instanceId: string;\n\n  /**\n   * Additional options for the HTTP request to the Unleash server, e.g. custom\n   * HTTP headers\n   */\n  http?: AxiosRequestConfig;\n\n  /**\n   * At which interval, in milliseconds, will this client update its feature\n   * state\n   */\n  refreshInterval?: number;\n\n  /**\n   * At which interval, in milliseconds, will this client send metrics\n   */\n  metricsInterval?: number;\n\n  /**\n   * Array of custom strategies. These classes mus implement the `UnleashStrategy` interface.\n   */\n  strategies?: Type\u003cUnleashStrategy\u003e[];\n\n  /**\n   * `nestjs-unleash` sends an initial registration request to the unleash server at startup. This behavior can be disabled by this option.\n   */\n  disableRegistration?: boolean;\n\n  /**\n   * Some strategies depend on the user ID of the currently logged in user. The\n   * user ID is expected by default in `request.user.id`. To customize this\n   * behavior, a custom user ID factory can be provided.\n   */\n  userIdFactory?: (request: Request\u003c{ id: string }\u003e) =\u003e string;\n}\n```\n\n## Default strategies\n\nThis module supports the [official standard activation strategies](https://docs.getunleash.io/docs/user_guide/activation_strategy). They do not need to be activated separately and work out of the box.\n\n## Custom strategies\n\nIn order to create a custom strategy you have to create a class wich inplements the `UnleashStrategy` interface:\n\n```ts\nimport { UnleashContext } from \"nestjs-unleash\";\n\nexport interface UnleashStrategy {\n  /**\n   * Must match the name you used to create the strategy in your Unleash\n   * server UI\n   */\n  name: string;\n\n  /**\n   * Determines whether the feature toggle is active\n   *\n   * @param parameters Custom paramemters as configured in Unleash server UI\n   * @param context applicaton/request context, i.e. UserID\n   */\n  isEnabled(parameters: unknown, context: UnleashContext): boolean;\n}\n```\n\nExample custom strategy:\n\n```ts\nimport { Injectable } from \"@nestjs/common\";\nimport { UnleashContext, UnleashStrategy } from \"nestjs-unleash\";\n\n@Injectable()\nexport class MyCustomStrategy implements UnleashStrategy {\n  name = \"MyCustomStrategy\";\n\n  isEnabled(parameters: any, context: UnleashContext): boolean {\n    return Math.random() \u003c 0.5;\n  }\n}\n```\n\nNow you can use it your module setup as follows:\n\n```ts\nimport { MyCustomStrategy } from \"./my-custom-strategy\";\n\n@Module({\n  imports: [\n    UnleashModule.forRoot({\n      // ...\n      strategies: [MyCustomStrategy],\n    }),\n  ],\n})\nexport class ApplicationModule {}\n```\n\n# License\n\nnestjs-unleash is distributed under the MIT license. [See LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmb0%2Fnestjs-unleash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmb0%2Fnestjs-unleash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmb0%2Fnestjs-unleash/lists"}