@nathapp/nestjs-throttler 2.1.5 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,185 @@
1
+ # @nathapp/nestjs-throttler
2
+
3
+ Proxy-aware rate limiting wrapper for NestJS applications using [@nestjs/throttler](https://github.com/nestjs/throttler).
4
+
5
+ ## Features
6
+
7
+ - **Proxy-aware IP detection** — Accurate client IP resolution behind reverse proxies and load balancers
8
+ - **Trust proxy configuration** — Support for X-Forwarded-For header validation with CIDR matching
9
+ - **Express & Fastify support** — Works with both NestJS adapters
10
+ - **Drop-in replacement** — Compatible with @nestjs/throttler decorators and features
11
+ - **IPv6 support** — Full IPv6 address and CIDR range matching
12
+ - **Trusted proxy presets** — Pre-configured for Cloudflare, AWS, Google Cloud, and more
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install @nathapp/nestjs-throttler @nestjs/throttler
18
+ ```
19
+
20
+ ## Quick Start
21
+
22
+ ```typescript
23
+ import { Module } from '@nestjs/common';
24
+ import { APP_GUARD } from '@nestjs/core';
25
+ import { ThrottlerModule, DefaultThrottlerGuard } from '@nathapp/nestjs-throttler';
26
+
27
+ @Module({
28
+ imports: [
29
+ ThrottlerModule.forRoot({
30
+ throttlers: [
31
+ { name: 'short', ttl: 1000, limit: 3 },
32
+ { name: 'long', ttl: 60000, limit: 100 }
33
+ ],
34
+ trustProxy: {
35
+ enabled: true,
36
+ trustedProxies: ['10.0.0.0/8', 'cloudflare']
37
+ }
38
+ })
39
+ ],
40
+ providers: [
41
+ {
42
+ provide: APP_GUARD,
43
+ useClass: DefaultThrottlerGuard,
44
+ }
45
+ ]
46
+ })
47
+ export class AppModule {}
48
+ ```
49
+
50
+ ## Trust Proxy Configuration
51
+
52
+ ### Basic Setup
53
+
54
+ ```typescript
55
+ ThrottlerModule.forRoot({
56
+ throttlers: [{ name: 'default', ttl: 60000, limit: 10 }],
57
+ trustProxy: {
58
+ enabled: true,
59
+ trustedProxies: ['127.0.0.0/8', '10.0.0.0/8']
60
+ }
61
+ })
62
+ ```
63
+
64
+ ### Using Preset Providers
65
+
66
+ ```typescript
67
+ import { TRUSTED_PROXY_PRESETS } from '@nathapp/nestjs-common';
68
+
69
+ ThrottlerModule.forRoot({
70
+ throttlers: [{ name: 'default', ttl: 60000, limit: 10 }],
71
+ trustProxy: {
72
+ enabled: true,
73
+ trustedProxies: ['cloudflare', 'aws', 'gcp']
74
+ }
75
+ })
76
+ ```
77
+
78
+ Available presets: `cloudflare`, `aws`, `gcp`, `azure`, `digitalocean`, `fastly`, `cloudfront`, `heroku`
79
+
80
+ ### Async Configuration
81
+
82
+ ```typescript
83
+ ThrottlerModule.forRootAsync({
84
+ imports: [ConfigModule],
85
+ inject: [ConfigService],
86
+ useFactory: (config: ConfigService) => ({
87
+ throttlers: [{ name: 'default', ttl: 60000, limit: 10 }],
88
+ trustProxy: {
89
+ enabled: config.get('TRUST_PROXY'),
90
+ trustedProxies: config.get('TRUSTED_PROXIES')
91
+ }
92
+ })
93
+ })
94
+ ```
95
+
96
+ ## Express vs Fastify Support
97
+
98
+ The module automatically detects and supports both Express and Fastify adapters.
99
+
100
+ ```typescript
101
+ // Express
102
+ const app = await NestFactory.create(AppModule);
103
+
104
+ // Fastify
105
+ const app = await NestFactory.create<NestFastifyApplication>(
106
+ AppModule,
107
+ new FastifyAdapter()
108
+ );
109
+ ```
110
+
111
+ ## Custom Rate Limiting
112
+
113
+ ### Using @Throttle() Decorator
114
+
115
+ ```typescript
116
+ import { Controller, Get } from '@nestjs/common';
117
+ import { Throttle } from '@nestjs/throttler';
118
+
119
+ @Controller()
120
+ export class UserController {
121
+ // Override default limit for this endpoint
122
+ @Throttle({ default: { limit: 5, ttl: 60000 } })
123
+ @Get('users')
124
+ getUsers() {
125
+ return [];
126
+ }
127
+ }
128
+ ```
129
+
130
+ ### Using @SkipThrottle() Decorator
131
+
132
+ ```typescript
133
+ import { Controller, Get } from '@nestjs/common';
134
+ import { SkipThrottle } from '@nestjs/throttler';
135
+
136
+ @Controller()
137
+ export class HealthController {
138
+ // Skip throttling for health checks
139
+ @SkipThrottle()
140
+ @Get('health')
141
+ check() {
142
+ return { status: 'ok' };
143
+ }
144
+ }
145
+ ```
146
+
147
+ ## Provider Capabilities
148
+
149
+ This wrapper adds the following capabilities over raw @nestjs/throttler:
150
+
151
+ | Feature | @nestjs/throttler | @nathapp/nestjs-throttler |
152
+ |---------|-------------------|---------------------------|
153
+ | Basic rate limiting | ✅ | ✅ |
154
+ | Multiple throttlers | ✅ | ✅ |
155
+ | Custom storage | ✅ | ✅ |
156
+ | Trust proxy support | ❌ | ✅ |
157
+ | X-Forwarded-For validation | ❌ | ✅ |
158
+ | CIDR matching | ❌ | ✅ |
159
+ | IPv6 support | ❌ | ✅ |
160
+ | Preset proxy providers | ❌ | ✅ |
161
+
162
+ ## How It Works
163
+
164
+ The `DefaultThrottlerGuard` extends @nestjs/throttler's `ThrottlerGuard` and overrides the `getTracker()` method to use `getClientIp()` from @nathapp/nestjs-common. This function:
165
+
166
+ 1. Checks if trust proxy is enabled
167
+ 2. Validates request origin against trusted proxy list (with CIDR support)
168
+ 3. Parses X-Forwarded-For header (right-to-left, skipping trusted proxies)
169
+ 4. Falls back to socket.remoteAddress if headers are untrusted
170
+ 5. Returns the real client IP for rate limiting
171
+
172
+ ## Security Considerations
173
+
174
+ - **Always configure trusted proxies** — Without trust proxy configuration, X-Forwarded-For headers are ignored and socket.remoteAddress is used
175
+ - **Use CIDR ranges** — Prefer CIDR notation (e.g., `10.0.0.0/8`) over individual IPs for internal networks
176
+ - **Preset providers are vetted** — Cloud provider presets (cloudflare, aws, etc.) are maintained and updated with official IP ranges
177
+ - **IPv6 support** — Both IPv4 and IPv6 addresses/CIDRs are fully supported
178
+
179
+ ## License
180
+
181
+ ISC
182
+
183
+ ## Author
184
+
185
+ William Khoo
@@ -1,3 +1,5 @@
1
+ import { ExecutionContext } from '@nestjs/common';
2
+ import { ThrottlerStorage, ThrottlerLimitDetail } from '@nestjs/throttler';
1
3
  import { TrustProxyOptions } from '@nathapp/nestjs-common';
2
4
  export interface ThrottlerModuleOptions {
3
5
  trustProxy?: TrustProxyOptions;
@@ -7,9 +9,9 @@ export interface ThrottlerModuleOptions {
7
9
  name?: string;
8
10
  }>;
9
11
  ignoreUserAgents?: RegExp[];
10
- skipIf?: (context: any) => boolean;
11
- storage?: any;
12
- errorMessage?: string | ((context: any, throttlerLimitDetail: any) => string);
13
- getTracker?: (req: any) => string | Promise<string>;
14
- generateKey?: (context: any, tracker: string, throttlerName: string) => string;
12
+ skipIf?: (context: ExecutionContext) => boolean;
13
+ storage?: ThrottlerStorage;
14
+ errorMessage?: string | ((context: ExecutionContext, throttlerLimitDetail: ThrottlerLimitDetail) => string);
15
+ getTracker?: (req: Record<string, any>) => string | Promise<string>;
16
+ generateKey?: (context: ExecutionContext, tracker: string, throttlerName: string) => string;
15
17
  }
@@ -1 +1 @@
1
- {"version":3,"file":"module.js","sourceRoot":"","sources":["../lib/module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAyE;AACzE,iDAAkG;AAClG,0DAA0G;AAE1G,uDAA0D;AAGnD,IAAM,eAAe,uBAArB,MAAM,eAAe;IAO1B,MAAM,CAAC,OAAO,CAAC,OAA+B;QAE5C,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,IAAI,IAAA,sCAAsB,GAAE,EAAE,CAAC;gBAC7B,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,0CAA0C,IAAA,mCAAmB,GAAE,KAAK;oBACpE,8CAA8C;oBAC9C,sFAAsF,CACvF,CAAC;YACJ,CAAC;YACD,IAAA,mCAAmB,EAAC,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;QAC7D,CAAC;aAAM,IAAI,CAAC,IAAA,sCAAsB,GAAE,EAAE,CAAC;YACrC,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,gEAAgE;gBAChE,gEAAgE;gBAChE,iHAAiH,CAClH,CAAC;QACJ,CAAC;QAGD,MAAM,EAAE,UAAU,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC;QAEpD,OAAO;YACL,MAAM,EAAE,iBAAe;YACvB,OAAO,EAAE,CAAC,2BAAmB,CAAC,OAAO,CAAC,gBAAuB,CAAC,CAAC;YAC/D,SAAS,EAAE,CAAC,uCAAqB,CAAC;YAClC,OAAO,EAAE,CAAC,uCAAqB,EAAE,2BAAmB,CAAC;SACtD,CAAC;IACJ,CAAC;IAMD,MAAM,CAAC,YAAY,CAAC,OAAqD;QACvE,MAAM,kBAAkB,GAAa;YACnC,OAAO,EAAE,oBAAoB;YAC7B,UAAU,EAAE,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;gBACnC,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;oBACvB,IAAI,IAAA,sCAAsB,GAAE,EAAE,CAAC;wBAC7B,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,0CAA0C,IAAA,mCAAmB,GAAE,KAAK;4BACpE,mDAAmD;4BACnD,sFAAsF,CACvF,CAAC;oBACJ,CAAC;oBAED,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;wBAC7C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;wBACjD,IAAA,mCAAmB,EAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;oBACjD,CAAC;yBAAM,CAAC;wBAEN,IAAA,mCAAmB,EAAC,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;oBAC7D,CAAC;gBACH,CAAC;qBAAM,IAAI,CAAC,IAAA,sCAAsB,GAAE,EAAE,CAAC;oBACrC,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,gEAAgE;wBAChE,gEAAgE;wBAChE,sHAAsH,CACvH,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;SAC7B,CAAC;QAGF,MAAM,EAAE,UAAU,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC;QAEpD,OAAO;YACL,MAAM,EAAE,iBAAe;YACvB,OAAO,EAAE,CAAC,2BAAmB,CAAC,YAAY,CAAC,gBAAuB,CAAC,CAAC;YACpE,SAAS,EAAE,CAAC,kBAAkB,EAAE,uCAAqB,CAAC;YACtD,OAAO,EAAE,CAAC,uCAAqB,EAAE,2BAAmB,CAAC;SACtD,CAAC;IACJ,CAAC;;AAlFU,0CAAe;AACF,sBAAM,GAAG,IAAI,eAAM,CAAC,iBAAiB,CAAC,AAAhC,CAAiC;0BADpD,eAAe;IAD3B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,eAAe,CAmF3B"}
1
+ {"version":3,"file":"module.js","sourceRoot":"","sources":["../lib/module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAyE;AACzE,iDAI2B;AAC3B,0DAA0G;AAE1G,uDAA0D;AAGnD,IAAM,eAAe,uBAArB,MAAM,eAAe;IA0B1B,MAAM,CAAC,OAAO,CAAC,OAA+B;QAE5C,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,IAAI,IAAA,sCAAsB,GAAE,EAAE,CAAC;gBAC7B,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,0CAA0C,IAAA,mCAAmB,GAAE,KAAK;oBACpE,8CAA8C;oBAC9C,sFAAsF,CACvF,CAAC;YACJ,CAAC;YACD,IAAA,mCAAmB,EAAC,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;QAC7D,CAAC;aAAM,IAAI,CAAC,IAAA,sCAAsB,GAAE,EAAE,CAAC;YACrC,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,gEAAgE;gBAChE,gEAAgE;gBAChE,iHAAiH,CAClH,CAAC;QACJ,CAAC;QAGD,MAAM,EAAE,UAAU,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC;QAEpD,OAAO;YACL,MAAM,EAAE,iBAAe;YACvB,OAAO,EAAE,CAAC,2BAAmB,CAAC,OAAO,CAAC,gBAA8C,CAAC,CAAC;YACtF,SAAS,EAAE,CAAC,uCAAqB,CAAC;YAClC,OAAO,EAAE,CAAC,uCAAqB,EAAE,2BAAmB,CAAC;SACtD,CAAC;IACJ,CAAC;IAuBD,MAAM,CAAC,YAAY,CAAC,OAAqD;QACvE,MAAM,kBAAkB,GAAa;YACnC,OAAO,EAAE,oBAAoB;YAC7B,UAAU,EAAE,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;gBACnC,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;oBACvB,IAAI,IAAA,sCAAsB,GAAE,EAAE,CAAC;wBAC7B,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,0CAA0C,IAAA,mCAAmB,GAAE,KAAK;4BACpE,mDAAmD;4BACnD,sFAAsF,CACvF,CAAC;oBACJ,CAAC;oBAED,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;wBAC7C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;wBACjD,IAAA,mCAAmB,EAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;oBACjD,CAAC;yBAAM,CAAC;wBAEN,IAAA,mCAAmB,EAAC,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;oBAC7D,CAAC;gBACH,CAAC;qBAAM,IAAI,CAAC,IAAA,sCAAsB,GAAE,EAAE,CAAC;oBACrC,iBAAe,CAAC,MAAM,CAAC,IAAI,CACzB,gEAAgE;wBAChE,gEAAgE;wBAChE,sHAAsH,CACvH,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;SAC7B,CAAC;QAGF,MAAM,EAAE,UAAU,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC;QAEpD,OAAO;YACL,MAAM,EAAE,iBAAe;YACvB,OAAO,EAAE,CAAC,2BAAmB,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC;YAC7D,SAAS,EAAE,CAAC,kBAAkB,EAAE,uCAAqB,CAAC;YACtD,OAAO,EAAE,CAAC,uCAAqB,EAAE,2BAAmB,CAAC;SACtD,CAAC;IACJ,CAAC;;AAtHU,0CAAe;AACF,sBAAM,GAAG,IAAI,eAAM,CAAC,iBAAiB,CAAC,AAAhC,CAAiC;0BADpD,eAAe;IAD3B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,eAAe,CAuH3B"}
@@ -1 +1 @@
1
- {"version":3,"file":"throttler.guard.js","sourceRoot":"","sources":["../lib/throttler.guard.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA8D;AAC9D,iDAAmD;AACnD,0DAAqD;AAG9C,IAAM,qBAAqB,GAA3B,MAAM,qBAAsB,SAAQ,0BAAc;IAKvD,KAAK,CAAC,UAAU,CAAC,GAAwB;QACvC,MAAM,EAAE,GAAG,IAAA,2BAAW,EAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,EAAE,IAAI,SAAS,CAAC;IACzB,CAAC;IAKS,kBAAkB,CAAC,OAAyB;QACpD,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QACnC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;IAC3D,CAAC;CACF,CAAA;AAjBY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;GACA,qBAAqB,CAiBjC"}
1
+ {"version":3,"file":"throttler.guard.js","sourceRoot":"","sources":["../lib/throttler.guard.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA8D;AAC9D,iDAAmD;AACnD,0DAAqD;AAuB9C,IAAM,qBAAqB,GAA3B,MAAM,qBAAsB,SAAQ,0BAAc;IAiBvD,KAAK,CAAC,UAAU,CAAC,GAAwB;QACvC,MAAM,EAAE,GAAG,IAAA,2BAAW,EAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,EAAE,IAAI,SAAS,CAAC;IACzB,CAAC;IAQS,kBAAkB,CAAC,OAAyB;QACpD,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QACnC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;IAC3D,CAAC;CACF,CAAA;AAhCY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;GACA,qBAAqB,CAgCjC"}
@@ -0,0 +1,90 @@
1
+ # Fix Plan: nestjs-throttler C+ → A-
2
+
3
+ **Date:** 2026-02-16
4
+ **Branch:** feat/monorepo-enterprise-upgrade
5
+
6
+ ## Phase 1: Fix Guard Integration + Failing Tests
7
+
8
+ ### Fix 1: BUG-2 — Guard API Compatibility with @nestjs/throttler v6
9
+ **File:** `lib/throttler.guard.ts`
10
+ **Impact:** All E2E tests fail — core functionality broken
11
+ **Change:**
12
+ 1. Check `@nestjs/throttler` v6 source/types to verify `getTracker()` signature
13
+ 2. Update `DefaultThrottlerGuard.getTracker()` to match expected v6 API
14
+ 3. Verify `getRequestResponse()` override is still needed in v6
15
+
16
+ ### Fix 2: BUG-1 — IPv6 CIDR Test
17
+ **File:** `test/throttler.guard.spec.ts`
18
+ **Impact:** 1 unit test failure
19
+ **Change:**
20
+ 1. Check if `getClientIp()` from `@nathapp/nestjs-common` supports IPv6 CIDR matching
21
+ 2. If not supported: update test expectation to match actual behavior (skip IPv6 CIDR for now)
22
+ 3. If supported: debug why it's not matching and fix
23
+
24
+ ### Fix 3: E2E Test Fixes
25
+ **File:** `test/throttler.e2e.spec.ts`
26
+ **Impact:** 14 E2E test failures
27
+ **Change:**
28
+ 1. After fixing the guard (Fix 1), re-run E2E tests
29
+ 2. Fix any remaining failures related to test setup/teardown
30
+ 3. Ensure Express and Fastify adapters both work
31
+
32
+ **Test command:**
33
+ ```bash
34
+ npx jest --config packages/nestjs-throttler/test/jest-test.json --no-coverage --forceExit
35
+ ```
36
+
37
+ **Commit:** `fix(nestjs-throttler): fix guard integration with @nestjs/throttler v6, fix failing tests`
38
+
39
+ ## Phase 2: Type Safety + Documentation
40
+
41
+ ### Fix 4: TYPE-1 — Replace `any` Types in Interface
42
+ **File:** `lib/interface/throttler-options.interface.ts`
43
+ **Change:**
44
+ 1. Import `ExecutionContext` from `@nestjs/common`
45
+ 2. Import `ThrottlerStorage` from `@nestjs/throttler` (if available)
46
+ 3. Replace `any` types:
47
+ - `skipIf?: (context: ExecutionContext) => boolean`
48
+ - `storage?: ThrottlerStorage` (or the correct type from @nestjs/throttler)
49
+ - `getTracker?: (req: Record<string, any>) => string | Promise<string>`
50
+ - `generateKey?: (context: ExecutionContext, tracker: string, throttlerName: string) => string`
51
+ - `errorMessage` callback params: use proper types
52
+
53
+ ### Fix 5: TYPE-2 — Remove `as any` Casts
54
+ **File:** `lib/module.ts`
55
+ **Change:**
56
+ 1. Align `ThrottlerModuleOptions` with what `CoreThrottlerModule.forRoot()` expects
57
+ 2. Remove `as any` casts on lines 40 and 75
58
+ 3. If types don't align perfectly, use a proper type mapping function instead of `as any`
59
+
60
+ ### Fix 6: ENH-1 — JSDoc on Public APIs
61
+ **Files:** `lib/throttler.guard.ts`, `lib/module.ts`, `lib/interface/throttler-options.interface.ts`
62
+ **Change:**
63
+ 1. Add class-level JSDoc to `DefaultThrottlerGuard` with usage example
64
+ 2. Add interface-level JSDoc to `ThrottlerModuleOptions`
65
+ 3. Add method-level JSDoc to `forRoot()` and `forRootAsync()` with examples
66
+
67
+ ### Fix 7: ENH-2 — Create README.md
68
+ **File:** `README.md`
69
+ **Change:** Create README with:
70
+ 1. Package description (proxy-aware rate limiting wrapper)
71
+ 2. Installation
72
+ 3. Quick start with `forRoot()` example
73
+ 4. Trust proxy configuration
74
+ 5. Express vs Fastify support note
75
+ 6. Custom `@Throttle()` and `@SkipThrottle()` decorators
76
+ 7. Provider capability (what this adds over raw `@nestjs/throttler`)
77
+
78
+ **Test command:**
79
+ ```bash
80
+ npx jest --config packages/nestjs-throttler/test/jest-test.json --no-coverage --forceExit
81
+ ```
82
+
83
+ **Commit:** `docs(nestjs-throttler): add type safety, JSDoc, and README`
84
+
85
+ ## Test Strategy
86
+ - Mode: test-after
87
+ - Existing tests must all pass after Phase 1
88
+ - No new tests needed (41 existing tests are comprehensive)
89
+
90
+ Do NOT push to remote.
@@ -0,0 +1,198 @@
1
+ # Deep Code Review: @nathapp/nestjs-throttler
2
+
3
+ **Date:** 2026-02-16
4
+ **Reviewer:** Subrina (Deep Review)
5
+ **Scope:** Full lib/ source (52 lines), test/ (1,065 lines)
6
+ **Branch:** feat/monorepo-enterprise-upgrade
7
+ **Version:** 2.1.5
8
+
9
+ ---
10
+
11
+ ## Executive Summary
12
+
13
+ **Grade: C+ (72/100)**
14
+
15
+ Small, focused package (52 lines lib) that wraps `@nestjs/throttler` with trusted proxy-aware IP resolution via `@nathapp/nestjs-common`'s `getClientIp()`. Clean architecture and good security concept, but **15 of 41 tests are failing** (37% failure rate) and there are several type safety and API design issues.
16
+
17
+ **Strengths:** Correct security architecture (proxy-aware IP tracking), dual Express/Fastify support, good E2E test coverage concept.
18
+
19
+ **Critical Gaps:** Failing tests, `any` types in interface, missing JSDoc, IPv6 CIDR matching bug.
20
+
21
+ ---
22
+
23
+ ## Findings
24
+
25
+ ### BUG-1: 15 Failing Tests (CRITICAL)
26
+ **Priority:** P0
27
+ **Impact:** 37% test failure rate blocks release
28
+
29
+ **E2E tests (14 failures):** All E2E tests in `throttler.e2e.spec.ts` fail. The guard's `getTracker()` returns a string but `@nestjs/throttler` v6+ may expect a different return type or the guard integration pattern changed.
30
+
31
+ **Unit test (1 failure):** IPv6 CIDR matching in `throttler.guard.spec.ts` — `getClientIp()` returns socket IP `2001:db8::1` instead of the forwarded IP `2001:db8:85a3::8a2e:370:7334` when proxy is in the `2001:db8::/32` range. This suggests `getClientIp()` in nestjs-common doesn't support IPv6 CIDR matching.
32
+
33
+ **Location:** `test/throttler.e2e.spec.ts`, `test/throttler.guard.spec.ts:212`
34
+
35
+ ---
36
+
37
+ ### BUG-2: E2E Guard Integration Broken
38
+ **Priority:** P0
39
+ **Impact:** Core functionality not working in E2E
40
+
41
+ The E2E tests register `DefaultThrottlerGuard` via `APP_GUARD` but the guard may not be integrating correctly with `@nestjs/throttler` v6. The `getTracker()` method signature may have changed — v6 expects `getTracker(req: Record<string, any>, context: ExecutionContext)` but current code only accepts `req`.
42
+
43
+ Need to verify against `@nestjs/throttler` v6 API and fix the guard override.
44
+
45
+ **Location:** `lib/throttler.guard.ts`, `test/throttler.e2e.spec.ts`
46
+
47
+ ---
48
+
49
+ ### TYPE-1: Excessive `any` Types in Interface
50
+ **Priority:** P1
51
+ **Impact:** Type safety violation
52
+
53
+ Multiple `any` types in `ThrottlerModuleOptions`:
54
+
55
+ ```typescript
56
+ skipIf?: (context: any) => boolean; // Should be ExecutionContext
57
+ errorMessage?: string | ((context: any, throttlerLimitDetail: any) => string); // Both any
58
+ storage?: any; // Should be ThrottlerStorage
59
+ getTracker?: (req: any) => string | Promise<string>; // Should be Record<string, any>
60
+ generateKey?: (context: any, tracker: string, throttlerName: string) => string; // Should be ExecutionContext
61
+ ```
62
+
63
+ **Fix:** Import proper types from `@nestjs/throttler` and `@nestjs/common`.
64
+
65
+ **Location:** `lib/interface/throttler-options.interface.ts:28-44`
66
+
67
+ ---
68
+
69
+ ### TYPE-2: `as any` Cast in forRoot
70
+ **Priority:** P1
71
+ **Impact:** Type safety bypass
72
+
73
+ ```typescript
74
+ imports: [CoreThrottlerModule.forRoot(throttlerOptions as any)],
75
+ ```
76
+
77
+ The `ThrottlerModuleOptions` interface doesn't match `@nestjs/throttler`'s expected type, so it's cast to `any`. Should align the interface or use a proper type mapping.
78
+
79
+ **Location:** `lib/module.ts:40`, `lib/module.ts:75`
80
+
81
+ ---
82
+
83
+ ### SEC-1: forRootAsync Trust Proxy Race Condition
84
+ **Priority:** P2
85
+ **Impact:** Low — trust proxy may not be configured before first request
86
+
87
+ In `forRootAsync`, the `TRUST_PROXY_CONFIG` provider runs during DI resolution. If an early request arrives before the provider factory completes, `getClientIp()` may use unconfigured trust proxy settings.
88
+
89
+ ```typescript
90
+ const trustProxyProvider: Provider = {
91
+ provide: 'TRUST_PROXY_CONFIG',
92
+ useFactory: async (...args: any[]) => {
93
+ // This runs asynchronously — gap before completion
94
+ configureTrustProxy(config, 'ThrottlerModule');
95
+ },
96
+ };
97
+ ```
98
+
99
+ **Mitigation:** This is low risk since NestJS waits for all providers to resolve before accepting requests. But the provider returns `null` — it's a side-effect-only provider. Consider using `onModuleInit` instead for clarity.
100
+
101
+ **Location:** `lib/module.ts:53-82`
102
+
103
+ ---
104
+
105
+ ### ENH-1: Missing JSDoc on Public APIs
106
+ **Priority:** P2
107
+ **Impact:** Developer experience
108
+
109
+ - `DefaultThrottlerGuard` — no class-level JSDoc
110
+ - `ThrottlerModuleOptions` — individual fields have docs but no interface-level summary
111
+ - No usage examples in JSDoc
112
+
113
+ **Location:** All files
114
+
115
+ ---
116
+
117
+ ### ENH-2: No README
118
+ **Priority:** P2
119
+ **Impact:** Discoverability
120
+
121
+ No README.md exists. Should document:
122
+ - Purpose (proxy-aware rate limiting)
123
+ - Quick start (forRoot/forRootAsync)
124
+ - Trust proxy configuration
125
+ - Express vs Fastify support
126
+ - Custom throttle decorators
127
+
128
+ ---
129
+
130
+ ### STYLE-1: Decorator Re-export Pattern
131
+ **Priority:** P3
132
+ **Impact:** Minor — unnecessary indirection
133
+
134
+ ```typescript
135
+ // lib/decorator/throttle.decorator.ts
136
+ export { Throttle, SkipThrottle } from '@nestjs/throttler';
137
+ ```
138
+
139
+ This just re-exports `@nestjs/throttler` decorators. Since `@nestjs/throttler` is already a peer dependency, consumers can import directly. This re-export adds no value but isn't harmful.
140
+
141
+ ---
142
+
143
+ ## Grading Rubric
144
+
145
+ | Dimension | Score | Rationale |
146
+ |:---|:---|:---|
147
+ | **Security** | 16/20 | Good proxy-aware IP architecture, IPv6 CIDR bug, race condition in async |
148
+ | **Reliability** | 10/20 | **15/41 tests failing** — critical issue |
149
+ | **API Design** | 14/20 | Clean forRoot/forRootAsync, but `any` types and `as any` cast |
150
+ | **Code Quality** | 14/20 | Small & focused, but no JSDoc, no README, `any` types |
151
+ | **Best Practices** | 18/20 | Good test structure, E2E coverage, dual adapter testing |
152
+
153
+ **Total: 72/100 (C+)**
154
+
155
+ ---
156
+
157
+ ## Fix Plan (P0 + P1 → A-)
158
+
159
+ ### Phase 1: Fix Failing Tests + Guard Integration
160
+ 1. Verify `@nestjs/throttler` v6 API — check `getTracker()` signature
161
+ 2. Fix `DefaultThrottlerGuard` to match v6 API
162
+ 3. Fix or skip IPv6 CIDR test (if `getClientIp` doesn't support IPv6 CIDR)
163
+ 4. Get all 41 tests passing
164
+
165
+ ### Phase 2: Type Safety + JSDoc + README
166
+ 1. Replace all `any` types in `ThrottlerModuleOptions` with proper types
167
+ 2. Remove `as any` casts in module.ts (align interface with throttler types)
168
+ 3. Add JSDoc to all public APIs
169
+ 4. Create README.md with usage examples
170
+
171
+ ### Expected Result
172
+ - All 41 tests passing
173
+ - Zero `any` types
174
+ - Full documentation
175
+ - Grade: A- (~87/100)
176
+
177
+ ---
178
+
179
+ ## Summary
180
+
181
+ | ID | Priority | Category | Description | Effort |
182
+ |:---|:---|:---|:---|:---|
183
+ | BUG-1 | P0 | Reliability | 15 failing tests (37% failure rate) | 2h |
184
+ | BUG-2 | P0 | Reliability | E2E guard integration broken | 1h |
185
+ | TYPE-1 | P1 | Type Safety | 5 `any` types in interface | 30min |
186
+ | TYPE-2 | P1 | Type Safety | `as any` cast in forRoot/forRootAsync | 30min |
187
+ | SEC-1 | P2 | Security | Async trust proxy race condition | 30min |
188
+ | ENH-1 | P2 | Docs | Missing JSDoc on public APIs | 30min |
189
+ | ENH-2 | P2 | Docs | No README.md | 1h |
190
+ | STYLE-1 | P3 | Style | Unnecessary decorator re-export | 5min |
191
+
192
+ **Blockers for 3.0.0:** BUG-1, BUG-2 (tests must pass)
193
+ **Blockers for A-:** TYPE-1, TYPE-2, ENH-1, ENH-2
194
+
195
+ ---
196
+
197
+ **Review Completed:** 2026-02-16
198
+ **Total Source Lines Reviewed:** 52 (lib/) + 1,065 (test/)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nathapp/nestjs-throttler",
3
- "version": "2.1.5",
3
+ "version": "3.0.0",
4
4
  "description": "NestJS Throttler with trusted proxy-aware IP resolution",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -19,14 +19,14 @@
19
19
  "node": ">=16"
20
20
  },
21
21
  "peerDependencies": {
22
- "@nathapp/nestjs-common": "^2.1.5",
22
+ "@nathapp/nestjs-common": "^3.0.0",
23
23
  "@nestjs/common": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
24
24
  "@nestjs/core": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
25
25
  "@nestjs/throttler": "^6.0.0 || ^7.0.0"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@nathapp/eslint-config": "1.0.1",
29
- "@nathapp/nestjs-common": "^2.1.5",
29
+ "@nathapp/nestjs-common": "^3.0.0",
30
30
  "@nathapp/typescript-config": "1.0.1",
31
31
  "@nestjs/common": "^11.0.0",
32
32
  "@nestjs/core": "^11.0.0",