@playstack/nest-rate-limit

NestJS rate-limit declarations, trusted client-IP resolution, guards, and response headers.

Free. MIT licensed. Check preview availability before installing. See package access.

@playstack/nest-rate-limit attaches portable rate-limit policy to NestJS routes after trustworthy request identity has been established.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/nest-rate-limit@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose module and route

PlaystackRateLimitModule.forRoot({
  limiter,
  clock,
  trustedProxyCidrs: ['10.0.0.0/8'],
})

@UseGuards(PlaystackAuthGuard, PlaystackAccountGuard, PlaystackRateLimitGuard)
@UseRateLimit({
  name: 'api.request',
  subjects: (request, ip) => ({
    ip,
    account: request.playstackAccount.accountId,
  }),
  cost: (request) => request.body.items.length,
  headers: true,
})
@Post('/batch')
createBatch() {}

Module configuration

`NestRateLimitOptions` property	Required	Purpose
`limiter`	Yes	Structural core limiter exposing `consume`.
`clock`	Yes	Formats retry response timing.
`trustedProxyCidrs`	No	Immediate peers allowed to contribute forwarded client-IP headers.

Use forRootAsync({ imports, inject, useFactory }) for DI-based composition.

Route declaration properties

Property	Required	Purpose
`name`	Yes	Configured core policy name.
`subjects(request, ip)`	Yes	Resolves all policy subjects from trusted request state.
`cost`	No	Static or request-derived positive operation cost.
`headers`	No	Emits `RateLimit-*`, and on denial `Retry-After`, headers.

Forwarded headers are ignored unless the immediate peer matches a trusted CIDR. The resolver walks from the nearest hop, normalizes IPv4-mapped IPv6, and canonicalizes native IPv6.

Denied operations return HTTP 429 and the stable playstack/rate_limited body. A fail-closed store failure returns 503 because the request was not proven over limit.

Boundary

The adapter chooses no persistence, installs no global guard, and does not trust forwarded headers by default. Applications supply the core limiter and place the guard after authentication/account resolution when those subjects are required.

API entry points and requirements

Reference snapshot: @playstack/nest-rate-limit@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Public entry point	Declaration file
`@playstack/nest-rate-limit`	`./dist/index.d.ts`
`@playstack/nest-rate-limit/package.json`	No TypeScript declaration (asset or metadata export).

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

Peer	Compatible range	When needed
`@nestjs/common`	`^10.0.0 \|\| ^11.0.0`	Required by the package.
`@nestjs/core`	`^10.0.0 \|\| ^11.0.0`	Required by the package.
`@playstack/core`	`0.1.0-beta.1`	Required by the package.
`@playstack/rate-limit`	`0.1.0-beta.1`	Required by the package.
`reflect-metadata`	`^0.1.13 \|\| ^0.2.0`	Required by the package.
`rxjs`	`^7.0.0`	Required by the package.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.