express-rate-limit 6.10.0 → 6.11.0

package/changelog.md

@@ -6,6 +6,14 @@ 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.11.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.11.0)
+
+### Added
+
+- Support for retrieving the current hit count and reset time for a given key
+  from a store (See
+  [#390](https://github.com/express-rate-limit/express-rate-limit/issues/389)).
+
 ## [6.10.0](https://github.com/express-rate-limit/express-rate-limit/releases/tag/v6.10.0)
 
 ### Added

package/dist/index.cjs

@@ -375,12 +375,29 @@ var MemoryStore = class {
     if (this.interval.unref)
       this.interval.unref();
   }
+  /**
+   * Method to fetch a client's hit count and reset time.
+   *
+   * @param key {string} - The identifier for a client.
+   *
+   * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
+   *
+   * @public
+   */
+  async get(key) {
+    if (this.hits[key] !== void 0)
+      return {
+        totalHits: this.hits[key],
+        resetTime: this.resetTime
+      };
+    return void 0;
+  }
   /**
    * 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.
+   * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
    *
    * @public
    */
@@ -447,6 +464,10 @@ var promisifyStore = (passedStore) => {
   }
   const legacyStore = passedStore;
   class PromisifiedStore {
+    /* istanbul ignore next */
+    async get(key) {
+      return void 0;
+    }
     async increment(key) {
       return new Promise((resolve, reject) => {
         legacyStore.incr(
@@ -556,6 +577,7 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
   }
 };
 var rateLimit = (passedOptions) => {
+  var _a;
   const config = parseOptions(passedOptions != null ? passedOptions : {});
   const options = getOptionsFromConfig(config);
   if (typeof config.store.init === "function")
@@ -636,6 +658,9 @@ var rateLimit = (passedOptions) => {
     }
   );
   middleware.resetKey = config.store.resetKey.bind(config.store);
+  middleware.getKey = (_a = config.store.get) == null ? void 0 : _a.bind(
+    config.store
+  );
   return middleware;
 };
 var lib_default = rateLimit;

package/dist/index.d.cts

@@ -46,7 +46,7 @@ export type RateLimitReachedEventHandler = (request: Request, response: Response
  * @property totalHits {number} - The number of hits for that client so far.
  * @property resetTime {Date | undefined} - The time when the counter resets.
  */
-export type IncrementResponse = {
+export type ClientRateLimitInfo = {
 	totalHits: number;
 	resetTime: Date | undefined;
 };
@@ -60,6 +60,14 @@ export type RateLimitRequestHandler = RequestHandler & {
 	 * @param key {string} - The identifier for a client.
 	 */
 	resetKey: (key: string) => void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+	 */
+	getKey?: (key: string) => Promise<ClientRateLimitInfo | undefined> | ClientRateLimitInfo | undefined;
 };
 /**
  * An interface that all hit counter stores must implement.
@@ -102,14 +110,22 @@ export type Store = {
 	 * @param options {Options} - The options used to setup the middleware.
 	 */
 	init?: (options: Options) => void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+	 */
+	get?: (key: string) => Promise<ClientRateLimitInfo | undefined> | ClientRateLimitInfo | undefined;
 	/**
 	 * 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.
+	 * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
 	 */
-	increment: (key: string) => Promise<IncrementResponse> | IncrementResponse;
+	increment: (key: string) => Promise<ClientRateLimitInfo> | ClientRateLimitInfo;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *
@@ -329,16 +345,26 @@ export declare class MemoryStore implements Store {
 	 * @param options {Options} - The options used to setup the middleware.
 	 */
 	init(options: Options): void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
+	 *
+	 * @public
+	 */
+	get(key: string): Promise<ClientRateLimitInfo | undefined>;
 	/**
 	 * 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.
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
 	 *
 	 * @public
 	 */
-	increment(key: string): Promise<IncrementResponse>;
+	increment(key: string): Promise<ClientRateLimitInfo>;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *

package/dist/index.d.mts

@@ -46,7 +46,7 @@ export type RateLimitReachedEventHandler = (request: Request, response: Response
  * @property totalHits {number} - The number of hits for that client so far.
  * @property resetTime {Date | undefined} - The time when the counter resets.
  */
-export type IncrementResponse = {
+export type ClientRateLimitInfo = {
 	totalHits: number;
 	resetTime: Date | undefined;
 };
@@ -60,6 +60,14 @@ export type RateLimitRequestHandler = RequestHandler & {
 	 * @param key {string} - The identifier for a client.
 	 */
 	resetKey: (key: string) => void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+	 */
+	getKey?: (key: string) => Promise<ClientRateLimitInfo | undefined> | ClientRateLimitInfo | undefined;
 };
 /**
  * An interface that all hit counter stores must implement.
@@ -102,14 +110,22 @@ export type Store = {
 	 * @param options {Options} - The options used to setup the middleware.
 	 */
 	init?: (options: Options) => void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+	 */
+	get?: (key: string) => Promise<ClientRateLimitInfo | undefined> | ClientRateLimitInfo | undefined;
 	/**
 	 * 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.
+	 * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
 	 */
-	increment: (key: string) => Promise<IncrementResponse> | IncrementResponse;
+	increment: (key: string) => Promise<ClientRateLimitInfo> | ClientRateLimitInfo;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *
@@ -329,16 +345,26 @@ export declare class MemoryStore implements Store {
 	 * @param options {Options} - The options used to setup the middleware.
 	 */
 	init(options: Options): void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
+	 *
+	 * @public
+	 */
+	get(key: string): Promise<ClientRateLimitInfo | undefined>;
 	/**
 	 * 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.
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
 	 *
 	 * @public
 	 */
-	increment(key: string): Promise<IncrementResponse>;
+	increment(key: string): Promise<ClientRateLimitInfo>;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *

package/dist/index.d.ts

@@ -46,7 +46,7 @@ export type RateLimitReachedEventHandler = (request: Request, response: Response
  * @property totalHits {number} - The number of hits for that client so far.
  * @property resetTime {Date | undefined} - The time when the counter resets.
  */
-export type IncrementResponse = {
+export type ClientRateLimitInfo = {
 	totalHits: number;
 	resetTime: Date | undefined;
 };
@@ -60,6 +60,14 @@ export type RateLimitRequestHandler = RequestHandler & {
 	 * @param key {string} - The identifier for a client.
 	 */
 	resetKey: (key: string) => void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+	 */
+	getKey?: (key: string) => Promise<ClientRateLimitInfo | undefined> | ClientRateLimitInfo | undefined;
 };
 /**
  * An interface that all hit counter stores must implement.
@@ -102,14 +110,22 @@ export type Store = {
 	 * @param options {Options} - The options used to setup the middleware.
 	 */
 	init?: (options: Options) => void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
+	 */
+	get?: (key: string) => Promise<ClientRateLimitInfo | undefined> | ClientRateLimitInfo | undefined;
 	/**
 	 * 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.
+	 * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
 	 */
-	increment: (key: string) => Promise<IncrementResponse> | IncrementResponse;
+	increment: (key: string) => Promise<ClientRateLimitInfo> | ClientRateLimitInfo;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *
@@ -329,16 +345,26 @@ export declare class MemoryStore implements Store {
 	 * @param options {Options} - The options used to setup the middleware.
 	 */
 	init(options: Options): void;
+	/**
+	 * Method to fetch a client's hit count and reset time.
+	 *
+	 * @param key {string} - The identifier for a client.
+	 *
+	 * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
+	 *
+	 * @public
+	 */
+	get(key: string): Promise<ClientRateLimitInfo | undefined>;
 	/**
 	 * 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.
+	 * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
 	 *
 	 * @public
 	 */
-	increment(key: string): Promise<IncrementResponse>;
+	increment(key: string): Promise<ClientRateLimitInfo>;
 	/**
 	 * Method to decrement a client's hit counter.
 	 *

package/dist/index.mjs

@@ -349,12 +349,29 @@ var MemoryStore = class {
     if (this.interval.unref)
       this.interval.unref();
   }
+  /**
+   * Method to fetch a client's hit count and reset time.
+   *
+   * @param key {string} - The identifier for a client.
+   *
+   * @returns {ClientRateLimitInfo | undefined} - The number of hits and reset time for that client.
+   *
+   * @public
+   */
+  async get(key) {
+    if (this.hits[key] !== void 0)
+      return {
+        totalHits: this.hits[key],
+        resetTime: this.resetTime
+      };
+    return void 0;
+  }
   /**
    * 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.
+   * @returns {ClientRateLimitInfo} - The number of hits and reset time for that client.
    *
    * @public
    */
@@ -421,6 +438,10 @@ var promisifyStore = (passedStore) => {
   }
   const legacyStore = passedStore;
   class PromisifiedStore {
+    /* istanbul ignore next */
+    async get(key) {
+      return void 0;
+    }
     async increment(key) {
       return new Promise((resolve, reject) => {
         legacyStore.incr(
@@ -530,6 +551,7 @@ var handleAsyncErrors = (fn) => async (request, response, next) => {
   }
 };
 var rateLimit = (passedOptions) => {
+  var _a;
   const config = parseOptions(passedOptions != null ? passedOptions : {});
   const options = getOptionsFromConfig(config);
   if (typeof config.store.init === "function")
@@ -610,6 +632,9 @@ var rateLimit = (passedOptions) => {
     }
   );
   middleware.resetKey = config.store.resetKey.bind(config.store);
+  middleware.getKey = (_a = config.store.get) == null ? void 0 : _a.bind(
+    config.store
+  );
   return middleware;
 };
 var lib_default = rateLimit;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "express-rate-limit",
-	"version": "6.10.0",
+	"version": "6.11.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",
@@ -60,11 +60,11 @@
 		"build:esm": "esbuild --platform=node --bundle --target=es2019 --format=esm --outfile=dist/index.mjs source/index.ts",
 		"build:types": "dts-bundle-generator --out-file=dist/index.d.ts source/index.ts && cp dist/index.d.ts dist/index.d.cts && cp dist/index.d.ts dist/index.d.mts",
 		"compile": "run-s clean build:*",
-		"lint:code": "xo --ignore test/external/",
-		"lint:rest": "prettier --ignore-path .gitignore --ignore-unknown --check .",
+		"lint:code": "xo",
+		"lint:rest": "prettier --check .",
 		"lint": "run-s lint:*",
-		"format:code": "npm run lint:code -- --fix",
-		"format:rest": "npm run lint:rest -- --write .",
+		"format:code": "xo --fix",
+		"format:rest": "prettier --write .",
 		"format": "run-s format:*",
 		"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",
@@ -119,11 +119,14 @@
 					"@typescript-eslint/no-unsafe-assignment": 0
 				}
 			}
+		],
+		"ignore": [
+			"test/external"
 		]
 	},
 	"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 "
+		"{source,test}/**/*.ts": "xo --fix",
+		"**/*.{json,yaml,md}": "prettier --write "
 	}
 }