express-rate-limit 7.1.5 → 7.3.0

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.
    *
@@ -296,6 +310,20 @@ var validations = {
         );
       }
     }
+  },
+  /**
+   * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+   */
+  creationStack() {
+    const { stack } = new Error(
+      "express-rate-limit validation check (set options.validate.creationStack=false to disable)"
+    );
+    if (stack?.includes("Layer.handle [as handle_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.`
+      );
+    }
   }
 };
 var getValidations = (_enabled) => {
@@ -616,6 +644,8 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
 var rateLimit = (passedOptions) => {
   const config = parseOptions(passedOptions ?? {});
   const options = getOptionsFromConfig(config);
+  config.validations.creationStack();
+  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.
 	 *
@@ -97,6 +101,10 @@ declare const validations: {
 	 * 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.
+	 */
+	creationStack(): 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.
 	 *
@@ -97,6 +101,10 @@ declare const validations: {
 	 * 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.
+	 */
+	creationStack(): 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.
 	 *
@@ -97,6 +101,10 @@ declare const validations: {
 	 * 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.
+	 */
+	creationStack(): 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.
    *
@@ -268,6 +282,20 @@ var validations = {
         );
       }
     }
+  },
+  /**
+   * Checks to see if the instance was created inside of a request handler, which would prevent it from working correctly.
+   */
+  creationStack() {
+    const { stack } = new Error(
+      "express-rate-limit validation check (set options.validate.creationStack=false to disable)"
+    );
+    if (stack?.includes("Layer.handle [as handle_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.`
+      );
+    }
   }
 };
 var getValidations = (_enabled) => {
@@ -588,6 +616,8 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
 var rateLimit = (passedOptions) => {
   const config = parseOptions(passedOptions ?? {});
   const options = getOptionsFromConfig(config);
+  config.validations.creationStack();
+  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.1.5",
+	"version": "7.3.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",
@@ -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

@@ -9,16 +9,6 @@
 
 </div>
 
----
-
-Sponsored by [Zuplo](https://zuplo.link/express-rate-limit) a fully-managed API
-Gateway for developers. Add
-[dynamic rate-limiting](https://zuplo.link/dynamic-rate-limiting),
-authentication and more to any API in minutes. Learn more at
-[zuplo.com](https://zuplo.link/express-rate-limit)
-
----
-
 Basic rate-limiting middleware for [Express](http://expressjs.com/). Use to
 limit repeated requests to public APIs and/or endpoints such as password reset.
 Plays nice with
@@ -38,13 +28,58 @@ const limiter = rateLimit({
 	limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
 	standardHeaders: 'draft-7', // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
 	legacyHeaders: false, // Disable the `X-RateLimit-*` headers.
-	// store: ... , // Use an external store for consistency across multiple server instances.
+	// store: ... , // Redis, Memcached, etc. See below.
 })
 
 // Apply the rate limiting middleware to all requests.
 app.use(limiter)
 ```
 
+### Data Stores
+
+The rate limiter comes with a built-in memory store, and supports a variety of
+[external data stores](https://express-rate-limit.mintlify.app/reference/stores).
+
+### Configuration
+
+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.                                   |
+
+## Thank You
+
+Sponsored by [Zuplo](https://zuplo.link/express-rate-limit) a fully-managed API
+Gateway for developers. Add
+[dynamic rate-limiting](https://zuplo.link/dynamic-rate-limiting),
+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
@@ -58,11 +93,13 @@ Thanks to Mintlify for hosting the documentation at
 
 ---
 
+Finally, thank you to everyone who's contributed to this project in any way! 🫶
+
 ## Issues and Contributing
 
 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)!