express-rate-limit 6.0.1 → 6.0.5

package/changelog.md

@@ -6,6 +6,62 @@ 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.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 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)
+
+### Fixed
+
+- Ensure CommonJS projects can import the module.
+
+### Added
+
+- Add additional tests that test:
+  - importing the library in `js-cjs`, `js-esm`, `ts-cjs`, `ts-esm`
+    environments.
+  - usage of the library with external stores (`redis`, `mongo`, `memcached`,
+    `precise`).
+
+### Changed
+
+- Use [`esbuild`](https://esbuild.github.io/) to generate ESM and CJS output.
+  This reduces the size of the built package from 138 kb to 13kb and build time
+  to 4 ms! :rocket:
+- Use [`dts-bundle-generator`](https://github.com/timocov/dts-bundle-generator)
+  to generate a single Typescript declaration file.
+
+## [6.0.1](https://github.com/nfriedly/express-rate-limit/releases/v6.0.1)
+
+### Fixed
+
+- Ensure CommonJS projects can import the module.
+
 ## [6.0.0](https://github.com/nfriedly/express-rate-limit/releases/v6.0.0)
 
 ### Added

package/dist/index.cjs

@@ -0,0 +1,226 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __markAsModule = (target) => __defProp(target, "__esModule", { value: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __reExport = (target, module2, copyDefault, desc) => {
+  if (module2 && typeof module2 === "object" || typeof module2 === "function") {
+    for (let key of __getOwnPropNames(module2))
+      if (!__hasOwnProp.call(target, key) && (copyDefault || key !== "default"))
+        __defProp(target, key, { get: () => module2[key], enumerable: !(desc = __getOwnPropDesc(module2, key)) || desc.enumerable });
+  }
+  return target;
+};
+var __toCommonJS = /* @__PURE__ */ ((cache) => {
+  return (module2, temp) => {
+    return cache && cache.get(module2) || (temp = __reExport(__markAsModule({}), module2, 1), cache && cache.set(module2, temp), temp);
+  };
+})(typeof WeakMap !== "undefined" ? /* @__PURE__ */ new WeakMap() : 0);
+
+// source/index.ts
+var source_exports = {};
+__export(source_exports, {
+  default: () => source_default
+});
+
+// source/memory-store.ts
+var calculateNextResetTime = (windowMs) => {
+  const resetTime = new Date();
+  resetTime.setMilliseconds(resetTime.getMilliseconds() + windowMs);
+  return resetTime;
+};
+var MemoryStore = class {
+  init(options) {
+    this.windowMs = options.windowMs;
+    this.resetTime = calculateNextResetTime(this.windowMs);
+    this.hits = {};
+    const interval = setInterval(async () => {
+      await this.resetAll();
+    }, this.windowMs);
+    if (interval.unref) {
+      interval.unref();
+    }
+  }
+  async increment(key) {
+    const totalHits = (this.hits[key] ?? 0) + 1;
+    this.hits[key] = totalHits;
+    return {
+      totalHits,
+      resetTime: this.resetTime
+    };
+  }
+  async decrement(key) {
+    const current = this.hits[key];
+    if (current) {
+      this.hits[key] = current - 1;
+    }
+  }
+  async resetKey(key) {
+    delete this.hits[key];
+  }
+  async resetAll() {
+    this.hits = {};
+    this.resetTime = calculateNextResetTime(this.windowMs);
+  }
+};
+
+// source/lib.ts
+var isLegacyStore = (store) => typeof store.incr === "function" && typeof store.increment !== "function";
+var promisifyStore = (passedStore) => {
+  if (!isLegacyStore(passedStore)) {
+    return passedStore;
+  }
+  const legacyStore = passedStore;
+  class PromisifiedStore {
+    async increment(key) {
+      return new Promise((resolve, reject) => {
+        legacyStore.incr(key, (error, totalHits, resetTime) => {
+          if (error)
+            reject(error);
+          resolve({ totalHits, resetTime });
+        });
+      });
+    }
+    async decrement(key) {
+      return Promise.resolve(legacyStore.decrement(key));
+    }
+    async resetKey(key) {
+      return Promise.resolve(legacyStore.resetKey(key));
+    }
+    async resetAll() {
+      if (typeof legacyStore.resetAll === "function")
+        return Promise.resolve(legacyStore.resetAll());
+    }
+  }
+  return new PromisifiedStore();
+};
+var parseOptions = (passedOptions) => {
+  const options = {
+    windowMs: 60 * 1e3,
+    store: new MemoryStore(),
+    max: 5,
+    message: "Too many requests, please try again later.",
+    statusCode: 429,
+    legacyHeaders: passedOptions.headers ?? true,
+    standardHeaders: passedOptions.draft_polli_ratelimit_headers ?? false,
+    requestPropertyName: "rateLimit",
+    skipFailedRequests: false,
+    skipSuccessfulRequests: false,
+    requestWasSuccessful: (_request, response) => response.statusCode < 400,
+    skip: (_request, _response) => false,
+    keyGenerator: (request, _response) => {
+      if (!request.ip) {
+        console.error("WARN | `express-rate-limit` | `request.ip` is undefined. You can avoid this by providing a custom `keyGenerator` function, but it may be indicative of a larger issue.");
+      }
+      return request.ip;
+    },
+    handler: (_request, response, _next, _optionsUsed) => {
+      response.status(options.statusCode).send(options.message);
+    },
+    onLimitReached: (_request, _response, _optionsUsed) => {
+    },
+    ...passedOptions
+  };
+  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") {
+    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;
+};
+var handleAsyncErrors = (fn) => async (request, response, next) => {
+  try {
+    await Promise.resolve(fn(request, response, next)).catch(next);
+  } catch (error) {
+    next(error);
+  }
+};
+var rateLimit = (passedOptions) => {
+  const options = parseOptions(passedOptions ?? {});
+  if (typeof options.store.init === "function")
+    options.store.init(options);
+  const middleware = handleAsyncErrors(async (request, response, next) => {
+    const skip = await options.skip(request, response);
+    if (skip) {
+      next();
+      return;
+    }
+    const augmentedRequest = request;
+    const key = await options.keyGenerator(request, response);
+    const { totalHits, resetTime } = await options.store.increment(key);
+    const retrieveQuota = typeof options.max === "function" ? options.max(request, response) : options.max;
+    const maxHits = await retrieveQuota;
+    augmentedRequest[options.requestPropertyName] = {
+      limit: maxHits,
+      current: totalHits,
+      remaining: Math.max(maxHits - totalHits, 0),
+      resetTime
+    };
+    if (options.legacyHeaders && !response.headersSent) {
+      response.setHeader("X-RateLimit-Limit", maxHits);
+      response.setHeader("X-RateLimit-Remaining", augmentedRequest[options.requestPropertyName].remaining);
+      if (resetTime instanceof Date) {
+        response.setHeader("Date", new Date().toUTCString());
+        response.setHeader("X-RateLimit-Reset", Math.ceil(resetTime.getTime() / 1e3));
+      }
+    }
+    if (options.standardHeaders && !response.headersSent) {
+      response.setHeader("RateLimit-Limit", maxHits);
+      response.setHeader("RateLimit-Remaining", augmentedRequest[options.requestPropertyName].remaining);
+      if (resetTime) {
+        const deltaSeconds = Math.ceil((resetTime.getTime() - Date.now()) / 1e3);
+        response.setHeader("RateLimit-Reset", Math.max(0, deltaSeconds));
+      }
+    }
+    if (options.skipFailedRequests || options.skipSuccessfulRequests) {
+      let decremented = false;
+      const decrementKey = async () => {
+        if (!decremented) {
+          await options.store.decrement(key);
+          decremented = true;
+        }
+      };
+      if (options.skipFailedRequests) {
+        response.on("finish", async () => {
+          if (!options.requestWasSuccessful(request, response))
+            await decrementKey();
+        });
+        response.on("close", async () => {
+          if (!response.writableEnded)
+            await decrementKey();
+        });
+        response.on("error", async () => {
+          await decrementKey();
+        });
+      }
+      if (options.skipSuccessfulRequests) {
+        response.on("finish", async () => {
+          if (options.requestWasSuccessful(request, response))
+            await decrementKey();
+        });
+      }
+    }
+    if (maxHits && totalHits === maxHits + 1) {
+      options.onLimitReached(request, response, options);
+    }
+    if (maxHits && totalHits > maxHits) {
+      if ((options.legacyHeaders || options.standardHeaders) && !response.headersSent) {
+        response.setHeader("Retry-After", Math.ceil(options.windowMs / 1e3));
+      }
+      options.handler(request, response, next, options);
+      return;
+    }
+    next();
+  });
+  middleware.resetKey = options.store.resetKey.bind(options.store);
+  return middleware;
+};
+var lib_default = rateLimit;
+
+// source/index.ts
+var source_default = lib_default;
+module.exports = __toCommonJS(source_exports);
+module.exports = rateLimit;

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+// Generated by dts-bundle-generator v6.3.0
+
+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
+ */
+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
+ *
+ * @param request {Request} - The Express request object
+ * @param response {Response} - The Express response object
+ *
+ * @returns {T} - The value needed
+ */
+export declare type ValueDeterminingMiddleware<T> = (request: Request, response: Response) => T | Promise<T>;
+/**
+ * Express request handler that sends back a response when a client is
+ * rate-limited.
+ *
+ * @param request {Request} - The Express request object
+ * @param response {Response} - The Express response object
+ * @param next {NextFunction} - The Express `next` function, can be called to skip responding
+ * @param optionsUsed {Options} - The options used to set up the middleware
+ */
+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 {Request} - The Express request object
+ * @param response {Response} - The Express response object
+ * @param optionsUsed {Options} - The options used to set up the middleware
+ */
+export declare type RateLimitReachedEventHandler = (request: Request, response: Response, optionsUsed: Options) => void;
+/**
+ * Data returned from the `Store` when a client's hit counter is incremented.
+ *
+ * @property totalHits {number} - The number of hits for that client so far
+ * @property resetTime {Date | undefined} - The time when the counter resets
+ */
+export declare type IncrementResponse = {
+	totalHits: number;
+	resetTime: Date | undefined;
+};
+/**
+ * A modified Express request handler with the rate limit functions.
+ */
+export declare type RateLimitRequestHandler = RequestHandler & {
+	/**
+	 * Method to reset a client's hit counter.
+	 *
+	 * @param key {string} - The identifier for a client
+	 */
+	resetKey: (key: string) => void;
+};
+/**
+ * An interface that all hit counter stores must implement.
+ *
+ * @deprecated 6.x - Implement the `Store` interface instead.
+ */
+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
+	 */
+	incr: (key: string, callback: IncrementCallback) => void;
+	/**
+	 * Method to decrement a client's hit counter.
+	 *
+	 * @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
+	 */
+	resetKey: (key: string) => void;
+	/**
+	 * Method to reset everyone's hit counter.
+	 */
+	resetAll?: () => void;
+}
+/**
+ * An interface that all hit counter stores must implement.
+ */
+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
+	 */
+	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
+	 */
+	increment: (key: string) => Promise<IncrementResponse> | IncrementResponse;
+	/**
+	 * Method to decrement a client's hit counter.
+	 *
+	 * @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
+	 */
+	resetKey: (key: string) => Promise<void> | void;
+	/**
+	 * Method to reset everyone's hit counter.
+	 */
+	resetAll?: () => Promise<void> | void;
+}
+/**
+ * The configuration options for the rate limiter.
+ */
+export interface Options {
+	/**
+	 * How long we should remember the requests.
+	 */
+	readonly windowMs: number;
+	/**
+	 * The maximum number of connection 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.
+	 */
+	readonly max: number | ValueDeterminingMiddleware<number>;
+	/**
+	 * The response body to send back when a client is rate limited.
+	 */
+	readonly message: any;
+	/**
+	 * The HTTP status code to send back when a client is rate limited.
+	 *
+	 * Defaults to `HTTP 429 Too Many Requests` (RFC 6585).
+	 */
+	readonly statusCode: number;
+	/**
+	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
+	 * of requests.
+	 */
+	readonly legacyHeaders: boolean;
+	/**
+	 * Whether to enable support for the rate limit standardization headers (`RateLimit-*`).
+	 */
+	readonly standardHeaders: boolean;
+	/**
+	 * The name of the property on the request object to store the rate limit info.
+	 *
+	 * Defaults to `rateLimit`.
+	 */
+	readonly requestPropertyName: string;
+	/**
+	 * If `true`, the library will (by default) skip all requests that have a 4XX
+	 * or 5XX status.
+	 */
+	readonly skipFailedRequests: boolean;
+	/**
+	 * If `true`, the library will (by default) skip all requests that have a
+	 * status code less than 400.
+	 */
+	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.
+	 */
+	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.
+	 */
+	readonly onLimitReached: RateLimitReachedEventHandler;
+	/**
+	 * The {@link Store} to use to store the hit count for each client.
+	 */
+	store: Store;
+	/**
+	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
+	 * of requests.
+	 *
+	 * @deprecated 6.x - This option was renamed to `legacyHeaders`.
+	 */
+	headers?: boolean;
+	/**
+	 * Whether to send `RateLimit-*` headers with the rate limit and the number
+	 * of requests.
+	 *
+	 * @deprecated 6.x - This option was renamed to `standardHeaders`.
+	 */
+	draft_polli_ratelimit_headers?: boolean;
+}
+/**
+ * The extended request object that includes information about the client's
+ * rate limit.
+ */
+export declare type AugmentedRequest = Request & {
+	[key: string]: RateLimitInfo;
+};
+/**
+ * The rate limit related information for each client included in the
+ * Express request object.
+ */
+export interface RateLimitInfo {
+	readonly limit: number;
+	readonly current: number;
+	readonly remaining: number;
+	readonly resetTime: Date | undefined;
+}
+declare const rateLimit: (passedOptions?: (Omit<Partial<Options>, "store"> & {
+	store?: LegacyStore | Store | undefined;
+}) | undefined) => RateLimitRequestHandler;
+export default rateLimit;
+
+export {};