@lunora/ratelimit 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/index.d.mts

@@ -1,61 +1,158 @@
 import { Middleware, Plugin } from '@lunora/server';
 import { Id } from '@lunora/values';
 import { LunoraError } from '@lunora/errors';
+/** Rate-limit algorithm. */
 type RateLimitKind = "fixed window" | "sliding window" | "token bucket";
+/** Why a request was denied. */
 type RateLimitReason = "deny" | "rate";
+/** Definition of a single named rate limit. */
 interface RateLimitConfig {
+  /**
+   * Maximum tokens that can accumulate (the rollover ceiling). Defaults to
+   * `rate`: for a token bucket that caps a burst at one period's worth of
+   * tokens, and for a fixed window it disables cross-window rollover. Ignored
+   * by sliding windows, which always cap at `rate` per `period`.
+   */
   capacity?: number;
   kind: RateLimitKind;
+  /** Window/refill period in milliseconds. */
   period: number;
+  /** Tokens granted per `period`. */
   rate: number;
+  /**
+   * Split a hot limit across N independent sub-buckets to avoid a single
+   * contended key/Durable Object. Each shard enforces `rate / shards` (and
+   * `capacity / shards`); a request is routed to a shard via a deterministic
+   * hash of `(name, key)`, so the same key always lands on the same shard and
+   * a single key's effective throughput is exactly `rate / shards`. Aggregate
+   * throughput across many distinct keys approaches `rate` as keys spread
+   * uniformly across shards. Reserve it for high-volume limits where
+   * contention bites; leave unset (one bucket) otherwise. Must be a positive
+   * integer — `1` is equivalent to unset.
+   */
   shards?: number;
+  /**
+   * Phase offset in epoch milliseconds for windowed algorithms — windows
+   * align to `start + n * period`. Ignored by token buckets. Defaults to `0`.
+   */
   start?: number;
 }
+/** A map of limit name to its config, used to construct a `RateLimiter`. */
 type RateLimitConfigMap<Names extends string = string> = Record<Names, RateLimitConfig>;
+/** Persisted accounting state for one `(name, key)` pair. */
 interface RateLimitValue {
+  /**
+   * Sliding window only: request count from the previous window, used to
+   * weight the current estimate. Unset for token-bucket / fixed-window.
+   */
   prev?: number;
+  /**
+   * Token-bucket: timestamp of the last refill. Fixed/sliding window: start of
+   * the window the value belongs to.
+   */
   ts: number;
+  /**
+   * Tokens available (token bucket), tokens remaining in the window (fixed
+   * window), or requests made in the current window (sliding window).
+   * Fractional for token buckets; negative when reserved ahead.
+   */
   value: number;
 }
+/** Outcome of a `RateLimiter.limit` / `RateLimiter.check` call. */
 interface RateLimitStatus {
+  /** Whether the request is permitted. */
   ok: boolean;
+  /** Why the request was denied. Absent when `ok`. */
   reason?: RateLimitReason;
+  /** Milliseconds until the request would succeed. `0` when `ok` without reservation. */
   retryAfter: number;
 }
+/** Per-call options for `RateLimiter.limit`. */
 interface RateLimitArgs {
+  /** Units to consume. Defaults to `1`. */
   count?: number;
+  /** Sub-key isolating the limit (per user/team/IP). Omit for a global limit. */
   key?: string;
+  /**
+   * Permit the request even when capacity is insufficient, reserving future
+   * capacity (the stored value goes negative). `retryAfter` then reports when
+   * the debt clears. Rejected only when `count` exceeds the bucket capacity.
+   */
   reserve?: boolean;
+  /** Throw `RateLimitError` instead of returning a failing status. */
   throws?: boolean;
 }
+/**
+ * Pluggable persistence. Reads and writes are keyed by an opaque storage key
+ * the limiter derives from the limit name and `key`. Implementations may be
+ * synchronous (in-memory) or asynchronous (SQLite/KV); the limiter awaits
+ * either.
+ */
 interface RateLimitStore {
   delete: (storageKey: string) => Promise<void> | void;
   get: (storageKey: string) => Promise<RateLimitValue | undefined> | RateLimitValue | undefined;
   set: (storageKey: string, value: RateLimitValue) => Promise<void> | void;
 }
+/** Inputs to {@link evaluate}. */
 interface EvaluateOptions {
+  /** When `false`, compute status without consuming (a `check`). */
   consume: boolean;
+  /** Units requested. */
   count: number;
+  /** Current time in epoch milliseconds. */
   now: number;
+  /** Permit a deficit by reserving future capacity (token bucket / within-window). */
   reserve: boolean;
 }
+/** Result of evaluating a limit against its prior state. */
 interface EvaluateResult {
   status: RateLimitStatus;
+  /** Next value to persist, or `undefined` when the call must not mutate state. */
   value: RateLimitValue | undefined;
 }
+/**
+ * Project a limit's stored state forward to `now` without consuming: how many
+ * units could be admitted right now. Token bucket → the refilled token count;
+ * fixed window → tokens left in the current (possibly rolled-over) window;
+ * sliding window → `rate` minus the weighted estimate, floored at zero. Pure,
+ * like {@link evaluate}, and shares its per-algorithm projection helpers so the
+ * two never diverge. Backs `RateLimiter.getValue` so it reports a live figure
+ * rather than the last value that happened to be persisted.
+ */
 declare const availableAt: (config: RateLimitConfig, prior: RateLimitValue | undefined, now: number) => {
   ts: number;
   value: number;
 };
+/**
+ * Evaluate a request against a limit's prior state. Pure: it never reads a
+ * clock or persists — the caller supplies `now` and writes back `value` when
+ * it is not `undefined`.
+ */
 declare const evaluate: (config: RateLimitConfig, prior: RateLimitValue | undefined, options: EvaluateOptions) => EvaluateResult;
 interface RateLimiterOptions<Names extends string> {
   config: RateLimitConfigMap<Names>;
+  /** Keys that are always denied, regardless of limit state. */
   denyList?: Iterable<string>;
+  /**
+   * Optional key normalizer applied to every incoming `args.key` (the
+   * deny-list check, the storage key, and downstream shard selection all see
+   * the normalized form). Use for case-folding, trimming, or canonicalizing
+   * IPs/emails so equivalent inputs share a single bucket. The deny-list
+   * itself is consulted as-is; normalize the deny-list entries up front to
+   * match.
+   */
   normalize?: (key: string) => string;
+  /** Clock injection for tests. Defaults to `Date.now`. */
   now?: () => number;
-  random?: () => number;
+  /** Persistence. Defaults to a per-instance in-memory store. */
   store?: RateLimitStore;
 }
+/**
+ * Enforces named rate limits over a pluggable store. Construct one per app with
+ * a config map; call {@link RateLimiter.limit} to consume and
+ * {@link RateLimiter.check} to peek. Framework-agnostic — the `@lunora/ratelimit`
+ * middleware wraps it for procedures.
+ */
 declare class RateLimiter<Names extends string = string> {
   private readonly config;
   private readonly denyList;
@@ -63,7 +160,16 @@ declare class RateLimiter<Names extends string = string> {
   private readonly now;
   private readonly store;
   constructor(options: RateLimiterOptions<Names>);
+  /** Peek at whether a request would be permitted without consuming. */
   check(name: Names, args?: Omit<RateLimitArgs, "reserve" | "throws">): Promise<RateLimitStatus>;
+  /**
+   * Read the current config and the units admittable right now for a
+   * `(name, key)` pair. The value is projected forward to the current clock
+   * (token-bucket refill, fixed-window rollover, sliding-window decay), not
+   * the last persisted figure. For a sharded limit it reads only the single
+   * shard `limit()`/`run()` would route this key to — the sibling shards are
+   * never touched by this key, so summing them would over-report.
+   */
   getValue(name: Names, args?: {
     key?: string;
   }): Promise<{
@@ -71,22 +177,65 @@ declare class RateLimiter<Names extends string = string> {
     ts: number;
     value: number;
   }>;
+  /** Consume capacity. Returns the outcome, or throws when `args.throws` is set. */
   limit(name: Names, args?: RateLimitArgs): Promise<RateLimitStatus>;
+  /** Clear accounting for a `(name, key)` pair (e.g. on successful login). */
   reset(name: Names, args?: {
     key?: string;
   }): Promise<void>;
   private resolve;
   private run;
 }
+/**
+ * Either a fixed {@link RateLimiter} or a function that derives one from `ctx`
+ * — the latter lets a procedure bind a durable, ORM-backed limiter at call time
+ * (e.g. `(ctx) => new RateLimiter({ config, store: createDbStore({ db: ctx.db }) })`).
+ */
 type LimiterResolver<Context> = ((context: Context) => Promise<RateLimiter> | RateLimiter) | RateLimiter;
 interface RateLimitMiddlewareOptions<Context> {
+  /** Units to consume per call. Defaults to `1`. */
   count?: number;
+  /**
+   * Behavior when the limiter itself throws (store unavailable, etc).
+   * Defaults to `false` (fail closed: deny the request with a 503). Set to
+   * `true` only when degraded availability is preferable to denying traffic
+   * — note that a failing limiter then permits every request through.
+   */
   failOpen?: boolean;
+  /** Sub-key derived from `ctx` (per-user/IP). Omit for a global limit. */
   key?: (context: Context) => string | undefined;
+  /** Override the error message thrown on rejection. */
   message?: string;
 }
+/**
+ * Procedure middleware that enforces a named rate limit before the handler
+ * runs. Attach it with `.use()`. On rejection it throws a structural
+ * `LunoraError` (`TOO_MANY_REQUESTS`/429, or `FORBIDDEN`/403 for deny-list
+ * hits) carrying `retryAfter` in milliseconds — the runtime maps it to the
+ * matching RPC/HTTP status without any import of `@lunora/server` at runtime.
+ *
+ * **Failure policy:** if resolving or invoking the limiter throws for a genuine
+ * availability reason (e.g. the persistence store is unavailable), the
+ * middleware **fails closed by default**: it logs via `console.error` and
+ * rejects the request with `503`. This is the safer default for
+ * security-sensitive limits (auth, account creation). Pass `failOpen: true` to
+ * swallow the error and admit the request instead — appropriate only when
+ * degraded availability is preferable to refusal. Deterministic caller misuse
+ * (an unconfigured limit name, a non-positive count, or a count that exceeds
+ * capacity) throws an `INTERNAL` `LunoraError` that is re-thrown as-is under
+ * **both** policies — a config bug is never masked as a 503 or silently admitted.
+ */
 declare const rateLimit: <Context>(limiter: LimiterResolver<Context>, name: string, options?: RateLimitMiddlewareOptions<Context>) => Middleware<Context, Context>;
+/**
+ * In-memory store. State lives for the lifetime of the process (or, inside a
+ * Durable Object, the instance) — adequate for single-DO limits but not shared
+ * across instances. Use {@link createSqlStore} for durable per-DO state.
+ */
 declare const createMemoryStore: () => RateLimitStore;
+/**
+ * Minimal projection of `state.storage.sql` (workerd's `SqlStorage`, also
+ * satisfied by `node:sqlite`). Only the `exec` overload is required.
+ */
 interface SqlLike {
   exec: <Row = Record<string, unknown>>(query: string, ...params: unknown[]) => {
     toArray: () => Row[];
@@ -94,9 +243,29 @@ interface SqlLike {
 }
 interface SqlStoreOptions {
   sql: SqlLike;
+  /** Table name. Created if missing. Defaults to `_lunora_rate_limits`. */
   table?: string;
 }
+/**
+ * SQLite-backed store for durable, per-DO rate-limit state. Persists each
+ * `(name, key)` pair as one row so limits survive hibernation and eviction.
+ *
+ * **Atomicity:** the store does not wrap individual operations in an explicit
+ * SQL transaction. Inside a Durable Object the DO's input gate serializes
+ * every RPC call against the storage, so the limiter's read-modify-write
+ * sequence runs to completion without interleaving — this is the same
+ * guarantee the surrounding `evaluate()` step depends on. **Outside a DO**
+ * (e.g. driving `createSqlStore` from a long-lived `node:sqlite` connection in
+ * tests or a custom host) the caller is responsible for serialization; the
+ * SQL surface used here (`exec`) is not a substitute for transactional
+ * isolation across concurrent invocations.
+ */
 declare const createSqlStore: (options: SqlStoreOptions) => RateLimitStore;
+/**
+ * The slice of an index-range builder the store uses. Mirrors `@lunora/server`'s
+ * `IndexRangeBuilder` field-for-field so the real `ctx.db` query builder is
+ * assignable; only `eq` is exercised.
+ */
 interface RateLimitDatabaseIndexRange {
   eq: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
   gt: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
@@ -104,10 +273,17 @@ interface RateLimitDatabaseIndexRange {
   lt: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
   lte: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
 }
+/** The slice of a `ctx.db` table query the store relies on. */
 interface RateLimitDatabaseQuery {
   first: () => Promise<Record<string, unknown> | null>;
   withIndex: (indexName: string, range: (q: RateLimitDatabaseIndexRange) => RateLimitDatabaseIndexRange) => RateLimitDatabaseQuery;
 }
+/**
+ * The slice of the Lunora ORM writer (`ctx.db` on a mutation/action) the store
+ * needs. The real `DatabaseWriter` is structurally assignable, so pass `ctx.db`
+ * directly — declared here (rather than imported) to keep `@lunora/ratelimit`
+ * free of a runtime dependency on `@lunora/server`.
+ */
 interface RateLimitDatabase {
   delete: <T extends string>(id: Id<T>) => Promise<void>;
   insert: <T extends string>(table: T, document: Record<string, unknown>) => Promise<Id<T>>;
@@ -115,22 +291,82 @@ interface RateLimitDatabase {
   query: (table: string) => RateLimitDatabaseQuery;
 }
 interface DatabaseStoreOptions {
+  /** The Lunora ORM writer — `ctx.db` inside a mutation or action. */
   db: RateLimitDatabase;
+  /** Index that resolves a row by its key column. Defaults to `by_key`. */
   index?: string;
+  /** Column storing the opaque key. Defaults to `key`. */
   keyField?: string;
+  /** Table holding one row per `(name, key)` pair. Defaults to `rateLimits`. */
   table?: string;
 }
+/**
+ * Store backed by a Lunora table through `ctx.db`, for durable per-DO limits
+ * inside a procedure (the procedure context exposes no raw SQL). Declare a
+ * table with the key column and its index, e.g.
+ *
+ * ```ts
+ * rateLimits: defineTable({
+ *     key: v.string(),
+ *     ts: v.number(),
+ *     value: v.number(),
+ *     prev: v.optional(v.number()),
+ * }).index("by_key", ["key"])
+ * ```
+ *
+ * Each operation is a read-then-write; inside a mutation/action that pair runs
+ * under the DO's input gate, so it is atomic against concurrent calls.
+ */
 declare const createDatabaseStore: (options: DatabaseStoreOptions) => RateLimitStore;
+/**
+ * DB-backed rate-limit middleware sugar. Collapses the common
+ *
+ * ```ts
+ * rateLimit((ctx) => new RateLimiter({ config, store: createDbStore({ db: ctx.db }) }), name, opts)
+ * ```
+ *
+ * into `dbRateLimit(config, name, opts)`: it builds a per-call {@link RateLimiter}
+ * whose accounting lives in a Lunora table via `ctx.db` (so the bucket is durable
+ * on the DO the procedure runs on). Every query/mutation/action ctx exposes a
+ * compatible `db`, so it slots straight into a `.use(...)` chain.
+ *
+ * Pass `options.store` to point at a non-default backing table/index/key column
+ * (defaults: table `rateLimits`, index `by_key`, key column `key`); the rest of
+ * `options` (`key`, `count`, `failOpen`, `message`) is forwarded to
+ * {@link rateLimit} unchanged. When `config` is precisely typed, `name`
+ * autocompletes to its declared limit names.
+ *
+ * Re-exported as `dbRateLimit` from the package root.
+ *
+ * ```ts
+ * const limits = { send: { kind: "token bucket", period: 60_000, rate: 30 } } satisfies RateLimitConfigMap;
+ *
+ * export const send = mutation
+ *   .input({ text: v.string() })
+ *   .use(dbRateLimit(limits, "send", { key: (ctx) => ctx.auth.userId ?? "anonymous" }))
+ *   .mutation(async ({ ctx, args }) => ...);
+ * ```
+ */
 declare const databaseRateLimit: <Context extends {
   db: RateLimitDatabase;
 }, Names extends string = string>(config: RateLimitConfigMap<Names>, name: Names, options?: RateLimitMiddlewareOptions<Context> & {
   store?: Omit<DatabaseStoreOptions, "db">;
 }) => Middleware<Context, Context>;
+/**
+ * Thrown by `RateLimiter.limit` when called with `{ throws: true }`. A
+ * `LunoraError` subclass whose code/status track `status.reason`: a rate
+ * rejection is `TOO_MANY_REQUESTS`/429, a deny-list hit is `FORBIDDEN`/403 —
+ * the same mapping the middleware applies, so both entry points surface the
+ * identical wire code (a permanent deny is never a retryable 429). The
+ * middleware itself throws a bare structural `LunoraError`, so this is for
+ * direct callers that prefer exceptions. Keeps `reason`/`retryAfter`.
+ */
 declare class RateLimitError extends LunoraError {
   readonly reason: RateLimitReason | undefined;
   readonly retryAfter: number;
   constructor(status: RateLimitStatus, message?: string);
 }
+/** Context shape the plugin middleware widens to: a `ratelimit` limiter on `ctx.api`. */
 interface RatelimitApiContext<Context> {
   api: (Context extends {
     api: infer A;
@@ -138,6 +374,36 @@ interface RatelimitApiContext<Context> {
     ratelimit: RateLimiter;
   };
 }
+/**
+ * Package `@lunora/ratelimit` as a first-party {@link Plugin}, the dogfooded
+ * form of the plugin contract: instead of (or alongside) the enforcing
+ * `rateLimit(...)` middleware, this exposes the resolved {@link RateLimiter}
+ * under `ctx.api.ratelimit` so a handler can `limit()`/`check()`/`reset()`
+ * programmatically.
+ *
+ * Install the middleware with one `.use(...)` (or fold it in with
+ * `composePluginMiddleware([...])`):
+ *
+ * ```ts
+ * const limiter = new RateLimiter({ config: { send: { kind: "token bucket", rate: 5, period: 60_000, capacity: 5 } } });
+ * const c = initLunora.dataModel&lt;DataModel>().create();
+ * export const send = c.mutation
+ *     .use(ratelimitPlugin(limiter).middleware!)
+ *     .mutation(async ({ ctx, args }) => {
+ *         const status = await ctx.api.ratelimit.limit("send", { key: ctx.userId });
+ *         if (!status.ok) throw new Error("slow down");
+ *         // …
+ *     });
+ * ```
+ *
+ * The plugin ships no schema extension — the limiter's persistence is whatever
+ * store the resolved {@link RateLimiter} was built with — so it is a
+ * middleware-only plugin and is skipped by `installPlugins(...)`'s schema fold.
+ *
+ * Built as a plain {@link Plugin} literal (the key is the fixed string
+ * `"ratelimit"`, so the `definePlugin` validation adds nothing) — this keeps
+ * `@lunora/server` a type-only dependency of `@lunora/ratelimit`.
+ */
 declare const ratelimitPlugin: <Context = unknown>(limiter: LimiterResolver<Context>) => Plugin<Record<never, never>, Context, Context & RatelimitApiContext<Context>>;
 declare const VERSION = "0.0.0";
 export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type SqlLike, type SqlStoreOptions, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin };

package/dist/index.d.ts

@@ -1,61 +1,158 @@
 import { Middleware, Plugin } from '@lunora/server';
 import { Id } from '@lunora/values';
 import { LunoraError } from '@lunora/errors';
+/** Rate-limit algorithm. */
 type RateLimitKind = "fixed window" | "sliding window" | "token bucket";
+/** Why a request was denied. */
 type RateLimitReason = "deny" | "rate";
+/** Definition of a single named rate limit. */
 interface RateLimitConfig {
+  /**
+   * Maximum tokens that can accumulate (the rollover ceiling). Defaults to
+   * `rate`: for a token bucket that caps a burst at one period's worth of
+   * tokens, and for a fixed window it disables cross-window rollover. Ignored
+   * by sliding windows, which always cap at `rate` per `period`.
+   */
   capacity?: number;
   kind: RateLimitKind;
+  /** Window/refill period in milliseconds. */
   period: number;
+  /** Tokens granted per `period`. */
   rate: number;
+  /**
+   * Split a hot limit across N independent sub-buckets to avoid a single
+   * contended key/Durable Object. Each shard enforces `rate / shards` (and
+   * `capacity / shards`); a request is routed to a shard via a deterministic
+   * hash of `(name, key)`, so the same key always lands on the same shard and
+   * a single key's effective throughput is exactly `rate / shards`. Aggregate
+   * throughput across many distinct keys approaches `rate` as keys spread
+   * uniformly across shards. Reserve it for high-volume limits where
+   * contention bites; leave unset (one bucket) otherwise. Must be a positive
+   * integer — `1` is equivalent to unset.
+   */
   shards?: number;
+  /**
+   * Phase offset in epoch milliseconds for windowed algorithms — windows
+   * align to `start + n * period`. Ignored by token buckets. Defaults to `0`.
+   */
   start?: number;
 }
+/** A map of limit name to its config, used to construct a `RateLimiter`. */
 type RateLimitConfigMap<Names extends string = string> = Record<Names, RateLimitConfig>;
+/** Persisted accounting state for one `(name, key)` pair. */
 interface RateLimitValue {
+  /**
+   * Sliding window only: request count from the previous window, used to
+   * weight the current estimate. Unset for token-bucket / fixed-window.
+   */
   prev?: number;
+  /**
+   * Token-bucket: timestamp of the last refill. Fixed/sliding window: start of
+   * the window the value belongs to.
+   */
   ts: number;
+  /**
+   * Tokens available (token bucket), tokens remaining in the window (fixed
+   * window), or requests made in the current window (sliding window).
+   * Fractional for token buckets; negative when reserved ahead.
+   */
   value: number;
 }
+/** Outcome of a `RateLimiter.limit` / `RateLimiter.check` call. */
 interface RateLimitStatus {
+  /** Whether the request is permitted. */
   ok: boolean;
+  /** Why the request was denied. Absent when `ok`. */
   reason?: RateLimitReason;
+  /** Milliseconds until the request would succeed. `0` when `ok` without reservation. */
   retryAfter: number;
 }
+/** Per-call options for `RateLimiter.limit`. */
 interface RateLimitArgs {
+  /** Units to consume. Defaults to `1`. */
   count?: number;
+  /** Sub-key isolating the limit (per user/team/IP). Omit for a global limit. */
   key?: string;
+  /**
+   * Permit the request even when capacity is insufficient, reserving future
+   * capacity (the stored value goes negative). `retryAfter` then reports when
+   * the debt clears. Rejected only when `count` exceeds the bucket capacity.
+   */
   reserve?: boolean;
+  /** Throw `RateLimitError` instead of returning a failing status. */
   throws?: boolean;
 }
+/**
+ * Pluggable persistence. Reads and writes are keyed by an opaque storage key
+ * the limiter derives from the limit name and `key`. Implementations may be
+ * synchronous (in-memory) or asynchronous (SQLite/KV); the limiter awaits
+ * either.
+ */
 interface RateLimitStore {
   delete: (storageKey: string) => Promise<void> | void;
   get: (storageKey: string) => Promise<RateLimitValue | undefined> | RateLimitValue | undefined;
   set: (storageKey: string, value: RateLimitValue) => Promise<void> | void;
 }
+/** Inputs to {@link evaluate}. */
 interface EvaluateOptions {
+  /** When `false`, compute status without consuming (a `check`). */
   consume: boolean;
+  /** Units requested. */
   count: number;
+  /** Current time in epoch milliseconds. */
   now: number;
+  /** Permit a deficit by reserving future capacity (token bucket / within-window). */
   reserve: boolean;
 }
+/** Result of evaluating a limit against its prior state. */
 interface EvaluateResult {
   status: RateLimitStatus;
+  /** Next value to persist, or `undefined` when the call must not mutate state. */
   value: RateLimitValue | undefined;
 }
+/**
+ * Project a limit's stored state forward to `now` without consuming: how many
+ * units could be admitted right now. Token bucket → the refilled token count;
+ * fixed window → tokens left in the current (possibly rolled-over) window;
+ * sliding window → `rate` minus the weighted estimate, floored at zero. Pure,
+ * like {@link evaluate}, and shares its per-algorithm projection helpers so the
+ * two never diverge. Backs `RateLimiter.getValue` so it reports a live figure
+ * rather than the last value that happened to be persisted.
+ */
 declare const availableAt: (config: RateLimitConfig, prior: RateLimitValue | undefined, now: number) => {
   ts: number;
   value: number;
 };
+/**
+ * Evaluate a request against a limit's prior state. Pure: it never reads a
+ * clock or persists — the caller supplies `now` and writes back `value` when
+ * it is not `undefined`.
+ */
 declare const evaluate: (config: RateLimitConfig, prior: RateLimitValue | undefined, options: EvaluateOptions) => EvaluateResult;
 interface RateLimiterOptions<Names extends string> {
   config: RateLimitConfigMap<Names>;
+  /** Keys that are always denied, regardless of limit state. */
   denyList?: Iterable<string>;
+  /**
+   * Optional key normalizer applied to every incoming `args.key` (the
+   * deny-list check, the storage key, and downstream shard selection all see
+   * the normalized form). Use for case-folding, trimming, or canonicalizing
+   * IPs/emails so equivalent inputs share a single bucket. The deny-list
+   * itself is consulted as-is; normalize the deny-list entries up front to
+   * match.
+   */
   normalize?: (key: string) => string;
+  /** Clock injection for tests. Defaults to `Date.now`. */
   now?: () => number;
-  random?: () => number;
+  /** Persistence. Defaults to a per-instance in-memory store. */
   store?: RateLimitStore;
 }
+/**
+ * Enforces named rate limits over a pluggable store. Construct one per app with
+ * a config map; call {@link RateLimiter.limit} to consume and
+ * {@link RateLimiter.check} to peek. Framework-agnostic — the `@lunora/ratelimit`
+ * middleware wraps it for procedures.
+ */
 declare class RateLimiter<Names extends string = string> {
   private readonly config;
   private readonly denyList;
@@ -63,7 +160,16 @@ declare class RateLimiter<Names extends string = string> {
   private readonly now;
   private readonly store;
   constructor(options: RateLimiterOptions<Names>);
+  /** Peek at whether a request would be permitted without consuming. */
   check(name: Names, args?: Omit<RateLimitArgs, "reserve" | "throws">): Promise<RateLimitStatus>;
+  /**
+   * Read the current config and the units admittable right now for a
+   * `(name, key)` pair. The value is projected forward to the current clock
+   * (token-bucket refill, fixed-window rollover, sliding-window decay), not
+   * the last persisted figure. For a sharded limit it reads only the single
+   * shard `limit()`/`run()` would route this key to — the sibling shards are
+   * never touched by this key, so summing them would over-report.
+   */
   getValue(name: Names, args?: {
     key?: string;
   }): Promise<{
@@ -71,22 +177,65 @@ declare class RateLimiter<Names extends string = string> {
     ts: number;
     value: number;
   }>;
+  /** Consume capacity. Returns the outcome, or throws when `args.throws` is set. */
   limit(name: Names, args?: RateLimitArgs): Promise<RateLimitStatus>;
+  /** Clear accounting for a `(name, key)` pair (e.g. on successful login). */
   reset(name: Names, args?: {
     key?: string;
   }): Promise<void>;
   private resolve;
   private run;
 }
+/**
+ * Either a fixed {@link RateLimiter} or a function that derives one from `ctx`
+ * — the latter lets a procedure bind a durable, ORM-backed limiter at call time
+ * (e.g. `(ctx) => new RateLimiter({ config, store: createDbStore({ db: ctx.db }) })`).
+ */
 type LimiterResolver<Context> = ((context: Context) => Promise<RateLimiter> | RateLimiter) | RateLimiter;
 interface RateLimitMiddlewareOptions<Context> {
+  /** Units to consume per call. Defaults to `1`. */
   count?: number;
+  /**
+   * Behavior when the limiter itself throws (store unavailable, etc).
+   * Defaults to `false` (fail closed: deny the request with a 503). Set to
+   * `true` only when degraded availability is preferable to denying traffic
+   * — note that a failing limiter then permits every request through.
+   */
   failOpen?: boolean;
+  /** Sub-key derived from `ctx` (per-user/IP). Omit for a global limit. */
   key?: (context: Context) => string | undefined;
+  /** Override the error message thrown on rejection. */
   message?: string;
 }
+/**
+ * Procedure middleware that enforces a named rate limit before the handler
+ * runs. Attach it with `.use()`. On rejection it throws a structural
+ * `LunoraError` (`TOO_MANY_REQUESTS`/429, or `FORBIDDEN`/403 for deny-list
+ * hits) carrying `retryAfter` in milliseconds — the runtime maps it to the
+ * matching RPC/HTTP status without any import of `@lunora/server` at runtime.
+ *
+ * **Failure policy:** if resolving or invoking the limiter throws for a genuine
+ * availability reason (e.g. the persistence store is unavailable), the
+ * middleware **fails closed by default**: it logs via `console.error` and
+ * rejects the request with `503`. This is the safer default for
+ * security-sensitive limits (auth, account creation). Pass `failOpen: true` to
+ * swallow the error and admit the request instead — appropriate only when
+ * degraded availability is preferable to refusal. Deterministic caller misuse
+ * (an unconfigured limit name, a non-positive count, or a count that exceeds
+ * capacity) throws an `INTERNAL` `LunoraError` that is re-thrown as-is under
+ * **both** policies — a config bug is never masked as a 503 or silently admitted.
+ */
 declare const rateLimit: <Context>(limiter: LimiterResolver<Context>, name: string, options?: RateLimitMiddlewareOptions<Context>) => Middleware<Context, Context>;
+/**
+ * In-memory store. State lives for the lifetime of the process (or, inside a
+ * Durable Object, the instance) — adequate for single-DO limits but not shared
+ * across instances. Use {@link createSqlStore} for durable per-DO state.
+ */
 declare const createMemoryStore: () => RateLimitStore;
+/**
+ * Minimal projection of `state.storage.sql` (workerd's `SqlStorage`, also
+ * satisfied by `node:sqlite`). Only the `exec` overload is required.
+ */
 interface SqlLike {
   exec: <Row = Record<string, unknown>>(query: string, ...params: unknown[]) => {
     toArray: () => Row[];
@@ -94,9 +243,29 @@ interface SqlLike {
 }
 interface SqlStoreOptions {
   sql: SqlLike;
+  /** Table name. Created if missing. Defaults to `_lunora_rate_limits`. */
   table?: string;
 }
+/**
+ * SQLite-backed store for durable, per-DO rate-limit state. Persists each
+ * `(name, key)` pair as one row so limits survive hibernation and eviction.
+ *
+ * **Atomicity:** the store does not wrap individual operations in an explicit
+ * SQL transaction. Inside a Durable Object the DO's input gate serializes
+ * every RPC call against the storage, so the limiter's read-modify-write
+ * sequence runs to completion without interleaving — this is the same
+ * guarantee the surrounding `evaluate()` step depends on. **Outside a DO**
+ * (e.g. driving `createSqlStore` from a long-lived `node:sqlite` connection in
+ * tests or a custom host) the caller is responsible for serialization; the
+ * SQL surface used here (`exec`) is not a substitute for transactional
+ * isolation across concurrent invocations.
+ */
 declare const createSqlStore: (options: SqlStoreOptions) => RateLimitStore;
+/**
+ * The slice of an index-range builder the store uses. Mirrors `@lunora/server`'s
+ * `IndexRangeBuilder` field-for-field so the real `ctx.db` query builder is
+ * assignable; only `eq` is exercised.
+ */
 interface RateLimitDatabaseIndexRange {
   eq: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
   gt: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
@@ -104,10 +273,17 @@ interface RateLimitDatabaseIndexRange {
   lt: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
   lte: (field: string, value: unknown) => RateLimitDatabaseIndexRange;
 }
+/** The slice of a `ctx.db` table query the store relies on. */
 interface RateLimitDatabaseQuery {
   first: () => Promise<Record<string, unknown> | null>;
   withIndex: (indexName: string, range: (q: RateLimitDatabaseIndexRange) => RateLimitDatabaseIndexRange) => RateLimitDatabaseQuery;
 }
+/**
+ * The slice of the Lunora ORM writer (`ctx.db` on a mutation/action) the store
+ * needs. The real `DatabaseWriter` is structurally assignable, so pass `ctx.db`
+ * directly — declared here (rather than imported) to keep `@lunora/ratelimit`
+ * free of a runtime dependency on `@lunora/server`.
+ */
 interface RateLimitDatabase {
   delete: <T extends string>(id: Id<T>) => Promise<void>;
   insert: <T extends string>(table: T, document: Record<string, unknown>) => Promise<Id<T>>;
@@ -115,22 +291,82 @@ interface RateLimitDatabase {
   query: (table: string) => RateLimitDatabaseQuery;
 }
 interface DatabaseStoreOptions {
+  /** The Lunora ORM writer — `ctx.db` inside a mutation or action. */
   db: RateLimitDatabase;
+  /** Index that resolves a row by its key column. Defaults to `by_key`. */
   index?: string;
+  /** Column storing the opaque key. Defaults to `key`. */
   keyField?: string;
+  /** Table holding one row per `(name, key)` pair. Defaults to `rateLimits`. */
   table?: string;
 }
+/**
+ * Store backed by a Lunora table through `ctx.db`, for durable per-DO limits
+ * inside a procedure (the procedure context exposes no raw SQL). Declare a
+ * table with the key column and its index, e.g.
+ *
+ * ```ts
+ * rateLimits: defineTable({
+ *     key: v.string(),
+ *     ts: v.number(),
+ *     value: v.number(),
+ *     prev: v.optional(v.number()),
+ * }).index("by_key", ["key"])
+ * ```
+ *
+ * Each operation is a read-then-write; inside a mutation/action that pair runs
+ * under the DO's input gate, so it is atomic against concurrent calls.
+ */
 declare const createDatabaseStore: (options: DatabaseStoreOptions) => RateLimitStore;
+/**
+ * DB-backed rate-limit middleware sugar. Collapses the common
+ *
+ * ```ts
+ * rateLimit((ctx) => new RateLimiter({ config, store: createDbStore({ db: ctx.db }) }), name, opts)
+ * ```
+ *
+ * into `dbRateLimit(config, name, opts)`: it builds a per-call {@link RateLimiter}
+ * whose accounting lives in a Lunora table via `ctx.db` (so the bucket is durable
+ * on the DO the procedure runs on). Every query/mutation/action ctx exposes a
+ * compatible `db`, so it slots straight into a `.use(...)` chain.
+ *
+ * Pass `options.store` to point at a non-default backing table/index/key column
+ * (defaults: table `rateLimits`, index `by_key`, key column `key`); the rest of
+ * `options` (`key`, `count`, `failOpen`, `message`) is forwarded to
+ * {@link rateLimit} unchanged. When `config` is precisely typed, `name`
+ * autocompletes to its declared limit names.
+ *
+ * Re-exported as `dbRateLimit` from the package root.
+ *
+ * ```ts
+ * const limits = { send: { kind: "token bucket", period: 60_000, rate: 30 } } satisfies RateLimitConfigMap;
+ *
+ * export const send = mutation
+ *   .input({ text: v.string() })
+ *   .use(dbRateLimit(limits, "send", { key: (ctx) => ctx.auth.userId ?? "anonymous" }))
+ *   .mutation(async ({ ctx, args }) => ...);
+ * ```
+ */
 declare const databaseRateLimit: <Context extends {
   db: RateLimitDatabase;
 }, Names extends string = string>(config: RateLimitConfigMap<Names>, name: Names, options?: RateLimitMiddlewareOptions<Context> & {
   store?: Omit<DatabaseStoreOptions, "db">;
 }) => Middleware<Context, Context>;
+/**
+ * Thrown by `RateLimiter.limit` when called with `{ throws: true }`. A
+ * `LunoraError` subclass whose code/status track `status.reason`: a rate
+ * rejection is `TOO_MANY_REQUESTS`/429, a deny-list hit is `FORBIDDEN`/403 —
+ * the same mapping the middleware applies, so both entry points surface the
+ * identical wire code (a permanent deny is never a retryable 429). The
+ * middleware itself throws a bare structural `LunoraError`, so this is for
+ * direct callers that prefer exceptions. Keeps `reason`/`retryAfter`.
+ */
 declare class RateLimitError extends LunoraError {
   readonly reason: RateLimitReason | undefined;
   readonly retryAfter: number;
   constructor(status: RateLimitStatus, message?: string);
 }
+/** Context shape the plugin middleware widens to: a `ratelimit` limiter on `ctx.api`. */
 interface RatelimitApiContext<Context> {
   api: (Context extends {
     api: infer A;
@@ -138,6 +374,36 @@ interface RatelimitApiContext<Context> {
     ratelimit: RateLimiter;
   };
 }
+/**
+ * Package `@lunora/ratelimit` as a first-party {@link Plugin}, the dogfooded
+ * form of the plugin contract: instead of (or alongside) the enforcing
+ * `rateLimit(...)` middleware, this exposes the resolved {@link RateLimiter}
+ * under `ctx.api.ratelimit` so a handler can `limit()`/`check()`/`reset()`
+ * programmatically.
+ *
+ * Install the middleware with one `.use(...)` (or fold it in with
+ * `composePluginMiddleware([...])`):
+ *
+ * ```ts
+ * const limiter = new RateLimiter({ config: { send: { kind: "token bucket", rate: 5, period: 60_000, capacity: 5 } } });
+ * const c = initLunora.dataModel&lt;DataModel>().create();
+ * export const send = c.mutation
+ *     .use(ratelimitPlugin(limiter).middleware!)
+ *     .mutation(async ({ ctx, args }) => {
+ *         const status = await ctx.api.ratelimit.limit("send", { key: ctx.userId });
+ *         if (!status.ok) throw new Error("slow down");
+ *         // …
+ *     });
+ * ```
+ *
+ * The plugin ships no schema extension — the limiter's persistence is whatever
+ * store the resolved {@link RateLimiter} was built with — so it is a
+ * middleware-only plugin and is skipped by `installPlugins(...)`'s schema fold.
+ *
+ * Built as a plain {@link Plugin} literal (the key is the fixed string
+ * `"ratelimit"`, so the `definePlugin` validation adds nothing) — this keeps
+ * `@lunora/server` a type-only dependency of `@lunora/ratelimit`.
+ */
 declare const ratelimitPlugin: <Context = unknown>(limiter: LimiterResolver<Context>) => Plugin<Record<never, never>, Context, Context & RatelimitApiContext<Context>>;
 declare const VERSION = "0.0.0";
 export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type SqlLike, type SqlStoreOptions, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/ratelimit",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.9",
   "description": "Rate limiting: token-bucket / fixed-window / sliding-window algorithms, deny list, sharding, pluggable stores, and procedure middleware",
   "keywords": [
     "cloudflare",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.4"
+    "@lunora/errors": "1.0.0-alpha.6"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"