express-rate-limit 6.1.0 → 6.2.0

package/changelog.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.2.0](https://github.com/nfriedly/express-rate-limit/releases/tag/v6.2.0)
+
+### Added
+
+- Export the `MemoryStore`, so it can now be imported as a named import
+  (`import { MemoryStore } from 'express-rate-limit'`).
+
+### Fixed
+
+- Deprecate the `onLimitReached` option (this was supposed to be deprecated in
+  v6.0.0 itself); developers should use a custom handler function that checks if
+  the rate limit has been exceeded instead.
+
 ## [6.1.0](https://github.com/nfriedly/express-rate-limit/releases/tag/v6.1.0)
 
 ### Added

package/dist/index.cjs

@@ -24,6 +24,7 @@ var __toCommonJS = /* @__PURE__ */ ((cache) => {
 // source/index.ts
 var source_exports = {};
 __export(source_exports, {
+  MemoryStore: () => MemoryStore,
   default: () => lib_default,
   rateLimit: () => lib_default
 });
@@ -221,4 +222,4 @@ var rateLimit = (passedOptions) => {
 };
 var lib_default = rateLimit;
 module.exports = __toCommonJS(source_exports);
-module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit;
+module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit; module.exports.MemoryStore = MemoryStore;

package/dist/index.d.ts

@@ -5,29 +5,29 @@ import { NextFunction, Request, RequestHandler, Response } from 'express';
 /**
  * Callback that fires when a client's hit counter is incremented.
  *
- * @param error {Error | undefined} - The error that occurred, if any
- * @param totalHits {number} - The number of hits for that client so far
- * @param resetTime {Date | undefined} - The time when the counter resets
+ * @param error {Error | undefined} - The error that occurred, if any.
+ * @param totalHits {number} - The number of hits for that client so far.
+ * @param resetTime {Date | undefined} - The time when the counter resets.
  */
 export declare type IncrementCallback = (error: Error | undefined, totalHits: number, resetTime: Date | undefined) => void;
 /**
  * Method (in the form of middleware) to generate/retrieve a value based on the
- * incoming request
+ * incoming request.
  *
- * @param request {Request} - The Express request object
- * @param response {Response} - The Express response object
+ * @param request {Request} - The Express request object.
+ * @param response {Response} - The Express response object.
  *
- * @returns {T} - The value needed
+ * @returns {T} - The value needed.
  */
 export declare type ValueDeterminingMiddleware<T> = (request: Request, response: Response) => T | Promise<T>;
 /**
  * Express request handler that sends back a response when a client is
  * rate-limited.
  *
- * @param request {Request} - The Express request object
- * @param response {Response} - The Express response object
- * @param next {NextFunction} - The Express `next` function, can be called to skip responding
- * @param optionsUsed {Options} - The options used to set up the middleware
+ * @param request {Request} - The Express request object.
+ * @param response {Response} - The Express response object.
+ * @param next {NextFunction} - The Express `next` function, can be called to skip responding.
+ * @param optionsUsed {Options} - The options used to set up the middleware.
  */
 export declare type RateLimitExceededEventHandler = (request: Request, response: Response, next: NextFunction, optionsUsed: Options) => void;
 /**
@@ -35,16 +35,16 @@ export declare type RateLimitExceededEventHandler = (request: Request, response:
  * but not for subsequent requests. May be used for logging, etc. Should *not*
  * send a response.
  *
- * @param request {Request} - The Express request object
- * @param response {Response} - The Express response object
- * @param optionsUsed {Options} - The options used to set up the middleware
+ * @param request {Request} - The Express request object.
+ * @param response {Response} - The Express response object.
+ * @param optionsUsed {Options} - The options used to set up the middleware.
  */
 export declare type RateLimitReachedEventHandler = (request: Request, response: Response, optionsUsed: Options) => void;
 /**
  * Data returned from the `Store` when a client's hit counter is incremented.
  *
- * @property totalHits {number} - The number of hits for that client so far
- * @property resetTime {Date | undefined} - The time when the counter resets
+ * @property totalHits {number} - The number of hits for that client so far.
+ * @property resetTime {Date | undefined} - The time when the counter resets.
  */
 export declare type IncrementResponse = {
 	totalHits: number;
@@ -57,7 +57,7 @@ export declare type RateLimitRequestHandler = RequestHandler & {
 	/**
 	 * Method to reset a client's hit counter.
 	 *
-	 * @param key {string} - The identifier for a client
+	 * @param key {string} - The identifier for a client.
 	 */
 	resetKey: (key: string) => void;
 };
@@ -70,20 +70,20 @@ export interface LegacyStore {
 	/**
 	 * Method to increment a client's hit counter.
 	 *
-	 * @param key {string} - The identifier for a client
-	 * @param callback {IncrementCallback} - The callback to call once the counter is incremented
+	 * @param key {string} - The identifier for a client.
+	 * @param callback {IncrementCallback} - The callback to call once the counter is incremented.
 	 */
 	incr: (key: string, callback: IncrementCallback) => void;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *
-	 * @param key {string} - The identifier for a client
+	 * @param key {string} - The identifier for a client.
 	 */
 	decrement: (key: string) => void;
 	/**
 	 * Method to reset a client's hit counter.
 	 *
-	 * @param key {string} - The identifier for a client
+	 * @param key {string} - The identifier for a client.
 	 */
 	resetKey: (key: string) => void;
 	/**
@@ -99,27 +99,27 @@ export interface Store {
 	 * Method that initializes the store, and has access to the options passed to
 	 * the middleware too.
 	 *
-	 * @param options {Options} - The options used to setup the middleware
+	 * @param options {Options} - The options used to setup the middleware.
 	 */
 	init?: (options: Options) => void;
 	/**
 	 * Method to increment a client's hit counter.
 	 *
-	 * @param key {string} - The identifier for a client
+	 * @param key {string} - The identifier for a client.
 	 *
-	 * @returns {IncrementResponse} - The number of hits and reset time for that client
+	 * @returns {IncrementResponse} - The number of hits and reset time for that client.
 	 */
 	increment: (key: string) => Promise<IncrementResponse> | IncrementResponse;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *
-	 * @param key {string} - The identifier for a client
+	 * @param key {string} - The identifier for a client.
 	 */
 	decrement: (key: string) => Promise<void> | void;
 	/**
 	 * Method to reset a client's hit counter.
 	 *
-	 * @param key {string} - The identifier for a client
+	 * @param key {string} - The identifier for a client.
 	 */
 	resetKey: (key: string) => Promise<void> | void;
 	/**
@@ -133,18 +133,24 @@ export interface Store {
 export interface Options {
 	/**
 	 * How long we should remember the requests.
+	 *
+	 * Defaults to `60000` ms (= 1 minute).
 	 */
 	readonly windowMs: number;
 	/**
-	 * The maximum number of connection to allow during the `window` before
+	 * The maximum number of connections to allow during the `window` before
 	 * rate limiting the client.
 	 *
 	 * Can be the limit itself as a number or express middleware that parses
 	 * the request and then figures out the limit.
+	 *
+	 * Defaults to `5`.
 	 */
 	readonly max: number | ValueDeterminingMiddleware<number>;
 	/**
 	 * The response body to send back when a client is rate limited.
+	 *
+	 * Defaults to `'Too many requests, please try again later.'`
 	 */
 	readonly message: any;
 	/**
@@ -156,10 +162,14 @@ export interface Options {
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
+	 *
+	 * Defaults to `true` (for backward compatibility).
 	 */
 	readonly legacyHeaders: boolean;
 	/**
-	 * Whether to enable support for the rate limit standardization headers (`RateLimit-*`).
+	 * Whether to enable support for the standardized rate limit headers (`RateLimit-*`).
+	 *
+	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
 	readonly standardHeaders: boolean;
 	/**
@@ -171,41 +181,57 @@ export interface Options {
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a 4XX
 	 * or 5XX status.
+	 *
+	 * Defaults to `false`.
 	 */
 	readonly skipFailedRequests: boolean;
 	/**
 	 * If `true`, the library will (by default) skip all requests that have a
 	 * status code less than 400.
+	 *
+	 * Defaults to `false`.
 	 */
 	readonly skipSuccessfulRequests: boolean;
-	/**
-	 * Method to determine whether or not the request counts as 'succesful'. Used
-	 * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
-	 */
-	readonly requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * Method to generate custom identifiers for clients.
 	 *
 	 * By default, the client's IP address is used.
 	 */
 	readonly keyGenerator: ValueDeterminingMiddleware<string>;
-	/**
-	 * Method (in the form of middleware) to determine whether or not this request
-	 * counts towards a client's quota.
-	 */
-	readonly skip: ValueDeterminingMiddleware<boolean>;
 	/**
 	 * 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.
 	 */
 	readonly handler: RateLimitExceededEventHandler;
 	/**
 	 * Express request handler that sends back a response when a client has
 	 * reached their rate limit, and will be rate limited on their next request.
+	 *
+	 * @deprecated 6.x - Please use a custom `handler` that checks the number of
+	 * hits instead.
 	 */
 	readonly onLimitReached: RateLimitReachedEventHandler;
 	/**
-	 * The {@link Store} to use to store the hit count for each client.
+	 * Method (in the form of middleware) to determine whether or not this request
+	 * counts towards a client's quota.
+	 *
+	 * By default, skips no requests.
+	 */
+	readonly skip: ValueDeterminingMiddleware<boolean>;
+	/**
+	 * Method to determine whether or not the request counts as 'succesful'. Used
+	 * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.
+	 *
+	 * By default, requests with a response status code less than 400 are considered
+	 * successful.
+	 */
+	readonly requestWasSuccessful: ValueDeterminingMiddleware<boolean>;
+	/**
+	 * The `Store` to use to store the hit count for each client.
+	 *
+	 * By default, the built-in `MemoryStore` will be used.
 	 */
 	store: Store;
 	/**
@@ -244,15 +270,74 @@ export interface RateLimitInfo {
  *
  * Create an instance of IP rate-limiting middleware for Express.
  *
- * @param passedOptions {Options} - Options to configure the rate limiter
+ * @param passedOptions {Options} - Options to configure the rate limiter.
  *
- * @returns {RateLimitRequestHandler} - The middleware that rate-limits clients based on your configuration
+ * @returns {RateLimitRequestHandler} - The middleware that rate-limits clients based on your configuration.
  *
  * @public
  */
 export declare const rateLimit: (passedOptions?: (Omit<Partial<Options>, "store"> & {
 	store?: LegacyStore | Store | undefined;
 }) | undefined) => RateLimitRequestHandler;
+/**
+ * A `Store` that stores the hit count for each client in memory.
+ *
+ * @public
+ */
+export declare class MemoryStore implements Store {
+	/**
+	 * The duration of time before which all hit counts are reset (in milliseconds).
+	 */
+	windowMs: number;
+	/**
+	 * The map that stores the number of hits for each client in memory.
+	 */
+	hits: {
+		[key: string]: number | undefined;
+	};
+	/**
+	 * The time at which all hit counts will be reset.
+	 */
+	resetTime: Date;
+	/**
+	 * Method that initializes the store.
+	 *
+	 * @param options {Options} - The options used to setup the middleware.
+	 */
+	init(options: Options): void;
+	/**
+	 * Method to increment a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {IncrementResponse} - The number of hits and reset time for that client.
+	 *
+	 * @public
+	 */
+	increment(key: string): Promise<IncrementResponse>;
+	/**
+	 * Method to decrement a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @public
+	 */
+	decrement(key: string): Promise<void>;
+	/**
+	 * Method to reset a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @public
+	 */
+	resetKey(key: string): Promise<void>;
+	/**
+	 * Method to reset everyone's hit counter.
+	 *
+	 * @public
+	 */
+	resetAll(): Promise<void>;
+}
 
 export {
 	rateLimit as default,

package/dist/index.mjs

@@ -191,6 +191,7 @@ var rateLimit = (passedOptions) => {
 };
 var lib_default = rateLimit;
 export {
+  MemoryStore,
   lib_default as default,
   lib_default as rateLimit
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "6.1.0",
+	"version": "6.2.0",
 	"description": "Basic IP rate-limiting middleware for Express. Use to limit repeated requests to public APIs and/or endpoints such as password reset.",
 	"author": {
 		"name": "Nathan Friedly",
@@ -50,7 +50,7 @@
 	},
 	"scripts": {
 		"clean": "del-cli dist/ coverage/ *.log *.tmp *.bak *.tgz",
-		"build:cjs": "esbuild --bundle --format=cjs --outfile=dist/index.cjs --footer:js=\"module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit;\" source/index.ts",
+		"build:cjs": "esbuild --bundle --format=cjs --outfile=dist/index.cjs --footer:js=\"module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit; module.exports.MemoryStore = MemoryStore;\" source/index.ts",
 		"build:esm": "esbuild --bundle --format=esm --outfile=dist/index.mjs source/index.ts",
 		"build:types": "dts-bundle-generator --out-file=dist/index.d.ts source/index.ts",
 		"compile": "run-s clean build:*",
@@ -73,21 +73,21 @@
 		"@jest/globals": "^27.4.6",
 		"@types/express": "^4.17.13",
 		"@types/jest": "^27.4.0",
-		"@types/node": "^16.11.19",
+		"@types/node": "^16.11.21",
 		"@types/supertest": "^2.0.11",
 		"cross-env": "^7.0.3",
 		"del-cli": "^4.0.1",
 		"dts-bundle-generator": "^6.4.0",
-		"esbuild": "^0.14.11",
+		"esbuild": "^0.14.12",
 		"express": "^4.17.1",
 		"husky": "^7.0.4",
 		"jest": "^27.4.7",
-		"lint-staged": "^12.1.7",
+		"lint-staged": "^12.2.2",
 		"npm-run-all": "^4.1.5",
-		"supertest": "^6.2.1",
-		"ts-jest": "^27.1.1",
+		"supertest": "^6.2.2",
+		"ts-jest": "^27.1.3",
 		"ts-node": "^10.4.0",
-		"typescript": "^4.5.2",
+		"typescript": "^4.5.5",
 		"xo": "^0.47.0"
 	},
 	"xo": {

package/readme.md

@@ -22,9 +22,9 @@ This module was designed to only handle the basics and didn't even support
 external stores initially. These other options all are excellent pieces of
 software and may be more appropriate for some situations:
 
-- [rate-limiter-flexible](https://www.npmjs.com/package/rate-limiter-flexible)
-- [express-brute](https://www.npmjs.com/package/express-brute)
-- [rate-limiter](https://www.npmjs.com/package/express-limiter)
+- [`rate-limiter-flexible`](https://www.npmjs.com/package/rate-limiter-flexible)
+- [`express-brute`](https://www.npmjs.com/package/express-brute)
+- [`rate-limiter`](https://www.npmjs.com/package/express-limiter)
 
 ## Installation
 
@@ -139,8 +139,7 @@ app.post('/create-account', createAccountLimiter, (request, response) => {
 To use a custom store:
 
 ```ts
-import rateLimit from 'express-rate-limit'
-import MemoryStore from 'express-rate-limit/memory-store.js'
+import rateLimit, { MemoryStore } from 'express-rate-limit'
 
 const apiLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
@@ -189,64 +188,55 @@ it does.
 For more information about the `trust proxy` setting, take a look at the
 [official Express documentation](https://expressjs.com/en/guide/behind-proxies.html).
 
-## Request API
-
-A `request.rateLimit` property is added to all requests with the `limit`,
-`current`, and `remaining` number of requests and, if the store provides it, a
-`resetTime` Date object. These may be used in your application code to take
-additional actions or inform the user of their status.
-
-The property name can be configured with the configuration option
-`requestPropertyName`
-
-## Configuration options
+## Configuration
 
 ### `windowMs`
 
+> `number`
+
 Time frame for which requests are checked/remembered. Also used in the
 `Retry-After` header when the limit is reached.
 
-Note: with non-default stores, you may need to configure this value twice, once
-here and once on the store. In some cases the units also differ (e.g. seconds vs
-miliseconds)
+Note: with stores that do not implement the `init` function (see the table in
+the [`stores` section below](#stores)), you may need to configure this value
+twice, once here and once on the store. In some cases the units also differ
+(e.g. seconds vs miliseconds).
 
 Defaults to `60000` ms (= 1 minute).
 
 ### `max`
 
-Max number of connections during `windowMs` milliseconds before sending a 429
-response.
+> `number | function`
 
-May be a number, or a function that returns a number or a promise. If `max` is a
-function, it will be called with `request` and `response` params.
+The maximum number of connections to allow during the `window` before rate
+limiting the client.
 
-Defaults to `5`. Set to `0` to disable.
+Can be the limit itself as a number or a (sync/async) function that accepts the
+Express `request` and `response` objects and then returns a number.
 
-Example of using a function:
+Defaults to `5`. Set it to `0` to disable the rate limiter.
 
-```ts
-import rateLimit from 'express-rate-limit'
+An example of using a function:
 
-const isPremium = (request) => {
+```ts
+const isPremium = async (user) => {
 	// ...
 }
 
 const limiter = rateLimit({
-	// `max` could also be an async function or return a promise
-	max: (request, response) => {
-		if (isPremium(request)) return 10
+	// ...
+	max: async (request, response) => {
+		if (await isPremium(request.user)) return 10
 		else return 5
 	},
-	// ...
 })
-
-// Apply the rate limiting middleware to all requests
-app.use(limiter)
 ```
 
 ### `message`
 
-Error message sent to user when `max` is exceeded.
+> `any`
+
+The response body to send back when a client is rate limited.
 
 May be a `string`, JSON object, or any other value that Express's
 [response.send](https://expressjs.com/en/4x/api.html#response.send) method
@@ -256,240 +246,208 @@ Defaults to `'Too many requests, please try again later.'`
 
 ### `statusCode`
 
-HTTP status code returned when `max` is exceeded.
+> `number`
+
+The HTTP status code to send back when a client is rate limited.
 
-Defaults to `429`.
+Defaults to `429` (HTTP 429 Too Many Requests - RFC 6585).
 
 ### `legacyHeaders`
 
-Enable headers for request limit (`X-RateLimit-Limit`) and current usage
-(`X-RateLimit-Remaining`) on all responses and time to wait before retrying
-(`Retry-After`) when `max` is exceeded.
+> `boolean`
+
+Whether to send the legacy rate limit headers for the limit
+(`X-RateLimit-Limit`), current usage (`X-RateLimit-Remaining`) and reset time
+(if the store provides it) (`X-RateLimit-Reset`) on all responses. If set to
+`true`, the middleware also sends the `Retry-After` header on all blocked
+requests.
 
-Defaults to `true`.
+Defaults to `true` (for backward compatibility).
 
 > Renamed in `6.x` from `headers` to `legacyHeaders`.
 
 ### `standardHeaders`
 
-Enable headers conforming to the
-[ratelimit standardization draft](https://github.com/ietf-wg-httpapi/ratelimit-headers/blob/main/draft-ietf-httpapi-ratelimit-headers.md)
-adopted by the IETF: `RateLimit-Limit`, `RateLimit-Remaining`, and, if the store
-supports it, `RateLimit-Reset`. May be used in conjunction with, or instead of
-the `legacyHeaders` option.
+> `boolean`
 
-This setting also enables the `Retry-After` header when `max` is exceeded.
+Whether to enable support for headers conforming to the
+[ratelimit standardization draft](https://github.com/ietf-wg-httpapi/ratelimit-headers/blob/main/draft-ietf-httpapi-ratelimit-headers.md)
+adopted by the IETF (`RateLimit-Limit`, `RateLimit-Remaining`, and, if the store
+supports it, `RateLimit-Reset`). If set to `true`, the middleware also sends the
+`Retry-After` header on all blocked requests. May be used in conjunction with,
+or instead of the `legacyHeaders` option.
 
-Defaults to `false` (for backward compatibility), but recommended to use.
+Defaults to `false` (for backward compatibility, but its use is recommended).
 
 > Renamed in `6.x` from `draft_polli_ratelimit_headers` to `standardHeaders`.
 
-### `keyGenerator`
+### `requestPropertyName`
 
-Function used to generate keys.
+> `string`
 
-Defaults to `request.ip`, similar to this:
+The name of the property on the Express `request` object to store the rate limit
+info.
 
-```ts
-const keyGenerator = (request /*, response*/) => request.ip
-```
+Defaults to `'rateLimit'`.
 
-### `handler`
+### `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
+
+(Technically they 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!)
+
+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 < 400.
+
+(Technically they 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!)
+
+Defaults to `false`.
+
+### `keyGenerator`
 
-The function to handle requests once the max limit is exceeded. It receives the
-`request` and the `response` objects. The `next` param is available if you need
-to pass to the next middleware/route. Finally, the `options` param has all of
-the options that originally passed in when creating the current limiter and the
-default values for other options.
+> `function`
 
-The `request.rateLimit` object has `limit`, `current`, and `remaining` number of
-requests and, if the store provides it, a `resetTime` Date object.
+Method to generate custom identifiers for clients.
 
-Defaults to:
+Should be a (sync/async) function that accepts the Express `request` and
+`response` objects and then returns a string.
+
+By default, the client's IP address is used:
 
 ```ts
-const handler = (request, response, next, options) => {
-	response.status(options.statusCode).send(options.message)
-}
+const limiter = rateLimit({
+	// ...
+	keyGenerator: (request, response) => request.ip,
+})
 ```
 
-### `requestWasSuccessful`
+### `handler`
 
-Function that is called when `skipFailedRequests` and/or
-`skipSuccessfulRequests` are set to `true`. May be overridden if, for example, a
-service sends out a 200 status code on errors.
+> `function`
 
-Defaults to
+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:
 
 ```ts
-const requestWasSuccessful = (request, response) => response.statusCode < 400
+const limiter = rateLimit({
+	// ...
+	handler: (request, response, next, options) =>
+		response.status(options.statusCode).send(options.message),
+})
 ```
 
-### `skipFailedRequests`
+### `onLimitReached`
 
-When set to `true`, failed requests won't be counted. Request considered failed
-when:
+> `function`
 
-- response status >= 400
-- requests that were cancelled before last chunk of data was sent (response
-  `close` event triggered)
-- response `error` event was triggered by response
+A (sync/async) function that accepts the Express `request` and `response`
+objects that is called when a client has reached their rate limit, and will be
+rate limited on their next request.
 
-(Technically they 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.)
+This method was
+[deprecated in v6](https://github.com/nfriedly/express-rate-limit/releases/v6.0.0) -
+Please use a custom `handler` that checks the number of hits instead.
 
-Defaults to `false`.
+### `skip`
 
-### `skipSuccessfulRequests`
+> `function`
 
-When set to `true` successful requests (response status < 400) won't be counted.
-(Technically they 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.)
+Function to determine whether or not this request counts towards a client's
+quota. Should be a (sync/async) function that accepts the Express `request` and
+`response` objects and then returns `true` or `false`.
 
-Defaults to `false`.
+Could also act as an allowlist for certain keys:
 
-### `skip`
+```ts
+const allowlist = ['192.168.0.56', '192.168.0.21']
 
-Function used to skip (whitelist) requests. Returning `true`, or a promise that
-resolves with `true`, from the function will skip limiting for that request.
+const limiter = rateLimit({
+	// ...
+	skip: (request, response) => allowlist.includes(request.ip),
+})
+```
 
-Defaults to always `false` (count all requests):
+By default, it skips no requests:
 
 ```ts
-const skip = (/*request, response*/) => false
+const limiter = rateLimit({
+	// ...
+	skip: (request, response) => false,
+})
 ```
 
-### `requestPropertyName`
+### `requestWasSuccessful`
 
-The name of the property that contains the rate limit information to add to the
-`request` object.
+> `function`
 
-Defaults to `rateLimit`.
+Method to determine whether or not the request counts as 'succesful'. Used when
+either `skipSuccessfulRequests` or `skipFailedRequests` is set to true. Should
+be a (sync/async) function that accepts the Express `request` and `response`
+objects and then returns `true` or `false`.
+
+By default, requests with a response status code less than 400 are considered
+successful:
+
+```ts
+const limiter = rateLimit({
+	// ...
+	requestWasSuccessful: (request, response) => response.statusCode < 400,
+})
+```
 
 ### `store`
 
-The storage to use when persisting rate limit attempts.
+> `Store`
 
-By default, the [memory store](source/memory-store.ts) is used.
+The `Store` to use to store the hit count for each client.
 
-Available data stores are:
+By default, the [`memory-store`](source/memory-store.ts) is used.
 
-- [memory-store](source/memory-store.ts): _(default)_ Simple in-memory option.
-  Does not share state when app has multiple processes or servers.
-- [rate-limit-redis](https://npmjs.com/package/rate-limit-redis): A
-  [Redis](http://redis.io/)-backed store, more suitable for large or demanding
-  deployments.
-- [rate-limit-memcached](https://npmjs.org/package/rate-limit-memcached): A
-  [Memcached](https://memcached.org/)-backed store.
-- [rate-limit-mongo](https://www.npmjs.com/package/rate-limit-mongo): A
-  [MongoDB](https://www.mongodb.com/)-backed store.
-- [precise-memory-rate-limit](https://www.npmjs.com/package/precise-memory-rate-limit) -
-  A memory store similar to the built-in one, except that it stores a distinct
-  timestamp for each IP rather than bucketing them together.
+Here is a list of external stores:
 
-You may also create your own store. It must implement the `Store` interface as
-follows:
+| Name                                                                                   | Description                                                                                           | Legacy/Modern       |
+| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------- |
+| [`memory-store`](source/memory-store.ts)                                               | _(default)_ Simple in-memory option. Does not share state when app has multiple processes or servers. | Modern as of v6.0.0 |
+| [`rate-limit-redis`](https://npmjs.com/package/rate-limit-redis)                       | A [Redis](http://redis.io/)-backed store, more suitable for large or demanding deployments.           | Modern as of v3.0.0 |
+| [`rate-limit-memcached`](https://npmjs.org/package/rate-limit-memcached)               | A [Memcached](https://memcached.org/)-backed store.                                                   | Legacy              |
+| [`rate-limit-mongo`](https://www.npmjs.com/package/rate-limit-mongo)                   | A [MongoDB](https://www.mongodb.com/)-backed store.                                                   | Legacy              |
+| [`precise-memory-rate-limit`](https://www.npmjs.com/package/precise-memory-rate-limit) | A memory store similar to the built-in one, except that it stores a distinct timestamp for each key.  | Legacy              |
 
-```ts
-import rateLimit, {
-	Store,
-	Options,
-	IncrementResponse,
-} from 'express-rate-limit'
-
-/**
- * A {@link Store} that stores the hit count for each client.
- *
- * @public
- */
-class SomeStore implements Store {
-	/**
-	 * Some store-specific parameter.
-	 */
-	customParam!: string
-	/**
-	 * The duration of time before which all hit counts are reset (in milliseconds).
-	 */
-	windowMs!: number
-
-	/**
-	 * @constructor for {@link SomeStore}. Only required if the user needs to pass
-	 * some store specific parameters. For example, in a Mongo Store, the user will
-	 * need to pass the URI, username and password for the Mongo database.
-	 *
-	 * @param customParam {string} - Some store-specific parameter.
-	 */
-	constructor(customParam: string) {
-		this.customParam = customParam
-	}
-
-	/**
-	 * Method that actually initializes the store. Must be synchronous.
-	 *
-	 * @param options {Options} - The options used to setup the middleware.
-	 *
-	 * @public
-	 */
-	init(options: Options): void {
-		this.windowMs = options.windowMs
-
-		// ...
-	}
-
-	/**
-	 * Method to increment a client's hit counter.
-	 *
-	 * @param key {string} - The identifier for a client
-	 *
-	 * @returns {IncrementResponse} - The number of hits and reset time for that client
-	 *
-	 * @public
-	 */
-	async increment(key: string): Promise<IncrementResponse> {
-		// ...
-
-		return {
-			totalHits,
-			resetTime,
-		}
-	}
-
-	/**
-	 * Method to decrement a client's hit counter.
-	 *
-	 * @param key {string} - The identifier for a client
-	 *
-	 * @public
-	 */
-	async decrement(key: string): Promise<void> {
-		// ...
-	}
-
-	/**
-	 * Method to reset a client's hit counter.
-	 *
-	 * @param key {string} - The identifier for a client
-	 *
-	 * @public
-	 */
-	async resetKey(key: string): Promise<void> {
-		// ...
-	}
-
-	/**
-	 * Method to reset everyone's hit counter.
-	 *
-	 * @public
-	 */
-	async resetAll(): Promise<void> {
-		// ...
-	}
-}
+Take a look at
+[this guide](https://github.com/nfriedly/express-rate-limit/wiki/Creating-Your-Own-Store)
+if you wish to create your own store.
 
-export default SomeStore
-```
+## Request API
+
+A `request.rateLimit` property is added to all requests with the `limit`,
+`current`, and `remaining` number of requests and, if the store provides it, a
+`resetTime` Date object. These may be used in your application code to take
+additional actions or inform the user of their status.
+
+The property name can be configured with the configuration option
+`requestPropertyName`.
 
 ## Instance API