@void-foundry/rate-limiter

NestJS rate-limiting module backed by Redis Lua scripts — three strategies, one decorator, zero boilerplate.

Installation

npm install @void-foundry/rate-limiter ioredis

Quick start

// app.module.ts
import Redis from 'ioredis';
import { RateLimiterModule } from '@void-foundry/rate-limiter';

const redis = new Redis(process.env.REDIS_URL);

@Module({
  imports: [
    RateLimiterModule.forRoot({ redis }),
  ],
})
export class AppModule {}

// wallet.controller.ts
import { RateLimiter, RateLimiterGuard } from '@void-foundry/rate-limiter';

@Controller('v1/wallets')
@UseGuards(JwtAuthGuard)
export class WalletController {
  @Post('bind')
  @HttpCode(200)
  @UseGuards(RateLimiterGuard)
  @RateLimiter({ name: 'wallets.bind', strategy: 'gcra', limit: 5, ttl: 60, keyType: RateLimiterKeyType.USER })
  async bind(@Body() body: unknown, @CurrentUser() user: JwtUserPayload) {
    // ...
  }
}

Strategies

| Strategy | Decorator value | Best for | |----------|----------------|----------| | Leaky bucket | 'leaky-bucket' | Smooth output rate, absorbs small bursts | | GCRA (sliding window) | 'gcra' | Precise burst control, lowest Redis memory | | Token bucket | 'token-bucket' | Explicit refill rate, generous burst allowance |

Peer dependencies

• @nestjs/common ^11.1
• @nestjs/core ^11.1
• ioredis ^5.4
• reflect-metadata ^0.2
• rxjs ^7.8

License

MIT