express-rate-limit 7.2.0 → 7.3.1

package/dist/index.cjs

@@ -99,6 +99,7 @@ var ValidationError = class extends Error {
 };
 var ChangeWarning = class extends ValidationError {
 };
+var usedStores = /* @__PURE__ */ new Set();
 var singleCountKeys = /* @__PURE__ */ new WeakMap();
 var validations = {
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
@@ -182,6 +183,19 @@ var validations = {
       );
     }
   },
+  /**
+   * Ensures a single store instance is not used with multiple express-rate-limit instances
+   */
+  unsharedStore(store) {
+    if (usedStores.has(store)) {
+      const maybeUniquePrefix = store?.localKeys ? "" : " (with a unique prefix)";
+      throw new ValidationError(
+        "ERR_ERL_STORE_REUSE",
+        `A Store instance must not be shared across multiple rate limiters. Create a new instance of ${store.constructor.name}${maybeUniquePrefix} for each limiter instead.`
+      );
+    }
+    usedStores.add(store);
+  },
   /**
    * Ensures a given key is incremented only once per request.
    *
@@ -213,8 +227,8 @@ var validations = {
     keys.push(prefixedKey);
   },
   /**
-   * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-   * major release.
+   * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+   * changing in the next major release.
    *
    * @param limit {number} - The maximum number of hits per client.
    *
@@ -245,8 +259,8 @@ var validations = {
     }
   },
   /**
-   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-   * major release.
+   * Warns the user that the `onLimitReached` option is deprecated and
+   * will be removed in the next major release.
    *
    * @param onLimitReached {any | undefined} - The maximum number of hits per client.
    *
@@ -277,9 +291,11 @@ var validations = {
     }
   },
   /**
-   * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+   * Checks the options.validate setting to ensure that only recognized
+   * validations are enabled or disabled.
    *
-   * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+   * If any unrecognized values are found, an error is logged that
+   * includes the list of supported vaidations.
    */
   validationsConfig() {
     const supportedValidations = Object.keys(this).filter(
@@ -298,13 +314,21 @@ var validations = {
     }
   },
   /**
-   * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+   * Checks to see if the instance was created inside of a request handler,
+   * which would prevent it from working correctly, with the default memory
+   * store (or any other store with localKeys.)
    */
-  creationStack() {
+  creationStack(store) {
     const { stack } = new Error(
       "express-rate-limit validation check (set options.validate.creationStack=false to disable)"
     );
     if (stack?.includes("Layer.handle [as handle_request]")) {
+      if (!store.localKeys) {
+        throw new ValidationError(
+          "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
+          "express-rate-limit instance should *usually* be created at app initialization, not when responding to a request."
+        );
+      }
       throw new ValidationError(
         "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
         `express-rate-limit instance should be created at app initialization, not when responding to a request.`
@@ -630,7 +654,8 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
 var rateLimit = (passedOptions) => {
   const config = parseOptions(passedOptions ?? {});
   const options = getOptionsFromConfig(config);
-  config.validations.creationStack();
+  config.validations.creationStack(config.store);
+  config.validations.unsharedStore(config.store);
   if (typeof config.store.init === "function")
     config.store.init(options);
   const middleware = handleAsyncErrors(

package/dist/index.d.cts

@@ -45,6 +45,10 @@ declare const validations: {
 	 * @param hits {any} - The `totalHits` returned by the store.
 	 */
 	positiveHits(hits: any): void;
+	/**
+	 * Ensures a single store instance is not used with multiple express-rate-limit instances
+	 */
+	unsharedStore(store: Store): void;
 	/**
 	 * Ensures a given key is incremented only once per request.
 	 *
@@ -56,8 +60,8 @@ declare const validations: {
 	 */
 	singleCount(request: Request, store: Store, key: string): void;
 	/**
-	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-	 * major release.
+	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+	 * changing in the next major release.
 	 *
 	 * @param limit {number} - The maximum number of hits per client.
 	 *
@@ -74,8 +78,8 @@ declare const validations: {
 	 */
 	draftPolliHeaders(draft_polli_ratelimit_headers?: any): void;
 	/**
-	 * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-	 * major release.
+	 * Warns the user that the `onLimitReached` option is deprecated and
+	 * will be removed in the next major release.
 	 *
 	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
 	 *
@@ -92,15 +96,19 @@ declare const validations: {
 	 */
 	headersResetTime(resetTime?: Date): void;
 	/**
-	 * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+	 * Checks the options.validate setting to ensure that only recognized
+	 * validations are enabled or disabled.
 	 *
-	 * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+	 * If any unrecognized values are found, an error is logged that
+	 * includes the list of supported vaidations.
 	 */
 	validationsConfig(): void;
 	/**
-	 * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+	 * Checks to see if the instance was created inside of a request handler,
+	 * which would prevent it from working correctly, with the default memory
+	 * store (or any other store with localKeys.)
 	 */
-	creationStack(): void;
+	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
 /**

package/dist/index.d.mts

@@ -45,6 +45,10 @@ declare const validations: {
 	 * @param hits {any} - The `totalHits` returned by the store.
 	 */
 	positiveHits(hits: any): void;
+	/**
+	 * Ensures a single store instance is not used with multiple express-rate-limit instances
+	 */
+	unsharedStore(store: Store): void;
 	/**
 	 * Ensures a given key is incremented only once per request.
 	 *
@@ -56,8 +60,8 @@ declare const validations: {
 	 */
 	singleCount(request: Request, store: Store, key: string): void;
 	/**
-	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-	 * major release.
+	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+	 * changing in the next major release.
 	 *
 	 * @param limit {number} - The maximum number of hits per client.
 	 *
@@ -74,8 +78,8 @@ declare const validations: {
 	 */
 	draftPolliHeaders(draft_polli_ratelimit_headers?: any): void;
 	/**
-	 * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-	 * major release.
+	 * Warns the user that the `onLimitReached` option is deprecated and
+	 * will be removed in the next major release.
 	 *
 	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
 	 *
@@ -92,15 +96,19 @@ declare const validations: {
 	 */
 	headersResetTime(resetTime?: Date): void;
 	/**
-	 * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+	 * Checks the options.validate setting to ensure that only recognized
+	 * validations are enabled or disabled.
 	 *
-	 * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+	 * If any unrecognized values are found, an error is logged that
+	 * includes the list of supported vaidations.
 	 */
 	validationsConfig(): void;
 	/**
-	 * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+	 * Checks to see if the instance was created inside of a request handler,
+	 * which would prevent it from working correctly, with the default memory
+	 * store (or any other store with localKeys.)
 	 */
-	creationStack(): void;
+	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
 /**

package/dist/index.d.ts

@@ -45,6 +45,10 @@ declare const validations: {
 	 * @param hits {any} - The `totalHits` returned by the store.
 	 */
 	positiveHits(hits: any): void;
+	/**
+	 * Ensures a single store instance is not used with multiple express-rate-limit instances
+	 */
+	unsharedStore(store: Store): void;
 	/**
 	 * Ensures a given key is incremented only once per request.
 	 *
@@ -56,8 +60,8 @@ declare const validations: {
 	 */
 	singleCount(request: Request, store: Store, key: string): void;
 	/**
-	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-	 * major release.
+	 * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+	 * changing in the next major release.
 	 *
 	 * @param limit {number} - The maximum number of hits per client.
 	 *
@@ -74,8 +78,8 @@ declare const validations: {
 	 */
 	draftPolliHeaders(draft_polli_ratelimit_headers?: any): void;
 	/**
-	 * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-	 * major release.
+	 * Warns the user that the `onLimitReached` option is deprecated and
+	 * will be removed in the next major release.
 	 *
 	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
 	 *
@@ -92,15 +96,19 @@ declare const validations: {
 	 */
 	headersResetTime(resetTime?: Date): void;
 	/**
-	 * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+	 * Checks the options.validate setting to ensure that only recognized
+	 * validations are enabled or disabled.
 	 *
-	 * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+	 * If any unrecognized values are found, an error is logged that
+	 * includes the list of supported vaidations.
 	 */
 	validationsConfig(): void;
 	/**
-	 * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+	 * Checks to see if the instance was created inside of a request handler,
+	 * which would prevent it from working correctly, with the default memory
+	 * store (or any other store with localKeys.)
 	 */
-	creationStack(): void;
+	creationStack(store: Store): void;
 };
 export type Validations = typeof validations;
 /**

package/dist/index.mjs

@@ -71,6 +71,7 @@ var ValidationError = class extends Error {
 };
 var ChangeWarning = class extends ValidationError {
 };
+var usedStores = /* @__PURE__ */ new Set();
 var singleCountKeys = /* @__PURE__ */ new WeakMap();
 var validations = {
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
@@ -154,6 +155,19 @@ var validations = {
       );
     }
   },
+  /**
+   * Ensures a single store instance is not used with multiple express-rate-limit instances
+   */
+  unsharedStore(store) {
+    if (usedStores.has(store)) {
+      const maybeUniquePrefix = store?.localKeys ? "" : " (with a unique prefix)";
+      throw new ValidationError(
+        "ERR_ERL_STORE_REUSE",
+        `A Store instance must not be shared across multiple rate limiters. Create a new instance of ${store.constructor.name}${maybeUniquePrefix} for each limiter instead.`
+      );
+    }
+    usedStores.add(store);
+  },
   /**
    * Ensures a given key is incremented only once per request.
    *
@@ -185,8 +199,8 @@ var validations = {
     keys.push(prefixedKey);
   },
   /**
-   * Warns the user that the behaviour for `max: 0` / `limit: 0` is changing in the next
-   * major release.
+   * Warns the user that the behaviour for `max: 0` / `limit: 0` is
+   * changing in the next major release.
    *
    * @param limit {number} - The maximum number of hits per client.
    *
@@ -217,8 +231,8 @@ var validations = {
     }
   },
   /**
-   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
-   * major release.
+   * Warns the user that the `onLimitReached` option is deprecated and
+   * will be removed in the next major release.
    *
    * @param onLimitReached {any | undefined} - The maximum number of hits per client.
    *
@@ -249,9 +263,11 @@ var validations = {
     }
   },
   /**
-   * Checks the options.validate setting to ensure that only recognized validations are enabled or disabled.
+   * Checks the options.validate setting to ensure that only recognized
+   * validations are enabled or disabled.
    *
-   * If any unrecognized values are found, an error is logged that includes the list of supported vaidations.
+   * If any unrecognized values are found, an error is logged that
+   * includes the list of supported vaidations.
    */
   validationsConfig() {
     const supportedValidations = Object.keys(this).filter(
@@ -270,13 +286,21 @@ var validations = {
     }
   },
   /**
-   * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+   * Checks to see if the instance was created inside of a request handler,
+   * which would prevent it from working correctly, with the default memory
+   * store (or any other store with localKeys.)
    */
-  creationStack() {
+  creationStack(store) {
     const { stack } = new Error(
       "express-rate-limit validation check (set options.validate.creationStack=false to disable)"
     );
     if (stack?.includes("Layer.handle [as handle_request]")) {
+      if (!store.localKeys) {
+        throw new ValidationError(
+          "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
+          "express-rate-limit instance should *usually* be created at app initialization, not when responding to a request."
+        );
+      }
       throw new ValidationError(
         "ERR_ERL_CREATED_IN_REQUEST_HANDLER",
         `express-rate-limit instance should be created at app initialization, not when responding to a request.`
@@ -602,7 +626,8 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
 var rateLimit = (passedOptions) => {
   const config = parseOptions(passedOptions ?? {});
   const options = getOptionsFromConfig(config);
-  config.validations.creationStack();
+  config.validations.creationStack(config.store);
+  config.validations.unsharedStore(config.store);
   if (typeof config.store.init === "function")
     config.store.init(options);
   const middleware = handleAsyncErrors(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "7.2.0",
+	"version": "7.3.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",
@@ -87,7 +87,7 @@
 		"del-cli": "5.1.0",
 		"dts-bundle-generator": "8.0.1",
 		"esbuild": "0.19.5",
-		"express": "4.18.2",
+		"express": "4.19.2",
 		"husky": "8.0.3",
 		"jest": "29.7.0",
 		"lint-staged": "15.0.2",

package/readme.md

@@ -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
 
@@ -71,6 +71,15 @@ Gateway for developers. Add
 authentication and more to any API in minutes. Learn more at
 [zuplo.com](https://zuplo.link/express-rate-limit)
 
+<p align="center">
+<a href="https://zuplo.link/express-rate-limit">
+<picture width="322">
+  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/express-rate-limit/express-rate-limit/assets/114976/cd2f6fa7-eae1-4fbb-be7d-b17df4c6f383">
+  <img alt="zuplo-logo" src="https://github.com/express-rate-limit/express-rate-limit/assets/114976/66fd75fa-b39e-4a8c-8d7a-52369bf244dc" width="322">
+</picture>
+</a>
+</p>
+
 ---
 
 Thanks to Mintlify for hosting the documentation at
@@ -90,7 +99,7 @@ Finally, thank you to everyone who's contributed to this project in any way!
 
 If you encounter a bug or want to see something added/changed, please go ahead
 and
-[open an issue](https://github.com/nfriexpress-rate-limitedly/express-rate-limit/issues/new)!
+[open an issue](https://github.com/express-rate-limit/express-rate-limit/issues/new)!
 If you need help with something, feel free to
 [start a discussion](https://github.com/express-rate-limit/express-rate-limit/discussions/new)!
 
@@ -102,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