express-rate-limit 5.4.0 → 6.0.0

package/dist/esm/types.d.ts

@@ -0,0 +1,239 @@
+import Express 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 {Express.Request} - The Express request object
+ * @param response {Express.Response} - The Express response object
+ *
+ * @returns {T} - The value needed
+ */
+export declare type ValueDeterminingMiddleware<T> = (request: Express.Request, response: Express.Response) => T | Promise<T>;
+/**
+ * Express request handler that sends back a response when a client is
+ * rate-limited.
+ *
+ * @param request {Express.Request} - The Express request object
+ * @param response {Express.Response} - The Express response object
+ * @param next {Express.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: Express.Request, response: Express.Response, next: Express.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 {Express.Request} - The Express request object
+ * @param response {Express.Response} - The Express response object
+ * @param optionsUsed {Options} - The options used to set up the middleware
+ */
+export declare type RateLimitReachedEventHandler = (request: Express.Request, response: Express.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 = Express.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 = Express.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;
+}

package/dist/esm/types.js

@@ -0,0 +1,4 @@
+// /source/types.ts
+// All the types used by this package
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/types.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,qCAAqC","sourcesContent":["// /source/types.ts\n// All the types used by this package\n\nimport Express from 'express'\n\n/**\n * Callback that fires when a client's hit counter is incremented.\n *\n * @param error {Error | undefined} - The error that occurred, if any\n * @param totalHits {number} - The number of hits for that client so far\n * @param resetTime {Date | undefined} - The time when the counter resets\n */\nexport type IncrementCallback = (\n\terror: Error | undefined,\n\ttotalHits: number,\n\tresetTime: Date | undefined,\n) => void\n\n/**\n * Method (in the form of middleware) to generate/retrieve a value based on the\n * incoming request\n *\n * @param request {Express.Request} - The Express request object\n * @param response {Express.Response} - The Express response object\n *\n * @returns {T} - The value needed\n */\nexport type ValueDeterminingMiddleware<T> = (\n\trequest: Express.Request,\n\tresponse: Express.Response,\n) => T | Promise<T>\n\n/**\n * Express request handler that sends back a response when a client is\n * rate-limited.\n *\n * @param request {Express.Request} - The Express request object\n * @param response {Express.Response} - The Express response object\n * @param next {Express.NextFunction} - The Express `next` function, can be called to skip responding\n * @param optionsUsed {Options} - The options used to set up the middleware\n */\nexport type RateLimitExceededEventHandler = (\n\trequest: Express.Request,\n\tresponse: Express.Response,\n\tnext: Express.NextFunction,\n\toptionsUsed: Options,\n) => void\n\n/**\n * Event callback that is triggered on a client's first request that exceeds the limit\n * but not for subsequent requests. May be used for logging, etc. Should *not*\n * send a response.\n *\n * @param request {Express.Request} - The Express request object\n * @param response {Express.Response} - The Express response object\n * @param optionsUsed {Options} - The options used to set up the middleware\n */\nexport type RateLimitReachedEventHandler = (\n\trequest: Express.Request,\n\tresponse: Express.Response,\n\toptionsUsed: Options,\n) => void\n\n/**\n * Data returned from the `Store` when a client's hit counter is incremented.\n *\n * @property totalHits {number} - The number of hits for that client so far\n * @property resetTime {Date | undefined} - The time when the counter resets\n */\nexport type IncrementResponse = {\n\ttotalHits: number\n\tresetTime: Date | undefined\n}\n\n/**\n * A modified Express request handler with the rate limit functions.\n */\nexport type RateLimitRequestHandler = Express.RequestHandler & {\n\t/**\n\t * Method to reset a client's hit counter.\n\t *\n\t * @param key {string} - The identifier for a client\n\t */\n\tresetKey: (key: string) => void\n}\n\n/**\n * An interface that all hit counter stores must implement.\n *\n * @deprecated 6.x - Implement the `Store` interface instead.\n */\nexport interface LegacyStore {\n\t/**\n\t * Method to increment a client's hit counter.\n\t *\n\t * @param key {string} - The identifier for a client\n\t * @param callback {IncrementCallback} - The callback to call once the counter is incremented\n\t */\n\tincr: (key: string, callback: IncrementCallback) => void\n\n\t/**\n\t * Method to decrement a client's hit counter.\n\t *\n\t * @param key {string} - The identifier for a client\n\t */\n\tdecrement: (key: string) => void\n\n\t/**\n\t * Method to reset a client's hit counter.\n\t *\n\t * @param key {string} - The identifier for a client\n\t */\n\tresetKey: (key: string) => void\n\n\t/**\n\t * Method to reset everyone's hit counter.\n\t */\n\tresetAll?: () => void\n}\n\n/**\n * An interface that all hit counter stores must implement.\n */\nexport interface Store {\n\t/**\n\t * Method that initializes the store, and has access to the options passed to\n\t * the middleware too.\n\t *\n\t * @param options {Options} - The options used to setup the middleware\n\t */\n\tinit?: (options: Options) => void\n\n\t/**\n\t * Method to increment a client's hit counter.\n\t *\n\t * @param key {string} - The identifier for a client\n\t *\n\t * @returns {IncrementResponse} - The number of hits and reset time for that client\n\t */\n\tincrement: (key: string) => Promise<IncrementResponse> | IncrementResponse\n\n\t/**\n\t * Method to decrement a client's hit counter.\n\t *\n\t * @param key {string} - The identifier for a client\n\t */\n\tdecrement: (key: string) => Promise<void> | void\n\n\t/**\n\t * Method to reset a client's hit counter.\n\t *\n\t * @param key {string} - The identifier for a client\n\t */\n\tresetKey: (key: string) => Promise<void> | void\n\n\t/**\n\t * Method to reset everyone's hit counter.\n\t */\n\tresetAll?: () => Promise<void> | void\n}\n\n/**\n * The configuration options for the rate limiter.\n */\nexport interface Options {\n\t/**\n\t * How long we should remember the requests.\n\t */\n\treadonly windowMs: number\n\n\t/**\n\t * The maximum number of connection to allow during the `window` before\n\t * rate limiting the client.\n\t *\n\t * Can be the limit itself as a number or express middleware that parses\n\t * the request and then figures out the limit.\n\t */\n\treadonly max: number | ValueDeterminingMiddleware<number>\n\n\t/**\n\t * The response body to send back when a client is rate limited.\n\t */\n\treadonly message: any\n\n\t/**\n\t * The HTTP status code to send back when a client is rate limited.\n\t *\n\t * Defaults to `HTTP 429 Too Many Requests` (RFC 6585).\n\t */\n\treadonly statusCode: number\n\n\t/**\n\t * Whether to send `X-RateLimit-*` headers with the rate limit and the number\n\t * of requests.\n\t */\n\treadonly legacyHeaders: boolean\n\n\t/**\n\t * Whether to enable support for the rate limit standardization headers (`RateLimit-*`).\n\t */\n\treadonly standardHeaders: boolean\n\n\t/**\n\t * The name of the property on the request object to store the rate limit info.\n\t *\n\t * Defaults to `rateLimit`.\n\t */\n\treadonly requestPropertyName: string\n\n\t/**\n\t * If `true`, the library will (by default) skip all requests that have a 4XX\n\t * or 5XX status.\n\t */\n\treadonly skipFailedRequests: boolean\n\n\t/**\n\t * If `true`, the library will (by default) skip all requests that have a\n\t * status code less than 400.\n\t */\n\treadonly skipSuccessfulRequests: boolean\n\n\t/**\n\t * Method to determine whether or not the request counts as 'succesful'. Used\n\t * when either `skipSuccessfulRequests` or `skipFailedRequests` is set to true.\n\t */\n\treadonly requestWasSuccessful: ValueDeterminingMiddleware<boolean>\n\n\t/**\n\t * Method to generate custom identifiers for clients.\n\t *\n\t * By default, the client's IP address is used.\n\t */\n\treadonly keyGenerator: ValueDeterminingMiddleware<string>\n\n\t/**\n\t * Method (in the form of middleware) to determine whether or not this request\n\t * counts towards a client's quota.\n\t */\n\treadonly skip: ValueDeterminingMiddleware<boolean>\n\n\t/**\n\t * Express request handler that sends back a response when a client is\n\t * rate-limited.\n\t */\n\treadonly handler: RateLimitExceededEventHandler\n\n\t/**\n\t * Express request handler that sends back a response when a client has\n\t * reached their rate limit, and will be rate limited on their next request.\n\t */\n\treadonly onLimitReached: RateLimitReachedEventHandler\n\n\t/**\n\t * The {@link Store} to use to store the hit count for each client.\n\t */\n\tstore: Store\n\n\t/**\n\t * Whether to send `X-RateLimit-*` headers with the rate limit and the number\n\t * of requests.\n\t *\n\t * @deprecated 6.x - This option was renamed to `legacyHeaders`.\n\t */\n\theaders?: boolean\n\n\t/**\n\t * Whether to send `RateLimit-*` headers with the rate limit and the number\n\t * of requests.\n\t *\n\t * @deprecated 6.x - This option was renamed to `standardHeaders`.\n\t */\n\tdraft_polli_ratelimit_headers?: boolean\n}\n\n/**\n * The extended request object that includes information about the client's\n * rate limit.\n */\nexport type AugmentedRequest = Express.Request & {\n\t[key: string]: RateLimitInfo\n}\n\n/**\n * The rate limit related information for each client included in the\n * Express request object.\n */\nexport interface RateLimitInfo {\n\treadonly limit: number\n\treadonly current: number\n\treadonly remaining: number\n\treadonly resetTime: Date | undefined\n}\n"]}

package/license.md

@@ -0,0 +1,20 @@
+# MIT License
+
+Copyright 2021 Nathan Friedly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,53 +1,154 @@
 {
-  "name": "express-rate-limit",
-  "version": "5.4.0",
-  "description": "Basic IP rate-limiting middleware for Express. Use to limit repeated requests to public APIs and/or endpoints such as password reset.",
-  "homepage": "https://github.com/nfriedly/express-rate-limit",
-  "author": {
-    "name": "Nathan Friedly",
-    "url": "http://nfriedly.com/"
-  },
-  "repository": "nfriedly/express-rate-limit",
-  "license": "MIT",
-  "main": "lib/express-rate-limit.js",
-  "files": [
-    "lib/"
-  ],
-  "keywords": [
-    "express-rate-limit",
-    "express",
-    "rate",
-    "limit",
-    "ratelimit",
-    "rate-limit",
-    "middleware",
-    "ip",
-    "auth",
-    "authorization",
-    "security",
-    "brute",
-    "force",
-    "bruteforce",
-    "brute-force",
-    "attack"
-  ],
-  "devDependencies": {
-    "bluebird": "^3.7.2",
-    "eslint": "^7.32.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "express": "^4.17.1",
-    "husky": "^7.0.2",
-    "mocha": "^9.1.2",
-    "prettier": "^2.4.1",
-    "pretty-quick": "^3.1.1",
-    "sinon": "^11.1.2",
-    "supertest": "^6.1.6"
-  },
-  "scripts": {
-    "lint": "eslint .",
-    "autofix": "npm run lint -- --fix",
-    "test": "npm run lint && mocha",
-    "precommit": "pretty-quick --staged"
-  }
+	"name": "express-rate-limit",
+	"version": "6.0.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",
+		"url": "http://nfriedly.com/"
+	},
+	"license": "MIT",
+	"homepage": "https://github.com/nfriedly/express-rate-limit",
+	"repository": "https://github.com/nfriedly/express-rate-limit",
+	"keywords": [
+		"express-rate-limit",
+		"express",
+		"rate",
+		"limit",
+		"ratelimit",
+		"rate-limit",
+		"middleware",
+		"ip",
+		"auth",
+		"authorization",
+		"security",
+		"brute",
+		"force",
+		"bruteforce",
+		"brute-force",
+		"attack"
+	],
+	"type": "module",
+	"module": "dist/esm/index.js",
+	"main": "dist/cjs/index.js",
+	"exports": {
+		".": {
+			"import": "./dist/esm/index.js",
+			"require": "./dist/cjs/index.js"
+		},
+		"./memory-store": {
+			"import": "./dist/esm/memory-store.js",
+			"require": "./dist/cjs/memory-store.js"
+		}
+	},
+	"typesVersions": {
+		"*": {
+			".": [
+				"./dist/esm/index.d.ts"
+			],
+			"./memory-store": [
+				"./dist/esm/memory-store.d.ts"
+			]
+		}
+	},
+	"files": [
+		"dist/",
+		"tsconfig.json",
+		"package.json",
+		"package-lock.json",
+		"readme.md",
+		"license.md",
+		"changelog.md"
+	],
+	"engines": {
+		"node": ">= 12.9.0"
+	},
+	"scripts": {
+		"clean": "del-cli dist/ coverage/ *.log *.tmp *.bak *.tgz",
+		"build:cjs": "tsc --project config/typescript/cjs.json",
+		"build:esm": "tsc --project config/typescript/esm.json",
+		"build": "run-p build:*",
+		"compile": "run-s clean build",
+		"lint": "xo",
+		"autofix": "xo --fix",
+		"test-lib": "cross-env TS_NODE_PROJECT=config/typescript/test.json NODE_OPTIONS=--experimental-vm-modules jest",
+		"test": "run-s compile lint test-lib",
+		"view-coverage": "npx serve coverage/lcov-report",
+		"pre-commit": "lint-staged",
+		"prepare": "npm run compile && husky install config/husky"
+	},
+	"peerDependencies": {
+		"express": "^4"
+	},
+	"devDependencies": {
+		"@jest/globals": "^27.4.2",
+		"@types/express": "^4.17.13",
+		"@types/jest": "^27.0.3",
+		"@types/node": "^16.11.17",
+		"@types/supertest": "^2.0.11",
+		"cross-env": "^7.0.3",
+		"del-cli": "^4.0.1",
+		"express": "^4.17.1",
+		"husky": "^7.0.4",
+		"jest": "^27.4.3",
+		"lint-staged": "^12.1.2",
+		"npm-run-all": "^4.1.5",
+		"supertest": "^6.1.6",
+		"ts-jest": "^27.1.1",
+		"ts-node": "^10.4.0",
+		"typescript": "^4.5.2",
+		"xo": "^0.47.0"
+	},
+	"xo": {
+		"prettier": true,
+		"rules": {
+			"@typescript-eslint/no-empty-function": 0,
+			"@typescript-eslint/no-dynamic-delete": 0,
+			"@typescript-eslint/no-confusing-void-expression": 0,
+			"@typescript-eslint/consistent-indexed-object-style": [
+				"error",
+				"index-signature"
+			],
+			"import/no-named-as-default-member": 0,
+			"import/no-cycle": 0
+		}
+	},
+	"prettier": {
+		"semi": false,
+		"useTabs": true,
+		"singleQuote": true,
+		"bracketSpacing": true,
+		"trailingComma": "all",
+		"proseWrap": "always"
+	},
+	"jest": {
+		"preset": "ts-jest/presets/default-esm",
+		"globals": {
+			"ts-jest": {
+				"useESM": true
+			}
+		},
+		"verbose": true,
+		"collectCoverage": true,
+		"collectCoverageFrom": [
+			"source/**/*.ts"
+		],
+		"testTimeout": 30000,
+		"testMatch": [
+			"**/test/**/*-test.[jt]s?(x)"
+		],
+		"moduleFileExtensions": [
+			"js",
+			"jsx",
+			"json",
+			"ts",
+			"tsx"
+		],
+		"moduleNameMapper": {
+			"^(\\.{1,2}/.*)\\.js$": "$1"
+		}
+	},
+	"lint-staged": {
+		"{source,test}/**/*.ts": "xo --fix",
+		"**/*.{json,yaml,md}": "prettier --write"
+	}
 }