Rate Limit Metadata API

Build an Express router that enforces a request quota (using the provided windowMs and maxHits options) and exposes the current rate-limit metadata to callers on a single GET /widgets route.

Capabilities

Return quota for allowed requests

• When a GET /widgets request is within the quota window, respond 200 with a JSON body containing limit, used, remaining, and resetTime (ISO string) taken from the rate-limit metadata, and emit standard rate-limit headers (RateLimit, RateLimit-Policy) that reflect the same numbers. @test

Blocked response advertises retry

• After exceeding the configured hit limit within the window, a subsequent GET /widgets responds 429 with JSON including the metadata fields plus retryAfterSeconds (derived from the metadata reset time), and sets Retry-After to match that value. @test

Custom request property

• When a custom request property name is provided in the options, the metadata is stored under that name (defaulting to rateLimit when omitted) and is the source of the response payloads, rather than any default property. @test

Implementation

@generates

API

export interface RateLimitRouterOptions {
  windowMs: number;
  maxHits: number;
  requestProperty?: string;
  headerDraft?: "draft-6" | "draft-7" | "draft-8" | "legacy";
}

export function createRateLimitedRouter(
  options: RateLimitRouterOptions
): import("express").Router;

Dependencies { .dependencies }

express { .dependency }

HTTP server framework used to build the router.

express-rate-limit { .dependency }

Provides request counting, metadata attachment, and rate-limit headers.