hono-rate-limiter 0.2.3 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![tests](https://img.shields.io/github/actions/workflow/status/rhinobase/hono-rate-limiter/test.yaml)](https://github.com/rhinobase/hono-rate-limiter/actions/workflows/test.yaml)
+[![tests](https://img.shields.io/github/actions/workflow/status/rhinobase/hono-rate-limiter/test.yml)](https://github.com/rhinobase/hono-rate-limiter/actions/workflows/test.yml)
 [![npm version](https://img.shields.io/npm/v/hono-rate-limiter.svg)](https://npmjs.org/package/hono-rate-limiter "View this project on NPM")
 [![npm downloads](https://img.shields.io/npm/dm/hono-rate-limiter)](https://www.npmjs.com/package/hono-rate-limiter)
 [![license](https://img.shields.io/npm/l/hono-rate-limiter)](LICENSE)
@@ -12,8 +12,8 @@
 Rate limiting middleware for [Hono](https://hono.dev/). Use to
 limit repeated requests to public APIs and/or endpoints such as password reset.
 
-> [!WARNING]  
-> The `keyGenerator` function is currently under construction and needs to be defined for `hono-rate-limiter` to work properly in your environment. Please ensure that you define the `keyGenerator` function according to the documentation before using the library.
+> [!NOTE]  
+> The `keyGenerator` function needs to be defined for `hono-rate-limiter` to work properly in your environment. Please ensure that you define the `keyGenerator` function according to the documentation before using the library.
 
 ## Usage
 
@@ -56,6 +56,11 @@ Here is a list of stores:
 
 Take a look at this [guide](https://express-rate-limit.mintlify.app/guides/creating-a-store) if you wish to create your own store.
 
+## Notes
+
+- The `keyGenerator` function determines what to limit a request on, it should represent a unique characteristic of a user or class of user that you wish to rate limit. Good choices include API keys in `Authorization` headers, URL paths or routes, specific query parameters used by your application, and/or user IDs.
+- It is not recommended to use IP addresses (since these can be shared by many users in many valid cases) or locations (the same), as you may find yourself unintentionally rate limiting a wider group of users than you intended.
+
 ## Contributing
 
 We would love to have more contributors involved!

package/index.cjs.js

@@ -10,6 +10,6 @@ class MemoryStore{init(options){this.windowMs=options.windowMs;if(this.interval)
 
 const isValidStore=value=>!!value?.increment;
 
-function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator=c=>c.req.header("cf-connecting-ip")??"",skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implmented!");if(typeof store.init==="function")store.init(options);return factory.createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
+function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implmented!");if(typeof store.init==="function")store.init(options);return factory.createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
 
 exports.rateLimiter = rateLimiter;

package/index.esm.js

@@ -6,6 +6,6 @@ class MemoryStore{init(options){this.windowMs=options.windowMs;if(this.interval)
 
 const isValidStore=value=>!!value?.increment;
 
-function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator=c=>c.req.header("cf-connecting-ip")??"",skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implmented!");if(typeof store.init==="function")store.init(options);return createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
+function rateLimiter(config){const{windowMs=6e4,limit=5,message="Too many requests, please try again later.",statusCode=429,standardHeaders="draft-6",requestPropertyName="rateLimit",requestStorePropertyName="rateLimitStore",skipFailedRequests=false,skipSuccessfulRequests=false,keyGenerator,skip=()=>false,requestWasSuccessful=c=>c.res.status<400,handler=async(c,_next,options)=>{c.status(options.statusCode);const responseMessage=typeof options.message==="function"?await options.message(c):options.message;if(typeof responseMessage==="string")return c.text(responseMessage);return c.json(responseMessage)},store=new MemoryStore}=config??{};const options={windowMs,limit,message,statusCode,standardHeaders,requestPropertyName,requestStorePropertyName,skipFailedRequests,skipSuccessfulRequests,keyGenerator,skip,requestWasSuccessful,handler,store};if(!isValidStore(store))throw new Error("The store is not correctly implmented!");if(typeof store.init==="function")store.init(options);return createMiddleware(async(c,next)=>{const isSkippable=await skip(c);if(isSkippable){await next();return}const key=await keyGenerator(c);const{totalHits,resetTime}=await store.increment(key);const retrieveLimit=typeof limit==="function"?limit(c):limit;const _limit=await retrieveLimit;const info={limit:_limit,used:totalHits,remaining:Math.max(_limit-totalHits,0),resetTime};c.set(requestPropertyName,info);c.set(requestStorePropertyName,{getKey:store.get?.bind(store),resetKey:store.resetKey.bind(store)});if(standardHeaders&&!c.finalized){if(standardHeaders==="draft-7"){setDraft7Headers(c,info,windowMs);}else {setDraft6Headers(c,info,windowMs);}}let decremented=false;const decrementKey=async()=>{if(!decremented){await store.decrement(key);decremented=true;}};const shouldSkipRequest=async()=>{if(skipFailedRequests||skipSuccessfulRequests){const wasRequestSuccessful=await requestWasSuccessful(c);if(skipFailedRequests&&!wasRequestSuccessful||skipSuccessfulRequests&&wasRequestSuccessful)await decrementKey();}};if(totalHits>_limit){if(standardHeaders){setRetryAfterHeader(c,info,windowMs);}await shouldSkipRequest();return handler(c,next,options)}try{await next();await shouldSkipRequest();}catch(error){if(skipFailedRequests)await decrementKey();}finally{if(!c.finalized)await decrementKey();}})}
 
 export { rateLimiter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-rate-limiter",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "license": "MIT",
   "keywords": [
     "hono",

package/src/core.d.ts

@@ -10,4 +10,4 @@ import type { ConfigType } from "./types";
  *
  * @public
  */
-export declare function rateLimiter<E extends Env = Env, P extends string = string, I extends Input = Input>(config?: Partial<ConfigType<E, P, I>>): import("hono").MiddlewareHandler<E, P, I>;
+export declare function rateLimiter<E extends Env = Env, P extends string = string, I extends Input = Input>(config: Pick<ConfigType<E, P, I>, "keyGenerator"> & Partial<Omit<ConfigType<E, P, I>, "keyGenerator">>): import("hono").MiddlewareHandler<E, P, I>;

package/src/index.d.ts

@@ -1,2 +1,2 @@
 export { rateLimiter } from "./core";
-export * from "./types";
+export type * from "./types";

package/src/{memoryStore.d.ts → store.d.ts}

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+import type { Env, Input } from "hono/types";
 import type { ClientRateLimitInfo, ConfigType, Store } from "./types";
 /**
  * The record that stores information about a client - namely, how many times
@@ -15,7 +16,7 @@ type Client = {
  *
  * @public
  */
-export declare class MemoryStore implements Store {
+export declare class MemoryStore<E extends Env = Env, P extends string = string, I extends Input = Input> implements Store<E, P, I> {
     /**
      * The duration of time before which all hit counts are reset (in milliseconds).
      */
@@ -46,7 +47,7 @@ export declare class MemoryStore implements Store {
      *
      * @param options {ConfigType} - The options used to setup the middleware.
      */
-    init(options: ConfigType): void;
+    init(options: ConfigType<E, P, I>): void;
     /**
      * Method to fetch a client's hit count and reset time.
      *

package/src/types.d.ts

@@ -36,11 +36,11 @@ export type RateLimitInfo = {
  * @param next {Next} - The Hono `next` function, can be called to skip responding.
  * @param optionsUsed {ConfigType} - The options used to set up the middleware.
  */
-export type RateLimitExceededEventHandler<E extends Env = any, P extends string = any, I extends Input = NonNullable<unknown>> = (c: Context<E, P, I>, next: Next, optionsUsed: ConfigType<E, P, I>) => void;
+export type RateLimitExceededEventHandler<E extends Env = Env, P extends string = string, I extends Input = Input> = (c: Context<E, P, I>, next: Next, optionsUsed: ConfigType<E, P, I>) => void;
 /**
  * The configuration options for the rate limiter.
  */
-export type ConfigType<E extends Env = any, P extends string = any, I extends Input = NonNullable<unknown>> = {
+export type ConfigType<E extends Env = Env, P extends string = string, I extends Input = Input> = {
     /**
      * How long we should remember the requests.
      *
@@ -134,20 +134,20 @@ export type ConfigType<E extends Env = any, P extends string = any, I extends In
      *
      * By default, the built-in `MemoryStore` will be used.
      */
-    store: Store;
+    store: Store<E, P, I>;
 };
 export type IncrementResponse = ClientRateLimitInfo;
 /**
  * An interface that all hit counter stores must implement.
  */
-export type Store = {
+export type Store<E extends Env = Env, P extends string = string, I extends Input = Input> = {
     /**
      * Method that initializes the store, and has access to the options passed to
      * the middleware too.
      *
      * @param options {ConfigType} - The options used to setup the middleware.
      */
-    init?: (options: ConfigType) => void;
+    init?: (options: ConfigType<E, P, I>) => void;
     /**
      * Method to fetch a client's hit count and reset time.
      *

package/src/validations.d.ts

@@ -1,2 +1,3 @@
+import type { Env, Input } from "hono/types";
 import type { Store } from "./types";
-export declare const isValidStore: (value: Store) => value is Store;
+export declare const isValidStore: <E extends Env = Env, P extends string = string, I extends Input = Input>(value: Store<E, P, I>) => value is Store<E, P, I>;