express-rate-limit 6.9.0 → 6.10.0

package/changelog.md

@@ -6,6 +6,22 @@ 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.10.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.10.0)
+
+### Added
+
+- Support for combined `RateLimit` header from the
+  [RateLimit header fields for HTTP standardization draft](https://github.com/ietf-wg-httpapi/ratelimit-headers)
+  adopted by the IETF. Enable by setting `standardHeaders: 'draft-7'`
+- New `standardHeaders: 'draft-6'` option, treated equivalent to
+  `standardHeaders: true` from previous releases. (`true` and `false` are still
+  supported.)
+- New `RateLimit-Policy` header added when `standardHeaders` is set to
+  `'draft-6'`, `'draft-7'`, or `true`
+- Warning when using deprecated `draft_polli_ratelimit_headers` option
+- Warning when using deprecated `onLimitReached` option
+- Warning when `totalHits` value returned from Store is invalid
+
 ## [6.9.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.9.0)
 
 ### Added

package/dist/index.cjs

@@ -31,6 +31,59 @@ __export(source_exports, {
 });
 module.exports = __toCommonJS(source_exports);
 
+// source/headers.ts
+var getResetSeconds = (resetTime, windowMs) => {
+  let resetSeconds = void 0;
+  if (resetTime) {
+    const deltaSeconds = Math.ceil((resetTime.getTime() - Date.now()) / 1e3);
+    resetSeconds = Math.max(0, deltaSeconds);
+  } else if (windowMs) {
+    resetSeconds = Math.ceil(windowMs / 1e3);
+  }
+  return resetSeconds;
+};
+var setLegacyHeaders = (response, info) => {
+  if (response.headersSent)
+    return;
+  response.setHeader("X-RateLimit-Limit", info.limit);
+  response.setHeader("X-RateLimit-Remaining", info.remaining);
+  if (info.resetTime instanceof Date) {
+    response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
+    response.setHeader(
+      "X-RateLimit-Reset",
+      Math.ceil(info.resetTime.getTime() / 1e3)
+    );
+  }
+};
+var setDraft6Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader("RateLimit-Limit", info.limit);
+  response.setHeader("RateLimit-Remaining", info.remaining);
+  if (resetSeconds)
+    response.setHeader("RateLimit-Reset", resetSeconds);
+};
+var setDraft7Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader(
+    "RateLimit",
+    `limit=${info.limit}, remaining=${info.remaining}, reset=${resetSeconds}`
+  );
+};
+var setRetryAfterHeader = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("Retry-After", resetSeconds);
+};
+
 // source/validations.ts
 var import_node_net = require("net");
 var ValidationError = class extends Error {
@@ -38,12 +91,12 @@ var ValidationError = class extends Error {
    * The code must be a string, in snake case and all capital, that starts with
    * the substring `ERR_ERL_`.
    *
-   * The message must be a string, starting with a lowercase character,
+   * The message must be a string, starting with an uppercase character,
    * describing the issue in detail.
    */
   constructor(code, message) {
     const url = `https://express-rate-limit.github.io/${code}/`;
-    super(`${message} See ${url} for more information on this error.`);
+    super(`${message} See ${url} for more information.`);
     __publicField(this, "name");
     __publicField(this, "code");
     __publicField(this, "help");
@@ -52,6 +105,8 @@ var ValidationError = class extends Error {
     this.help = url;
   }
 };
+var ChangeWarning = class extends ValidationError {
+};
 var _Validations = class _Validations {
   constructor(enabled) {
     // eslint-disable-next-line @typescript-eslint/parameter-properties
@@ -129,6 +184,22 @@ var _Validations = class _Validations {
       }
     });
   }
+  /**
+   * Ensures totalHits value from store is a positive integer.
+   *
+   * @param hits {any} - The `totalHits` returned by the store.
+   */
+  positiveHits(hits) {
+    this.wrap(() => {
+      if (typeof hits !== "number" || hits < 1 || hits !== Math.round(hits)) {
+        throw new ValidationError(
+          "ERR_ERL_INVALID_HITS",
+          `The totalHits value returned from the store must be a positive integer, got ${hits}`
+          // eslint-disable-line @typescript-eslint/restrict-template-expressions
+        );
+      }
+    });
+  }
   /**
    * Ensures a given key is incremented only once per request.
    *
@@ -160,6 +231,78 @@ var _Validations = class _Validations {
       keys.push(key);
     });
   }
+  /**
+   * Warns the user that the behaviour for `max: 0` is changing in the next
+   * major release.
+   *
+   * @param max {number} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  max(max) {
+    this.wrap(() => {
+      if (max === 0) {
+        throw new ChangeWarning(
+          "WRN_ERL_MAX_ZERO",
+          `Setting max to 0 disables rate limiting in express-rate-limit v6 and older, but will cause all requests to be blocked in v7`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `draft_polli_ratelimit_headers` option is deprecated
+   * and will be removed in the next major release.
+   *
+   * @param draft_polli_ratelimit_headers {boolean|undefined} - The now-deprecated setting that was used to enable standard headers.
+   *
+   * @returns {void}
+   */
+  draftPolliHeaders(draft_polli_ratelimit_headers) {
+    this.wrap(() => {
+      if (draft_polli_ratelimit_headers) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_DRAFT_POLLI_HEADERS",
+          `The draft_polli_ratelimit_headers configuration option is deprecated and will be removed in express-rate-limit v7, please set standardHeaders: 'draft-6' instead.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
+   * major release.
+   *
+   * @param onLimitReached {function|undefined} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  onLimitReached(onLimitReached) {
+    this.wrap(() => {
+      if (onLimitReached) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_ON_LIMIT_REACHED",
+          `The onLimitReached configuration option is deprecated and will be removed in express-rate-limit v7.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user when the selected headers option requires a reset time but
+   * the store does not provide one.
+   *
+   * @param resetTime {Date | undefined} - The timestamp when the client's hit count will be reset.
+   *
+   * @returns {void}
+   */
+  headersResetTime(resetTime) {
+    this.wrap(() => {
+      if (!resetTime) {
+        throw new ValidationError(
+          "ERR_ERL_HEADERS_NO_RESET",
+          `standardHeaders:  'draft-7' requires a 'resetTime', but the store did not provide one. The 'windowMs' value will be used instead, which may cause clients to wait longer than necessary.`
+        );
+      }
+    });
+  }
   wrap(validation) {
     if (!this.enabled) {
       return;
@@ -167,7 +310,10 @@ var _Validations = class _Validations {
     try {
       validation.call(this);
     } catch (error) {
-      console.error(error);
+      if (error instanceof ChangeWarning)
+        console.warn(error);
+      else
+        console.error(error);
     }
   }
 };
@@ -319,6 +465,7 @@ var promisifyStore = (passedStore) => {
     async resetKey(key) {
       return legacyStore.resetKey(key);
     }
+    /* istanbul ignore next */
     async resetAll() {
       if (typeof legacyStore.resetAll === "function")
         return legacyStore.resetAll();
@@ -347,13 +494,20 @@ var parseOptions = (passedOptions) => {
   var _a, _b, _c, _d;
   const notUndefinedOptions = omitUndefinedOptions(passedOptions);
   const validations = new Validations((_a = notUndefinedOptions == null ? void 0 : notUndefinedOptions.validate) != null ? _a : true);
+  validations.draftPolliHeaders(
+    notUndefinedOptions.draft_polli_ratelimit_headers
+  );
+  validations.onLimitReached(notUndefinedOptions.onLimitReached);
+  let standardHeaders = (_b = notUndefinedOptions.standardHeaders) != null ? _b : false;
+  if (standardHeaders === true || standardHeaders === void 0 && notUndefinedOptions.draft_polli_ratelimit_headers) {
+    standardHeaders = "draft-6";
+  }
   const config = {
     windowMs: 60 * 1e3,
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
-    legacyHeaders: (_b = passedOptions.headers) != null ? _b : true,
-    standardHeaders: (_c = passedOptions.draft_polli_ratelimit_headers) != null ? _c : false,
+    legacyHeaders: (_c = passedOptions.headers) != null ? _c : true,
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
@@ -372,13 +526,15 @@ var parseOptions = (passedOptions) => {
         response
       ) : config.message;
       if (!response.writableEnded) {
-        response.send(message != null ? message : "Too many requests, please try again later.");
+        response.send(message);
       }
     },
     onLimitReached(_request, _response, _optionsUsed) {
     },
-    // Allow the options object to be overriden by the options passed to the middleware.
+    // Allow the default options to be overriden by the options passed to the middleware.
     ...notUndefinedOptions,
+    // `standardHeaders` is resolved into a draft version above, use that.
+    standardHeaders,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overriden with an un-promisified store!
     store: promisifyStore((_d = notUndefinedOptions.store) != null ? _d : new MemoryStore()),
@@ -414,40 +570,27 @@ var rateLimit = (passedOptions) => {
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
       const { totalHits, resetTime } = await config.store.increment(key);
+      config.validations.positiveHits(totalHits);
       config.validations.singleCount(request, config.store, key);
       const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
-      augmentedRequest[config.requestPropertyName] = {
+      config.validations.max(maxHits);
+      const info = {
         limit: maxHits,
         current: totalHits,
         remaining: Math.max(maxHits - totalHits, 0),
         resetTime
       };
+      augmentedRequest[config.requestPropertyName] = info;
       if (config.legacyHeaders && !response.headersSent) {
-        response.setHeader("X-RateLimit-Limit", maxHits);
-        response.setHeader(
-          "X-RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime instanceof Date) {
-          response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
-          response.setHeader(
-            "X-RateLimit-Reset",
-            Math.ceil(resetTime.getTime() / 1e3)
-          );
-        }
+        setLegacyHeaders(response, info);
       }
       if (config.standardHeaders && !response.headersSent) {
-        response.setHeader("RateLimit-Limit", maxHits);
-        response.setHeader(
-          "RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime) {
-          const deltaSeconds = Math.ceil(
-            (resetTime.getTime() - Date.now()) / 1e3
-          );
-          response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
+        if (config.standardHeaders === "draft-6") {
+          setDraft6Headers(response, info, config.windowMs);
+        } else if (config.standardHeaders === "draft-7") {
+          config.validations.headersResetTime(info.resetTime);
+          setDraft7Headers(response, info, config.windowMs);
         }
       }
       if (config.skipFailedRequests || config.skipSuccessfulRequests) {
@@ -483,8 +626,8 @@ var rateLimit = (passedOptions) => {
       }
       config.validations.disable();
       if (maxHits && totalHits > maxHits) {
-        if ((config.legacyHeaders || config.standardHeaders) && !response.headersSent) {
-          response.setHeader("Retry-After", Math.ceil(config.windowMs / 1e3));
+        if (config.legacyHeaders || config.standardHeaders) {
+          setRetryAfterHeader(response, info, config.windowMs);
         }
         config.handler(request, response, next, options);
         return;

package/dist/index.d.cts

@@ -139,6 +139,7 @@ export type Store = {
 	 */
 	localKeys?: boolean;
 };
+export type DraftHeadersVersion = "draft-6" | "draft-7";
 /**
  * The configuration options for the rate limiter.
  */
@@ -183,7 +184,7 @@ export type Options = {
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	standardHeaders: boolean;
+	standardHeaders: boolean | DraftHeadersVersion;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *

package/dist/index.d.mts

@@ -139,6 +139,7 @@ export type Store = {
 	 */
 	localKeys?: boolean;
 };
+export type DraftHeadersVersion = "draft-6" | "draft-7";
 /**
  * The configuration options for the rate limiter.
  */
@@ -183,7 +184,7 @@ export type Options = {
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	standardHeaders: boolean;
+	standardHeaders: boolean | DraftHeadersVersion;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *

package/dist/index.d.ts

@@ -139,6 +139,7 @@ export type Store = {
 	 */
 	localKeys?: boolean;
 };
+export type DraftHeadersVersion = "draft-6" | "draft-7";
 /**
  * The configuration options for the rate limiter.
  */
@@ -183,7 +184,7 @@ export type Options = {
 	 *
 	 * Defaults to `false` (for backward compatibility, but its use is recommended).
 	 */
-	standardHeaders: boolean;
+	standardHeaders: boolean | DraftHeadersVersion;
 	/**
 	 * The name of the property on the request object to store the rate limit info.
 	 *

package/dist/index.mjs

@@ -5,6 +5,59 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 
+// source/headers.ts
+var getResetSeconds = (resetTime, windowMs) => {
+  let resetSeconds = void 0;
+  if (resetTime) {
+    const deltaSeconds = Math.ceil((resetTime.getTime() - Date.now()) / 1e3);
+    resetSeconds = Math.max(0, deltaSeconds);
+  } else if (windowMs) {
+    resetSeconds = Math.ceil(windowMs / 1e3);
+  }
+  return resetSeconds;
+};
+var setLegacyHeaders = (response, info) => {
+  if (response.headersSent)
+    return;
+  response.setHeader("X-RateLimit-Limit", info.limit);
+  response.setHeader("X-RateLimit-Remaining", info.remaining);
+  if (info.resetTime instanceof Date) {
+    response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
+    response.setHeader(
+      "X-RateLimit-Reset",
+      Math.ceil(info.resetTime.getTime() / 1e3)
+    );
+  }
+};
+var setDraft6Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader("RateLimit-Limit", info.limit);
+  response.setHeader("RateLimit-Remaining", info.remaining);
+  if (resetSeconds)
+    response.setHeader("RateLimit-Reset", resetSeconds);
+};
+var setDraft7Headers = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const windowSeconds = Math.ceil(windowMs / 1e3);
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("RateLimit-Policy", `${info.limit};w=${windowSeconds}`);
+  response.setHeader(
+    "RateLimit",
+    `limit=${info.limit}, remaining=${info.remaining}, reset=${resetSeconds}`
+  );
+};
+var setRetryAfterHeader = (response, info, windowMs) => {
+  if (response.headersSent)
+    return;
+  const resetSeconds = getResetSeconds(info.resetTime, windowMs);
+  response.setHeader("Retry-After", resetSeconds);
+};
+
 // source/validations.ts
 import { isIP } from "net";
 var ValidationError = class extends Error {
@@ -12,12 +65,12 @@ var ValidationError = class extends Error {
    * The code must be a string, in snake case and all capital, that starts with
    * the substring `ERR_ERL_`.
    *
-   * The message must be a string, starting with a lowercase character,
+   * The message must be a string, starting with an uppercase character,
    * describing the issue in detail.
    */
   constructor(code, message) {
     const url = `https://express-rate-limit.github.io/${code}/`;
-    super(`${message} See ${url} for more information on this error.`);
+    super(`${message} See ${url} for more information.`);
     __publicField(this, "name");
     __publicField(this, "code");
     __publicField(this, "help");
@@ -26,6 +79,8 @@ var ValidationError = class extends Error {
     this.help = url;
   }
 };
+var ChangeWarning = class extends ValidationError {
+};
 var _Validations = class _Validations {
   constructor(enabled) {
     // eslint-disable-next-line @typescript-eslint/parameter-properties
@@ -103,6 +158,22 @@ var _Validations = class _Validations {
       }
     });
   }
+  /**
+   * Ensures totalHits value from store is a positive integer.
+   *
+   * @param hits {any} - The `totalHits` returned by the store.
+   */
+  positiveHits(hits) {
+    this.wrap(() => {
+      if (typeof hits !== "number" || hits < 1 || hits !== Math.round(hits)) {
+        throw new ValidationError(
+          "ERR_ERL_INVALID_HITS",
+          `The totalHits value returned from the store must be a positive integer, got ${hits}`
+          // eslint-disable-line @typescript-eslint/restrict-template-expressions
+        );
+      }
+    });
+  }
   /**
    * Ensures a given key is incremented only once per request.
    *
@@ -134,6 +205,78 @@ var _Validations = class _Validations {
       keys.push(key);
     });
   }
+  /**
+   * Warns the user that the behaviour for `max: 0` is changing in the next
+   * major release.
+   *
+   * @param max {number} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  max(max) {
+    this.wrap(() => {
+      if (max === 0) {
+        throw new ChangeWarning(
+          "WRN_ERL_MAX_ZERO",
+          `Setting max to 0 disables rate limiting in express-rate-limit v6 and older, but will cause all requests to be blocked in v7`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `draft_polli_ratelimit_headers` option is deprecated
+   * and will be removed in the next major release.
+   *
+   * @param draft_polli_ratelimit_headers {boolean|undefined} - The now-deprecated setting that was used to enable standard headers.
+   *
+   * @returns {void}
+   */
+  draftPolliHeaders(draft_polli_ratelimit_headers) {
+    this.wrap(() => {
+      if (draft_polli_ratelimit_headers) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_DRAFT_POLLI_HEADERS",
+          `The draft_polli_ratelimit_headers configuration option is deprecated and will be removed in express-rate-limit v7, please set standardHeaders: 'draft-6' instead.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user that the `onLimitReached` option is deprecated and will be removed in the next
+   * major release.
+   *
+   * @param onLimitReached {function|undefined} - The maximum number of hits per client.
+   *
+   * @returns {void}
+   */
+  onLimitReached(onLimitReached) {
+    this.wrap(() => {
+      if (onLimitReached) {
+        throw new ChangeWarning(
+          "WRN_ERL_DEPRECATED_ON_LIMIT_REACHED",
+          `The onLimitReached configuration option is deprecated and will be removed in express-rate-limit v7.`
+        );
+      }
+    });
+  }
+  /**
+   * Warns the user when the selected headers option requires a reset time but
+   * the store does not provide one.
+   *
+   * @param resetTime {Date | undefined} - The timestamp when the client's hit count will be reset.
+   *
+   * @returns {void}
+   */
+  headersResetTime(resetTime) {
+    this.wrap(() => {
+      if (!resetTime) {
+        throw new ValidationError(
+          "ERR_ERL_HEADERS_NO_RESET",
+          `standardHeaders:  'draft-7' requires a 'resetTime', but the store did not provide one. The 'windowMs' value will be used instead, which may cause clients to wait longer than necessary.`
+        );
+      }
+    });
+  }
   wrap(validation) {
     if (!this.enabled) {
       return;
@@ -141,7 +284,10 @@ var _Validations = class _Validations {
     try {
       validation.call(this);
     } catch (error) {
-      console.error(error);
+      if (error instanceof ChangeWarning)
+        console.warn(error);
+      else
+        console.error(error);
     }
   }
 };
@@ -293,6 +439,7 @@ var promisifyStore = (passedStore) => {
     async resetKey(key) {
       return legacyStore.resetKey(key);
     }
+    /* istanbul ignore next */
     async resetAll() {
       if (typeof legacyStore.resetAll === "function")
         return legacyStore.resetAll();
@@ -321,13 +468,20 @@ var parseOptions = (passedOptions) => {
   var _a, _b, _c, _d;
   const notUndefinedOptions = omitUndefinedOptions(passedOptions);
   const validations = new Validations((_a = notUndefinedOptions == null ? void 0 : notUndefinedOptions.validate) != null ? _a : true);
+  validations.draftPolliHeaders(
+    notUndefinedOptions.draft_polli_ratelimit_headers
+  );
+  validations.onLimitReached(notUndefinedOptions.onLimitReached);
+  let standardHeaders = (_b = notUndefinedOptions.standardHeaders) != null ? _b : false;
+  if (standardHeaders === true || standardHeaders === void 0 && notUndefinedOptions.draft_polli_ratelimit_headers) {
+    standardHeaders = "draft-6";
+  }
   const config = {
     windowMs: 60 * 1e3,
     max: 5,
     message: "Too many requests, please try again later.",
     statusCode: 429,
-    legacyHeaders: (_b = passedOptions.headers) != null ? _b : true,
-    standardHeaders: (_c = passedOptions.draft_polli_ratelimit_headers) != null ? _c : false,
+    legacyHeaders: (_c = passedOptions.headers) != null ? _c : true,
     requestPropertyName: "rateLimit",
     skipFailedRequests: false,
     skipSuccessfulRequests: false,
@@ -346,13 +500,15 @@ var parseOptions = (passedOptions) => {
         response
       ) : config.message;
       if (!response.writableEnded) {
-        response.send(message != null ? message : "Too many requests, please try again later.");
+        response.send(message);
       }
     },
     onLimitReached(_request, _response, _optionsUsed) {
     },
-    // Allow the options object to be overriden by the options passed to the middleware.
+    // Allow the default options to be overriden by the options passed to the middleware.
     ...notUndefinedOptions,
+    // `standardHeaders` is resolved into a draft version above, use that.
+    standardHeaders,
     // Note that this field is declared after the user's options are spread in,
     // so that this field doesn't get overriden with an un-promisified store!
     store: promisifyStore((_d = notUndefinedOptions.store) != null ? _d : new MemoryStore()),
@@ -388,40 +544,27 @@ var rateLimit = (passedOptions) => {
       const augmentedRequest = request;
       const key = await config.keyGenerator(request, response);
       const { totalHits, resetTime } = await config.store.increment(key);
+      config.validations.positiveHits(totalHits);
       config.validations.singleCount(request, config.store, key);
       const retrieveQuota = typeof config.max === "function" ? config.max(request, response) : config.max;
       const maxHits = await retrieveQuota;
-      augmentedRequest[config.requestPropertyName] = {
+      config.validations.max(maxHits);
+      const info = {
         limit: maxHits,
         current: totalHits,
         remaining: Math.max(maxHits - totalHits, 0),
         resetTime
       };
+      augmentedRequest[config.requestPropertyName] = info;
       if (config.legacyHeaders && !response.headersSent) {
-        response.setHeader("X-RateLimit-Limit", maxHits);
-        response.setHeader(
-          "X-RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime instanceof Date) {
-          response.setHeader("Date", (/* @__PURE__ */ new Date()).toUTCString());
-          response.setHeader(
-            "X-RateLimit-Reset",
-            Math.ceil(resetTime.getTime() / 1e3)
-          );
-        }
+        setLegacyHeaders(response, info);
       }
       if (config.standardHeaders && !response.headersSent) {
-        response.setHeader("RateLimit-Limit", maxHits);
-        response.setHeader(
-          "RateLimit-Remaining",
-          augmentedRequest[config.requestPropertyName].remaining
-        );
-        if (resetTime) {
-          const deltaSeconds = Math.ceil(
-            (resetTime.getTime() - Date.now()) / 1e3
-          );
-          response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
+        if (config.standardHeaders === "draft-6") {
+          setDraft6Headers(response, info, config.windowMs);
+        } else if (config.standardHeaders === "draft-7") {
+          config.validations.headersResetTime(info.resetTime);
+          setDraft7Headers(response, info, config.windowMs);
         }
       }
       if (config.skipFailedRequests || config.skipSuccessfulRequests) {
@@ -457,8 +600,8 @@ var rateLimit = (passedOptions) => {
       }
       config.validations.disable();
       if (maxHits && totalHits > maxHits) {
-        if ((config.legacyHeaders || config.standardHeaders) && !response.headersSent) {
-          response.setHeader("Retry-After", Math.ceil(config.windowMs / 1e3));
+        if (config.legacyHeaders || config.standardHeaders) {
+          setRetryAfterHeader(response, info, config.windowMs);
         }
         config.handler(request, response, next, options);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "6.9.0",
+	"version": "6.10.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",
@@ -52,7 +52,7 @@
 		"changelog.md"
 	],
 	"engines": {
-		"node": ">= 14.0.0"
+		"node": ">= 14"
 	},
 	"scripts": {
 		"clean": "del-cli dist/ coverage/ *.log *.tmp *.bak *.tgz",
@@ -66,7 +66,7 @@
 		"format:code": "npm run lint:code -- --fix",
 		"format:rest": "npm run lint:rest -- --write .",
 		"format": "run-s format:*",
-		"test:lib": "cross-env NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules jest",
+		"test:lib": "cross-env NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules jest --config config/jest.json",
 		"test:ext": "cd test/external/ && bash run-all-tests",
 		"test": "run-s lint test:lib",
 		"pre-commit": "lint-staged",
@@ -76,9 +76,11 @@
 		"express": "^4 || ^5"
 	},
 	"devDependencies": {
-		"@jest/globals": "29.6.1",
+		"@express-rate-limit/prettier": "1.0.0",
+		"@express-rate-limit/tsconfig": "1.0.0",
+		"@jest/globals": "29.6.2",
 		"@types/express": "4.17.17",
-		"@types/jest": "29.5.2",
+		"@types/jest": "29.5.3",
 		"@types/node": "20.4.0",
 		"@types/supertest": "2.0.12",
 		"cross-env": "7.0.3",
@@ -87,9 +89,10 @@
 		"esbuild": "0.18.11",
 		"express": "4.18.2",
 		"husky": "8.0.3",
-		"jest": "29.6.1",
+		"jest": "29.6.2",
 		"lint-staged": "13.2.3",
 		"npm-run-all": "4.1.5",
+		"ratelimit-header-parser": "0.1.0",
 		"supertest": "6.3.3",
 		"ts-jest": "29.1.1",
 		"ts-node": "10.9.1",
@@ -112,40 +115,13 @@
 			{
 				"files": "test/library/*.ts",
 				"rules": {
-					"@typescript-eslint/no-unsafe-argument": 0
+					"@typescript-eslint/no-unsafe-argument": 0,
+					"@typescript-eslint/no-unsafe-assignment": 0
 				}
 			}
 		]
 	},
-	"prettier": {
-		"semi": false,
-		"useTabs": true,
-		"singleQuote": true,
-		"bracketSpacing": true,
-		"trailingComma": "all",
-		"proseWrap": "always"
-	},
-	"jest": {
-		"preset": "ts-jest/presets/default-esm",
-		"collectCoverage": true,
-		"collectCoverageFrom": [
-			"source/**/*.ts"
-		],
-		"testTimeout": 30000,
-		"testMatch": [
-			"**/test/library/**/*-test.[jt]s?(x)"
-		],
-		"moduleFileExtensions": [
-			"js",
-			"jsx",
-			"json",
-			"ts",
-			"tsx"
-		],
-		"moduleNameMapper": {
-			"^(\\.{1,2}/.*)\\.js$": "$1"
-		}
-	},
+	"prettier": "@express-rate-limit/prettier",
 	"lint-staged": {
 		"{source,test}/**/*.ts": "xo --ignore test/external/ --fix",
 		"**/*.{json,yaml,md}": "prettier --ignore-path .gitignore --ignore-unknown --write "

package/readme.md

@@ -12,7 +12,7 @@ authentication and more to any API in minutes. Learn more at
 
 <div align="center">
 
-[![Tests](https://github.com/express-rate-limit/express-rate-limit/workflows/Test/badge.svg)](https://github.com/express-rate-limit/express-rate-limit/actions)
+[![tests](https://github.com/express-rate-limit/express-rate-limit/actions/workflows/ci.yaml/badge.svg)](https://github.com/express-rate-limit/express-rate-limit/actions/workflows/ci.yaml)
 [![npm version](https://img.shields.io/npm/v/express-rate-limit.svg)](https://npmjs.org/package/express-rate-limit 'View this project on NPM')
 [![npm downloads](https://img.shields.io/npm/dm/express-rate-limit)](https://www.npmjs.com/package/express-rate-limit)
 
@@ -97,13 +97,13 @@ Import it in a CommonJS project (`type: commonjs` or no `type` field in
 `package.json`) as follows:
 
 ```ts
-const rateLimit = require('express-rate-limit')
+const { rateLimit } = require('express-rate-limit')
 ```
 
 Import it in a ESM project (`type: module` in `package.json`) as follows:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 ```
 
 ### Examples
@@ -112,13 +112,13 @@ To use it in an API-only server where the rate-limiter should be applied to all
 requests:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 
 const limiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
 	// store: ... , // Use an external store for more precise rate limiting
 })
 
@@ -131,12 +131,12 @@ To use it in a 'regular' web server (e.g. anything that uses
 requests:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 
 const apiLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
+	standardHeaders: 'draft-7', // Set `RateLimit` and `RateLimit-Policy`` headers
 	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
 	// store: ... , // Use an external store for more precise rate limiting
 })
@@ -148,13 +148,13 @@ app.use('/api', apiLimiter)
 To create multiple instances to apply different rules to different endpoints:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 
 const apiLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
 	// store: ... , // Use an external store for more precise rate limiting
 })
 
@@ -165,8 +165,8 @@ const createAccountLimiter = rateLimit({
 	max: 5, // Limit each IP to 5 create account requests per `window` (here, per hour)
 	message:
 		'Too many accounts created from this IP, please try again after an hour',
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
-	legacyHeaders: false, // Disable the `X-RateLimit-*` headers
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
 })
 
 app.post('/create-account', createAccountLimiter, (request, response) => {
@@ -177,7 +177,7 @@ app.post('/create-account', createAccountLimiter, (request, response) => {
 To use a custom store:
 
 ```ts
-import rateLimit from 'express-rate-limit'
+import { rateLimit } from 'express-rate-limit'
 import RedisStore from 'rate-limit-redis'
 import RedisClient from 'ioredis'
 
@@ -185,7 +185,8 @@ const redisClient = new RedisClient()
 const rateLimiter = rateLimit({
 	windowMs: 15 * 60 * 1000, // 15 minutes
 	max: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes)
-	standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
+	standardHeaders: 'draft-7', // draft-6: RateLimit-* headers; draft-7: combined RateLimit header
+	legacyHeaders: false, // X-RateLimit-* headers
 	store: new RedisStore({
 		/* ... */
 	}), // Use the external store
@@ -329,16 +330,38 @@ Defaults to `true` (for backward compatibility).
 
 ### `standardHeaders`
 
-> `boolean`
+> `boolean` | `'draft-6'` | `'draft-7'`
 
 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.
+[RateLimit header fields for HTTP standardization draft](https://github.com/ietf-wg-httpapi/ratelimit-headers)
+adopted by the IETF.
+
+If set to `draft-6`, separate `RateLimit-Policy` `RateLimit-Limit`,
+`RateLimit-Remaining`, and, if the store supports it, `RateLimit-Reset` headers
+are set on the response, in accordance with
+[draft-ietf-httpapi-ratelimit-headers-06](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-06).
+
+If set to `draft-7`, a combined `RateLimit` header is set containing limit,
+remaining, and reset values, and a `RateLimit-Policy` header is set, in
+accordiance with
+[draft-ietf-httpapi-ratelimit-headers-07](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-07).
+`windowMs` is used for the reset value if the store does not provide a reset
+time.
 
-Defaults to `false` (for backward compatibility, but its use is recommended).
+If set to `true`, it is treated as `draft-6`, however this behavior may change
+in a future semver major release.
+
+If set to any truthy value, the middleware also sends the `Retry-After` header
+on all blocked requests.
+
+The `standardHeaders` option may be used in conjunction with, or instead of the
+`legacyHeaders` option.
+
+ℹ️ Tip: use
+[ratelimit-header-parser](https://www.npmjs.com/package/ratelimit-header-parser)
+in clients to read/parse any form of express-rate-limit's headers.
+
+Defaults to `false`.
 
 > Renamed in `6.x` from `draft_polli_ratelimit_headers` to `standardHeaders`.
 
@@ -430,8 +453,8 @@ const limiter = rateLimit({
 > `function`
 
 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.
+objects that is called the on the request where a client has just exceeded their
+rate limit.
 
 This method was
 [deprecated in v6](https://github.com/express-rate-limit/express-rate-limit/releases/v6.0.0) -
@@ -515,7 +538,7 @@ Here is a list of external stores:
 | [`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              |
+| [`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.  | Modern as of v2.0.0 |
 
 Take a look at
 [this guide](https://github.com/express-rate-limit/express-rate-limit/wiki/Creating-Your-Own-Store)

package/tsconfig.json

@@ -1,13 +1,5 @@
 {
 	"include": ["source/"],
 	"exclude": ["node_modules/"],
-	"compilerOptions": {
-		"declaration": true,
-		"strict": true,
-		"noUnusedLocals": true,
-		"noImplicitReturns": true,
-		"noFallthroughCasesInSwitch": true,
-		"esModuleInterop": true,
-		"moduleResolution": "node"
-	}
+	"extends": "@express-rate-limit/tsconfig"
 }