Skip to content

Commit

Permalink
docs: re-order config options to group related ones together
Browse files Browse the repository at this point in the history
  • Loading branch information
@nfriedly
nfriedly committed Jun 4, 2024
1 parent c33e774 commit 120d160
Show file tree
Hide file tree
Showing 2 changed files with 117 additions and 89 deletions.
144 changes: 72 additions & 72 deletions docs/reference/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,24 @@ RFC 6585.

</Note>

## `handler`

> `function`
Express request handler that sends back a response when a client is
rate-limited.

By default, sends back the `statusCode` and `message` set via the `options`,
similar to this:

```ts
const limiter = rateLimit({
// ...
handler: (req, res, next, options) =>
res.status(options.statusCode).send(options.message),
})
```

## `legacyHeaders`

> `boolean`
Expand Down Expand Up @@ -184,55 +202,18 @@ library in clients to read/parse any form of headers.

Defaults to `false`.

## `requestPropertyName`

> `string`
The name of the property on the Express `request` object to store the rate limit
info.

Defaults to `'rateLimit'`.

## `skipFailedRequests`

> `boolean`
When set to `true`, failed requests won't be counted. Request considered failed
when the `requestWasSuccessful` option returns `false`. By default, this means
requests fail when:

- the response status >= `400`
- the request was cancelled before last chunk of data was sent (response `close`
event triggered)
- the response `error` event was triggered by response

<Note>

Technically, the requests are counted and then un-counted, so a large number of
slow requests all at once could still trigger a rate-limit. This may be fixed in
a future release. PRs welcome!

</Note>

Defaults to `false`.

## `skipSuccessfulRequests`

> `boolean`
If `true`, the library will (by default) skip all requests that are considered
'failed' by the `requestWasSuccessful` function. By default, this means requests
succeed when the response status code less than `400`.
## `store`

<Note>
> `Store`
Technically, the requests are counted and then un-counted, so a large number of
slow requests all at once could still trigger a rate-limit. This may be fixed in
a future release. PRs welcome!
The `Store` to use to store the hit count for each client.

</Note>
By default, the
[`memory-store`](https://github.com/express-rate-limit/express-rate-limit/blob/main/source/memory-store.ts)
is used.

Defaults to `false`.
See [Data Stores](/reference/stores) for a list of avaliable stores and other
information.

## `keyGenerator`

Expand Down Expand Up @@ -261,23 +242,14 @@ rate limiter. This could be combined with a second instance of

</Note>

## `handler`

> `function`
## `requestPropertyName`

Express request handler that sends back a response when a client is
rate-limited.
> `string`
By default, sends back the `statusCode` and `message` set via the `options`,
similar to this:
The name of the property on the Express `request` object to store the rate limit
info.

```ts
const limiter = rateLimit({
// ...
handler: (req, res, next, options) =>
res.status(options.statusCode).send(options.message),
})
```
Defaults to `'rateLimit'`.

## `skip`

Expand Down Expand Up @@ -307,6 +279,47 @@ const limiter = rateLimit({
})
```

## `skipSuccessfulRequests`

> `boolean`
If `true`, the library will (by default) skip all requests that are considered
'failed' by the `requestWasSuccessful` function. By default, this means requests
succeed when the response status code less than `400`.

<Note>

Technically, the requests are counted and then un-counted, so a large number of
slow requests all at once could still trigger a rate-limit. This may be fixed in
a future release. PRs welcome!

</Note>

Defaults to `false`.

## `skipFailedRequests`

> `boolean`
When set to `true`, failed requests won't be counted. Request considered failed
when the `requestWasSuccessful` option returns `false`. By default, this means
requests fail when:

- the response status >= `400`
- the request was cancelled before last chunk of data was sent (response `close`
event triggered)
- the response `error` event was triggered by response

<Note>

Technically, the requests are counted and then un-counted, so a large number of
slow requests all at once could still trigger a rate-limit. This may be fixed in
a future release. PRs welcome!

</Note>

Defaults to `false`.

## `requestWasSuccessful`

> `function`
Expand Down Expand Up @@ -368,16 +381,3 @@ Supported validations are:
- [validationsConfig](/reference/error-codes#err-erl-unknown-validation)

Defaults to `true`.

## `store`

> `Store`
The `Store` to use to store the hit count for each client.

By default, the
[`memory-store`](https://github.com/express-rate-limit/express-rate-limit/blob/main/source/memory-store.ts)
is used.

See [Data Stores](/reference/stores) for a list of avaliable stores and other
information.
62 changes: 45 additions & 17 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,23 +45,23 @@ The rate limiter comes with a built-in memory store, and supports a variety of
All function options may be async. Click the name for additional info and
default values.

| Option | Type | Remarks |
| ------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------- |
| [`windowMs`](https://express-rate-limit.mintlify.app/reference/configuration#windowms) | `number` | How long to remember requests for, in milliseconds. |
| [`limit`](https://express-rate-limit.mintlify.app/reference/configuration#limit) | `number` \| `function` | How many requests to allow. |
| [`message`](https://express-rate-limit.mintlify.app/reference/configuration#message) | `string` \| `json` \| `function` | Response to return after limit is reached. |
| [`statusCode`](https://express-rate-limit.mintlify.app/reference/configuration#statuscode) | `number` | HTTP status code after limit is reached (default is 429). |
| [`legacyHeaders`](https://express-rate-limit.mintlify.app/reference/configuration#legacyheaders) | `boolean` | Enable the `X-Rate-Limit` header. |
| [`standardHeaders`](https://express-rate-limit.mintlify.app/reference/configuration#standardheaders) | `'draft-6'` \| `'draft-7'` | Enable the `Ratelimit` header. |
| [`requestPropertyName`](https://express-rate-limit.mintlify.app/reference/configuration#requestpropertyname) | `string` | Add rate limit info to the `req` object. |
| [`skipFailedRequests`](https://express-rate-limit.mintlify.app/reference/configuration#skipfailedrequests) | `boolean` | Uncount 4xx/5xx responses. |
| [`skipSuccessfulRequests`](https://express-rate-limit.mintlify.app/reference/configuration#skipsuccessfulrequests) | `boolean` | Uncount 1xx/2xx/3xx responses. |
| [`keyGenerator`](https://express-rate-limit.mintlify.app/reference/configuration#keygenerator) | `function` | Identify users (defaults to IP address). |
| [`handler`](https://express-rate-limit.mintlify.app/reference/configuration#handler) | `function` | Function to run after limit is reached (overrides `message` and `statusCode` settings, if set). |
| [`skip`](https://express-rate-limit.mintlify.app/reference/configuration#skip) | `function` | Return `true` to bypass the limiter for the given request. |
| [`requestWasSuccessful`](https://express-rate-limit.mintlify.app/reference/configuration#requestwassuccessful) | `function` | Used by `skipFailedRequests` and `skipSuccessfulRequests`. |
| [`validate`](https://express-rate-limit.mintlify.app/reference/configuration#validate) | `boolean` \| `object` | Enable or disable built-in validation checks. |
| [`store`](https://express-rate-limit.mintlify.app/reference/configuration#store) | `Store` | Use a custom store to share hit counts across multiple nodes. |
| Option | Type | Remarks |
| -------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
| [`windowMs`] | `number` | How long to remember requests for, in milliseconds. |
| [`limit`] | `number` \| `function` | How many requests to allow. |
| [`message`] | `string` \| `json` \| `function` | Response to return after limit is reached. |
| [`statusCode`] | `number` | HTTP status code after limit is reached (default is 429). |
| [`handler`] | `function` | Function to run after limit is reached (overrides `message` and `statusCode` settings, if set). |
| [`legacyHeaders`] | `boolean` | Enable the `X-Rate-Limit` header. |
| [`standardHeaders`] | `'draft-6'` \| `'draft-7'` | Enable the `Ratelimit` header. |
| [`store`] | `Store` | Use a custom store to share hit counts across multiple nodes. |
| [`keyGenerator`] | `function` | Identify users (defaults to IP address). |
| [`requestPropertyName`] | `string` | Add rate limit info to the `req` object. |
| [`skip`] | `function` | Return `true` to bypass the limiter for the given request. |
| [`skipSuccessfulRequests`] | `boolean` | Uncount 1xx/2xx/3xx responses. |
| [`skipFailedRequests`] | `boolean` | Uncount 4xx/5xx responses. |
| [`requestWasSuccessful`] | `function` | Used by `skipSuccessfulRequests` and `skipFailedRequests`. |
| [`validate`] | `boolean` \| `object` | Enable or disable built-in validation checks. |

## Thank You

Expand Down Expand Up @@ -111,3 +111,31 @@ Then you can pick up any issue and fix/implement it!

MIT © [Nathan Friedly](http://nfriedly.com/),
[Vedant K](https://github.com/gamemaker1)

[`windowMs`]:
https://express-rate-limit.mintlify.app/reference/configuration#windowms
[`limit`]: https://express-rate-limit.mintlify.app/reference/configuration#limit
[`message`]:
https://express-rate-limit.mintlify.app/reference/configuration#message
[`statusCode`]:
https://express-rate-limit.mintlify.app/reference/configuration#statuscode
[`handler`]:
https://express-rate-limit.mintlify.app/reference/configuration#handler
[`legacyHeaders`]:
https://express-rate-limit.mintlify.app/reference/configuration#legacyheaders
[`standardHeaders`]:
https://express-rate-limit.mintlify.app/reference/configuration#standardheaders
[`store`]: https://express-rate-limit.mintlify.app/reference/configuration#store
[`keyGenerator`]:
https://express-rate-limit.mintlify.app/reference/configuration#keygenerator
[`requestPropertyName`]:
https://express-rate-limit.mintlify.app/reference/configuration#requestpropertyname
[`skip`]: https://express-rate-limit.mintlify.app/reference/configuration#skip
[`skipSuccessfulRequests`]:
https://express-rate-limit.mintlify.app/reference/configuration#skipsuccessfulrequests
[`skipFailedRequests`]:
https://express-rate-limit.mintlify.app/reference/configuration#skipfailedrequests
[`requestWasSuccessful`]:
https://express-rate-limit.mintlify.app/reference/configuration#requestwassuccessful
[`validate`]:
https://express-rate-limit.mintlify.app/reference/configuration#validate

0 comments on commit 120d160

Please sign in to comment.