express-rate-limit 6.0.4 → 6.2.1

package/changelog.md

@@ -6,12 +6,56 @@ 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
+
+- Added a named export `rateLimit` in case the default import does not work.
+
+### Fixed
+
+- Added a named export `default`, so Typescript CommonJS developers can
+  default-import the library (`import rateLimit from 'express-rate-limit'`).
+
+## [6.0.5](https://github.com/nfriedly/express-rate-limit/releases/tag/v6.0.5)
+
+### Fixed
+
+- Use named imports for ExpressJS types so users do not need to enable the
+  `esModuleInterop` flag in their Typescript compiler configuration.
+
+## [6.0.4](https://github.com/nfriedly/express-rate-limit/releases/tag/v6.0.4)
+
+### Fixed
+
+- Upload the built package as a `.tgz` to GitHub releases.
+
+### Changed
+
+- Add ` main` and `module` fields to `package.json`. This helps tools such as
+  ESLint that do not yet support the `exports` field.
+- Bumped the minimum node.js version in `package-lock.json` to match
+  `package.json`
+
 ## [6.0.3](https://github.com/nfriedly/express-rate-limit/releases/tag/v6.0.3)
 
 ### Changed
 
-- Bumped minimum Node version from 12.9 to 14.5 because the transpiled output
-  uses the nullish coalescing operator (`??`), which
+- Bumped minimum Node version from 12.9 to 14.5 in `package.json` because the
+  transpiled output uses the nullish coalescing operator (`??`), which
   [isn't supported in node.js prior to 14.x](https://node.green/#ES2020-features--nullish-coalescing-operator-----).
 
 ## [6.0.2](https://github.com/nfriedly/express-rate-limit/releases/v6.0.2)

package/dist/index.cjs

@@ -24,7 +24,9 @@ var __toCommonJS = /* @__PURE__ */ ((cache) => {
 // source/index.ts
 var source_exports = {};
 __export(source_exports, {
-  default: () => source_default
+  MemoryStore: () => MemoryStore,
+  default: () => lib_default,
+  rateLimit: () => lib_default
 });
 
 // source/memory-store.ts
@@ -99,9 +101,9 @@ var promisifyStore = (passedStore) => {
   return new PromisifiedStore();
 };
 var parseOptions = (passedOptions) => {
-  const options = {
+  const notUndefinedOptions = omitUndefinedOptions(passedOptions);
+  const config = {
     windowMs: 60 * 1e3,
-    store: new MemoryStore(),
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
@@ -119,17 +121,17 @@ var parseOptions = (passedOptions) => {
       return request.ip;
     },
     handler: (_request, response, _next, _optionsUsed) => {
-      response.status(options.statusCode).send(options.message);
+      response.status(config.statusCode).send(config.message);
     },
     onLimitReached: (_request, _response, _optionsUsed) => {
     },
-    ...passedOptions
+    ...notUndefinedOptions,
+    store: promisifyStore(notUndefinedOptions.store ?? new MemoryStore())
   };
-  if (typeof options.store.incr !== "function" && typeof options.store.increment !== "function" || typeof options.store.decrement !== "function" || typeof options.store.resetKey !== "function" || typeof options.store.resetAll !== "undefined" && typeof options.store.resetAll !== "function" || typeof options.store.init !== "undefined" && typeof options.store.init !== "function") {
+  if (typeof config.store.increment !== "function" || typeof config.store.decrement !== "function" || typeof config.store.resetKey !== "function" || typeof config.store.resetAll !== "undefined" && typeof config.store.resetAll !== "function" || typeof config.store.init !== "undefined" && typeof config.store.init !== "function") {
     throw new TypeError("An invalid store was passed. Please ensure that the store is a class that implements the `Store` interface.");
   }
-  options.store = promisifyStore(options.store);
-  return options;
+  return config;
 };
 var handleAsyncErrors = (fn) => async (request, response, next) => {
   try {
@@ -218,9 +220,16 @@ var rateLimit = (passedOptions) => {
   middleware.resetKey = options.store.resetKey.bind(options.store);
   return middleware;
 };
+var omitUndefinedOptions = (passedOptions) => {
+  const omittedOptions = {};
+  for (const k of Object.keys(passedOptions)) {
+    const key = k;
+    if (passedOptions[key] !== void 0) {
+      omittedOptions[key] = passedOptions[key];
+    }
+  }
+  return omittedOptions;
+};
 var lib_default = rateLimit;
-
-// source/index.ts
-var source_default = lib_default;
 module.exports = __toCommonJS(source_exports);
-module.exports = rateLimit;
+module.exports = rateLimit; module.exports.default = rateLimit; module.exports.rateLimit = rateLimit; module.exports.MemoryStore = MemoryStore;

package/dist/index.d.ts

@@ -1,50 +1,50 @@
-// Generated by dts-bundle-generator v6.2.0
+// Generated by dts-bundle-generator v6.4.0
 
-import Express from 'express';
+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 {Express.Request} - The Express request object
- * @param response {Express.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: Express.Request, response: Express.Response) => T | Promise<T>;
+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 {Express.Request} - The Express request object
- * @param response {Express.Response} - The Express response object
- * @param next {Express.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: Express.Request, response: Express.Response, next: Express.NextFunction, optionsUsed: Options) => void;
+export declare type RateLimitExceededEventHandler = (request: Request, response: Response, next: NextFunction, optionsUsed: Options) => void;
 /**
  * Event callback that is triggered on a client's first request that exceeds the limit
  * but not for subsequent requests. May be used for logging, etc. Should *not*
  * send a response.
  *
- * @param request {Express.Request} - The Express request object
- * @param response {Express.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: Express.Request, response: Express.Response, optionsUsed: Options) => void;
+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;
@@ -53,11 +53,11 @@ export declare type IncrementResponse = {
 /**
  * A modified Express request handler with the rate limit functions.
  */
-export declare type RateLimitRequestHandler = Express.RequestHandler & {
+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,43 +181,59 @@ 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.
 	 */
-	store: Store;
+	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 | LegacyStore;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
@@ -227,7 +253,7 @@ export interface Options {
  * The extended request object that includes information about the client's
  * rate limit.
  */
-export declare type AugmentedRequest = Express.Request & {
+export declare type AugmentedRequest = Request & {
 	[key: string]: RateLimitInfo;
 };
 /**
@@ -240,9 +266,79 @@ export interface RateLimitInfo {
 	readonly remaining: number;
 	readonly resetTime: Date | undefined;
 }
-declare const rateLimit: (passedOptions?: (Omit<Partial<Options>, "store"> & {
-	store?: LegacyStore | Store | undefined;
-}) | undefined) => RateLimitRequestHandler;
-export default rateLimit;
+/**
+ *
+ * Create an instance of IP rate-limiting middleware for Express.
+ *
+ * @param passedOptions {Options} - Options to configure the rate limiter.
+ *
+ * @returns {RateLimitRequestHandler} - The middleware that rate-limits clients based on your configuration.
+ *
+ * @public
+ */
+export declare const rateLimit: (passedOptions?: Partial<Options> | 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,
+};
 
 export {};

package/dist/index.mjs

@@ -70,9 +70,9 @@ var promisifyStore = (passedStore) => {
   return new PromisifiedStore();
 };
 var parseOptions = (passedOptions) => {
-  const options = {
+  const notUndefinedOptions = omitUndefinedOptions(passedOptions);
+  const config = {
     windowMs: 60 * 1e3,
-    store: new MemoryStore(),
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
@@ -90,17 +90,17 @@ var parseOptions = (passedOptions) => {
       return request.ip;
     },
     handler: (_request, response, _next, _optionsUsed) => {
-      response.status(options.statusCode).send(options.message);
+      response.status(config.statusCode).send(config.message);
     },
     onLimitReached: (_request, _response, _optionsUsed) => {
     },
-    ...passedOptions
+    ...notUndefinedOptions,
+    store: promisifyStore(notUndefinedOptions.store ?? new MemoryStore())
   };
-  if (typeof options.store.incr !== "function" && typeof options.store.increment !== "function" || typeof options.store.decrement !== "function" || typeof options.store.resetKey !== "function" || typeof options.store.resetAll !== "undefined" && typeof options.store.resetAll !== "function" || typeof options.store.init !== "undefined" && typeof options.store.init !== "function") {
+  if (typeof config.store.increment !== "function" || typeof config.store.decrement !== "function" || typeof config.store.resetKey !== "function" || typeof config.store.resetAll !== "undefined" && typeof config.store.resetAll !== "function" || typeof config.store.init !== "undefined" && typeof config.store.init !== "function") {
     throw new TypeError("An invalid store was passed. Please ensure that the store is a class that implements the `Store` interface.");
   }
-  options.store = promisifyStore(options.store);
-  return options;
+  return config;
 };
 var handleAsyncErrors = (fn) => async (request, response, next) => {
   try {
@@ -189,10 +189,19 @@ var rateLimit = (passedOptions) => {
   middleware.resetKey = options.store.resetKey.bind(options.store);
   return middleware;
 };
+var omitUndefinedOptions = (passedOptions) => {
+  const omittedOptions = {};
+  for (const k of Object.keys(passedOptions)) {
+    const key = k;
+    if (passedOptions[key] !== void 0) {
+      omittedOptions[key] = passedOptions[key];
+    }
+  }
+  return omittedOptions;
+};
 var lib_default = rateLimit;
-
-// source/index.ts
-var source_default = lib_default;
 export {
-  source_default as default
+  MemoryStore,
+  lib_default as default,
+  lib_default as rateLimit
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "6.0.4",
+	"version": "6.2.1",
 	"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;\" 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:*",
@@ -61,7 +61,7 @@
 		"autofix:rest": "prettier --ignore-path .gitignore --ignore-unknown --write .",
 		"autofix": "run-s autofix:*",
 		"test:lib": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
-		"test:ext": "npm pack && cd test/external/ && bash run-all-tests",
+		"test:ext": "cd test/external/ && bash run-all-tests",
 		"test": "run-s lint test:*",
 		"pre-commit": "lint-staged",
 		"prepare": "run-s compile && husky install config/husky"
@@ -70,24 +70,24 @@
 		"express": "^4"
 	},
 	"devDependencies": {
-		"@jest/globals": "^27.4.2",
+		"@jest/globals": "^27.4.6",
 		"@types/express": "^4.17.13",
-		"@types/jest": "^27.0.3",
-		"@types/node": "^16.11.17",
+		"@types/jest": "^27.4.0",
+		"@types/node": "^16.11.21",
 		"@types/supertest": "^2.0.11",
 		"cross-env": "^7.0.3",
 		"del-cli": "^4.0.1",
-		"dts-bundle-generator": "^6.2.0",
-		"esbuild": "^0.14.8",
+		"dts-bundle-generator": "^6.4.0",
+		"esbuild": "^0.14.12",
 		"express": "^4.17.1",
 		"husky": "^7.0.4",
-		"jest": "^27.4.3",
-		"lint-staged": "^12.1.2",
+		"jest": "^27.4.7",
+		"lint-staged": "^12.2.2",
 		"npm-run-all": "^4.1.5",
-		"supertest": "^6.1.6",
-		"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
 
@@ -58,57 +58,19 @@ Javascript and Typescript projects.
 
 **This package requires you to use Node 14 or above.**
 
-#### Javascript
-
-Import it in a CommonJS project as follows:
-
-```ts
-const rateLimit = require('express-rate-limit')
-```
-
-Import it in a ESM project as follows:
-
-```ts
-import rateLimit from 'express-rate-limit'
-```
-
-#### Typescript
-
-If you are using this library in a Typescript project that outputs CommonJS (no
-`type: module` in `package.json` and `module: commonjs` in `tsconfig.json`), set
-`esModuleInterop` to `true` in the `compilerOptions` of your `tsconfig.json` and
-then import it as follows:
-
-```ts
-import rateLimit from 'express-rate-limit'
-```
-
-If you cannot set `esModuleInterop` to true, import it as follows instead:
+Import it in a CommonJS project (`type: commonjs` or no `type` field in
+`package.json`) as follows:
 
 ```ts
 const rateLimit = require('express-rate-limit')
 ```
 
-And use the following to import any types if you need to:
-
-```ts
-import { Store, IncrementResponse, ... } from 'express-rate-limit'
-```
-
-If you are using this library in a Typescript project that outputs ESM
-(`type: module` in `package.json` and `module: esnext` in `tsconfig.json`),
-import it as follows:
+Import it in a ESM project (`type: module` in `package.json`) as follows:
 
 ```ts
 import rateLimit from 'express-rate-limit'
 ```
 
-And use the following to import any types if you need to:
-
-```ts
-import rateLimit, { Store, IncrementResponse, ... } from 'express-rate-limit'
-```
-
 ### Examples
 
 To use it in an API-only server where the rate-limiter should be applied to all
@@ -177,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
@@ -227,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
@@ -294,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`
 
-Defaults to `true`.
+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` (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`
 
-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.
+> `boolean`
 
-The `request.rateLimit` object has `limit`, `current`, and `remaining` number of
-requests and, if the store provides it, a `resetTime` Date object.
+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:
 
-Defaults to:
+- 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`
+
+> `function`
+
+Method to generate custom identifiers for clients.
+
+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`
 
-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.
+Express request handler that sends back a response when a client is
+rate-limited.
 
-Defaults to
+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`
+
+> `function`
 
-The name of the property that contains the rate limit information to add to the
-`request` object.
+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`.
 
-Defaults to `rateLimit`.
+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
 

package/tsconfig.json

@@ -1,15 +1,13 @@
 {
+	"include": ["source/"],
+	"exclude": ["node_modules/"],
 	"compilerOptions": {
 		"declaration": true,
-
 		"strict": true,
 		"noUnusedLocals": true,
 		"noImplicitReturns": true,
 		"noFallthroughCasesInSwitch": true,
-
-		"moduleResolution": "node",
-		"esModuleInterop": true
-	},
-	"include": ["./source/**/*.ts"],
-	"exclude": ["./node_modules"]
+		"esModuleInterop": true,
+		"moduleResolution": "node"
+	}
 }