@ayepi/rate 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -3,6 +3,10 @@ import { Doer, DoerTaskOptions } from "@ayepi/core/doer";
 
 //#region src/index.d.ts
 
+/** Default key namespace. */
+declare const DEFAULT_PREFIX = "rl:";
+/** Default algorithm. */
+declare const DEFAULT_ALGORITHM: Algorithm;
 /** 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. */
@@ -144,16 +148,68 @@ declare function rateLimit<const R extends readonly AnyMiddleware[] = readonly [
 type RateLimitDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<{
   ratelimit: RateLimitInfo;
 }, R>;
+/** Details of a sustained backlog, passed to {@link RateLimitedDoerOptions.onBacklog}. */
+interface RateLimitedBacklogInfo {
+  /** Tasks waiting on the rate limit to admit them (the queue depth). */
+  readonly pending: number;
+  /** How long the queue has been *continuously* non-empty (ms). */
+  readonly nonEmptyForMs: number;
+}
+/**
+ * Per-task options for a {@link rateLimitedDoer} — {@link DoerTaskOptions} (`group`/`priority`/
+ * `createdAt`) plus a per-request **group limit** override. When a `group` and a group limit are
+ * present, the task must clear both the global limit **and** its group's limit to be admitted.
+ */
+interface RateTaskOptions extends DoerTaskOptions {
+  /** Per-task group rate limit (a second gate, bucketed by `group`). Overrides {@link RateLimitedDoerOptions.groupLimit}. */
+  readonly groupLimit?: number;
+  /** Window for the group limit (ms; default: the global `window`). */
+  readonly groupWindow?: number;
+  /** Algorithm for the group limit (default: the global `algorithm`). */
+  readonly groupAlgorithm?: Algorithm;
+}
+/** A {@link Doer} whose `do` accepts {@link RateTaskOptions} — i.e. a per-task group limit. */
+interface RateLimitedDoer extends Doer {
+  /** Accept a task; `opts` may carry a per-task `group` + `groupLimit` (a second, per-group gate). */
+  do(task: () => Promise<void>, opts?: RateTaskOptions): void;
+}
 /** 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. */
+  /** Limit key for the **global** bucket — a single shared bucket by default (`'doer'`), or derived per task. */
   readonly key?: string | ((opts: DoerTaskOptions) => string);
+  /**
+   * Default **group** limit — a second gate bucketed by a task's `group`, on top of the global limit.
+   * A per-task {@link RateTaskOptions.groupLimit} overrides it. Omit for no group gate (global only).
+   * The group window/algorithm default to the global ones unless overridden per task.
+   */
+  readonly groupLimit?: number;
+  /** Derive a task's group bucket key (default: `opts.group`). Return `undefined` to skip the group gate for a task. */
+  readonly groupKey?: (opts: DoerTaskOptions) => string | undefined;
+  /**
+   * Store for the group buckets (default: the global `store`). A distributed store limits groups
+   * across a fleet. Groups need not be known up front — bucket state is per-group and **auto-evicted
+   * when idle** (the {@link memoryStore} sweeps expired/idle keys; `@ayepi/rate/redis` sets TTLs), so
+   * an unbounded, dynamic group space (per-user/per-model) won't grow without bound. For high churn,
+   * pass a tuned store, e.g. `groupStore: memoryStore({ sweepEvery: 200, idleMs: 30_000 })`.
+   */
+  readonly groupStore?: RateLimitStore;
   /** 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;
+  /**
+   * Notified when the pending queue stays **continuously non-empty** past
+   * {@link RateLimitedDoerOptions.backlogAfterMs} — a sustained backlog of tasks the rate limit can't
+   * admit fast enough. Purely observational (for alerting/autoscaling); it must not throw — if it
+   * does, the throw is ignored. Requires `backlogAfterMs`.
+   */
+  readonly onBacklog?: (info: RateLimitedBacklogInfo) => void;
+  /** How long the queue must stay non-empty before {@link RateLimitedDoerOptions.onBacklog} first fires (ms). */
+  readonly backlogAfterMs?: number;
+  /** Re-fire `onBacklog` every this many ms while still backed up. Omit to fire once per backlog episode. */
+  readonly backlogEveryMs?: number;
   /**
    * 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
@@ -176,14 +232,40 @@ interface RateLimitedDoerOptions extends LimiterOptions {
  * const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
  * const w = createWork({ work: [sendEmail] as const, doer })
  * ```
+ *
+ * **Two-tier limiting.** Set a `groupLimit` (default, or per task via {@link RateTaskOptions}) and a
+ * task must clear both the global limit **and** its `group`'s limit — e.g. a global API cap plus a
+ * per-user / per-model cap. The group gate is checked first (a denied group check consumes nothing),
+ * so a task whose group is at its limit is **skipped** rather than blocking other groups, and the
+ * shared global bucket isn't spent on it. `group`/`groupLimit` are read at admission time.
  */
-declare function rateLimitedDoer(opts: RateLimitedDoerOptions): Doer;
+declare function rateLimitedDoer(opts: RateLimitedDoerOptions): RateLimitedDoer;
+/** Options for {@link memoryStore}. */
+interface MemoryStoreOptions {
+  /**
+   * Sweep expired/idle entries once every this many `consume` calls (default 1000). Lower bounds
+   * memory tighter when keys churn — e.g. many short-lived rate-limit **groups** (per-user/per-model)
+   * that aren't known up front — at a little more periodic scan cost.
+   */
+  readonly sweepEvery?: number;
+  /**
+   * Drop an idle **token-bucket** key after this long with no activity (ms, default 10 min).
+   * Windowed (`fixed-window`/`sliding-window`) counters are always dropped once their window has
+   * elapsed, regardless of this.
+   */
+  readonly idleMs?: number;
+}
 /**
- * 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.
+ * 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`, which sets key TTLs) to
+ * share limits across pods.
+ *
+ * **Bounded memory for dynamic keys.** Entries are swept lazily so an unbounded, not-known-in-advance
+ * key space (per-user/per-model rate-limit **groups**) doesn't grow without bound: a windowed counter
+ * is dropped once its window elapses, and an idle token-bucket after {@link MemoryStoreOptions.idleMs}.
+ * Active keys live long enough to enforce the limit; idle ones go away. Tune {@link MemoryStoreOptions}
+ * for high churn.
  */
-declare function memoryStore(): RateLimitStore;
+declare function memoryStore(opts?: MemoryStoreOptions): RateLimitStore;
 //#endregion
-export { Algorithm, Limiter, LimiterOptions, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedDoerOptions, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };
+export { Algorithm, DEFAULT_ALGORITHM, DEFAULT_PREFIX, Limiter, LimiterOptions, MemoryStoreOptions, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedBacklogInfo, RateLimitedDoer, RateLimitedDoerOptions, RateTaskOptions, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/index.d.ts

@@ -3,6 +3,10 @@ import { Doer, DoerTaskOptions } from "@ayepi/core/doer";
 
 //#region src/index.d.ts
 
+/** Default key namespace. */
+declare const DEFAULT_PREFIX = "rl:";
+/** Default algorithm. */
+declare const DEFAULT_ALGORITHM: Algorithm;
 /** 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. */
@@ -144,16 +148,68 @@ declare function rateLimit<const R extends readonly AnyMiddleware[] = readonly [
 type RateLimitDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<{
   ratelimit: RateLimitInfo;
 }, R>;
+/** Details of a sustained backlog, passed to {@link RateLimitedDoerOptions.onBacklog}. */
+interface RateLimitedBacklogInfo {
+  /** Tasks waiting on the rate limit to admit them (the queue depth). */
+  readonly pending: number;
+  /** How long the queue has been *continuously* non-empty (ms). */
+  readonly nonEmptyForMs: number;
+}
+/**
+ * Per-task options for a {@link rateLimitedDoer} — {@link DoerTaskOptions} (`group`/`priority`/
+ * `createdAt`) plus a per-request **group limit** override. When a `group` and a group limit are
+ * present, the task must clear both the global limit **and** its group's limit to be admitted.
+ */
+interface RateTaskOptions extends DoerTaskOptions {
+  /** Per-task group rate limit (a second gate, bucketed by `group`). Overrides {@link RateLimitedDoerOptions.groupLimit}. */
+  readonly groupLimit?: number;
+  /** Window for the group limit (ms; default: the global `window`). */
+  readonly groupWindow?: number;
+  /** Algorithm for the group limit (default: the global `algorithm`). */
+  readonly groupAlgorithm?: Algorithm;
+}
+/** A {@link Doer} whose `do` accepts {@link RateTaskOptions} — i.e. a per-task group limit. */
+interface RateLimitedDoer extends Doer {
+  /** Accept a task; `opts` may carry a per-task `group` + `groupLimit` (a second, per-group gate). */
+  do(task: () => Promise<void>, opts?: RateTaskOptions): void;
+}
 /** 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. */
+  /** Limit key for the **global** bucket — a single shared bucket by default (`'doer'`), or derived per task. */
   readonly key?: string | ((opts: DoerTaskOptions) => string);
+  /**
+   * Default **group** limit — a second gate bucketed by a task's `group`, on top of the global limit.
+   * A per-task {@link RateTaskOptions.groupLimit} overrides it. Omit for no group gate (global only).
+   * The group window/algorithm default to the global ones unless overridden per task.
+   */
+  readonly groupLimit?: number;
+  /** Derive a task's group bucket key (default: `opts.group`). Return `undefined` to skip the group gate for a task. */
+  readonly groupKey?: (opts: DoerTaskOptions) => string | undefined;
+  /**
+   * Store for the group buckets (default: the global `store`). A distributed store limits groups
+   * across a fleet. Groups need not be known up front — bucket state is per-group and **auto-evicted
+   * when idle** (the {@link memoryStore} sweeps expired/idle keys; `@ayepi/rate/redis` sets TTLs), so
+   * an unbounded, dynamic group space (per-user/per-model) won't grow without bound. For high churn,
+   * pass a tuned store, e.g. `groupStore: memoryStore({ sweepEvery: 200, idleMs: 30_000 })`.
+   */
+  readonly groupStore?: RateLimitStore;
   /** 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;
+  /**
+   * Notified when the pending queue stays **continuously non-empty** past
+   * {@link RateLimitedDoerOptions.backlogAfterMs} — a sustained backlog of tasks the rate limit can't
+   * admit fast enough. Purely observational (for alerting/autoscaling); it must not throw — if it
+   * does, the throw is ignored. Requires `backlogAfterMs`.
+   */
+  readonly onBacklog?: (info: RateLimitedBacklogInfo) => void;
+  /** How long the queue must stay non-empty before {@link RateLimitedDoerOptions.onBacklog} first fires (ms). */
+  readonly backlogAfterMs?: number;
+  /** Re-fire `onBacklog` every this many ms while still backed up. Omit to fire once per backlog episode. */
+  readonly backlogEveryMs?: number;
   /**
    * 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
@@ -176,14 +232,40 @@ interface RateLimitedDoerOptions extends LimiterOptions {
  * const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
  * const w = createWork({ work: [sendEmail] as const, doer })
  * ```
+ *
+ * **Two-tier limiting.** Set a `groupLimit` (default, or per task via {@link RateTaskOptions}) and a
+ * task must clear both the global limit **and** its `group`'s limit — e.g. a global API cap plus a
+ * per-user / per-model cap. The group gate is checked first (a denied group check consumes nothing),
+ * so a task whose group is at its limit is **skipped** rather than blocking other groups, and the
+ * shared global bucket isn't spent on it. `group`/`groupLimit` are read at admission time.
  */
-declare function rateLimitedDoer(opts: RateLimitedDoerOptions): Doer;
+declare function rateLimitedDoer(opts: RateLimitedDoerOptions): RateLimitedDoer;
+/** Options for {@link memoryStore}. */
+interface MemoryStoreOptions {
+  /**
+   * Sweep expired/idle entries once every this many `consume` calls (default 1000). Lower bounds
+   * memory tighter when keys churn — e.g. many short-lived rate-limit **groups** (per-user/per-model)
+   * that aren't known up front — at a little more periodic scan cost.
+   */
+  readonly sweepEvery?: number;
+  /**
+   * Drop an idle **token-bucket** key after this long with no activity (ms, default 10 min).
+   * Windowed (`fixed-window`/`sliding-window`) counters are always dropped once their window has
+   * elapsed, regardless of this.
+   */
+  readonly idleMs?: number;
+}
 /**
- * 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.
+ * 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`, which sets key TTLs) to
+ * share limits across pods.
+ *
+ * **Bounded memory for dynamic keys.** Entries are swept lazily so an unbounded, not-known-in-advance
+ * key space (per-user/per-model rate-limit **groups**) doesn't grow without bound: a windowed counter
+ * is dropped once its window elapses, and an idle token-bucket after {@link MemoryStoreOptions.idleMs}.
+ * Active keys live long enough to enforce the limit; idle ones go away. Tune {@link MemoryStoreOptions}
+ * for high churn.
  */
-declare function memoryStore(): RateLimitStore;
+declare function memoryStore(opts?: MemoryStoreOptions): RateLimitStore;
 //#endregion
-export { Algorithm, Limiter, LimiterOptions, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedDoerOptions, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };
+export { Algorithm, DEFAULT_ALGORITHM, DEFAULT_PREFIX, Limiter, LimiterOptions, MemoryStoreOptions, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedBacklogInfo, RateLimitedDoer, RateLimitedDoerOptions, RateTaskOptions, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/index.js

@@ -65,10 +65,10 @@ function limiter(opts) {
 	const rule = {
 		limit: opts.limit,
 		window: opts.window,
-		algorithm: opts.algorithm ?? DEFAULT_ALGORITHM,
+		algorithm: opts.algorithm ?? "fixed-window",
 		countRejected: opts.countRejected ?? false
 	};
-	const prefix = opts.prefix ?? DEFAULT_PREFIX;
+	const prefix = opts.prefix ?? "rl:";
 	return {
 		rule,
 		check: (key, now) => store.consume(prefix + key, rule, now ?? Date.now()),
@@ -150,18 +150,78 @@ const DOER_RETRY_FLOOR = 50;
 * const doer = rateLimitedDoer({ limit: 100, window: 60_000, algorithm: 'token-bucket' })
 * const w = createWork({ work: [sendEmail] as const, doer })
 * ```
+*
+* **Two-tier limiting.** Set a `groupLimit` (default, or per task via {@link RateTaskOptions}) and a
+* task must clear both the global limit **and** its `group`'s limit — e.g. a global API cap plus a
+* per-user / per-model cap. The group gate is checked first (a denied group check consumes nothing),
+* so a task whose group is at its limit is **skipped** rather than blocking other groups, and the
+* shared global bucket isn't spent on it. `group`/`groupLimit` are read at admission time.
 */
 function rateLimitedDoer(opts) {
-	const lim = limiter(opts);
+	const store = opts.store ?? memoryStore();
+	const lim = limiter({
+		...opts,
+		store
+	});
 	const inner = opts.doer ?? unlimitedDoer();
 	const now = opts.now ?? Date.now;
 	const floor = opts.retryFloor ?? DOER_RETRY_FLOOR;
 	const keyOf = (o) => typeof opts.key === "function" ? opts.key(o ?? {}) : opts.key ?? "doer";
+	const groupStore = opts.groupStore ?? store;
+	const groupPrefix = (opts.prefix ?? "rl:") + "grp:";
+	const groupKeyOf = (o) => opts.groupKey ? opts.groupKey(o ?? {}) : o?.group;
+	const groupRuleFor = (o) => {
+		const limit = o?.groupLimit ?? opts.groupLimit;
+		if (limit === void 0) return;
+		return {
+			limit,
+			window: o?.groupWindow ?? opts.window,
+			algorithm: o?.groupAlgorithm ?? opts.algorithm ?? "fixed-window",
+			countRejected: false
+		};
+	};
+	const report = (err) => {
+		try {
+			opts.onError?.(err);
+		} catch {}
+	};
 	const pending = [];
 	const idle = [];
 	let seq = 0;
 	let draining = false;
 	let timer = null;
+	const backlogWatch = opts.onBacklog !== void 0 && opts.backlogAfterMs !== void 0;
+	let nonEmptySince = null;
+	let backlogTimer = null;
+	const armBacklog = (ms) => {
+		backlogTimer = setTimeout(fireBacklog, ms);
+		backlogTimer.unref?.();
+	};
+	function fireBacklog() {
+		try {
+			opts.onBacklog({
+				pending: pending.length,
+				nonEmptyForMs: now() - nonEmptySince
+			});
+		} catch {}
+		if (opts.backlogEveryMs !== void 0) armBacklog(opts.backlogEveryMs);
+		else backlogTimer = null;
+	}
+	const syncBacklog = () => {
+		if (!backlogWatch) return;
+		if (pending.length > 0) {
+			if (nonEmptySince === null) {
+				nonEmptySince = now();
+				armBacklog(opts.backlogAfterMs);
+			}
+		} else {
+			nonEmptySince = null;
+			if (backlogTimer) {
+				clearTimeout(backlogTimer);
+				backlogTimer = null;
+			}
+		}
+	};
 	const arm = (ms) => {
 		if (timer) return;
 		timer = setTimeout(() => {
@@ -170,40 +230,67 @@ function rateLimitedDoer(opts) {
 		}, Math.max(floor, ms));
 		timer.unref?.();
 	};
+	/**
+	* The oldest pending task not skipped this round (a fresh scan, so tasks queued mid-drain are
+	* seen). `pending` is in insertion (seq) order, so equal `createdAt` ties keep the earliest.
+	*/
+	const nextPending = (skipped) => {
+		let best;
+		for (const t of pending) {
+			if (skipped.has(t)) continue;
+			if (!best || t.createdAt < best.createdAt) best = t;
+		}
+		return best;
+	};
 	const drain = async () => {
 		if (draining) return;
 		draining = true;
 		try {
-			while (pending.length > 0) {
+			const skipped = /* @__PURE__ */ new Set();
+			let soonest = Infinity;
+			for (;;) {
 				if (inner.available() <= 0) {
-					arm(floor);
+					soonest = Math.min(soonest, floor);
 					break;
 				}
-				let best = 0;
-				for (let i = 1; i < pending.length; i++) {
-					const a = pending[i];
-					const b = pending[best];
-					if (a.createdAt < b.createdAt || a.createdAt === b.createdAt && a.seq < b.seq) best = i;
+				const task = nextPending(skipped);
+				if (!task) break;
+				const o = task.opts;
+				const groupRule = groupRuleFor(o);
+				const gk = groupKeyOf(o);
+				if (groupRule && gk !== void 0) {
+					let gr;
+					try {
+						gr = await groupStore.consume(groupPrefix + gk, groupRule, now());
+					} catch (err) {
+						report(err);
+						soonest = Math.min(soonest, floor);
+						break;
+					}
+					if (!gr.allowed) {
+						soonest = Math.min(soonest, gr.retryAfter);
+						skipped.add(task);
+						continue;
+					}
 				}
-				const task = pending[best];
 				let res;
 				try {
-					res = await lim.check(keyOf(task.opts), now());
+					res = await lim.check(keyOf(o), now());
 				} catch (err) {
-					try {
-						opts.onError?.(err);
-					} catch {}
-					arm(floor);
+					report(err);
+					soonest = Math.min(soonest, floor);
 					break;
 				}
 				if (!res.allowed) {
-					arm(res.retryAfter);
+					soonest = Math.min(soonest, res.retryAfter);
 					break;
 				}
-				pending.splice(best, 1);
+				pending.splice(pending.indexOf(task), 1);
 				inner.do(task.run, task.opts);
 			}
 			if (pending.length === 0) for (const r of idle.splice(0)) r();
+			else arm(soonest);
+			syncBacklog();
 		} finally {
 			draining = false;
 		}
@@ -217,6 +304,7 @@ function rateLimitedDoer(opts) {
 				createdAt: o?.createdAt ?? now(),
 				seq: seq++
 			});
+			syncBacklog();
 			drain();
 		},
 		done: () => pending.length === 0 ? inner.done() : new Promise((r) => idle.push(() => void inner.done().then(r)))
@@ -297,19 +385,26 @@ function tokenBucket(buckets, key, rule, now) {
 	};
 }
 /**
-* 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.
+* 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`, which sets key TTLs) to
+* share limits across pods.
+*
+* **Bounded memory for dynamic keys.** Entries are swept lazily so an unbounded, not-known-in-advance
+* key space (per-user/per-model rate-limit **groups**) doesn't grow without bound: a windowed counter
+* is dropped once its window elapses, and an idle token-bucket after {@link MemoryStoreOptions.idleMs}.
+* Active keys live long enough to enforce the limit; idle ones go away. Tune {@link MemoryStoreOptions}
+* for high churn.
 */
-function memoryStore() {
+function memoryStore(opts = {}) {
+	const sweepEvery = opts.sweepEvery ?? SWEEP_EVERY;
+	const idleMs = opts.idleMs ?? BUCKET_IDLE_MS;
 	const counters = /* @__PURE__ */ new Map();
 	const buckets = /* @__PURE__ */ new Map();
 	let ops = 0;
 	const sweep = (now) => {
-		if (++ops % SWEEP_EVERY !== 0) return;
+		if (++ops % sweepEvery !== 0) return;
 		for (const [k, e] of counters) if (e.reset <= now) counters.delete(k);
-		for (const [k, b] of buckets) if (now - b.ts > BUCKET_IDLE_MS) buckets.delete(k);
+		for (const [k, b] of buckets) if (now - b.ts > idleMs) buckets.delete(k);
 	};
 	return {
 		consume(key, rule, now) {
@@ -328,4 +423,4 @@ function memoryStore() {
 	};
 }
 //#endregion
-export { limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };
+export { DEFAULT_ALGORITHM, DEFAULT_PREFIX, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/server.cjs

@@ -1,22 +1,34 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_index = require("./index.cjs");
 //#region src/server.ts
+/** Resolve a {@link Dynamic} option for a request (calls it with `io` when it's a function). */
+function resolve(value, io) {
+	return typeof value === "function" ? value(io) : value;
+}
 /** Bind a {@link rateLimit} def to its runtime policy. */
 function rateLimitServer(def, opts) {
-	const lim = require_index.limiter(opts);
+	const store = opts.store ?? require_index.memoryStore();
+	const prefix = opts.prefix ?? "rl:";
 	const message = opts.message;
+	const ruleFor = (io) => ({
+		limit: resolve(opts.limit, io),
+		window: resolve(opts.window, io),
+		algorithm: (opts.algorithm !== void 0 ? resolve(opts.algorithm, io) : void 0) ?? "fixed-window",
+		countRejected: (opts.countRejected !== void 0 ? resolve(opts.countRejected, io) : void 0) ?? false
+	});
 	const run = async (io) => {
 		const kio = {
 			req: io.req,
 			ctx: io.ctx
 		};
+		const rule = ruleFor(kio);
 		const advertise = (info) => {
 			if (!opts.alwaysHeaders) return;
 			for (const [name, value] of Object.entries(require_index.rateLimitHeaders(info, opts.headers))) io.setHeader(name, value);
 		};
 		const fullBudget = () => ({
-			limit: lim.rule.limit,
-			remaining: lim.rule.limit,
+			limit: rule.limit,
+			remaining: rule.limit,
 			reset: 0,
 			retryAfter: 0
 		});
@@ -27,7 +39,7 @@ function rateLimitServer(def, opts) {
 		}
 		let result;
 		try {
-			result = await lim.check(opts.key(kio));
+			result = await store.consume(prefix + opts.key(kio), rule, Date.now());
 		} catch (err) {
 			try {
 				opts.onError?.(err);

package/dist/server.d.cts

@@ -5,22 +5,47 @@ import { AnyMiddleware, BoundMiddleware, Json, StackCtx } from "@ayepi/core";
 
 /** The `requires` chain of a middleware def. */
 type ReqOf<M extends AnyMiddleware> = M['__req'];
+/** The `io` (request + accumulated, typed context) passed to every per-request option of a bound {@link rateLimit}. */
+type KeyIO<M extends AnyMiddleware> = RateKeyIO<StackCtx<ReqOf<M>>>;
+/**
+ * A per-request option: derive `T` from the rate-limit key {@link RateKeyIO} — the same
+ * `(io) => T` shape `key` and `skip` use. `io.ctx` is typed from the def's `requires`.
+ */
+type RateKeyFn<M extends AnyMiddleware, T> = (io: KeyIO<M>) => T;
+/**
+ * A {@link RateLimitServerOptions} field that is either a fixed `T` or resolved **per request**
+ * from the key {@link RateKeyIO}. Use a function to vary the policy by caller — e.g. a larger
+ * `limit` for a premium plan, a longer `window` for a trusted client.
+ */
+type Dynamic<M extends AnyMiddleware, T> = T | RateKeyFn<M, T>;
 /**
  * Server-side options for binding a {@link rateLimit} def — the limiting policy and
  * response customization, with `key`/`skip`/`message` typed against the def's
  * `requires` context.
  *
+ * The rule itself — `limit`, `window`, `algorithm`, `countRejected` — can be a fixed value or
+ * a `(io) => T` resolved per request, so limits can differ by caller (plan, tenant, API key).
+ * **Resolve these from a stable property of the identity** (the same key should always map to
+ * the same `window`/`algorithm`): the store buckets its per-key state by them, so varying
+ * `window`/`algorithm` for one key across requests gives inconsistent accounting. Varying only
+ * `limit` is always safe. See {@link Dynamic}.
+ *
  * @typeParam M - the rate-limit def being bound.
  */
 interface RateLimitServerOptions<M extends AnyMiddleware> {
   /** Derive the rate-limit key from the request context (e.g. `io.ctx.user.id`). */
-  readonly key: (io: RateKeyIO<StackCtx<ReqOf<M>>>) => string;
-  /** 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;
+  readonly key: RateKeyFn<M, string>;
+  /** Max requests (or token-bucket capacity) per window — fixed, or per request. */
+  readonly limit: Dynamic<M, number>;
+  /** Window length in milliseconds (also the token refill period) — fixed, or per request. */
+  readonly window: Dynamic<M, number>;
+  /** Algorithm (default `'fixed-window'`) — fixed, or per request. */
+  readonly algorithm?: Dynamic<M, Algorithm>;
+  /**
+   * Count requests that are themselves rejected (over-limit) against the limit — fixed, or per
+   * request. Default `false`; see {@link RateLimitRule.countRejected}.
+   */
+  readonly countRejected?: Dynamic<M, boolean>;
   /** Backend store (default an in-process memory store). */
   readonly store?: RateLimitStore;
   /** Key prefix/namespace (default `'rl:'`). */
@@ -28,7 +53,7 @@ interface RateLimitServerOptions<M extends AnyMiddleware> {
   /** Over-limit status code (default `429`). */
   readonly status?: number;
   /** Over-limit body — a string, a JSON value, or a function of the limiter info and request. */
-  readonly message?: string | Json | ((info: RateLimitInfo, io: RateKeyIO<StackCtx<ReqOf<M>>>) => string | Json);
+  readonly message?: string | Json | ((info: RateLimitInfo, io: KeyIO<M>) => string | Json);
   /** Response headers (draft `RateLimit-*` + `Retry-After` by default; `false` for none; a function for your own). */
   readonly headers?: boolean | ((info: RateLimitInfo) => Record<string, string>);
   /**
@@ -39,7 +64,7 @@ interface RateLimitServerOptions<M extends AnyMiddleware> {
    */
   readonly alwaysHeaders?: boolean;
   /** Bypass the limiter for some requests (e.g. an allow-list). */
-  readonly skip?: (io: RateKeyIO<StackCtx<ReqOf<M>>>) => boolean;
+  readonly skip?: RateKeyFn<M, boolean>;
   /**
    * What to do when the **store itself errors** (e.g. Redis is down) — `true` serves the
    * request through (as if allowed, full budget); `false` (default) is fail-**closed**: the
@@ -64,4 +89,4 @@ declare const rateLimit: typeof rateLimit$1 & {
   server: typeof rateLimitServer;
 };
 //#endregion
-export { RateLimitServerOptions, rateLimit };
+export { Dynamic, RateKeyFn, RateLimitServerOptions, rateLimit };