@geekmidas/rate-limit 10.0.0-alpha.99 → 10.0.0

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# @geekmidas/rate-limit
+
+## 10.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @geekmidas/cache@10.0.0
+  - @geekmidas/logger@10.0.0
+  - @geekmidas/services@10.0.0
+
+## 9.0.2
+
+### Patch Changes
+
+- [#12](https://github.com/geekmidas/toolbox/pull/12) [`d53863a`](https://github.com/geekmidas/toolbox/commit/d53863a84db2e4ab5420e08f79128b637043fc42) Thanks [@geekmidas](https://github.com/geekmidas)! - Align every published package on a single version and keep them in step.
+
+  All packages now share one version, enforced by a changesets `fixed` group. The
+  baseline is 9.0.1 — @geekmidas/client's published version — so nothing moves
+  backwards; this release takes the whole set to 9.0.2 together.
+
+  Independent versions made "which version of the docs applies to me"
+  unanswerable: a reader on constructs@7 and cli@2 was on no version at all. One
+  number per release makes versioned documentation possible, and lets 9 freeze as
+  the current paradigm while the constructs rework is developed against it.
+
+  Every release now publishes every package, and a major anywhere is a major
+  everywhere. Peer ranges get simpler in return.
+
+- Updated dependencies [[`d53863a`](https://github.com/geekmidas/toolbox/commit/d53863a84db2e4ab5420e08f79128b637043fc42)]:
+  - @geekmidas/cache@9.0.2
+  - @geekmidas/logger@9.0.2
+  - @geekmidas/services@9.0.2
+
+## 4.0.1
+
+### Patch Changes
+
+- 🐛 [#11](https://github.com/geekmidas/toolbox/pull/11) [`40f4dc0`](https://github.com/geekmidas/toolbox/commit/40f4dc095911b2223a255029d8f776caf7781309) Thanks [@geekmidas](https://github.com/geekmidas)! - Patch release across all packages to realign published versions with the
+  registry. The previous release only published the four packages that had
+  version bumps; the remaining packages failed with "cannot publish over the
+  previously published versions" because their versions were unchanged.
+- Updated dependencies [[`40f4dc0`](https://github.com/geekmidas/toolbox/commit/40f4dc095911b2223a255029d8f776caf7781309)]:
+  - @geekmidas/cache@1.1.2
+  - @geekmidas/logger@1.0.3
+  - @geekmidas/services@2.0.1
+
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @geekmidas/services@2.0.0
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`811d740`](https://github.com/geekmidas/toolbox/commit/811d740ae3875d59ad1b0dc50261266963c8cb76)]:
+  - @geekmidas/services@1.1.0
+
+## 2.0.1
+
+### Patch Changes
+
+- 🐛 [`d70c6c0`](https://github.com/geekmidas/toolbox/commit/d70c6c0aeb8a79da2473ac77dbd8255a4a2f5651) Thanks [@geekmidas](https://github.com/geekmidas)! - Fix `package.json` exports so TypeScript declarations resolve correctly under NodeNext/Bundler module resolution. Each subpath export now nests `types` inside its `import`/`require` condition, pointing at the `.d.mts` and `.d.cts` files that `tsdown` actually emits (previously the exports referenced non-existent `.d.ts` files, causing type-resolution failures for consumers). Both ESM (`.mjs`) and CJS (`.cjs`) runtime entry points are preserved. Additionally, `@geekmidas/ui` had `import` paths pointing at `.js` files that were never emitted — those are corrected to `.mjs`.
+
+- Updated dependencies [[`d70c6c0`](https://github.com/geekmidas/toolbox/commit/d70c6c0aeb8a79da2473ac77dbd8255a4a2f5651)]:
+  - @geekmidas/cache@1.1.1
+  - @geekmidas/logger@1.0.2
+  - @geekmidas/services@1.0.2
+
+## 2.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`be4f7a9`](https://github.com/geekmidas/toolbox/commit/be4f7a9bd5de7f08adbca582916d6902e0c24de2)]:
+  - @geekmidas/cache@1.1.0
+
+## 1.0.0
+
+### Major Changes
+
+- [`ff7b115`](https://github.com/geekmidas/toolbox/commit/ff7b11599f60f84ac6cdc73714c853ecf786b2e8) Thanks [@geekmidas](https://github.com/geekmidas)! - Version 1 Stable release
+
+### Patch Changes
+
+- Updated dependencies [[`ff7b115`](https://github.com/geekmidas/toolbox/commit/ff7b11599f60f84ac6cdc73714c853ecf786b2e8)]:
+  - @geekmidas/cache@1.0.0
+  - @geekmidas/logger@1.0.0
+  - @geekmidas/services@1.0.0

package/README.md

@@ -58,11 +58,11 @@ try {
 Rate limiting is built into the constructs package:
 
 ```typescript
-import { api } from '../constructs/api';
+import { e } from '@geekmidas/constructs/endpoints';
 import { InMemoryCache } from '@geekmidas/cache/memory';
 import { z } from 'zod';
 
-export const sendMessage = api
+export const sendMessage = e
   .post('/api/messages')
   .rateLimit({
     limit: 10,                    // 10 requests
@@ -347,7 +347,7 @@ try {
 
 ```typescript
 // Strict limit for auth endpoints
-export const login = api
+export const login = e
   .post('/auth/login')
   .rateLimit({
     limit: 5,
@@ -360,7 +360,7 @@ export const login = api
   });
 
 // Generous limit for read endpoints
-export const getUsers = api
+export const getUsers = e
   .get('/users')
   .rateLimit({
     limit: 1000,

package/dist/index.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
 //#region src/index.ts
 /**
 * Error thrown when rate limit is exceeded
@@ -30,13 +30,15 @@ async function checkRateLimit(config, ctx) {
 		resetTime: Date.now() + config.windowMs,
 		retryAfter: config.windowMs
 	};
-	const key = await (config.keyGenerator || defaultKeyGenerator)(ctx);
+	const keyGenerator = config.keyGenerator || defaultKeyGenerator;
+	const key = await keyGenerator(ctx);
 	const now = Date.now();
 	let data = await config.cache.get(key);
 	if (!data || data.resetTime <= now) {
+		const resetTime = now + config.windowMs;
 		data = {
 			count: 1,
-			resetTime: now + config.windowMs
+			resetTime
 		};
 		const ttlSeconds = Math.ceil(config.windowMs / 1e3);
 		await config.cache.set(key, data, ttlSeconds);
@@ -77,10 +79,10 @@ function getRateLimitHeaders(info, config) {
 	if (info.remaining === 0) headers["Retry-After"] = Math.ceil(info.retryAfter / 1e3).toString();
 	return headers;
 }
+
 //#endregion
 exports.TooManyRequestsError = TooManyRequestsError;
 exports.checkRateLimit = checkRateLimit;
 exports.defaultKeyGenerator = defaultKeyGenerator;
 exports.getRateLimitHeaders = getRateLimitHeaders;
-
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Cache } from '@geekmidas/cache';\nimport type { Logger } from '@geekmidas/logger';\nimport type { Service, ServiceRecord } from '@geekmidas/services';\n\n/**\n * Error thrown when rate limit is exceeded\n */\nexport class TooManyRequestsError extends Error {\n\tpublic readonly statusCode = 429;\n\tpublic readonly retryAfter?: number;\n\n\tconstructor(message?: string, retryAfter?: number) {\n\t\tsuper(message || 'Too many requests, please try again later.');\n\t\tthis.name = 'TooManyRequestsError';\n\t\tthis.retryAfter = retryAfter;\n\t}\n}\n\n/**\n * Rate limit configuration for an endpoint\n */\nexport interface RateLimitConfig {\n\t/**\n\t * Maximum number of requests allowed in the window\n\t */\n\tlimit: number;\n\n\t/**\n\t * Time window in milliseconds\n\t */\n\twindowMs: number;\n\n\t/**\n\t * Cache instance to store rate limit data\n\t */\n\tcache: Cache;\n\n\t/**\n\t * Key generator function to identify clients\n\t * Defaults to using IP address\n\t */\n\tkeyGenerator?: RateLimitKeyGenerator;\n\n\t/**\n\t * Skip rate limiting for certain requests\n\t */\n\tskip?: RateLimitSkipFn;\n\n\t/**\n\t * Optional message to return when rate limit is exceeded\n\t */\n\tmessage?: string;\n\n\t/**\n\t * Optional custom handler when rate limit is exceeded\n\t */\n\thandler?: RateLimitExceededHandler;\n\n\t/**\n\t * Whether to include rate limit headers in response\n\t * @default true\n\t */\n\tstandardHeaders?: boolean;\n\n\t/**\n\t * Whether to include legacy rate limit headers\n\t * @default false\n\t */\n\tlegacyHeaders?: boolean;\n}\n\n/**\n * Context for rate limiting decisions\n */\nexport interface RateLimitContext<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> {\n\theader: (key: string) => string | undefined;\n\tservices: ServiceRecord<TServices>;\n\tlogger: TLogger;\n\tsession: TSession;\n\tpath: string;\n\tmethod: string;\n}\n\n/**\n * Function to generate a unique key for rate limiting\n */\nexport type RateLimitKeyGenerator<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => string | Promise<string>;\n\n/**\n * Function to determine if rate limiting should be skipped\n */\nexport type RateLimitSkipFn<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => boolean | Promise<boolean>;\n\n/**\n * Handler for when rate limit is exceeded\n */\nexport type RateLimitExceededHandler<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n\tinfo: RateLimitInfo,\n) => void | Promise<void>;\n\n/**\n * Information about current rate limit status\n */\nexport interface RateLimitInfo {\n\t/**\n\t * Current request count in the window\n\t */\n\tcount: number;\n\n\t/**\n\t * Maximum allowed requests\n\t */\n\tlimit: number;\n\n\t/**\n\t * Remaining requests allowed\n\t */\n\tremaining: number;\n\n\t/**\n\t * Time when the window resets (Unix timestamp)\n\t */\n\tresetTime: number;\n\n\t/**\n\t * Time until reset in milliseconds\n\t */\n\tretryAfter: number;\n}\n\n/**\n * Headers to be set on responses\n */\nexport interface RateLimitHeaders {\n\t'X-RateLimit-Limit'?: string;\n\t'X-RateLimit-Remaining'?: string;\n\t'X-RateLimit-Reset'?: string;\n\t'Retry-After'?: string;\n\t'X-RateLimit-Retry-After'?: string;\n\t'X-RateLimit-Reset-After'?: string;\n}\n\n/**\n * Data stored in cache for rate limiting\n */\nexport interface RateLimitData {\n\tcount: number;\n\tresetTime: number;\n}\n\n/**\n * Default key generator using IP address\n */\nexport const defaultKeyGenerator: RateLimitKeyGenerator = (ctx) => {\n\t// Try various headers for IP address\n\tconst ip =\n\t\tctx.header('x-forwarded-for')?.split(',')[0]?.trim() ||\n\t\tctx.header('x-real-ip') ||\n\t\tctx.header('x-client-ip') ||\n\t\tctx.header('cf-connecting-ip') ||\n\t\t'unknown';\n\n\treturn `rate-limit:${ctx.method}:${ctx.path}:${ip}`;\n};\n\n/**\n * Check rate limit and throw error if exceeded\n */\nexport async function checkRateLimit<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n>(\n\tconfig: RateLimitConfig,\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n): Promise<RateLimitInfo> {\n\t// Check if we should skip rate limiting\n\tif (config.skip && (await config.skip(ctx))) {\n\t\treturn {\n\t\t\tcount: 0,\n\t\t\tlimit: config.limit,\n\t\t\tremaining: config.limit,\n\t\t\tresetTime: Date.now() + config.windowMs,\n\t\t\tretryAfter: config.windowMs,\n\t\t};\n\t}\n\n\t// Generate key for this request\n\tconst keyGenerator = config.keyGenerator || defaultKeyGenerator;\n\tconst key = await keyGenerator(ctx);\n\n\t// Get current data from cache\n\tconst now = Date.now();\n\tlet data = await config.cache.get<RateLimitData>(key);\n\n\t// If no data or window expired, create new entry\n\tif (!data || data.resetTime <= now) {\n\t\tconst resetTime = now + config.windowMs;\n\t\tdata = { count: 1, resetTime };\n\n\t\t// Store with TTL matching the window\n\t\tconst ttlSeconds = Math.ceil(config.windowMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t} else {\n\t\t// Increment count\n\t\tdata.count++;\n\n\t\t// Calculate remaining TTL\n\t\tconst remainingMs = data.resetTime - now;\n\t\tconst ttlSeconds = Math.ceil(remainingMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t}\n\n\t// Calculate rate limit info\n\tconst info: RateLimitInfo = {\n\t\tcount: data.count,\n\t\tlimit: config.limit,\n\t\tremaining: Math.max(0, config.limit - data.count),\n\t\tresetTime: data.resetTime,\n\t\tretryAfter: data.resetTime - now,\n\t};\n\n\t// Check if limit exceeded\n\tif (data.count > config.limit) {\n\t\t// Call custom handler if provided\n\t\tif (config.handler) {\n\t\t\tawait config.handler(ctx, info);\n\t\t}\n\n\t\t// Throw rate limit error\n\t\tconst retryAfterSeconds = Math.ceil(info.retryAfter / 1000);\n\t\tthrow new TooManyRequestsError(\n\t\t\tconfig.message || 'Too many requests, please try again later.',\n\t\t\tretryAfterSeconds,\n\t\t);\n\t}\n\n\treturn info;\n}\n\n/**\n * Generate rate limit headers\n */\nexport function getRateLimitHeaders(\n\tinfo: RateLimitInfo,\n\tconfig: RateLimitConfig,\n): RateLimitHeaders {\n\tconst headers: RateLimitHeaders = {};\n\n\tif (config.standardHeaders !== false) {\n\t\theaders['X-RateLimit-Limit'] = info.limit.toString();\n\t\theaders['X-RateLimit-Remaining'] = info.remaining.toString();\n\t\theaders['X-RateLimit-Reset'] = new Date(info.resetTime).toISOString();\n\t}\n\n\tif (config.legacyHeaders) {\n\t\theaders['X-RateLimit-Retry-After'] = info.retryAfter.toString();\n\t\theaders['X-RateLimit-Reset-After'] = Math.ceil(\n\t\t\tinfo.retryAfter / 1000,\n\t\t).toString();\n\t}\n\n\t// Always set Retry-After when limit is exceeded\n\tif (info.remaining === 0) {\n\t\theaders['Retry-After'] = Math.ceil(info.retryAfter / 1000).toString();\n\t}\n\n\treturn headers;\n}\n"],"mappings":";;;;;AAOA,IAAa,uBAAb,cAA0C,MAAM;CAC/C,aAA6B;CAC7B;CAEA,YAAY,SAAkB,YAAqB;EAClD,MAAM,WAAW,4CAA4C;EAC7D,KAAK,OAAO;EACZ,KAAK,aAAa;CACnB;AACD;;;;AA8JA,MAAa,uBAA8C,QAAQ;CAElE,MAAM,KACL,IAAI,OAAO,iBAAiB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,KACnD,IAAI,OAAO,WAAW,KACtB,IAAI,OAAO,aAAa,KACxB,IAAI,OAAO,kBAAkB,KAC7B;CAED,OAAO,cAAc,IAAI,OAAO,GAAG,IAAI,KAAK,GAAG;AAChD;;;;AAKA,eAAsB,eAKrB,QACA,KACyB;CAEzB,IAAI,OAAO,QAAS,MAAM,OAAO,KAAK,GAAG,GACxC,OAAO;EACN,OAAO;EACP,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,KAAK,IAAI,IAAI,OAAO;EAC/B,YAAY,OAAO;CACpB;CAKD,MAAM,MAAM,OADS,OAAO,gBAAgB,oBAAA,CACb,GAAG;CAGlC,MAAM,MAAM,KAAK,IAAI;CACrB,IAAI,OAAO,MAAM,OAAO,MAAM,IAAmB,GAAG;CAGpD,IAAI,CAAC,QAAQ,KAAK,aAAa,KAAK;EAEnC,OAAO;GAAE,OAAO;GAAG,WADD,MAAM,OAAO;EACF;EAG7B,MAAM,aAAa,KAAK,KAAK,OAAO,WAAW,GAAI;EACnD,MAAM,OAAO,MAAM,IAAI,KAAK,MAAM,UAAU;CAC7C,OAAO;EAEN,KAAK;EAGL,MAAM,cAAc,KAAK,YAAY;EACrC,MAAM,aAAa,KAAK,KAAK,cAAc,GAAI;EAC/C,MAAM,OAAO,MAAM,IAAI,KAAK,MAAM,UAAU;CAC7C;CAGA,MAAM,OAAsB;EAC3B,OAAO,KAAK;EACZ,OAAO,OAAO;EACd,WAAW,KAAK,IAAI,GAAG,OAAO,QAAQ,KAAK,KAAK;EAChD,WAAW,KAAK;EAChB,YAAY,KAAK,YAAY;CAC9B;CAGA,IAAI,KAAK,QAAQ,OAAO,OAAO;EAE9B,IAAI,OAAO,SACV,MAAM,OAAO,QAAQ,KAAK,IAAI;EAI/B,MAAM,oBAAoB,KAAK,KAAK,KAAK,aAAa,GAAI;EAC1D,MAAM,IAAI,qBACT,OAAO,WAAW,8CAClB,iBACD;CACD;CAEA,OAAO;AACR;;;;AAKA,SAAgB,oBACf,MACA,QACmB;CACnB,MAAM,UAA4B,CAAC;CAEnC,IAAI,OAAO,oBAAoB,OAAO;EACrC,QAAQ,uBAAuB,KAAK,MAAM,SAAS;EACnD,QAAQ,2BAA2B,KAAK,UAAU,SAAS;EAC3D,QAAQ,uBAAuB,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,YAAY;CACrE;CAEA,IAAI,OAAO,eAAe;EACzB,QAAQ,6BAA6B,KAAK,WAAW,SAAS;EAC9D,QAAQ,6BAA6B,KAAK,KACzC,KAAK,aAAa,GACnB,CAAC,CAAC,SAAS;CACZ;CAGA,IAAI,KAAK,cAAc,GACtB,QAAQ,iBAAiB,KAAK,KAAK,KAAK,aAAa,GAAI,CAAC,CAAC,SAAS;CAGrE,OAAO;AACR"}
+{"version":3,"file":"index.cjs","names":["message?: string","retryAfter?: number","defaultKeyGenerator: RateLimitKeyGenerator","config: RateLimitConfig","ctx: RateLimitContext<TServices, TLogger, TSession>","info: RateLimitInfo","headers: RateLimitHeaders"],"sources":["../src/index.ts"],"sourcesContent":["import type { Cache } from '@geekmidas/cache';\nimport type { Logger } from '@geekmidas/logger';\nimport type { Service, ServiceRecord } from '@geekmidas/services';\n\n/**\n * Error thrown when rate limit is exceeded\n */\nexport class TooManyRequestsError extends Error {\n\tpublic readonly statusCode = 429;\n\tpublic readonly retryAfter?: number;\n\n\tconstructor(message?: string, retryAfter?: number) {\n\t\tsuper(message || 'Too many requests, please try again later.');\n\t\tthis.name = 'TooManyRequestsError';\n\t\tthis.retryAfter = retryAfter;\n\t}\n}\n\n/**\n * Rate limit configuration for an endpoint\n */\nexport interface RateLimitConfig {\n\t/**\n\t * Maximum number of requests allowed in the window\n\t */\n\tlimit: number;\n\n\t/**\n\t * Time window in milliseconds\n\t */\n\twindowMs: number;\n\n\t/**\n\t * Cache instance to store rate limit data\n\t */\n\tcache: Cache;\n\n\t/**\n\t * Key generator function to identify clients\n\t * Defaults to using IP address\n\t */\n\tkeyGenerator?: RateLimitKeyGenerator;\n\n\t/**\n\t * Skip rate limiting for certain requests\n\t */\n\tskip?: RateLimitSkipFn;\n\n\t/**\n\t * Optional message to return when rate limit is exceeded\n\t */\n\tmessage?: string;\n\n\t/**\n\t * Optional custom handler when rate limit is exceeded\n\t */\n\thandler?: RateLimitExceededHandler;\n\n\t/**\n\t * Whether to include rate limit headers in response\n\t * @default true\n\t */\n\tstandardHeaders?: boolean;\n\n\t/**\n\t * Whether to include legacy rate limit headers\n\t * @default false\n\t */\n\tlegacyHeaders?: boolean;\n}\n\n/**\n * Context for rate limiting decisions\n */\nexport interface RateLimitContext<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> {\n\theader: (key: string) => string | undefined;\n\tservices: ServiceRecord<TServices>;\n\tlogger: TLogger;\n\tsession: TSession;\n\tpath: string;\n\tmethod: string;\n}\n\n/**\n * Function to generate a unique key for rate limiting\n */\nexport type RateLimitKeyGenerator<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => string | Promise<string>;\n\n/**\n * Function to determine if rate limiting should be skipped\n */\nexport type RateLimitSkipFn<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => boolean | Promise<boolean>;\n\n/**\n * Handler for when rate limit is exceeded\n */\nexport type RateLimitExceededHandler<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n\tinfo: RateLimitInfo,\n) => void | Promise<void>;\n\n/**\n * Information about current rate limit status\n */\nexport interface RateLimitInfo {\n\t/**\n\t * Current request count in the window\n\t */\n\tcount: number;\n\n\t/**\n\t * Maximum allowed requests\n\t */\n\tlimit: number;\n\n\t/**\n\t * Remaining requests allowed\n\t */\n\tremaining: number;\n\n\t/**\n\t * Time when the window resets (Unix timestamp)\n\t */\n\tresetTime: number;\n\n\t/**\n\t * Time until reset in milliseconds\n\t */\n\tretryAfter: number;\n}\n\n/**\n * Headers to be set on responses\n */\nexport interface RateLimitHeaders {\n\t'X-RateLimit-Limit'?: string;\n\t'X-RateLimit-Remaining'?: string;\n\t'X-RateLimit-Reset'?: string;\n\t'Retry-After'?: string;\n\t'X-RateLimit-Retry-After'?: string;\n\t'X-RateLimit-Reset-After'?: string;\n}\n\n/**\n * Data stored in cache for rate limiting\n */\nexport interface RateLimitData {\n\tcount: number;\n\tresetTime: number;\n}\n\n/**\n * Default key generator using IP address\n */\nexport const defaultKeyGenerator: RateLimitKeyGenerator = (ctx) => {\n\t// Try various headers for IP address\n\tconst ip =\n\t\tctx.header('x-forwarded-for')?.split(',')[0]?.trim() ||\n\t\tctx.header('x-real-ip') ||\n\t\tctx.header('x-client-ip') ||\n\t\tctx.header('cf-connecting-ip') ||\n\t\t'unknown';\n\n\treturn `rate-limit:${ctx.method}:${ctx.path}:${ip}`;\n};\n\n/**\n * Check rate limit and throw error if exceeded\n */\nexport async function checkRateLimit<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n>(\n\tconfig: RateLimitConfig,\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n): Promise<RateLimitInfo> {\n\t// Check if we should skip rate limiting\n\tif (config.skip && (await config.skip(ctx))) {\n\t\treturn {\n\t\t\tcount: 0,\n\t\t\tlimit: config.limit,\n\t\t\tremaining: config.limit,\n\t\t\tresetTime: Date.now() + config.windowMs,\n\t\t\tretryAfter: config.windowMs,\n\t\t};\n\t}\n\n\t// Generate key for this request\n\tconst keyGenerator = config.keyGenerator || defaultKeyGenerator;\n\tconst key = await keyGenerator(ctx);\n\n\t// Get current data from cache\n\tconst now = Date.now();\n\tlet data = await config.cache.get<RateLimitData>(key);\n\n\t// If no data or window expired, create new entry\n\tif (!data || data.resetTime <= now) {\n\t\tconst resetTime = now + config.windowMs;\n\t\tdata = { count: 1, resetTime };\n\n\t\t// Store with TTL matching the window\n\t\tconst ttlSeconds = Math.ceil(config.windowMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t} else {\n\t\t// Increment count\n\t\tdata.count++;\n\n\t\t// Calculate remaining TTL\n\t\tconst remainingMs = data.resetTime - now;\n\t\tconst ttlSeconds = Math.ceil(remainingMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t}\n\n\t// Calculate rate limit info\n\tconst info: RateLimitInfo = {\n\t\tcount: data.count,\n\t\tlimit: config.limit,\n\t\tremaining: Math.max(0, config.limit - data.count),\n\t\tresetTime: data.resetTime,\n\t\tretryAfter: data.resetTime - now,\n\t};\n\n\t// Check if limit exceeded\n\tif (data.count > config.limit) {\n\t\t// Call custom handler if provided\n\t\tif (config.handler) {\n\t\t\tawait config.handler(ctx, info);\n\t\t}\n\n\t\t// Throw rate limit error\n\t\tconst retryAfterSeconds = Math.ceil(info.retryAfter / 1000);\n\t\tthrow new TooManyRequestsError(\n\t\t\tconfig.message || 'Too many requests, please try again later.',\n\t\t\tretryAfterSeconds,\n\t\t);\n\t}\n\n\treturn info;\n}\n\n/**\n * Generate rate limit headers\n */\nexport function getRateLimitHeaders(\n\tinfo: RateLimitInfo,\n\tconfig: RateLimitConfig,\n): RateLimitHeaders {\n\tconst headers: RateLimitHeaders = {};\n\n\tif (config.standardHeaders !== false) {\n\t\theaders['X-RateLimit-Limit'] = info.limit.toString();\n\t\theaders['X-RateLimit-Remaining'] = info.remaining.toString();\n\t\theaders['X-RateLimit-Reset'] = new Date(info.resetTime).toISOString();\n\t}\n\n\tif (config.legacyHeaders) {\n\t\theaders['X-RateLimit-Retry-After'] = info.retryAfter.toString();\n\t\theaders['X-RateLimit-Reset-After'] = Math.ceil(\n\t\t\tinfo.retryAfter / 1000,\n\t\t).toString();\n\t}\n\n\t// Always set Retry-After when limit is exceeded\n\tif (info.remaining === 0) {\n\t\theaders['Retry-After'] = Math.ceil(info.retryAfter / 1000).toString();\n\t}\n\n\treturn headers;\n}\n"],"mappings":";;;;;AAOA,IAAa,uBAAb,cAA0C,MAAM;CAC/C,AAAgB,aAAa;CAC7B,AAAgB;CAEhB,YAAYA,SAAkBC,YAAqB;AAClD,QAAM,WAAW,6CAA6C;AAC9D,OAAK,OAAO;AACZ,OAAK,aAAa;CAClB;AACD;;;;AA8JD,MAAaC,sBAA6C,CAAC,QAAQ;CAElE,MAAM,KACL,IAAI,OAAO,kBAAkB,EAAE,MAAM,IAAI,CAAC,IAAI,MAAM,IACpD,IAAI,OAAO,YAAY,IACvB,IAAI,OAAO,cAAc,IACzB,IAAI,OAAO,mBAAmB,IAC9B;AAED,SAAQ,aAAa,IAAI,OAAO,GAAG,IAAI,KAAK,GAAG,GAAG;AAClD;;;;AAKD,eAAsB,eAKrBC,QACAC,KACyB;AAEzB,KAAI,OAAO,QAAS,MAAM,OAAO,KAAK,IAAI,CACzC,QAAO;EACN,OAAO;EACP,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,KAAK,KAAK,GAAG,OAAO;EAC/B,YAAY,OAAO;CACnB;CAIF,MAAM,eAAe,OAAO,gBAAgB;CAC5C,MAAM,MAAM,MAAM,aAAa,IAAI;CAGnC,MAAM,MAAM,KAAK,KAAK;CACtB,IAAI,OAAO,MAAM,OAAO,MAAM,IAAmB,IAAI;AAGrD,MAAK,QAAQ,KAAK,aAAa,KAAK;EACnC,MAAM,YAAY,MAAM,OAAO;AAC/B,SAAO;GAAE,OAAO;GAAG;EAAW;EAG9B,MAAM,aAAa,KAAK,KAAK,OAAO,WAAW,IAAK;AACpD,QAAM,OAAO,MAAM,IAAI,KAAK,MAAM,WAAW;CAC7C,OAAM;AAEN,OAAK;EAGL,MAAM,cAAc,KAAK,YAAY;EACrC,MAAM,aAAa,KAAK,KAAK,cAAc,IAAK;AAChD,QAAM,OAAO,MAAM,IAAI,KAAK,MAAM,WAAW;CAC7C;CAGD,MAAMC,OAAsB;EAC3B,OAAO,KAAK;EACZ,OAAO,OAAO;EACd,WAAW,KAAK,IAAI,GAAG,OAAO,QAAQ,KAAK,MAAM;EACjD,WAAW,KAAK;EAChB,YAAY,KAAK,YAAY;CAC7B;AAGD,KAAI,KAAK,QAAQ,OAAO,OAAO;AAE9B,MAAI,OAAO,QACV,OAAM,OAAO,QAAQ,KAAK,KAAK;EAIhC,MAAM,oBAAoB,KAAK,KAAK,KAAK,aAAa,IAAK;AAC3D,QAAM,IAAI,qBACT,OAAO,WAAW,8CAClB;CAED;AAED,QAAO;AACP;;;;AAKD,SAAgB,oBACfA,MACAF,QACmB;CACnB,MAAMG,UAA4B,CAAE;AAEpC,KAAI,OAAO,oBAAoB,OAAO;AACrC,UAAQ,uBAAuB,KAAK,MAAM,UAAU;AACpD,UAAQ,2BAA2B,KAAK,UAAU,UAAU;AAC5D,UAAQ,uBAAuB,IAAI,KAAK,KAAK,WAAW,aAAa;CACrE;AAED,KAAI,OAAO,eAAe;AACzB,UAAQ,6BAA6B,KAAK,WAAW,UAAU;AAC/D,UAAQ,6BAA6B,KAAK,KACzC,KAAK,aAAa,IAClB,CAAC,UAAU;CACZ;AAGD,KAAI,KAAK,cAAc,EACtB,SAAQ,iBAAiB,KAAK,KAAK,KAAK,aAAa,IAAK,CAAC,UAAU;AAGtE,QAAO;AACP"}

package/dist/index.d.cts

@@ -1,11 +1,13 @@
 import { Cache } from "@geekmidas/cache";
 import { Logger } from "@geekmidas/logger";
 import { Service, ServiceRecord } from "@geekmidas/services";
+
 //#region src/index.d.ts
+
 /**
  * Error thrown when rate limit is exceeded
  */
-export declare class TooManyRequestsError extends Error {
+declare class TooManyRequestsError extends Error {
   readonly statusCode = 429;
   readonly retryAfter?: number;
   constructor(message?: string, retryAfter?: number);
@@ -13,7 +15,7 @@ export declare class TooManyRequestsError extends Error {
 /**
  * Rate limit configuration for an endpoint
  */
-export interface RateLimitConfig {
+interface RateLimitConfig {
   /**
    * Maximum number of requests allowed in the window
    */
@@ -57,7 +59,7 @@ export interface RateLimitConfig {
 /**
  * Context for rate limiting decisions
  */
-export interface RateLimitContext<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> {
+interface RateLimitContext<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> {
   header: (key: string) => string | undefined;
   services: ServiceRecord<TServices>;
   logger: TLogger;
@@ -68,19 +70,19 @@ export interface RateLimitContext<TServices extends Service[] = [], TLogger exte
 /**
  * Function to generate a unique key for rate limiting
  */
-export type RateLimitKeyGenerator<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => string | Promise<string>;
+type RateLimitKeyGenerator<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => string | Promise<string>;
 /**
  * Function to determine if rate limiting should be skipped
  */
-export type RateLimitSkipFn<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => boolean | Promise<boolean>;
+type RateLimitSkipFn<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => boolean | Promise<boolean>;
 /**
  * Handler for when rate limit is exceeded
  */
-export type RateLimitExceededHandler<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>, info: RateLimitInfo) => void | Promise<void>;
+type RateLimitExceededHandler<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>, info: RateLimitInfo) => void | Promise<void>;
 /**
  * Information about current rate limit status
  */
-export interface RateLimitInfo {
+interface RateLimitInfo {
   /**
    * Current request count in the window
    */
@@ -105,7 +107,7 @@ export interface RateLimitInfo {
 /**
  * Headers to be set on responses
  */
-export interface RateLimitHeaders {
+interface RateLimitHeaders {
   'X-RateLimit-Limit'?: string;
   'X-RateLimit-Remaining'?: string;
   'X-RateLimit-Reset'?: string;
@@ -116,21 +118,23 @@ export interface RateLimitHeaders {
 /**
  * Data stored in cache for rate limiting
  */
-export interface RateLimitData {
+interface RateLimitData {
   count: number;
   resetTime: number;
 }
 /**
  * Default key generator using IP address
  */
-export declare const defaultKeyGenerator: RateLimitKeyGenerator;
+declare const defaultKeyGenerator: RateLimitKeyGenerator;
 /**
  * Check rate limit and throw error if exceeded
  */
-export declare function checkRateLimit<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown>(config: RateLimitConfig, ctx: RateLimitContext<TServices, TLogger, TSession>): Promise<RateLimitInfo>;
+declare function checkRateLimit<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown>(config: RateLimitConfig, ctx: RateLimitContext<TServices, TLogger, TSession>): Promise<RateLimitInfo>;
 /**
  * Generate rate limit headers
  */
-export declare function getRateLimitHeaders(info: RateLimitInfo, config: RateLimitConfig): RateLimitHeaders;
+declare function getRateLimitHeaders(info: RateLimitInfo, config: RateLimitConfig): RateLimitHeaders;
+//# sourceMappingURL=index.d.ts.map
 //#endregion
+export { RateLimitConfig, RateLimitContext, RateLimitData, RateLimitExceededHandler, RateLimitHeaders, RateLimitInfo, RateLimitKeyGenerator, RateLimitSkipFn, TooManyRequestsError, checkRateLimit, defaultKeyGenerator, getRateLimitHeaders };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;qBAOa,6BAA6B;WACzB;WACA;EAEhB,YAAY,kBAAkB;;;;;iBAUd;;;;EAIhB;;;;EAKA;;;;EAKA,OAAO;;;;;EAMP,eAAe;;;;EAKf,OAAO;;;;EAKP;;;;EAKA,UAAU;;;;;EAMV;;;;;EAMA;;;;;iBAMgB,iBAChB,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB;EAEA,SAAS;EACT,UAAU,cAAc;EACxB,QAAQ;EACR,SAAS;EACT;EACA;;;;;YAMW,sBACX,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,uBAEA,KAAK,iBAAiB,WAAW,SAAS,uBAC7B;;;;YAKF,gBACX,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,uBAEA,KAAK,iBAAiB,WAAW,SAAS,wBAC5B;;;;YAKH,yBACX,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,uBAEA,KAAK,iBAAiB,WAAW,SAAS,WAC1C,MAAM,yBACK;;;;iBAKK;;;;EAIhB;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;;iBAMgB;EAChB;EACA;EACA;EACA;EACA;EACA;;;;;iBAMgB;EAChB;EACA;;;;;qBAMY,qBAAqB;;;;wBAeZ,eACrB,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,oBAEA,QAAQ,iBACR,KAAK,iBAAiB,WAAW,SAAS,YACxC,QAAQ;;;;wBAoEK,oBACf,MAAM,eACN,QAAQ,kBACN"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAOA;AAciB,cAdJ,oBAAA,SAA6B,KAAK,CAcf;EAAA,SAAA,UAAA,GAAA,GAAA;EAAA,SAcxB,UAAA,CAAA,EAAA,MAAA;EAAK,WAMG,CAAA,OAAA,CAAA,EAAA,MAAA,EAAA,UAAA,CAAA,EAAA,MAAA;;;AAemB;AAkBnC;AAAiC,UArDhB,eAAA,CAqDgB;EAAA;;;EAED,KAIP,EAAA,MAAA;EAAS;;;EAEhB,QAAA,EAAA,MAAA;EAQN;;;EACc,KACT,EAzDT,KAyDS;EAAM;;;;EAG4B,YAA7C,CAAA,EAtDU,qBAsDV;EAAgB;AACD;AAKrB;EAA2B,IAAA,CAAA,EAvDnB,eAuDmB;EAAA;;;EAEK,OAGT,CAAA,EAAA,MAAA;EAAS;;;EAAV,OACP,CAAA,EAnDJ,wBAmDI;EAAO;AAKtB;;;EAC0B,eACT,CAAA,EAAA,OAAA;EAAM;;;;EAG4B,aAA7C,CAAA,EAAA,OAAA;;;AAEa;AAKnB;AA8BiB,UAhFA,gBAgFgB,CAAA,kBA/Ed,OA+Ec,EAAA,GAAA,EAAA,EAAA,gBA9EhB,MA8EgB,GA9EP,MA8EO,EAAA,WAAA,OAAA,CAAA,CAAA;EAYhB,MAAA,EAAA,CAAA,GAAA,EAAA,MAAa,EAAA,GAAA,MAAA,GAAA,SAAA;EAQjB,QAAA,EA9FF,aAwGV,CAxGwB,SA8FS,CAAA;EAeZ,MAAA,EA5Gb,OA4Ga;EAAc,OAAA,EA3G1B,QA2G0B;EAAA,IACjB,EAAA,MAAA;EAAO,MACT,EAAA,MAAA;;;;;AAI0B,KAzG/B,qBAyG+B,CAAA,kBAxGxB,OAwGwB,EAAA,GAAA,EAAA,EAAA,gBAvG1B,MAuG0B,GAvGjB,MAuGiB,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,GAAA,EApGrC,gBAoGqC,CApGpB,SAoGoB,EApGT,OAoGS,EApGA,QAoGA,CAAA,EAAA,GAAA,MAAA,GAnG7B,OAmG6B,CAAA,MAAA,CAAA;;;;AACjC,KA/FE,eA+FF,CAAA,kBA9FS,OA8FT,EAAA,GAAA,EAAA,EAAA,gBA7FO,MA6FP,GA7FgB,MA6FhB,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,GAAA,EA1FJ,gBA0FI,CA1Fa,SA0Fb,EA1FwB,OA0FxB,EA1FiC,QA0FjC,CAAA,EAAA,GAAA,OAAA,GAzFK,OAyFL,CAAA,OAAA,CAAA;AAoEV;;;AAES,KA1JG,wBA0JH,CAAA,kBAzJU,OAyJV,EAAA,GAAA,EAAA,EAAA,gBAxJQ,MAwJR,GAxJiB,MAwJjB,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,GAAA,EArJH,gBAqJG,CArJc,SAqJd,EArJyB,OAqJzB,EArJkC,QAqJlC,CAAA,EAAA,IAAA,EApJF,aAoJE,EAAA,GAAA,IAAA,GAnJG,OAmJH,CAAA,IAAA,CAAA;;AACU;;UA/IF,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;UA8BA,gBAAA;;;;;;;;;;;UAYA,aAAA;;;;;;;cAQJ,qBAAqB;;;;iBAeZ,iCACH,gCACF,SAAS,oCAGjB,sBACH,iBAAiB,WAAW,SAAS,YACxC,QAAQ;;;;iBAoEK,mBAAA,OACT,uBACE,kBACN"}

package/dist/index.d.mts

@@ -1,11 +1,13 @@
 import { Cache } from "@geekmidas/cache";
 import { Logger } from "@geekmidas/logger";
 import { Service, ServiceRecord } from "@geekmidas/services";
+
 //#region src/index.d.ts
+
 /**
  * Error thrown when rate limit is exceeded
  */
-export declare class TooManyRequestsError extends Error {
+declare class TooManyRequestsError extends Error {
   readonly statusCode = 429;
   readonly retryAfter?: number;
   constructor(message?: string, retryAfter?: number);
@@ -13,7 +15,7 @@ export declare class TooManyRequestsError extends Error {
 /**
  * Rate limit configuration for an endpoint
  */
-export interface RateLimitConfig {
+interface RateLimitConfig {
   /**
    * Maximum number of requests allowed in the window
    */
@@ -57,7 +59,7 @@ export interface RateLimitConfig {
 /**
  * Context for rate limiting decisions
  */
-export interface RateLimitContext<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> {
+interface RateLimitContext<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> {
   header: (key: string) => string | undefined;
   services: ServiceRecord<TServices>;
   logger: TLogger;
@@ -68,19 +70,19 @@ export interface RateLimitContext<TServices extends Service[] = [], TLogger exte
 /**
  * Function to generate a unique key for rate limiting
  */
-export type RateLimitKeyGenerator<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => string | Promise<string>;
+type RateLimitKeyGenerator<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => string | Promise<string>;
 /**
  * Function to determine if rate limiting should be skipped
  */
-export type RateLimitSkipFn<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => boolean | Promise<boolean>;
+type RateLimitSkipFn<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>) => boolean | Promise<boolean>;
 /**
  * Handler for when rate limit is exceeded
  */
-export type RateLimitExceededHandler<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>, info: RateLimitInfo) => void | Promise<void>;
+type RateLimitExceededHandler<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown> = (ctx: RateLimitContext<TServices, TLogger, TSession>, info: RateLimitInfo) => void | Promise<void>;
 /**
  * Information about current rate limit status
  */
-export interface RateLimitInfo {
+interface RateLimitInfo {
   /**
    * Current request count in the window
    */
@@ -105,7 +107,7 @@ export interface RateLimitInfo {
 /**
  * Headers to be set on responses
  */
-export interface RateLimitHeaders {
+interface RateLimitHeaders {
   'X-RateLimit-Limit'?: string;
   'X-RateLimit-Remaining'?: string;
   'X-RateLimit-Reset'?: string;
@@ -116,21 +118,23 @@ export interface RateLimitHeaders {
 /**
  * Data stored in cache for rate limiting
  */
-export interface RateLimitData {
+interface RateLimitData {
   count: number;
   resetTime: number;
 }
 /**
  * Default key generator using IP address
  */
-export declare const defaultKeyGenerator: RateLimitKeyGenerator;
+declare const defaultKeyGenerator: RateLimitKeyGenerator;
 /**
  * Check rate limit and throw error if exceeded
  */
-export declare function checkRateLimit<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown>(config: RateLimitConfig, ctx: RateLimitContext<TServices, TLogger, TSession>): Promise<RateLimitInfo>;
+declare function checkRateLimit<TServices extends Service[] = [], TLogger extends Logger = Logger, TSession = unknown>(config: RateLimitConfig, ctx: RateLimitContext<TServices, TLogger, TSession>): Promise<RateLimitInfo>;
 /**
  * Generate rate limit headers
  */
-export declare function getRateLimitHeaders(info: RateLimitInfo, config: RateLimitConfig): RateLimitHeaders;
+declare function getRateLimitHeaders(info: RateLimitInfo, config: RateLimitConfig): RateLimitHeaders;
+//# sourceMappingURL=index.d.ts.map
 //#endregion
+export { RateLimitConfig, RateLimitContext, RateLimitData, RateLimitExceededHandler, RateLimitHeaders, RateLimitInfo, RateLimitKeyGenerator, RateLimitSkipFn, TooManyRequestsError, checkRateLimit, defaultKeyGenerator, getRateLimitHeaders };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;qBAOa,6BAA6B;WACzB;WACA;EAEhB,YAAY,kBAAkB;;;;;iBAUd;;;;EAIhB;;;;EAKA;;;;EAKA,OAAO;;;;;EAMP,eAAe;;;;EAKf,OAAO;;;;EAKP;;;;EAKA,UAAU;;;;;EAMV;;;;;EAMA;;;;;iBAMgB,iBAChB,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB;EAEA,SAAS;EACT,UAAU,cAAc;EACxB,QAAQ;EACR,SAAS;EACT;EACA;;;;;YAMW,sBACX,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,uBAEA,KAAK,iBAAiB,WAAW,SAAS,uBAC7B;;;;YAKF,gBACX,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,uBAEA,KAAK,iBAAiB,WAAW,SAAS,wBAC5B;;;;YAKH,yBACX,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,uBAEA,KAAK,iBAAiB,WAAW,SAAS,WAC1C,MAAM,yBACK;;;;iBAKK;;;;EAIhB;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;;iBAMgB;EAChB;EACA;EACA;EACA;EACA;EACA;;;;;iBAMgB;EAChB;EACA;;;;;qBAMY,qBAAqB;;;;wBAeZ,eACrB,kBAAkB,gBAClB,gBAAgB,SAAS,QACzB,oBAEA,QAAQ,iBACR,KAAK,iBAAiB,WAAW,SAAS,YACxC,QAAQ;;;;wBAoEK,oBACf,MAAM,eACN,QAAQ,kBACN"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAOA;AAciB,cAdJ,oBAAA,SAA6B,KAAK,CAcf;EAAA,SAAA,UAAA,GAAA,GAAA;EAAA,SAcxB,UAAA,CAAA,EAAA,MAAA;EAAK,WAMG,CAAA,OAAA,CAAA,EAAA,MAAA,EAAA,UAAA,CAAA,EAAA,MAAA;;;AAemB;AAkBnC;AAAiC,UArDhB,eAAA,CAqDgB;EAAA;;;EAED,KAIP,EAAA,MAAA;EAAS;;;EAEhB,QAAA,EAAA,MAAA;EAQN;;;EACc,KACT,EAzDT,KAyDS;EAAM;;;;EAG4B,YAA7C,CAAA,EAtDU,qBAsDV;EAAgB;AACD;AAKrB;EAA2B,IAAA,CAAA,EAvDnB,eAuDmB;EAAA;;;EAEK,OAGT,CAAA,EAAA,MAAA;EAAS;;;EAAV,OACP,CAAA,EAnDJ,wBAmDI;EAAO;AAKtB;;;EAC0B,eACT,CAAA,EAAA,OAAA;EAAM;;;;EAG4B,aAA7C,CAAA,EAAA,OAAA;;;AAEa;AAKnB;AA8BiB,UAhFA,gBAgFgB,CAAA,kBA/Ed,OA+Ec,EAAA,GAAA,EAAA,EAAA,gBA9EhB,MA8EgB,GA9EP,MA8EO,EAAA,WAAA,OAAA,CAAA,CAAA;EAYhB,MAAA,EAAA,CAAA,GAAA,EAAA,MAAa,EAAA,GAAA,MAAA,GAAA,SAAA;EAQjB,QAAA,EA9FF,aAwGV,CAxGwB,SA8FS,CAAA;EAeZ,MAAA,EA5Gb,OA4Ga;EAAc,OAAA,EA3G1B,QA2G0B;EAAA,IACjB,EAAA,MAAA;EAAO,MACT,EAAA,MAAA;;;;;AAI0B,KAzG/B,qBAyG+B,CAAA,kBAxGxB,OAwGwB,EAAA,GAAA,EAAA,EAAA,gBAvG1B,MAuG0B,GAvGjB,MAuGiB,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,GAAA,EApGrC,gBAoGqC,CApGpB,SAoGoB,EApGT,OAoGS,EApGA,QAoGA,CAAA,EAAA,GAAA,MAAA,GAnG7B,OAmG6B,CAAA,MAAA,CAAA;;;;AACjC,KA/FE,eA+FF,CAAA,kBA9FS,OA8FT,EAAA,GAAA,EAAA,EAAA,gBA7FO,MA6FP,GA7FgB,MA6FhB,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,GAAA,EA1FJ,gBA0FI,CA1Fa,SA0Fb,EA1FwB,OA0FxB,EA1FiC,QA0FjC,CAAA,EAAA,GAAA,OAAA,GAzFK,OAyFL,CAAA,OAAA,CAAA;AAoEV;;;AAES,KA1JG,wBA0JH,CAAA,kBAzJU,OAyJV,EAAA,GAAA,EAAA,EAAA,gBAxJQ,MAwJR,GAxJiB,MAwJjB,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,GAAA,EArJH,gBAqJG,CArJc,SAqJd,EArJyB,OAqJzB,EArJkC,QAqJlC,CAAA,EAAA,IAAA,EApJF,aAoJE,EAAA,GAAA,IAAA,GAnJG,OAmJH,CAAA,IAAA,CAAA;;AACU;;UA/IF,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;UA8BA,gBAAA;;;;;;;;;;;UAYA,aAAA;;;;;;;cAQJ,qBAAqB;;;;iBAeZ,iCACH,gCACF,SAAS,oCAGjB,sBACH,iBAAiB,WAAW,SAAS,YACxC,QAAQ;;;;iBAoEK,mBAAA,OACT,uBACE,kBACN"}

package/dist/index.mjs

@@ -29,13 +29,15 @@ async function checkRateLimit(config, ctx) {
 		resetTime: Date.now() + config.windowMs,
 		retryAfter: config.windowMs
 	};
-	const key = await (config.keyGenerator || defaultKeyGenerator)(ctx);
+	const keyGenerator = config.keyGenerator || defaultKeyGenerator;
+	const key = await keyGenerator(ctx);
 	const now = Date.now();
 	let data = await config.cache.get(key);
 	if (!data || data.resetTime <= now) {
+		const resetTime = now + config.windowMs;
 		data = {
 			count: 1,
-			resetTime: now + config.windowMs
+			resetTime
 		};
 		const ttlSeconds = Math.ceil(config.windowMs / 1e3);
 		await config.cache.set(key, data, ttlSeconds);
@@ -76,7 +78,7 @@ function getRateLimitHeaders(info, config) {
 	if (info.remaining === 0) headers["Retry-After"] = Math.ceil(info.retryAfter / 1e3).toString();
 	return headers;
 }
+
 //#endregion
 export { TooManyRequestsError, checkRateLimit, defaultKeyGenerator, getRateLimitHeaders };
-
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Cache } from '@geekmidas/cache';\nimport type { Logger } from '@geekmidas/logger';\nimport type { Service, ServiceRecord } from '@geekmidas/services';\n\n/**\n * Error thrown when rate limit is exceeded\n */\nexport class TooManyRequestsError extends Error {\n\tpublic readonly statusCode = 429;\n\tpublic readonly retryAfter?: number;\n\n\tconstructor(message?: string, retryAfter?: number) {\n\t\tsuper(message || 'Too many requests, please try again later.');\n\t\tthis.name = 'TooManyRequestsError';\n\t\tthis.retryAfter = retryAfter;\n\t}\n}\n\n/**\n * Rate limit configuration for an endpoint\n */\nexport interface RateLimitConfig {\n\t/**\n\t * Maximum number of requests allowed in the window\n\t */\n\tlimit: number;\n\n\t/**\n\t * Time window in milliseconds\n\t */\n\twindowMs: number;\n\n\t/**\n\t * Cache instance to store rate limit data\n\t */\n\tcache: Cache;\n\n\t/**\n\t * Key generator function to identify clients\n\t * Defaults to using IP address\n\t */\n\tkeyGenerator?: RateLimitKeyGenerator;\n\n\t/**\n\t * Skip rate limiting for certain requests\n\t */\n\tskip?: RateLimitSkipFn;\n\n\t/**\n\t * Optional message to return when rate limit is exceeded\n\t */\n\tmessage?: string;\n\n\t/**\n\t * Optional custom handler when rate limit is exceeded\n\t */\n\thandler?: RateLimitExceededHandler;\n\n\t/**\n\t * Whether to include rate limit headers in response\n\t * @default true\n\t */\n\tstandardHeaders?: boolean;\n\n\t/**\n\t * Whether to include legacy rate limit headers\n\t * @default false\n\t */\n\tlegacyHeaders?: boolean;\n}\n\n/**\n * Context for rate limiting decisions\n */\nexport interface RateLimitContext<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> {\n\theader: (key: string) => string | undefined;\n\tservices: ServiceRecord<TServices>;\n\tlogger: TLogger;\n\tsession: TSession;\n\tpath: string;\n\tmethod: string;\n}\n\n/**\n * Function to generate a unique key for rate limiting\n */\nexport type RateLimitKeyGenerator<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => string | Promise<string>;\n\n/**\n * Function to determine if rate limiting should be skipped\n */\nexport type RateLimitSkipFn<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => boolean | Promise<boolean>;\n\n/**\n * Handler for when rate limit is exceeded\n */\nexport type RateLimitExceededHandler<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n\tinfo: RateLimitInfo,\n) => void | Promise<void>;\n\n/**\n * Information about current rate limit status\n */\nexport interface RateLimitInfo {\n\t/**\n\t * Current request count in the window\n\t */\n\tcount: number;\n\n\t/**\n\t * Maximum allowed requests\n\t */\n\tlimit: number;\n\n\t/**\n\t * Remaining requests allowed\n\t */\n\tremaining: number;\n\n\t/**\n\t * Time when the window resets (Unix timestamp)\n\t */\n\tresetTime: number;\n\n\t/**\n\t * Time until reset in milliseconds\n\t */\n\tretryAfter: number;\n}\n\n/**\n * Headers to be set on responses\n */\nexport interface RateLimitHeaders {\n\t'X-RateLimit-Limit'?: string;\n\t'X-RateLimit-Remaining'?: string;\n\t'X-RateLimit-Reset'?: string;\n\t'Retry-After'?: string;\n\t'X-RateLimit-Retry-After'?: string;\n\t'X-RateLimit-Reset-After'?: string;\n}\n\n/**\n * Data stored in cache for rate limiting\n */\nexport interface RateLimitData {\n\tcount: number;\n\tresetTime: number;\n}\n\n/**\n * Default key generator using IP address\n */\nexport const defaultKeyGenerator: RateLimitKeyGenerator = (ctx) => {\n\t// Try various headers for IP address\n\tconst ip =\n\t\tctx.header('x-forwarded-for')?.split(',')[0]?.trim() ||\n\t\tctx.header('x-real-ip') ||\n\t\tctx.header('x-client-ip') ||\n\t\tctx.header('cf-connecting-ip') ||\n\t\t'unknown';\n\n\treturn `rate-limit:${ctx.method}:${ctx.path}:${ip}`;\n};\n\n/**\n * Check rate limit and throw error if exceeded\n */\nexport async function checkRateLimit<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n>(\n\tconfig: RateLimitConfig,\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n): Promise<RateLimitInfo> {\n\t// Check if we should skip rate limiting\n\tif (config.skip && (await config.skip(ctx))) {\n\t\treturn {\n\t\t\tcount: 0,\n\t\t\tlimit: config.limit,\n\t\t\tremaining: config.limit,\n\t\t\tresetTime: Date.now() + config.windowMs,\n\t\t\tretryAfter: config.windowMs,\n\t\t};\n\t}\n\n\t// Generate key for this request\n\tconst keyGenerator = config.keyGenerator || defaultKeyGenerator;\n\tconst key = await keyGenerator(ctx);\n\n\t// Get current data from cache\n\tconst now = Date.now();\n\tlet data = await config.cache.get<RateLimitData>(key);\n\n\t// If no data or window expired, create new entry\n\tif (!data || data.resetTime <= now) {\n\t\tconst resetTime = now + config.windowMs;\n\t\tdata = { count: 1, resetTime };\n\n\t\t// Store with TTL matching the window\n\t\tconst ttlSeconds = Math.ceil(config.windowMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t} else {\n\t\t// Increment count\n\t\tdata.count++;\n\n\t\t// Calculate remaining TTL\n\t\tconst remainingMs = data.resetTime - now;\n\t\tconst ttlSeconds = Math.ceil(remainingMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t}\n\n\t// Calculate rate limit info\n\tconst info: RateLimitInfo = {\n\t\tcount: data.count,\n\t\tlimit: config.limit,\n\t\tremaining: Math.max(0, config.limit - data.count),\n\t\tresetTime: data.resetTime,\n\t\tretryAfter: data.resetTime - now,\n\t};\n\n\t// Check if limit exceeded\n\tif (data.count > config.limit) {\n\t\t// Call custom handler if provided\n\t\tif (config.handler) {\n\t\t\tawait config.handler(ctx, info);\n\t\t}\n\n\t\t// Throw rate limit error\n\t\tconst retryAfterSeconds = Math.ceil(info.retryAfter / 1000);\n\t\tthrow new TooManyRequestsError(\n\t\t\tconfig.message || 'Too many requests, please try again later.',\n\t\t\tretryAfterSeconds,\n\t\t);\n\t}\n\n\treturn info;\n}\n\n/**\n * Generate rate limit headers\n */\nexport function getRateLimitHeaders(\n\tinfo: RateLimitInfo,\n\tconfig: RateLimitConfig,\n): RateLimitHeaders {\n\tconst headers: RateLimitHeaders = {};\n\n\tif (config.standardHeaders !== false) {\n\t\theaders['X-RateLimit-Limit'] = info.limit.toString();\n\t\theaders['X-RateLimit-Remaining'] = info.remaining.toString();\n\t\theaders['X-RateLimit-Reset'] = new Date(info.resetTime).toISOString();\n\t}\n\n\tif (config.legacyHeaders) {\n\t\theaders['X-RateLimit-Retry-After'] = info.retryAfter.toString();\n\t\theaders['X-RateLimit-Reset-After'] = Math.ceil(\n\t\t\tinfo.retryAfter / 1000,\n\t\t).toString();\n\t}\n\n\t// Always set Retry-After when limit is exceeded\n\tif (info.remaining === 0) {\n\t\theaders['Retry-After'] = Math.ceil(info.retryAfter / 1000).toString();\n\t}\n\n\treturn headers;\n}\n"],"mappings":";;;;AAOA,IAAa,uBAAb,cAA0C,MAAM;CAC/C,aAA6B;CAC7B;CAEA,YAAY,SAAkB,YAAqB;EAClD,MAAM,WAAW,4CAA4C;EAC7D,KAAK,OAAO;EACZ,KAAK,aAAa;CACnB;AACD;;;;AA8JA,MAAa,uBAA8C,QAAQ;CAElE,MAAM,KACL,IAAI,OAAO,iBAAiB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,KACnD,IAAI,OAAO,WAAW,KACtB,IAAI,OAAO,aAAa,KACxB,IAAI,OAAO,kBAAkB,KAC7B;CAED,OAAO,cAAc,IAAI,OAAO,GAAG,IAAI,KAAK,GAAG;AAChD;;;;AAKA,eAAsB,eAKrB,QACA,KACyB;CAEzB,IAAI,OAAO,QAAS,MAAM,OAAO,KAAK,GAAG,GACxC,OAAO;EACN,OAAO;EACP,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,KAAK,IAAI,IAAI,OAAO;EAC/B,YAAY,OAAO;CACpB;CAKD,MAAM,MAAM,OADS,OAAO,gBAAgB,oBAAA,CACb,GAAG;CAGlC,MAAM,MAAM,KAAK,IAAI;CACrB,IAAI,OAAO,MAAM,OAAO,MAAM,IAAmB,GAAG;CAGpD,IAAI,CAAC,QAAQ,KAAK,aAAa,KAAK;EAEnC,OAAO;GAAE,OAAO;GAAG,WADD,MAAM,OAAO;EACF;EAG7B,MAAM,aAAa,KAAK,KAAK,OAAO,WAAW,GAAI;EACnD,MAAM,OAAO,MAAM,IAAI,KAAK,MAAM,UAAU;CAC7C,OAAO;EAEN,KAAK;EAGL,MAAM,cAAc,KAAK,YAAY;EACrC,MAAM,aAAa,KAAK,KAAK,cAAc,GAAI;EAC/C,MAAM,OAAO,MAAM,IAAI,KAAK,MAAM,UAAU;CAC7C;CAGA,MAAM,OAAsB;EAC3B,OAAO,KAAK;EACZ,OAAO,OAAO;EACd,WAAW,KAAK,IAAI,GAAG,OAAO,QAAQ,KAAK,KAAK;EAChD,WAAW,KAAK;EAChB,YAAY,KAAK,YAAY;CAC9B;CAGA,IAAI,KAAK,QAAQ,OAAO,OAAO;EAE9B,IAAI,OAAO,SACV,MAAM,OAAO,QAAQ,KAAK,IAAI;EAI/B,MAAM,oBAAoB,KAAK,KAAK,KAAK,aAAa,GAAI;EAC1D,MAAM,IAAI,qBACT,OAAO,WAAW,8CAClB,iBACD;CACD;CAEA,OAAO;AACR;;;;AAKA,SAAgB,oBACf,MACA,QACmB;CACnB,MAAM,UAA4B,CAAC;CAEnC,IAAI,OAAO,oBAAoB,OAAO;EACrC,QAAQ,uBAAuB,KAAK,MAAM,SAAS;EACnD,QAAQ,2BAA2B,KAAK,UAAU,SAAS;EAC3D,QAAQ,uBAAuB,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,YAAY;CACrE;CAEA,IAAI,OAAO,eAAe;EACzB,QAAQ,6BAA6B,KAAK,WAAW,SAAS;EAC9D,QAAQ,6BAA6B,KAAK,KACzC,KAAK,aAAa,GACnB,CAAC,CAAC,SAAS;CACZ;CAGA,IAAI,KAAK,cAAc,GACtB,QAAQ,iBAAiB,KAAK,KAAK,KAAK,aAAa,GAAI,CAAC,CAAC,SAAS;CAGrE,OAAO;AACR"}
+{"version":3,"file":"index.mjs","names":["message?: string","retryAfter?: number","defaultKeyGenerator: RateLimitKeyGenerator","config: RateLimitConfig","ctx: RateLimitContext<TServices, TLogger, TSession>","info: RateLimitInfo","headers: RateLimitHeaders"],"sources":["../src/index.ts"],"sourcesContent":["import type { Cache } from '@geekmidas/cache';\nimport type { Logger } from '@geekmidas/logger';\nimport type { Service, ServiceRecord } from '@geekmidas/services';\n\n/**\n * Error thrown when rate limit is exceeded\n */\nexport class TooManyRequestsError extends Error {\n\tpublic readonly statusCode = 429;\n\tpublic readonly retryAfter?: number;\n\n\tconstructor(message?: string, retryAfter?: number) {\n\t\tsuper(message || 'Too many requests, please try again later.');\n\t\tthis.name = 'TooManyRequestsError';\n\t\tthis.retryAfter = retryAfter;\n\t}\n}\n\n/**\n * Rate limit configuration for an endpoint\n */\nexport interface RateLimitConfig {\n\t/**\n\t * Maximum number of requests allowed in the window\n\t */\n\tlimit: number;\n\n\t/**\n\t * Time window in milliseconds\n\t */\n\twindowMs: number;\n\n\t/**\n\t * Cache instance to store rate limit data\n\t */\n\tcache: Cache;\n\n\t/**\n\t * Key generator function to identify clients\n\t * Defaults to using IP address\n\t */\n\tkeyGenerator?: RateLimitKeyGenerator;\n\n\t/**\n\t * Skip rate limiting for certain requests\n\t */\n\tskip?: RateLimitSkipFn;\n\n\t/**\n\t * Optional message to return when rate limit is exceeded\n\t */\n\tmessage?: string;\n\n\t/**\n\t * Optional custom handler when rate limit is exceeded\n\t */\n\thandler?: RateLimitExceededHandler;\n\n\t/**\n\t * Whether to include rate limit headers in response\n\t * @default true\n\t */\n\tstandardHeaders?: boolean;\n\n\t/**\n\t * Whether to include legacy rate limit headers\n\t * @default false\n\t */\n\tlegacyHeaders?: boolean;\n}\n\n/**\n * Context for rate limiting decisions\n */\nexport interface RateLimitContext<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> {\n\theader: (key: string) => string | undefined;\n\tservices: ServiceRecord<TServices>;\n\tlogger: TLogger;\n\tsession: TSession;\n\tpath: string;\n\tmethod: string;\n}\n\n/**\n * Function to generate a unique key for rate limiting\n */\nexport type RateLimitKeyGenerator<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => string | Promise<string>;\n\n/**\n * Function to determine if rate limiting should be skipped\n */\nexport type RateLimitSkipFn<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n) => boolean | Promise<boolean>;\n\n/**\n * Handler for when rate limit is exceeded\n */\nexport type RateLimitExceededHandler<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n> = (\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n\tinfo: RateLimitInfo,\n) => void | Promise<void>;\n\n/**\n * Information about current rate limit status\n */\nexport interface RateLimitInfo {\n\t/**\n\t * Current request count in the window\n\t */\n\tcount: number;\n\n\t/**\n\t * Maximum allowed requests\n\t */\n\tlimit: number;\n\n\t/**\n\t * Remaining requests allowed\n\t */\n\tremaining: number;\n\n\t/**\n\t * Time when the window resets (Unix timestamp)\n\t */\n\tresetTime: number;\n\n\t/**\n\t * Time until reset in milliseconds\n\t */\n\tretryAfter: number;\n}\n\n/**\n * Headers to be set on responses\n */\nexport interface RateLimitHeaders {\n\t'X-RateLimit-Limit'?: string;\n\t'X-RateLimit-Remaining'?: string;\n\t'X-RateLimit-Reset'?: string;\n\t'Retry-After'?: string;\n\t'X-RateLimit-Retry-After'?: string;\n\t'X-RateLimit-Reset-After'?: string;\n}\n\n/**\n * Data stored in cache for rate limiting\n */\nexport interface RateLimitData {\n\tcount: number;\n\tresetTime: number;\n}\n\n/**\n * Default key generator using IP address\n */\nexport const defaultKeyGenerator: RateLimitKeyGenerator = (ctx) => {\n\t// Try various headers for IP address\n\tconst ip =\n\t\tctx.header('x-forwarded-for')?.split(',')[0]?.trim() ||\n\t\tctx.header('x-real-ip') ||\n\t\tctx.header('x-client-ip') ||\n\t\tctx.header('cf-connecting-ip') ||\n\t\t'unknown';\n\n\treturn `rate-limit:${ctx.method}:${ctx.path}:${ip}`;\n};\n\n/**\n * Check rate limit and throw error if exceeded\n */\nexport async function checkRateLimit<\n\tTServices extends Service[] = [],\n\tTLogger extends Logger = Logger,\n\tTSession = unknown,\n>(\n\tconfig: RateLimitConfig,\n\tctx: RateLimitContext<TServices, TLogger, TSession>,\n): Promise<RateLimitInfo> {\n\t// Check if we should skip rate limiting\n\tif (config.skip && (await config.skip(ctx))) {\n\t\treturn {\n\t\t\tcount: 0,\n\t\t\tlimit: config.limit,\n\t\t\tremaining: config.limit,\n\t\t\tresetTime: Date.now() + config.windowMs,\n\t\t\tretryAfter: config.windowMs,\n\t\t};\n\t}\n\n\t// Generate key for this request\n\tconst keyGenerator = config.keyGenerator || defaultKeyGenerator;\n\tconst key = await keyGenerator(ctx);\n\n\t// Get current data from cache\n\tconst now = Date.now();\n\tlet data = await config.cache.get<RateLimitData>(key);\n\n\t// If no data or window expired, create new entry\n\tif (!data || data.resetTime <= now) {\n\t\tconst resetTime = now + config.windowMs;\n\t\tdata = { count: 1, resetTime };\n\n\t\t// Store with TTL matching the window\n\t\tconst ttlSeconds = Math.ceil(config.windowMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t} else {\n\t\t// Increment count\n\t\tdata.count++;\n\n\t\t// Calculate remaining TTL\n\t\tconst remainingMs = data.resetTime - now;\n\t\tconst ttlSeconds = Math.ceil(remainingMs / 1000);\n\t\tawait config.cache.set(key, data, ttlSeconds);\n\t}\n\n\t// Calculate rate limit info\n\tconst info: RateLimitInfo = {\n\t\tcount: data.count,\n\t\tlimit: config.limit,\n\t\tremaining: Math.max(0, config.limit - data.count),\n\t\tresetTime: data.resetTime,\n\t\tretryAfter: data.resetTime - now,\n\t};\n\n\t// Check if limit exceeded\n\tif (data.count > config.limit) {\n\t\t// Call custom handler if provided\n\t\tif (config.handler) {\n\t\t\tawait config.handler(ctx, info);\n\t\t}\n\n\t\t// Throw rate limit error\n\t\tconst retryAfterSeconds = Math.ceil(info.retryAfter / 1000);\n\t\tthrow new TooManyRequestsError(\n\t\t\tconfig.message || 'Too many requests, please try again later.',\n\t\t\tretryAfterSeconds,\n\t\t);\n\t}\n\n\treturn info;\n}\n\n/**\n * Generate rate limit headers\n */\nexport function getRateLimitHeaders(\n\tinfo: RateLimitInfo,\n\tconfig: RateLimitConfig,\n): RateLimitHeaders {\n\tconst headers: RateLimitHeaders = {};\n\n\tif (config.standardHeaders !== false) {\n\t\theaders['X-RateLimit-Limit'] = info.limit.toString();\n\t\theaders['X-RateLimit-Remaining'] = info.remaining.toString();\n\t\theaders['X-RateLimit-Reset'] = new Date(info.resetTime).toISOString();\n\t}\n\n\tif (config.legacyHeaders) {\n\t\theaders['X-RateLimit-Retry-After'] = info.retryAfter.toString();\n\t\theaders['X-RateLimit-Reset-After'] = Math.ceil(\n\t\t\tinfo.retryAfter / 1000,\n\t\t).toString();\n\t}\n\n\t// Always set Retry-After when limit is exceeded\n\tif (info.remaining === 0) {\n\t\theaders['Retry-After'] = Math.ceil(info.retryAfter / 1000).toString();\n\t}\n\n\treturn headers;\n}\n"],"mappings":";;;;AAOA,IAAa,uBAAb,cAA0C,MAAM;CAC/C,AAAgB,aAAa;CAC7B,AAAgB;CAEhB,YAAYA,SAAkBC,YAAqB;AAClD,QAAM,WAAW,6CAA6C;AAC9D,OAAK,OAAO;AACZ,OAAK,aAAa;CAClB;AACD;;;;AA8JD,MAAaC,sBAA6C,CAAC,QAAQ;CAElE,MAAM,KACL,IAAI,OAAO,kBAAkB,EAAE,MAAM,IAAI,CAAC,IAAI,MAAM,IACpD,IAAI,OAAO,YAAY,IACvB,IAAI,OAAO,cAAc,IACzB,IAAI,OAAO,mBAAmB,IAC9B;AAED,SAAQ,aAAa,IAAI,OAAO,GAAG,IAAI,KAAK,GAAG,GAAG;AAClD;;;;AAKD,eAAsB,eAKrBC,QACAC,KACyB;AAEzB,KAAI,OAAO,QAAS,MAAM,OAAO,KAAK,IAAI,CACzC,QAAO;EACN,OAAO;EACP,OAAO,OAAO;EACd,WAAW,OAAO;EAClB,WAAW,KAAK,KAAK,GAAG,OAAO;EAC/B,YAAY,OAAO;CACnB;CAIF,MAAM,eAAe,OAAO,gBAAgB;CAC5C,MAAM,MAAM,MAAM,aAAa,IAAI;CAGnC,MAAM,MAAM,KAAK,KAAK;CACtB,IAAI,OAAO,MAAM,OAAO,MAAM,IAAmB,IAAI;AAGrD,MAAK,QAAQ,KAAK,aAAa,KAAK;EACnC,MAAM,YAAY,MAAM,OAAO;AAC/B,SAAO;GAAE,OAAO;GAAG;EAAW;EAG9B,MAAM,aAAa,KAAK,KAAK,OAAO,WAAW,IAAK;AACpD,QAAM,OAAO,MAAM,IAAI,KAAK,MAAM,WAAW;CAC7C,OAAM;AAEN,OAAK;EAGL,MAAM,cAAc,KAAK,YAAY;EACrC,MAAM,aAAa,KAAK,KAAK,cAAc,IAAK;AAChD,QAAM,OAAO,MAAM,IAAI,KAAK,MAAM,WAAW;CAC7C;CAGD,MAAMC,OAAsB;EAC3B,OAAO,KAAK;EACZ,OAAO,OAAO;EACd,WAAW,KAAK,IAAI,GAAG,OAAO,QAAQ,KAAK,MAAM;EACjD,WAAW,KAAK;EAChB,YAAY,KAAK,YAAY;CAC7B;AAGD,KAAI,KAAK,QAAQ,OAAO,OAAO;AAE9B,MAAI,OAAO,QACV,OAAM,OAAO,QAAQ,KAAK,KAAK;EAIhC,MAAM,oBAAoB,KAAK,KAAK,KAAK,aAAa,IAAK;AAC3D,QAAM,IAAI,qBACT,OAAO,WAAW,8CAClB;CAED;AAED,QAAO;AACP;;;;AAKD,SAAgB,oBACfA,MACAF,QACmB;CACnB,MAAMG,UAA4B,CAAE;AAEpC,KAAI,OAAO,oBAAoB,OAAO;AACrC,UAAQ,uBAAuB,KAAK,MAAM,UAAU;AACpD,UAAQ,2BAA2B,KAAK,UAAU,UAAU;AAC5D,UAAQ,uBAAuB,IAAI,KAAK,KAAK,WAAW,aAAa;CACrE;AAED,KAAI,OAAO,eAAe;AACzB,UAAQ,6BAA6B,KAAK,WAAW,UAAU;AAC/D,UAAQ,6BAA6B,KAAK,KACzC,KAAK,aAAa,IAClB,CAAC,UAAU;CACZ;AAGD,KAAI,KAAK,cAAc,EACtB,SAAQ,iBAAiB,KAAK,KAAK,KAAK,aAAa,IAAK,CAAC,UAAU;AAGtE,QAAO;AACP"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/rate-limit",
-  "version": "10.0.0-alpha.99",
+  "version": "10.0.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -15,9 +15,6 @@
       }
     }
   },
-  "files": [
-    "dist"
-  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/geekmidas/toolbox"
@@ -28,9 +25,9 @@
   },
   "dependencies": {},
   "peerDependencies": {
-    "@geekmidas/cache": "^10.0.0-alpha.99",
-    "@geekmidas/logger": "^10.0.0-alpha.99",
-    "@geekmidas/services": "^10.0.0-alpha.99"
+    "@geekmidas/cache": "^10.0.0",
+    "@geekmidas/logger": "^10.0.0",
+    "@geekmidas/services": "^10.0.0"
   },
   "peerDependenciesMeta": {
     "@geekmidas/cache": {
@@ -44,12 +41,11 @@
     }
   },
   "devDependencies": {
-    "@geekmidas/cache": "^10.0.0-alpha.99",
-    "@geekmidas/logger": "^10.0.0-alpha.99",
-    "@geekmidas/services": "^10.0.0-alpha.99"
+    "@geekmidas/cache": "^10.0.0",
+    "@geekmidas/logger": "^10.0.0",
+    "@geekmidas/services": "^10.0.0"
   },
   "scripts": {
-    "ts": "tsc --noEmit --skipLibCheck src/**/*.ts",
-    "build": "tsdown --config ../../tsdown.config.ts --filter ."
+    "ts": "tsc --noEmit --skipLibCheck src/**/*.ts"
   }
 }

package/src/__benchmarks__/rateLimit.bench.ts

@@ -0,0 +1,109 @@
+import { InMemoryCache } from '@geekmidas/cache/memory';
+import { bench, describe } from 'vitest';
+import {
+	checkRateLimit,
+	type RateLimitConfig,
+	type RateLimitContext,
+} from '../index';
+
+// Helper to create a mock context
+function createContext(ip: string): RateLimitContext {
+	return {
+		header: (key: string) => (key === 'x-forwarded-for' ? ip : undefined),
+		services: {},
+		logger: {
+			info: () => {},
+			error: () => {},
+			debug: () => {},
+			warn: () => {},
+		} as any,
+		session: {},
+		path: '/test',
+		method: 'GET',
+	};
+}
+
+describe('Rate Limiting', () => {
+	const cache = new InMemoryCache();
+	const config: RateLimitConfig = {
+		limit: 100,
+		windowMs: 60000,
+		cache,
+	};
+
+	bench('checkRateLimit - single IP', async () => {
+		const ctx = createContext('127.0.0.1');
+		await checkRateLimit(config, ctx);
+	});
+
+	bench('checkRateLimit - varying IPs', async () => {
+		const ip = `192.168.1.${Math.floor(Math.random() * 255)}`;
+		const ctx = createContext(ip);
+		await checkRateLimit(config, ctx);
+	});
+});
+
+describe('Rate Limiting - High Volume', () => {
+	bench('100 requests same IP', async () => {
+		const cache = new InMemoryCache();
+		const config: RateLimitConfig = {
+			limit: 1000,
+			windowMs: 60000,
+			cache,
+		};
+		const ctx = createContext('10.0.0.1');
+
+		for (let i = 0; i < 100; i++) {
+			await checkRateLimit(config, ctx);
+		}
+	});
+
+	bench('100 requests different IPs', async () => {
+		const cache = new InMemoryCache();
+		const config: RateLimitConfig = {
+			limit: 100,
+			windowMs: 60000,
+			cache,
+		};
+
+		for (let i = 0; i < 100; i++) {
+			const ctx = createContext(`10.0.0.${i}`);
+			await checkRateLimit(config, ctx);
+		}
+	});
+});
+
+describe('Rate Limiting - Window Sizes', () => {
+	bench('1 second window', async () => {
+		const cache = new InMemoryCache();
+		const config: RateLimitConfig = {
+			limit: 10,
+			windowMs: 1000,
+			cache,
+		};
+		const ctx = createContext('127.0.0.1');
+		await checkRateLimit(config, ctx);
+	});
+
+	bench('1 minute window', async () => {
+		const cache = new InMemoryCache();
+		const config: RateLimitConfig = {
+			limit: 100,
+			windowMs: 60000,
+			cache,
+		};
+		const ctx = createContext('127.0.0.1');
+		await checkRateLimit(config, ctx);
+	});
+
+	bench('1 hour window', async () => {
+		const cache = new InMemoryCache();
+		const config: RateLimitConfig = {
+			limit: 1000,
+			windowMs: 3600000,
+			cache,
+		};
+		const ctx = createContext('127.0.0.1');
+		await checkRateLimit(config, ctx);
+	});
+});

package/src/__tests__/rate-limit.spec.ts

@@ -0,0 +1,321 @@
+import { InMemoryCache } from '@geekmidas/cache/memory';
+import { describe, expect, it, vi } from 'vitest';
+import {
+	checkRateLimit,
+	defaultKeyGenerator,
+	getRateLimitHeaders,
+	type RateLimitConfig,
+	type RateLimitContext,
+	type RateLimitData,
+	TooManyRequestsError,
+} from '../index';
+
+describe('Rate Limiting', () => {
+	const createContext = (
+		overrides?: Partial<RateLimitContext>,
+	): RateLimitContext => ({
+		header: vi.fn((key: string) => {
+			if (key === 'x-forwarded-for') return '192.168.1.1';
+			return undefined;
+		}),
+		services: [],
+		logger: {
+			debug: vi.fn(),
+			info: vi.fn(),
+			warn: vi.fn(),
+			error: vi.fn(),
+			child: vi.fn().mockReturnThis(),
+		} as any,
+		session: {},
+		path: '/api/test',
+		method: 'GET',
+		...overrides,
+	});
+
+	describe('defaultKeyGenerator', () => {
+		it('should generate key with IP from x-forwarded-for', () => {
+			const ctx = createContext();
+			const key = defaultKeyGenerator(ctx);
+			expect(key).toBe('rate-limit:GET:/api/test:192.168.1.1');
+		});
+
+		it('should use x-real-ip when x-forwarded-for is not available', () => {
+			const ctx = createContext({
+				header: vi.fn((key: string) => {
+					if (key === 'x-real-ip') return '10.0.0.1';
+					return undefined;
+				}),
+			});
+			const key = defaultKeyGenerator(ctx);
+			expect(key).toBe('rate-limit:GET:/api/test:10.0.0.1');
+		});
+
+		it('should use unknown when no IP header is available', () => {
+			const ctx = createContext({
+				header: vi.fn(() => undefined),
+			});
+			const key = defaultKeyGenerator(ctx);
+			expect(key).toBe('rate-limit:GET:/api/test:unknown');
+		});
+
+		it('should handle comma-separated IPs in x-forwarded-for', () => {
+			const ctx = createContext({
+				header: vi.fn((key: string) => {
+					if (key === 'x-forwarded-for')
+						return '192.168.1.1, 10.0.0.1, 172.16.0.1';
+					return undefined;
+				}),
+			});
+			const key = defaultKeyGenerator(ctx);
+			expect(key).toBe('rate-limit:GET:/api/test:192.168.1.1');
+		});
+	});
+
+	describe('checkRateLimit', () => {
+		it('should allow requests within the limit', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 5,
+				windowMs: 60000, // 1 minute
+				cache,
+			};
+			const ctx = createContext();
+
+			const info = await checkRateLimit(config, ctx);
+			expect(info.count).toBe(1);
+			expect(info.remaining).toBe(4);
+			expect(info.limit).toBe(5);
+		});
+
+		it('should increment count on subsequent requests', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 5,
+				windowMs: 60000,
+				cache,
+			};
+			const ctx = createContext();
+
+			// First request
+			await checkRateLimit(config, ctx);
+
+			// Second request
+			const info = await checkRateLimit(config, ctx);
+			expect(info.count).toBe(2);
+			expect(info.remaining).toBe(3);
+		});
+
+		it('should throw TooManyRequestsError when limit is exceeded', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 2,
+				windowMs: 60000,
+				cache,
+			};
+			const ctx = createContext();
+
+			// Use up the limit
+			await checkRateLimit(config, ctx);
+			await checkRateLimit(config, ctx);
+
+			// Exceed the limit
+			await expect(checkRateLimit(config, ctx)).rejects.toThrow(
+				TooManyRequestsError,
+			);
+		});
+
+		it('should use custom message when rate limit is exceeded', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 1,
+				windowMs: 60000,
+				cache,
+				message: 'Custom rate limit message',
+			};
+			const ctx = createContext();
+
+			await checkRateLimit(config, ctx);
+
+			try {
+				await checkRateLimit(config, ctx);
+			} catch (error) {
+				expect(error).toBeInstanceOf(TooManyRequestsError);
+				expect((error as TooManyRequestsError).message).toBe(
+					'Custom rate limit message',
+				);
+			}
+		});
+
+		it('should skip rate limiting when skip function returns true', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 1,
+				windowMs: 60000,
+				cache,
+				skip: vi.fn().mockResolvedValue(true),
+			};
+			const ctx = createContext();
+
+			// Should not throw even though limit would be exceeded
+			await checkRateLimit(config, ctx);
+			const info = await checkRateLimit(config, ctx);
+
+			expect(info.count).toBe(0);
+			expect(info.remaining).toBe(1);
+			expect(config.skip).toHaveBeenCalledWith(ctx);
+		});
+
+		it('should call custom handler when rate limit is exceeded', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const handler = vi.fn();
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 1,
+				windowMs: 60000,
+				cache,
+				handler,
+			};
+			const ctx = createContext();
+
+			await checkRateLimit(config, ctx);
+
+			try {
+				await checkRateLimit(config, ctx);
+			} catch {
+				// Expected to throw
+			}
+
+			expect(handler).toHaveBeenCalledWith(
+				ctx,
+				expect.objectContaining({
+					count: 2,
+					limit: 1,
+					remaining: 0,
+				}),
+			);
+		});
+
+		it('should use custom key generator', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const keyGenerator = vi.fn().mockReturnValue('custom-key');
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 5,
+				windowMs: 60000,
+				cache,
+				keyGenerator,
+			};
+			const ctx = createContext();
+
+			await checkRateLimit(config, ctx);
+
+			expect(keyGenerator).toHaveBeenCalledWith(ctx);
+		});
+
+		it('should reset count after window expires', async () => {
+			const cache = new InMemoryCache<RateLimitData>();
+			const config: RateLimitConfig<RateLimitData> = {
+				limit: 2,
+				windowMs: 100, // 100ms window
+				cache,
+			};
+			const ctx = createContext();
+
+			// Use up the limit
+			await checkRateLimit(config, ctx);
+			await checkRateLimit(config, ctx);
+
+			// Wait for window to expire
+			await new Promise((resolve) => setTimeout(resolve, 150));
+
+			// Should be allowed again
+			const info = await checkRateLimit(config, ctx);
+			expect(info.count).toBe(1);
+			expect(info.remaining).toBe(1);
+		});
+	});
+
+	describe('getRateLimitHeaders', () => {
+		it('should generate standard headers by default', () => {
+			const info = {
+				count: 3,
+				limit: 10,
+				remaining: 7,
+				resetTime: Date.now() + 60000,
+				retryAfter: 60000,
+			};
+			const config: RateLimitConfig = {
+				limit: 10,
+				windowMs: 60000,
+				cache: new InMemoryCache(),
+			};
+
+			const headers = getRateLimitHeaders(info, config);
+
+			expect(headers['X-RateLimit-Limit']).toBe('10');
+			expect(headers['X-RateLimit-Remaining']).toBe('7');
+			expect(headers['X-RateLimit-Reset']).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+			expect(headers['Retry-After']).toBeUndefined();
+		});
+
+		it('should include Retry-After when limit is exceeded', () => {
+			const info = {
+				count: 11,
+				limit: 10,
+				remaining: 0,
+				resetTime: Date.now() + 60000,
+				retryAfter: 60000,
+			};
+			const config: RateLimitConfig = {
+				limit: 10,
+				windowMs: 60000,
+				cache: new InMemoryCache(),
+			};
+
+			const headers = getRateLimitHeaders(info, config);
+
+			expect(headers['Retry-After']).toBe('60');
+		});
+
+		it('should not include standard headers when disabled', () => {
+			const info = {
+				count: 3,
+				limit: 10,
+				remaining: 7,
+				resetTime: Date.now() + 60000,
+				retryAfter: 60000,
+			};
+			const config: RateLimitConfig = {
+				limit: 10,
+				windowMs: 60000,
+				cache: new InMemoryCache(),
+				standardHeaders: false,
+			};
+
+			const headers = getRateLimitHeaders(info, config);
+
+			expect(headers['X-RateLimit-Limit']).toBeUndefined();
+			expect(headers['X-RateLimit-Remaining']).toBeUndefined();
+			expect(headers['X-RateLimit-Reset']).toBeUndefined();
+		});
+
+		it('should include legacy headers when enabled', () => {
+			const info = {
+				count: 3,
+				limit: 10,
+				remaining: 7,
+				resetTime: Date.now() + 60000,
+				retryAfter: 60000,
+			};
+			const config: RateLimitConfig = {
+				limit: 10,
+				windowMs: 60000,
+				cache: new InMemoryCache(),
+				legacyHeaders: true,
+			};
+
+			const headers = getRateLimitHeaders(info, config);
+
+			expect(headers['X-RateLimit-Retry-After']).toBe('60000');
+			expect(headers['X-RateLimit-Reset-After']).toBe('60');
+		});
+	});
+});

package/src/index.ts

@@ -0,0 +1,290 @@
+import type { Cache } from '@geekmidas/cache';
+import type { Logger } from '@geekmidas/logger';
+import type { Service, ServiceRecord } from '@geekmidas/services';
+
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export class TooManyRequestsError extends Error {
+	public readonly statusCode = 429;
+	public readonly retryAfter?: number;
+
+	constructor(message?: string, retryAfter?: number) {
+		super(message || 'Too many requests, please try again later.');
+		this.name = 'TooManyRequestsError';
+		this.retryAfter = retryAfter;
+	}
+}
+
+/**
+ * Rate limit configuration for an endpoint
+ */
+export interface RateLimitConfig {
+	/**
+	 * Maximum number of requests allowed in the window
+	 */
+	limit: number;
+
+	/**
+	 * Time window in milliseconds
+	 */
+	windowMs: number;
+
+	/**
+	 * Cache instance to store rate limit data
+	 */
+	cache: Cache;
+
+	/**
+	 * Key generator function to identify clients
+	 * Defaults to using IP address
+	 */
+	keyGenerator?: RateLimitKeyGenerator;
+
+	/**
+	 * Skip rate limiting for certain requests
+	 */
+	skip?: RateLimitSkipFn;
+
+	/**
+	 * Optional message to return when rate limit is exceeded
+	 */
+	message?: string;
+
+	/**
+	 * Optional custom handler when rate limit is exceeded
+	 */
+	handler?: RateLimitExceededHandler;
+
+	/**
+	 * Whether to include rate limit headers in response
+	 * @default true
+	 */
+	standardHeaders?: boolean;
+
+	/**
+	 * Whether to include legacy rate limit headers
+	 * @default false
+	 */
+	legacyHeaders?: boolean;
+}
+
+/**
+ * Context for rate limiting decisions
+ */
+export interface RateLimitContext<
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+	TSession = unknown,
+> {
+	header: (key: string) => string | undefined;
+	services: ServiceRecord<TServices>;
+	logger: TLogger;
+	session: TSession;
+	path: string;
+	method: string;
+}
+
+/**
+ * Function to generate a unique key for rate limiting
+ */
+export type RateLimitKeyGenerator<
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+	TSession = unknown,
+> = (
+	ctx: RateLimitContext<TServices, TLogger, TSession>,
+) => string | Promise<string>;
+
+/**
+ * Function to determine if rate limiting should be skipped
+ */
+export type RateLimitSkipFn<
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+	TSession = unknown,
+> = (
+	ctx: RateLimitContext<TServices, TLogger, TSession>,
+) => boolean | Promise<boolean>;
+
+/**
+ * Handler for when rate limit is exceeded
+ */
+export type RateLimitExceededHandler<
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+	TSession = unknown,
+> = (
+	ctx: RateLimitContext<TServices, TLogger, TSession>,
+	info: RateLimitInfo,
+) => void | Promise<void>;
+
+/**
+ * Information about current rate limit status
+ */
+export interface RateLimitInfo {
+	/**
+	 * Current request count in the window
+	 */
+	count: number;
+
+	/**
+	 * Maximum allowed requests
+	 */
+	limit: number;
+
+	/**
+	 * Remaining requests allowed
+	 */
+	remaining: number;
+
+	/**
+	 * Time when the window resets (Unix timestamp)
+	 */
+	resetTime: number;
+
+	/**
+	 * Time until reset in milliseconds
+	 */
+	retryAfter: number;
+}
+
+/**
+ * Headers to be set on responses
+ */
+export interface RateLimitHeaders {
+	'X-RateLimit-Limit'?: string;
+	'X-RateLimit-Remaining'?: string;
+	'X-RateLimit-Reset'?: string;
+	'Retry-After'?: string;
+	'X-RateLimit-Retry-After'?: string;
+	'X-RateLimit-Reset-After'?: string;
+}
+
+/**
+ * Data stored in cache for rate limiting
+ */
+export interface RateLimitData {
+	count: number;
+	resetTime: number;
+}
+
+/**
+ * Default key generator using IP address
+ */
+export const defaultKeyGenerator: RateLimitKeyGenerator = (ctx) => {
+	// Try various headers for IP address
+	const ip =
+		ctx.header('x-forwarded-for')?.split(',')[0]?.trim() ||
+		ctx.header('x-real-ip') ||
+		ctx.header('x-client-ip') ||
+		ctx.header('cf-connecting-ip') ||
+		'unknown';
+
+	return `rate-limit:${ctx.method}:${ctx.path}:${ip}`;
+};
+
+/**
+ * Check rate limit and throw error if exceeded
+ */
+export async function checkRateLimit<
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+	TSession = unknown,
+>(
+	config: RateLimitConfig,
+	ctx: RateLimitContext<TServices, TLogger, TSession>,
+): Promise<RateLimitInfo> {
+	// Check if we should skip rate limiting
+	if (config.skip && (await config.skip(ctx))) {
+		return {
+			count: 0,
+			limit: config.limit,
+			remaining: config.limit,
+			resetTime: Date.now() + config.windowMs,
+			retryAfter: config.windowMs,
+		};
+	}
+
+	// Generate key for this request
+	const keyGenerator = config.keyGenerator || defaultKeyGenerator;
+	const key = await keyGenerator(ctx);
+
+	// Get current data from cache
+	const now = Date.now();
+	let data = await config.cache.get<RateLimitData>(key);
+
+	// If no data or window expired, create new entry
+	if (!data || data.resetTime <= now) {
+		const resetTime = now + config.windowMs;
+		data = { count: 1, resetTime };
+
+		// Store with TTL matching the window
+		const ttlSeconds = Math.ceil(config.windowMs / 1000);
+		await config.cache.set(key, data, ttlSeconds);
+	} else {
+		// Increment count
+		data.count++;
+
+		// Calculate remaining TTL
+		const remainingMs = data.resetTime - now;
+		const ttlSeconds = Math.ceil(remainingMs / 1000);
+		await config.cache.set(key, data, ttlSeconds);
+	}
+
+	// Calculate rate limit info
+	const info: RateLimitInfo = {
+		count: data.count,
+		limit: config.limit,
+		remaining: Math.max(0, config.limit - data.count),
+		resetTime: data.resetTime,
+		retryAfter: data.resetTime - now,
+	};
+
+	// Check if limit exceeded
+	if (data.count > config.limit) {
+		// Call custom handler if provided
+		if (config.handler) {
+			await config.handler(ctx, info);
+		}
+
+		// Throw rate limit error
+		const retryAfterSeconds = Math.ceil(info.retryAfter / 1000);
+		throw new TooManyRequestsError(
+			config.message || 'Too many requests, please try again later.',
+			retryAfterSeconds,
+		);
+	}
+
+	return info;
+}
+
+/**
+ * Generate rate limit headers
+ */
+export function getRateLimitHeaders(
+	info: RateLimitInfo,
+	config: RateLimitConfig,
+): RateLimitHeaders {
+	const headers: RateLimitHeaders = {};
+
+	if (config.standardHeaders !== false) {
+		headers['X-RateLimit-Limit'] = info.limit.toString();
+		headers['X-RateLimit-Remaining'] = info.remaining.toString();
+		headers['X-RateLimit-Reset'] = new Date(info.resetTime).toISOString();
+	}
+
+	if (config.legacyHeaders) {
+		headers['X-RateLimit-Retry-After'] = info.retryAfter.toString();
+		headers['X-RateLimit-Reset-After'] = Math.ceil(
+			info.retryAfter / 1000,
+		).toString();
+	}
+
+	// Always set Retry-After when limit is exceeded
+	if (info.remaining === 0) {
+		headers['Retry-After'] = Math.ceil(info.retryAfter / 1000).toString();
+	}
+
+	return headers;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"]
+}