---
title: "@playstack/nest-rate-limit"
description: "NestJS rate-limit declarations, trusted client-IP resolution, guards, and response headers."
tags: ["package","operations","rate-limiting","nestjs","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

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

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

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

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

{/* package-install:end */}

## Compose module and route

```ts
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.

{/* package-reference:start */}

## 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](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}