Packages

@xtaskjs/throttler

Per-endpoint and global rate limiting with memory or Redis backing and custom key generators.

npm install @xtaskjs/throttler Package path: packages/throttler

Overview

What this package owns in the runtime

Throttler integrates rate limiting into the xtask route pipeline. It limits requests per time window using configurable storage backends, supports custom key generators for IP, user, or API-key-based identification, and applies limits globally or per-method through decorators.

What it provides

configureThrottler() sets global defaults with memory or Redis driver, TTL, and request limit.
@Throttle(limit, ttl) decorator applies per-endpoint limits overriding global defaults.
keyGenerator option accepts request and context to compute any throttle key (IP, user ID, API key).
TTL format supports 500ms, 30s, 5m, 1h, 1d shorthand strings.

How it fits

Initialized automatically by @xtaskjs/core when the package is installed and configureThrottler() has been called.
Applies before controller handlers so rate checking runs consistently regardless of framework adapter.
Demonstrated by the 24-throttler_app sample with global and per-endpoint throttle policies.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

3/5

HTTP Delivery

5/5

Security

5/5

Operations

4/5

Integrations

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Call configureThrottler() with driver, TTL, limit, and optional key generator settings so defaults are ready before the pipeline executes.

During CreateApplication()

The throttler lifecycle registers the rate-limit middleware into the route pipeline so every decorated or globally configured endpoint is checked automatically.

During app.close()

Connected Redis stores and in-memory counters are released together with the application lifecycle.

API Surface

Representative exports from the upstream package

Rate limit decorators

Throttle
InjectThrottlerService
InjectThrottlerLifecycleManager

Usage

Typical adoption flow

1. Set global defaults

Call configureThrottler() near app startup with your preferred driver, default TTL, and request limit so all routes inherit a baseline policy.

2. Override per endpoint

Apply @Throttle(limit, ttl) to individual controller methods when specific routes need stricter or more lenient limits than the global default.

3. Customize the throttle key

Provide a keyGenerator function to throttle by user ID, API key, or any other request-derived value instead of the default IP-based identification.

Example

Reference snippet

Global config plus per-endpoint override

import { Controller, Get } from "@xtaskjs/common";
import { Throttle, configureThrottler } from "@xtaskjs/throttler";

configureThrottler({
  driver: "memory",
  ttl: "1m",
  limit: 100,
});

@Controller("/items")
export class ItemsController {
  @Get("/")
  @Throttle(10, "30s")
  list() {
    return [];
  }

  @Get("/heavy")
  @Throttle(2, "1m")
  heavy() {
    return { ok: true };
  }

  @Get("/open")
  open() {
    return { ok: true };
  }
}

Samples

Official samples to inspect next

Reference samples: 24-throttler_app