name |
the name for internal tracking of which throttler set is being used. Defaults to `default` if not passed |
ttl |
the number of milliseconds that each request will last in storage |
limit |
the maximum number of requests within the TTL limit |
blockDuration |
the number of milliseconds the request will be blocked |
ignoreUserAgents |
an array of regular expressions of user-agents to ignore when it comes to throttling requests |
skipIf |
a function that takes in the ExecutionContext and returns a boolean to short circuit the throttler logic. Like @SkipThrottler(), but based on the request |
getTracker |
a function that takes in the Request and ExecutionContext, and returns a string to override the default logic of the getTracker method |
generateKey |
a function that takes in the ExecutionContext, the tracker string and the throttler name as a string and returns a string to override the final key which will be used to store the rate limit value. This overrides the default logic of the generateKey method |
If you need to set up storages instead, or want to use a some of the above options in a more global sense, applying to each throttler set, you can pass the options above via the `throttlers` option key and use the below table
storage |
a custom storage service for where the throttling should be kept track. See Storages below. |
ignoreUserAgents |
an array of regular expressions of user-agents to ignore when it comes to throttling requests |
skipIf |
a function that takes in the ExecutionContext and returns a boolean to short circuit the throttler logic. Like @SkipThrottler(), but based on the request |
throttlers |
an array of throttler sets, defined using the table above |
errorMessage |
a string OR a function that takes in the ExecutionContext and the ThrottlerLimitDetail and returns a string which overrides the default throttler error message |
getTracker |
a function that takes in the Request and ExecutionContext, and returns a string to override the default logic of the getTracker method |
generateKey |
a function that takes in the ExecutionContext, the tracker string and the throttler name as a string and returns a string to override the final key which will be used to store the rate limit value. This overrides the default logic of the generateKey method |
#### Async Configuration
You may want to get your rate-limiting configuration asynchronously instead of synchronously. You can use the `forRootAsync()` method, which allows for dependency injection and `async` methods.
One approach would be to use a factory function:
```typescript
@Module({
imports: [
ThrottlerModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (config: ConfigService) => [
{
ttl: config.get('THROTTLE_TTL'),
limit: config.get('THROTTLE_LIMIT'),
},
],
}),
],
})
export class AppModule {}
```
You can also use the `useClass` syntax:
```typescript
@Module({
imports: [
ThrottlerModule.forRootAsync({
imports: [ConfigModule],
useClass: ThrottlerConfigService,
}),
],
})
export class AppModule {}
```
This is doable, as long as `ThrottlerConfigService` implements the interface `ThrottlerOptionsFactory`.
### Storages
The built in storage is an in memory cache that keeps track of the requests made until they have passed the TTL set by the global options. You can drop in your own storage option to the `storage` option of the `ThrottlerModule` so long as the class implements the `ThrottlerStorage` interface.
> **Note:** `ThrottlerStorage` can be imported from `@nestjs/throttler`.
### Time Helpers
There are a couple of helper methods to make the timings more readable if you prefer to use them over the direct definition. `@nestjs/throttler` exports five different helpers, `seconds`, `minutes`, `hours`, `days`, and `weeks`. To use them, simply call `seconds(5)` or any of the other helpers, and the correct number of milliseconds will be returned.
### Migrating to v5 from earlier versions
If you migrate to v5 from earlier versions, you need to wrap your options in an array.
If you are using a custom storage, you should wrap you `ttl` and `limit` in an array and assign it to the `throttlers` property of the options object.
Any `@SkipThrottle()` should now take in an object with `string: boolean` props. The strings are the names of the throttlers. If you do not have a name, pass the string `'default'`, as this is what will be used under the hood otherwise.
**Migration examples for decorators:**
```typescript
// Before v5
@SkipThrottle()
@Throttle(10, 60)
// After v5 (with default throttler)
@SkipThrottle({ default: true })
@Throttle({ default: { limit: 10, ttl: 60000 } })
// After v5 (with named throttlers)
@SkipThrottle({ short: true, medium: true })
@Throttle({ short: { limit: 5, ttl: 1000 }, long: { limit: 100, ttl: 60000 } })
```
Any `@Throttle()` decorators should also now take in an object with string keys, relating to the names of the throttler contexts (again, `'default'` if no name) and values of objects that have `limit` and `ttl` keys.
> **Important:** The `ttl` is now in **milliseconds**. If you want to keep your ttl in seconds for readability, use the `seconds` helper from this package. It just multiplies the ttl by 1000 to make it in milliseconds.
> **Note:** When using named throttlers, simply using `@SkipThrottle()` without parameters will not work as expected. See the [Important note on using decorators with Named Throttlers](#important-note-on-using-decorators-with-named-throttlers) section for details.
## Community Storage Providers
- [Redis](https://github.com/CSenshi/nestjs-redis/tree/main/packages/throttler-storage) (`node-redis` based)
- [Redis](https://github.com/jmcdo29/nest-lab/tree/main/packages/throttler-storage-redis) (`ioredis` based)
- [Mongo](https://www.npmjs.com/package/nestjs-throttler-storage-mongo)
Feel free to submit a PR with your custom storage provider being added to this list.
## License
Nest is [MIT licensed](LICENSE).
