@ayepi/rate 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,189 @@
+import { AnyMiddleware, Json, MaybePromise, MiddlewareDef } from "@ayepi/core";
+import { Doer, DoerTaskOptions } from "@ayepi/core/doer";
+
+//#region src/index.d.ts
+
+/** The rate-limiting algorithm. */
+type Algorithm = 'fixed-window' | 'sliding-window' | 'token-bucket';
+/** Limiter state for one key, exposed to handlers (via `ctx.ratelimit`) and response headers. */
+interface RateLimitInfo {
+  /** The configured request limit for the window. */
+  readonly limit: number;
+  /** Requests (or tokens) remaining before the limit is hit. */
+  readonly remaining: number;
+  /** Milliseconds until the window/bucket resets. */
+  readonly reset: number;
+  /** Milliseconds to wait before retrying (0 when allowed). */
+  readonly retryAfter: number;
+}
+/** A store's decision for one key. */
+interface RateLimitResult extends RateLimitInfo {
+  /** Whether this request is within the limit. */
+  readonly allowed: boolean;
+}
+/** The rule a store evaluates a key against. */
+interface RateLimitRule {
+  readonly limit: number;
+  readonly window: number;
+  readonly algorithm: Algorithm;
+  /**
+   * Whether a request that is **itself rejected** (over the limit) still counts
+   * against the limit. Default `false` — rejected requests are not recorded, so a
+   * client cannot extend its own block by continuing to hammer the endpoint. Set
+   * `true` for the stricter behavior where every attempt consumes budget.
+   * (No effect on `token-bucket`, which never charges a request it can't admit.)
+   */
+  readonly countRejected?: boolean;
+}
+/**
+ * Pluggable backend that atomically records a hit and decides the outcome.
+ * Implementing the algorithm in the store keeps it correct across instances
+ * (the in-memory store is single-process; `@ayepi/rate/redis` is distributed).
+ */
+interface RateLimitStore {
+  /** Record a hit for `key` under `rule` at time `now` (ms) and return the decision. */
+  consume(key: string, rule: RateLimitRule, now: number): MaybePromise<RateLimitResult>;
+  /** Clear all state for `key` (optional). */
+  reset?(key: string): MaybePromise<void>;
+}
+/** The argument passed to `key`/`skip`/`message` — the request plus accumulated context. */
+interface RateKeyIO<Ctx extends object> {
+  readonly req: Request;
+  readonly ctx: Ctx;
+}
+/** Configuration for a standalone {@link limiter} — the base of {@link RateLimitOptions}. */
+interface LimiterOptions {
+  /** Max requests (or token-bucket capacity) per window. */
+  readonly limit: number;
+  /** Window length in milliseconds (also the token refill period). */
+  readonly window: number;
+  /** Algorithm (default `'fixed-window'`). */
+  readonly algorithm?: Algorithm;
+  /** Backend store (default an in-process {@link memoryStore}). */
+  readonly store?: RateLimitStore;
+  /** Key prefix/namespace (default `'rl:'`). */
+  readonly prefix?: string;
+  /**
+   * Count requests that are themselves rejected (over-limit) against the limit.
+   * Default `false` — see {@link RateLimitRule.countRejected}.
+   */
+  readonly countRejected?: boolean;
+}
+/** Response customization shared by {@link rateLimitResponse} and {@link rateLimit}. */
+interface RateLimitResponseOptions {
+  /** Over-limit status code (default `429`). */
+  readonly status?: number;
+  /** Over-limit body — a string, a JSON value, or a function of the limiter info. */
+  readonly message?: string | Json | ((info: RateLimitInfo) => string | Json);
+  /**
+   * Response headers. `true` (default) emits draft `RateLimit-Limit`/`-Remaining`/
+   * `-Reset` — plus `Retry-After` **only when the request was rejected**; `false`
+   * emits none; a function returns your own map.
+   */
+  readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
+}
+/**
+ * Options for the {@link rateLimit} **def** — frontend-safe only.
+ *
+ * @typeParam R - middleware this one depends on (their context is typed in the
+ *   server-side `key`/`skip`).
+ */
+interface RateLimitDefOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware this one depends on — their context is available (and typed) in `key`/`skip`. */
+  readonly requires?: R;
+  /** Middleware name for docs/debugging (default `'rateLimit'`). */
+  readonly name?: string;
+}
+/** A reusable rate limiter bound to a rule + store — usable anywhere, not just middleware. */
+interface Limiter {
+  /** Record a hit for `key` (at `now`, default `Date.now()`) and return the decision. */
+  check(key: string, now?: number): MaybePromise<RateLimitResult>;
+  /** Clear all state for `key`. */
+  reset(key: string): MaybePromise<void>;
+  /** The rule this limiter enforces. */
+  readonly rule: RateLimitRule;
+}
+/**
+ * Create a standalone {@link Limiter} — the rate-limit primitive the
+ * {@link rateLimit} middleware is built on. Use it anywhere you have a key: a
+ * plain handler, a queue/cron worker, a CLI, a different framework.
+ *
+ * ```ts
+ * const lim = limiter({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+ * const { allowed, retryAfter } = await lim.check(userId)
+ * if (!allowed) throw reject(429, 'RATE_LIMITED', `retry in ${retryAfter}ms`)
+ * ```
+ */
+declare function limiter(opts: LimiterOptions): Limiter;
+/**
+ * Compute the rate-limit response headers for `info`. `true` (default) emits the
+ * draft `RateLimit-Limit`/`-Remaining`/`-Reset` headers — plus `Retry-After` **only
+ * when the request was rejected** (`retryAfter > 0`); `false` emits none; a function
+ * returns your own map (which **replaces** the defaults).
+ *
+ * Shared by {@link rateLimitResponse} (the 429) and the middleware's `alwaysHeaders`
+ * option (informational headers on allowed responses).
+ */
+declare function rateLimitHeaders(info: RateLimitInfo, headers?: boolean | ((info: RateLimitInfo) => Record<string, string>)): Record<string, string>;
+/**
+ * Build a rate-limit (429) `Response` from limiter info — usable on its own,
+ * outside any middleware (e.g. from a handler that called {@link limiter} directly).
+ */
+declare function rateLimitResponse(info: RateLimitInfo, opts?: RateLimitResponseOptions): Response;
+/**
+ * Create a rate-limiting middleware **def**. The def declares what the middleware
+ * contributes (`{ ratelimit: RateLimitInfo }`) and its dependencies — but **no**
+ * policy. Bind the key/limit/window/store with
+ * [`rateLimit.server(def, { key, limit, window })`](./server).
+ *
+ * @typeParam R - inferred from `requires`; their context types flow into the
+ *   server-side `key`/`skip`/`message`.
+ */
+declare function rateLimit<const R extends readonly AnyMiddleware[] = readonly []>(opts?: RateLimitDefOptions<R>): RateLimitDef<R>;
+/** The def type a {@link rateLimit} call produces — what `rateLimit.server` binds against. */
+type RateLimitDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<{
+  ratelimit: RateLimitInfo;
+}, R>;
+/** Options for {@link rateLimitedDoer} — a {@link LimiterOptions} plus doer-specific knobs. */
+interface RateLimitedDoerOptions extends LimiterOptions {
+  /** Limit key — a single shared bucket by default (`'doer'`), or derived per task. */
+  readonly key?: string | ((opts: DoerTaskOptions) => string);
+  /** Floor on the re-check delay for deferred tasks (ms, default 50). */
+  readonly retryFloor?: number;
+  /** Clock injection (default `Date.now`). */
+  readonly now?: () => number;
+  /** The doer that actually runs admitted tasks (default {@link unlimitedDoer}). Compose policies. */
+  readonly doer?: Doer;
+  /**
+   * Observe a store error during admission (e.g. a distributed store hiccup). The drain loop
+   * never crashes on it — the task stays pending and admission is retried shortly. Off by
+   * default; it must not throw — if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+}
+/**
+ * A {@link Doer} (see `@ayepi/core/doer`) that caps the **start rate** of tasks using a
+ * standalone {@link limiter} — the same primitive (and pluggable {@link RateLimitStore}/
+ * algorithm) the {@link rateLimit} middleware uses. When the limiter admits a task it is
+ * handed to an **inner doer** (default {@link unlimitedDoer}), so you can compose a rate
+ * cap with a concurrency/ordering policy (e.g. `rateLimitedDoer({ …, doer: priorityDoer({ max: 4 }) })`).
+ * Excess tasks wait, oldest-first; a distributed store rate-limits **across a fleet**.
+ *
+ * ```ts
+ * import { rateLimitedDoer } from '@ayepi/rate'
+ * import { createWork } from '@ayepi/work'
+ *
+ * const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+ * const w = createWork({ work: [sendEmail] as const, doer })
+ * ```
+ */
+declare function rateLimitedDoer(opts: RateLimitedDoerOptions): Doer;
+/**
+ * An in-process {@link RateLimitStore} implementing all three algorithms. The
+ * default store — fine for a single instance; use a distributed store (e.g.
+ * `@ayepi/rate/redis`) to share limits across pods. Expired entries are swept
+ * lazily.
+ */
+declare function memoryStore(): RateLimitStore;
+//#endregion
+export { Algorithm, Limiter, LimiterOptions, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedDoerOptions, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import { AnyMiddleware, Json, MaybePromise, MiddlewareDef } from "@ayepi/core";
+import { Doer, DoerTaskOptions } from "@ayepi/core/doer";
+
+//#region src/index.d.ts
+
+/** The rate-limiting algorithm. */
+type Algorithm = 'fixed-window' | 'sliding-window' | 'token-bucket';
+/** Limiter state for one key, exposed to handlers (via `ctx.ratelimit`) and response headers. */
+interface RateLimitInfo {
+  /** The configured request limit for the window. */
+  readonly limit: number;
+  /** Requests (or tokens) remaining before the limit is hit. */
+  readonly remaining: number;
+  /** Milliseconds until the window/bucket resets. */
+  readonly reset: number;
+  /** Milliseconds to wait before retrying (0 when allowed). */
+  readonly retryAfter: number;
+}
+/** A store's decision for one key. */
+interface RateLimitResult extends RateLimitInfo {
+  /** Whether this request is within the limit. */
+  readonly allowed: boolean;
+}
+/** The rule a store evaluates a key against. */
+interface RateLimitRule {
+  readonly limit: number;
+  readonly window: number;
+  readonly algorithm: Algorithm;
+  /**
+   * Whether a request that is **itself rejected** (over the limit) still counts
+   * against the limit. Default `false` — rejected requests are not recorded, so a
+   * client cannot extend its own block by continuing to hammer the endpoint. Set
+   * `true` for the stricter behavior where every attempt consumes budget.
+   * (No effect on `token-bucket`, which never charges a request it can't admit.)
+   */
+  readonly countRejected?: boolean;
+}
+/**
+ * Pluggable backend that atomically records a hit and decides the outcome.
+ * Implementing the algorithm in the store keeps it correct across instances
+ * (the in-memory store is single-process; `@ayepi/rate/redis` is distributed).
+ */
+interface RateLimitStore {
+  /** Record a hit for `key` under `rule` at time `now` (ms) and return the decision. */
+  consume(key: string, rule: RateLimitRule, now: number): MaybePromise<RateLimitResult>;
+  /** Clear all state for `key` (optional). */
+  reset?(key: string): MaybePromise<void>;
+}
+/** The argument passed to `key`/`skip`/`message` — the request plus accumulated context. */
+interface RateKeyIO<Ctx extends object> {
+  readonly req: Request;
+  readonly ctx: Ctx;
+}
+/** Configuration for a standalone {@link limiter} — the base of {@link RateLimitOptions}. */
+interface LimiterOptions {
+  /** Max requests (or token-bucket capacity) per window. */
+  readonly limit: number;
+  /** Window length in milliseconds (also the token refill period). */
+  readonly window: number;
+  /** Algorithm (default `'fixed-window'`). */
+  readonly algorithm?: Algorithm;
+  /** Backend store (default an in-process {@link memoryStore}). */
+  readonly store?: RateLimitStore;
+  /** Key prefix/namespace (default `'rl:'`). */
+  readonly prefix?: string;
+  /**
+   * Count requests that are themselves rejected (over-limit) against the limit.
+   * Default `false` — see {@link RateLimitRule.countRejected}.
+   */
+  readonly countRejected?: boolean;
+}
+/** Response customization shared by {@link rateLimitResponse} and {@link rateLimit}. */
+interface RateLimitResponseOptions {
+  /** Over-limit status code (default `429`). */
+  readonly status?: number;
+  /** Over-limit body — a string, a JSON value, or a function of the limiter info. */
+  readonly message?: string | Json | ((info: RateLimitInfo) => string | Json);
+  /**
+   * Response headers. `true` (default) emits draft `RateLimit-Limit`/`-Remaining`/
+   * `-Reset` — plus `Retry-After` **only when the request was rejected**; `false`
+   * emits none; a function returns your own map.
+   */
+  readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
+}
+/**
+ * Options for the {@link rateLimit} **def** — frontend-safe only.
+ *
+ * @typeParam R - middleware this one depends on (their context is typed in the
+ *   server-side `key`/`skip`).
+ */
+interface RateLimitDefOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware this one depends on — their context is available (and typed) in `key`/`skip`. */
+  readonly requires?: R;
+  /** Middleware name for docs/debugging (default `'rateLimit'`). */
+  readonly name?: string;
+}
+/** A reusable rate limiter bound to a rule + store — usable anywhere, not just middleware. */
+interface Limiter {
+  /** Record a hit for `key` (at `now`, default `Date.now()`) and return the decision. */
+  check(key: string, now?: number): MaybePromise<RateLimitResult>;
+  /** Clear all state for `key`. */
+  reset(key: string): MaybePromise<void>;
+  /** The rule this limiter enforces. */
+  readonly rule: RateLimitRule;
+}
+/**
+ * Create a standalone {@link Limiter} — the rate-limit primitive the
+ * {@link rateLimit} middleware is built on. Use it anywhere you have a key: a
+ * plain handler, a queue/cron worker, a CLI, a different framework.
+ *
+ * ```ts
+ * const lim = limiter({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+ * const { allowed, retryAfter } = await lim.check(userId)
+ * if (!allowed) throw reject(429, 'RATE_LIMITED', `retry in ${retryAfter}ms`)
+ * ```
+ */
+declare function limiter(opts: LimiterOptions): Limiter;
+/**
+ * Compute the rate-limit response headers for `info`. `true` (default) emits the
+ * draft `RateLimit-Limit`/`-Remaining`/`-Reset` headers — plus `Retry-After` **only
+ * when the request was rejected** (`retryAfter > 0`); `false` emits none; a function
+ * returns your own map (which **replaces** the defaults).
+ *
+ * Shared by {@link rateLimitResponse} (the 429) and the middleware's `alwaysHeaders`
+ * option (informational headers on allowed responses).
+ */
+declare function rateLimitHeaders(info: RateLimitInfo, headers?: boolean | ((info: RateLimitInfo) => Record<string, string>)): Record<string, string>;
+/**
+ * Build a rate-limit (429) `Response` from limiter info — usable on its own,
+ * outside any middleware (e.g. from a handler that called {@link limiter} directly).
+ */
+declare function rateLimitResponse(info: RateLimitInfo, opts?: RateLimitResponseOptions): Response;
+/**
+ * Create a rate-limiting middleware **def**. The def declares what the middleware
+ * contributes (`{ ratelimit: RateLimitInfo }`) and its dependencies — but **no**
+ * policy. Bind the key/limit/window/store with
+ * [`rateLimit.server(def, { key, limit, window })`](./server).
+ *
+ * @typeParam R - inferred from `requires`; their context types flow into the
+ *   server-side `key`/`skip`/`message`.
+ */
+declare function rateLimit<const R extends readonly AnyMiddleware[] = readonly []>(opts?: RateLimitDefOptions<R>): RateLimitDef<R>;
+/** The def type a {@link rateLimit} call produces — what `rateLimit.server` binds against. */
+type RateLimitDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<{
+  ratelimit: RateLimitInfo;
+}, R>;
+/** Options for {@link rateLimitedDoer} — a {@link LimiterOptions} plus doer-specific knobs. */
+interface RateLimitedDoerOptions extends LimiterOptions {
+  /** Limit key — a single shared bucket by default (`'doer'`), or derived per task. */
+  readonly key?: string | ((opts: DoerTaskOptions) => string);
+  /** Floor on the re-check delay for deferred tasks (ms, default 50). */
+  readonly retryFloor?: number;
+  /** Clock injection (default `Date.now`). */
+  readonly now?: () => number;
+  /** The doer that actually runs admitted tasks (default {@link unlimitedDoer}). Compose policies. */
+  readonly doer?: Doer;
+  /**
+   * Observe a store error during admission (e.g. a distributed store hiccup). The drain loop
+   * never crashes on it — the task stays pending and admission is retried shortly. Off by
+   * default; it must not throw — if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+}
+/**
+ * A {@link Doer} (see `@ayepi/core/doer`) that caps the **start rate** of tasks using a
+ * standalone {@link limiter} — the same primitive (and pluggable {@link RateLimitStore}/
+ * algorithm) the {@link rateLimit} middleware uses. When the limiter admits a task it is
+ * handed to an **inner doer** (default {@link unlimitedDoer}), so you can compose a rate
+ * cap with a concurrency/ordering policy (e.g. `rateLimitedDoer({ …, doer: priorityDoer({ max: 4 }) })`).
+ * Excess tasks wait, oldest-first; a distributed store rate-limits **across a fleet**.
+ *
+ * ```ts
+ * import { rateLimitedDoer } from '@ayepi/rate'
+ * import { createWork } from '@ayepi/work'
+ *
+ * const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
+ * const w = createWork({ work: [sendEmail] as const, doer })
+ * ```
+ */
+declare function rateLimitedDoer(opts: RateLimitedDoerOptions): Doer;
+/**
+ * An in-process {@link RateLimitStore} implementing all three algorithms. The
+ * default store — fine for a single instance; use a distributed store (e.g.
+ * `@ayepi/rate/redis`) to share limits across pods. Expired entries are swept
+ * lazily.
+ */
+declare function memoryStore(): RateLimitStore;
+//#endregion
+export { Algorithm, Limiter, LimiterOptions, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedDoerOptions, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };