express-rate-limit 6.11.2 → 7.0.0

package/dist/index.d.cts

@@ -1,7 +1,104 @@
-// Generated by dts-bundle-generator v7.0.0
+// Generated by dts-bundle-generator v8.0.1
 
 import { NextFunction, Request, RequestHandler, Response } from 'express';
 
+declare const validations: {
+	enabled: {
+		[key: string]: boolean;
+	};
+	disable(): void;
+	/**
+	 * Checks whether the IP address is valid, and that it does not have a port
+	 * number in it.
+	 *
+	 * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_invalid_ip_address.
+	 *
+	 * @param ip {string | undefined} - The IP address provided by Express as request.ip.
+	 *
+	 * @returns {void}
+	 */
+	ip(ip: string | undefined): void;
+	/**
+	 * Makes sure the trust proxy setting is not set to `true`.
+	 *
+	 * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_permissive_trust_proxy.
+	 *
+	 * @param request {Request} - The Express request object.
+	 *
+	 * @returns {void}
+	 */
+	trustProxy(request: Request): void;
+	/**
+	 * Makes sure the trust proxy setting is set in case the `X-Forwarded-For`
+	 * header is present.
+	 *
+	 * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_unset_trust_proxy.
+	 *
+	 * @param request {Request} - The Express request object.
+	 *
+	 * @returns {void}
+	 */
+	xForwardedForHeader(request: Request): void;
+	/**
+	 * Ensures totalHits value from store is a positive integer.
+	 *
+	 * @param hits {any} - The `totalHits` returned by the store.
+	 */
+	positiveHits(hits: any): void;
+	/**
+	 * Ensures a given key is incremented only once per request.
+	 *
+	 * @param request {Request} - The Express request object.
+	 * @param store {Store} - The store class.
+	 * @param key {string} - The key used to store the client's hit count.
+	 *
+	 * @returns {void}
+	 */
+	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.
+	 *
+	 * @param limit {number} - The maximum number of hits per client.
+	 *
+	 * @returns {void}
+	 */
+	limit(limit: number): void;
+	/**
+	 * 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 {any | undefined} - The now-deprecated setting that was used to enable standard headers.
+	 *
+	 * @returns {void}
+	 */
+	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.
+	 *
+	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
+	 *
+	 * @returns {void}
+	 */
+	onLimitReached(onLimitReached?: any): void;
+	/**
+	 * 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?: Date): void;
+	/**
+	 * 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.
+	 */
+	validationsConfig(): void;
+};
+export type Validations = typeof validations;
 /**
  * Callback that fires when a client's hit counter is incremented.
  *
@@ -163,6 +260,15 @@ export type Store = {
 	prefix?: string;
 };
 export type DraftHeadersVersion = "draft-6" | "draft-7";
+/**
+ * Validate configuration object for enabling or disabling specific validations.
+ *
+ * The keys must also be keys in the validations object, except `enable`, `disable`,
+ * and `default`.
+ */
+export type EnabledValidations = {
+	[key in keyof Omit<Validations, "enabled" | "disable"> | "default"]?: boolean;
+};
 /**
  * The configuration options for the rate limiter.
  */
@@ -182,7 +288,7 @@ export type Options = {
 	 *
 	 * Defaults to `5`.
 	 */
-	max: number | ValueDeterminingMiddleware<number>;
+	limit: number | ValueDeterminingMiddleware<number>;
 	/**
 	 * The response body to send back when a client is rate limited.
 	 *
@@ -241,14 +347,6 @@ export type Options = {
 	 * By default, sends back the `statusCode` and `message` set via the options.
 	 */
 	handler: RateLimitExceededEventHandler;
-	/**
-	 * Express request handler that sends back a response when a client has
-	 * reached their rate limit, and will be rate limited on their next request.
-	 *
-	 * @deprecated 6.x - Please use a custom `handler` that checks the number of
-	 * hits instead.
-	 */
-	onLimitReached: RateLimitReachedEventHandler;
 	/**
 	 * Method (in the form of middleware) to determine whether or not this request
 	 * counts towards a client's quota.
@@ -271,9 +369,9 @@ export type Options = {
 	 */
 	store: Store | LegacyStore;
 	/**
-	 * Whether or not the validation checks should run.
+	 * The list of validation checks that should run.
 	 */
-	validate: boolean;
+	validate: boolean | EnabledValidations;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
@@ -282,12 +380,16 @@ export type Options = {
 	 */
 	headers?: boolean;
 	/**
-	 * Whether to send `RateLimit-*` headers with the rate limit and the number
-	 * of requests.
+	 * The maximum number of connections to allow during the `window` before
+	 * rate limiting the client.
+	 *
+	 * Can be the limit itself as a number or express middleware that parses
+	 * the request and then figures out the limit.
 	 *
-	 * @deprecated 6.x - This option was renamed to `standardHeaders`.
+	 * @deprecated 7.x - This option was renamed to `limit`. However, it will not
+	 * be removed from the library in the foreseeable future.
 	 */
-	draft_polli_ratelimit_headers?: boolean;
+	max?: number | ValueDeterminingMiddleware<number>;
 };
 /**
  * The extended request object that includes information about the client's
@@ -302,7 +404,7 @@ export type AugmentedRequest = Request & {
  */
 export type RateLimitInfo = {
 	limit: number;
-	current: number;
+	used: number;
 	remaining: number;
 	resetTime: Date | undefined;
 };
@@ -317,6 +419,16 @@ export type RateLimitInfo = {
  * @public
  */
 export declare const rateLimit: (passedOptions?: Partial<Options>) => RateLimitRequestHandler;
+/**
+ * The record that stores information about a client - namely, how many times
+ * they have hit the endpoint, and when their hit count resets.
+ *
+ * Similar to `ClientRateLimitInfo`, except `resetTime` is a compulsory field.
+ */
+export type Client = {
+	totalHits: number;
+	resetTime: Date;
+};
 /**
  * A `Store` that stores the hit count for each client in memory.
  *
@@ -328,19 +440,21 @@ export declare class MemoryStore implements Store {
 	 */
 	windowMs: number;
 	/**
-	 * The map that stores the number of hits for each client in memory.
-	 */
-	hits: {
-		[key: string]: number | undefined;
-	};
-	/**
-	 * The time at which all hit counts will be reset.
+	 * These two maps store usage (requests) and reset time by key (for example, IP
+	 * addresses or API keys).
+	 *
+	 * They are split into two to avoid having to iterate through the entire set to
+	 * determine which ones need reset. Instead, `Client`s are moved from `previous`
+	 * to `current` as they hit the endpoint. Once `windowMs` has elapsed, all clients
+	 * left in `previous`, i.e., those that have not made any recent requests, are
+	 * known to be expired and can be deleted in bulk.
 	 */
-	resetTime: Date;
+	previous: Map<string, Client>;
+	current: Map<string, Client>;
 	/**
-	 * Reference to the active timer.
+	 * A reference to the active timer.
 	 */
-	interval?: NodeJS.Timer;
+	interval?: NodeJS.Timeout;
 	/**
 	 * Confirmation that the keys incremented in once instance of MemoryStore
 	 * cannot affect other instances.
@@ -401,6 +515,34 @@ export declare class MemoryStore implements Store {
 	 * @public
 	 */
 	shutdown(): void;
+	/**
+	 * Recycles a client by setting its hit count to zero, and reset time to
+	 * `windowMs` milliseconds from now.
+	 *
+	 * NOT to be confused with `#resetKey()`, which removes a client from both the
+	 * `current` and `previous` maps.
+	 *
+	 * @param client {Client} - The client to recycle.
+	 * @param now {number} - The current time, to which the `windowMs` is added to get the `resetTime` for the client.
+	 *
+	 * @return {Client} - The modified client that was passed in, to allow for chaining.
+	 */
+	private resetClient;
+	/**
+	 * Retrieves or creates a client, given a key. Also ensures that the client being
+	 * returned is in the `current` map.
+	 *
+	 * @param key {string} - The key under which the client is (or is to be) stored.
+	 *
+	 * @returns {Client} - The requested client.
+	 */
+	private getClient;
+	/**
+	 * Move current clients to previous, create a new map for current.
+	 *
+	 * This function is called every `windowMs`.
+	 */
+	private clearExpired;
 }
 
 export {

package/dist/index.d.mts

@@ -1,7 +1,104 @@
-// Generated by dts-bundle-generator v7.0.0
+// Generated by dts-bundle-generator v8.0.1
 
 import { NextFunction, Request, RequestHandler, Response } from 'express';
 
+declare const validations: {
+	enabled: {
+		[key: string]: boolean;
+	};
+	disable(): void;
+	/**
+	 * Checks whether the IP address is valid, and that it does not have a port
+	 * number in it.
+	 *
+	 * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_invalid_ip_address.
+	 *
+	 * @param ip {string | undefined} - The IP address provided by Express as request.ip.
+	 *
+	 * @returns {void}
+	 */
+	ip(ip: string | undefined): void;
+	/**
+	 * Makes sure the trust proxy setting is not set to `true`.
+	 *
+	 * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_permissive_trust_proxy.
+	 *
+	 * @param request {Request} - The Express request object.
+	 *
+	 * @returns {void}
+	 */
+	trustProxy(request: Request): void;
+	/**
+	 * Makes sure the trust proxy setting is set in case the `X-Forwarded-For`
+	 * header is present.
+	 *
+	 * See https://github.com/express-rate-limit/express-rate-limit/wiki/Error-Codes#err_erl_unset_trust_proxy.
+	 *
+	 * @param request {Request} - The Express request object.
+	 *
+	 * @returns {void}
+	 */
+	xForwardedForHeader(request: Request): void;
+	/**
+	 * Ensures totalHits value from store is a positive integer.
+	 *
+	 * @param hits {any} - The `totalHits` returned by the store.
+	 */
+	positiveHits(hits: any): void;
+	/**
+	 * Ensures a given key is incremented only once per request.
+	 *
+	 * @param request {Request} - The Express request object.
+	 * @param store {Store} - The store class.
+	 * @param key {string} - The key used to store the client's hit count.
+	 *
+	 * @returns {void}
+	 */
+	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.
+	 *
+	 * @param limit {number} - The maximum number of hits per client.
+	 *
+	 * @returns {void}
+	 */
+	limit(limit: number): void;
+	/**
+	 * 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 {any | undefined} - The now-deprecated setting that was used to enable standard headers.
+	 *
+	 * @returns {void}
+	 */
+	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.
+	 *
+	 * @param onLimitReached {any | undefined} - The maximum number of hits per client.
+	 *
+	 * @returns {void}
+	 */
+	onLimitReached(onLimitReached?: any): void;
+	/**
+	 * 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?: Date): void;
+	/**
+	 * 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.
+	 */
+	validationsConfig(): void;
+};
+export type Validations = typeof validations;
 /**
  * Callback that fires when a client's hit counter is incremented.
  *
@@ -163,6 +260,15 @@ export type Store = {
 	prefix?: string;
 };
 export type DraftHeadersVersion = "draft-6" | "draft-7";
+/**
+ * Validate configuration object for enabling or disabling specific validations.
+ *
+ * The keys must also be keys in the validations object, except `enable`, `disable`,
+ * and `default`.
+ */
+export type EnabledValidations = {
+	[key in keyof Omit<Validations, "enabled" | "disable"> | "default"]?: boolean;
+};
 /**
  * The configuration options for the rate limiter.
  */
@@ -182,7 +288,7 @@ export type Options = {
 	 *
 	 * Defaults to `5`.
 	 */
-	max: number | ValueDeterminingMiddleware<number>;
+	limit: number | ValueDeterminingMiddleware<number>;
 	/**
 	 * The response body to send back when a client is rate limited.
 	 *
@@ -241,14 +347,6 @@ export type Options = {
 	 * By default, sends back the `statusCode` and `message` set via the options.
 	 */
 	handler: RateLimitExceededEventHandler;
-	/**
-	 * Express request handler that sends back a response when a client has
-	 * reached their rate limit, and will be rate limited on their next request.
-	 *
-	 * @deprecated 6.x - Please use a custom `handler` that checks the number of
-	 * hits instead.
-	 */
-	onLimitReached: RateLimitReachedEventHandler;
 	/**
 	 * Method (in the form of middleware) to determine whether or not this request
 	 * counts towards a client's quota.
@@ -271,9 +369,9 @@ export type Options = {
 	 */
 	store: Store | LegacyStore;
 	/**
-	 * Whether or not the validation checks should run.
+	 * The list of validation checks that should run.
 	 */
-	validate: boolean;
+	validate: boolean | EnabledValidations;
 	/**
 	 * Whether to send `X-RateLimit-*` headers with the rate limit and the number
 	 * of requests.
@@ -282,12 +380,16 @@ export type Options = {
 	 */
 	headers?: boolean;
 	/**
-	 * Whether to send `RateLimit-*` headers with the rate limit and the number
-	 * of requests.
+	 * The maximum number of connections to allow during the `window` before
+	 * rate limiting the client.
+	 *
+	 * Can be the limit itself as a number or express middleware that parses
+	 * the request and then figures out the limit.
 	 *
-	 * @deprecated 6.x - This option was renamed to `standardHeaders`.
+	 * @deprecated 7.x - This option was renamed to `limit`. However, it will not
+	 * be removed from the library in the foreseeable future.
 	 */
-	draft_polli_ratelimit_headers?: boolean;
+	max?: number | ValueDeterminingMiddleware<number>;
 };
 /**
  * The extended request object that includes information about the client's
@@ -302,7 +404,7 @@ export type AugmentedRequest = Request & {
  */
 export type RateLimitInfo = {
 	limit: number;
-	current: number;
+	used: number;
 	remaining: number;
 	resetTime: Date | undefined;
 };
@@ -317,6 +419,16 @@ export type RateLimitInfo = {
  * @public
  */
 export declare const rateLimit: (passedOptions?: Partial<Options>) => RateLimitRequestHandler;
+/**
+ * The record that stores information about a client - namely, how many times
+ * they have hit the endpoint, and when their hit count resets.
+ *
+ * Similar to `ClientRateLimitInfo`, except `resetTime` is a compulsory field.
+ */
+export type Client = {
+	totalHits: number;
+	resetTime: Date;
+};
 /**
  * A `Store` that stores the hit count for each client in memory.
  *
@@ -328,19 +440,21 @@ export declare class MemoryStore implements Store {
 	 */
 	windowMs: number;
 	/**
-	 * The map that stores the number of hits for each client in memory.
-	 */
-	hits: {
-		[key: string]: number | undefined;
-	};
-	/**
-	 * The time at which all hit counts will be reset.
+	 * These two maps store usage (requests) and reset time by key (for example, IP
+	 * addresses or API keys).
+	 *
+	 * They are split into two to avoid having to iterate through the entire set to
+	 * determine which ones need reset. Instead, `Client`s are moved from `previous`
+	 * to `current` as they hit the endpoint. Once `windowMs` has elapsed, all clients
+	 * left in `previous`, i.e., those that have not made any recent requests, are
+	 * known to be expired and can be deleted in bulk.
 	 */
-	resetTime: Date;
+	previous: Map<string, Client>;
+	current: Map<string, Client>;
 	/**
-	 * Reference to the active timer.
+	 * A reference to the active timer.
 	 */
-	interval?: NodeJS.Timer;
+	interval?: NodeJS.Timeout;
 	/**
 	 * Confirmation that the keys incremented in once instance of MemoryStore
 	 * cannot affect other instances.
@@ -401,6 +515,34 @@ export declare class MemoryStore implements Store {
 	 * @public
 	 */
 	shutdown(): void;
+	/**
+	 * Recycles a client by setting its hit count to zero, and reset time to
+	 * `windowMs` milliseconds from now.
+	 *
+	 * NOT to be confused with `#resetKey()`, which removes a client from both the
+	 * `current` and `previous` maps.
+	 *
+	 * @param client {Client} - The client to recycle.
+	 * @param now {number} - The current time, to which the `windowMs` is added to get the `resetTime` for the client.
+	 *
+	 * @return {Client} - The modified client that was passed in, to allow for chaining.
+	 */
+	private resetClient;
+	/**
+	 * Retrieves or creates a client, given a key. Also ensures that the client being
+	 * returned is in the `current` map.
+	 *
+	 * @param key {string} - The key under which the client is (or is to be) stored.
+	 *
+	 * @returns {Client} - The requested client.
+	 */
+	private getClient;
+	/**
+	 * Move current clients to previous, create a new map for current.
+	 *
+	 * This function is called every `windowMs`.
+	 */
+	private clearExpired;
 }
 
 export {