Paquetes

@xtaskjs/throttler

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

npm install @xtaskjs/throttler Ruta del paquete: packages/throttler

Resumen

Qué controla este paquete en el 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.

Qué ofrece

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.

Cómo encaja

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.

Mapa de uso

Qué peso tiene este paquete dentro del runtime

Arranque

3/5

Entrega HTTP

5/5

Seguridad

5/5

Operaciones

4/5

Integraciones

4/5

Flujo del paquete

Cómo atraviesa este paquete las fases del runtime de xtaskjs

Antes del arranque

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

Durante CreateApplication()

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

Durante app.close()

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

Superficie API

Exports representativos del paquete original

Rate limit decorators

Throttle
InjectThrottlerService
InjectThrottlerLifecycleManager

Uso

Flujo típico de adopción

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.

Ejemplo

Fragmento de referencia

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 };
  }
}

Ejemplos

Ejemplos oficiales para revisar después

Ejemplos de referencia: 24-throttler_app

Relacionados