@ayepi/rate 0.4.0 → 0.5.0

package/README.md

@@ -74,7 +74,7 @@ if (!allowed) {
 await lim.reset(userId) // clear a key
 ```
 
-- `limiter(opts)` → `{ check(key, now?), reset(key), rule }` — the actual limiting
+- `limiter(opts)` → `{ check(key, { now?, cost? }?), reset(key), rule }` — the actual limiting
   (pluggable store + algorithm), no HTTP involved.
 - `rateLimitResponse(info, opts?)` → a `Response` (status/message/headers), if you
   want one.
@@ -86,8 +86,8 @@ await lim.reset(userId) // clear a key
 `rateLimitedDoer` is a [`Doer`](https://www.npmjs.com/package/@ayepi/core) (from
 `@ayepi/core/doer`) that caps the **start rate** of tasks through the same `limiter()`
 primitive — so an `@ayepi/work` engine processes work no faster than a budget allows.
-It also stays on the main `@ayepi/rate` entry. Excess tasks wait, oldest-first, and a
-distributed store limits across a fleet:
+It also stays on the main `@ayepi/rate` entry. Excess tasks wait and are admitted oldest-first
+(or most urgent first with `order: 'priority'`), and a distributed store limits across a fleet:
 
 ```ts
 import { rateLimitedDoer } from '@ayepi/rate'

package/ayepi-rate-stores-doer.md

@@ -30,20 +30,29 @@ interface RateLimitRule {
 }
 
 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>;
+  /**
+   * Record a hit of weight `cost` for `key` under `rule` at time `now` (ms) and return the decision.
+   * Allowed when the window's total plus `cost` stays within `rule.limit` (token-bucket: the bucket holds
+   * `cost` tokens). A cost of 0 records nothing and reports the current state.
+   */
+  consume(key: string, rule: RateLimitRule, now: number, cost: number): MaybePromise<RateLimitResult>;
   /** Clear all state for `key` (optional). */
   reset?(key: string): MaybePromise<void>;
 }
 ```
 
-A custom store should honor `rule.countRejected`: when it is falsy (the default), a request
-the store **rejects** must not consume budget (don't persist its increment). The bundled
+A custom store should honor `cost` and `rule.countRejected`: a hit adds `cost` (not 1) to the
+window, and when `countRejected` is falsy (the default), a hit the store **rejects** must not
+consume budget (don't persist its increment). The bundled
 `memoryStore` and `redisStore` both do this; `token-bucket` is naturally exempt (it never
 charges a request it can't admit).
 
 The **algorithm lives in the store**, not in the limiter — that is what keeps the limit
-correct across instances. Implement `RateLimitStore` for any backend (Postgres, DynamoDB,
+correct across instances. A store that can read and write per-key cells atomically (a database
+transaction) can reuse the bundled algorithms: `applyHit(state, key, rule, now, cost)` runs one hit
+against `state = { counters, buckets }`, two Map-like tables (`get`/`set`) of `{ count, reset }`
+window counters and `{ tokens, ts }` token buckets, writing every changed cell back with `set`.
+`memoryStore` runs it on Maps; `@ayepi/sqlite`'s `sqliteRateStore` on rows inside one transaction. Implement `RateLimitStore` for any backend (Postgres, DynamoDB,
 Memcached, …); only `consume` is required.
 
 ### `memoryStore` (default, bundled)
@@ -144,6 +153,8 @@ interface RateLimitedDoerOptions extends LimiterOptions {
   /** Re-fire `onBacklog` every this many ms while still backed up (omit to fire once). */
   readonly backlogEveryMs?: number;
 
+  /** Which waiting task is admitted next: 'oldest' (default) or 'priority' (highest priority, then oldest). */
+  readonly order?: 'oldest' | 'priority';
   /** Floor on the re-check delay for deferred tasks (ms, default 50). */
   readonly retryFloor?: number;
   /** Clock injection (default `Date.now`). */
@@ -157,6 +168,7 @@ interface RateTaskOptions extends DoerTaskOptions {
   readonly groupLimit?: number;      // overrides the configured default; enables the group gate for this task
   readonly groupWindow?: number;     // default: the global `window`
   readonly groupAlgorithm?: Algorithm; // default: the global `algorithm`
+  readonly cost?: number;            // weight against both gates (default 1)
 }
 
 /** A Doer whose `do` accepts RateTaskOptions (assignable to Doer). */
@@ -177,9 +189,22 @@ A `Doer` (from `@ayepi/core/doer`) that caps the **start rate** of tasks using t
 `limiter()` primitive (and the same pluggable store/algorithm) the middleware uses. It does
 **not** run tasks itself — when the limiter admits a task it hands it to an **inner doer**
 (default `unlimitedDoer()`), so you can compose a rate cap with a concurrency/ordering
-policy. Excess tasks wait, **oldest-first**; with a distributed store this rate-limits
+policy. Excess tasks wait and are admitted **oldest-first**, or with `order: 'priority'` the
+highest `priority` first (then the oldest); with a distributed store this rate-limits
 **across a fleet**.
 
+```ts
+// urgent calls never queue behind a rate-limited backlog: priority order here, a concurrency cap inside
+const llm = rateLimitedDoer({ limit: 60, window: 60_000, order: 'priority', doer: priorityDoer({ max: 4, buffer: 0 }) })
+llm.do(() => answerUser(), { priority: 10 })
+llm.do(() => summarizeInBackground(), { priority: 0 })
+```
+
+The inner doer's `available()` gates admission, so a task waits here (in `order`) rather than in
+the inner doer, and the rate budget is spent only when the inner doer can take it. A bounded inner
+doer accepts `max + buffer` tasks; give it `buffer: 0` so tasks are admitted only into a free slot
+and a later, more urgent task is never passed by one already buffered.
+
 A `Doer` exposes `available()`, `do(task, opts?)`, and `done()` — see the doer section
 below. `rateLimitedDoer`'s `available()` is `min(limit − pending, inner.available())`.
 
@@ -208,7 +233,7 @@ Semantics:
   consumes nothing (the group rule forces `countRejected: false`), so a task whose group is at
   its limit is **skipped**, not admitted — and no global token is spent on it.
 - **Head-of-line avoidance.** A skipped (group-capped) task is left pending while **other
-  groups' tasks proceed**, so a hot user/model can't block everyone. Within a group, oldest-first.
+  groups' tasks proceed**, so a hot user/model can't block everyone. Within a group, tasks go in `order`.
 - **Global exhaustion stops the round.** When the shared global bucket is out, nothing more is
   admitted this pass. Edge case: a task that cleared its group but then hits an exhausted global
   had its group token spent (bounded, self-corrects on retry) — only when global is the bottleneck.
@@ -329,7 +354,8 @@ was rejected).
 ### Store consultation
 
 `limiter()` builds a `RateLimitRule` from `{ limit, window, algorithm }`, prepends
-`prefix` (default `'rl:'`) to the key, and calls `store.consume(prefixedKey, rule, now)`.
+`prefix` (default `'rl:'`) to the key, and calls `store.consume(prefixedKey, rule, now, cost)`
+(`cost` from `check(key, { cost })`, default 1; a negative or non-finite cost throws a `RangeError`).
 The store records the hit and returns `{ allowed, limit, remaining, reset, retryAfter }`.
 The limiter is stateless beyond its rule + store reference — all per-key state lives in the
 store, which is why a distributed store gives a distributed limit.
@@ -340,7 +366,8 @@ store, which is why a distributed store gives a distributed limit.
 
 1. builds `kio = { req, ctx }`;
 2. if `skip(kio)` → calls `io.next({ ratelimit: <full budget> })` (admit, no store hit);
-3. otherwise `await limiter.check(key(kio))`;
+3. otherwise resolves `cost` (default 1) and `await store.consume(prefix + key(kio), rule, now, cost)`
+   (a bad cost throws before the store is consulted, so `failOpen` never hides it);
 4. if **not** allowed → returns `rateLimitResponse(info, { status, headers, message })` —
    a `Response`, which `@ayepi/core` treats as a **short-circuit**: the rest of the chain
    and the handler are skipped (HTTP sends the `Response`; ws turns it into an error
@@ -354,14 +381,14 @@ limiter's dependency middleware run first and their context is available — see
 
 ### The doer abstraction
 
-`rateLimitedDoer` keeps a `pending` queue. Each `drain` scans it **oldest-first** and admits
+`rateLimitedDoer` keeps a `pending` queue. Each `drain` scans it in `order` (**oldest-first**, or priority then age) and admits
 every task that clears its gates, skipping (not blocking on) group-capped ones:
 
 - if the inner doer has no capacity (`inner.available() <= 0`), it records a short re-check and stops;
-- for the oldest not-yet-skipped task, it checks the **group gate first** (when a `group` + group
+- for the first not-yet-skipped task in `order`, it checks the **group gate first** (when a `group` + group
   limit apply): a denied group check consumes nothing, so the task is **skipped** (left pending) and
   the scan continues to other groups — recording that group's `retryAfter`;
-- then the **global gate** (`limiter.check(key, now)`): if denied, the shared bucket is out, so no
+- then the **global gate** (`limiter.check(key, { now, cost })`): if denied, the shared bucket is out, so no
   further task can be admitted this round and the scan stops (recording the global `retryAfter`);
 - if both allow, it removes the task and calls `inner.do(task.run, task.opts)`.
 

package/ayepi-rate.md

@@ -109,7 +109,12 @@ Everything below is exported. `@internal` symbols are intentionally omitted.
 | `RateLimitDefOptions` | interface | Options for the `rateLimit` def (`name`/`requires`). |
 | `RateLimitedDoerOptions` | interface | Options for `rateLimitedDoer` (global + group limits, backlog watch). |
 | `RateLimitedDoer` | interface | The doer `rateLimitedDoer` returns (a `Doer` whose `do` takes `RateTaskOptions`). |
-| `RateTaskOptions` | interface | Per-task options — `DoerTaskOptions` + `groupLimit`/`groupWindow`/`groupAlgorithm`. |
+| `RateTaskOptions` | interface | Per-task options — `DoerTaskOptions` + `groupLimit`/`groupWindow`/`groupAlgorithm`/`cost`. |
+| `applyHit` | function | The single implementation of all three algorithms over a `RateState` (Map-like cells); `memoryStore` runs it on Maps, `@ayepi/sqlite`'s store on rows. |
+| `RateState` / `RateCells` / `RateCounter` / `RateBucket` | interfaces | The cells `applyHit` reads and writes back: window counters `{ count, reset }` and token buckets `{ tokens, ts }`. |
+| `RateHit` | interface | One hit for `limiter.check`: `{ now?, cost? }`. |
+| `hitCost` | function | Validate a hit's cost (default 1); throws `RangeError` when negative or non-finite. |
+| `DEFAULT_COST` | const | `1` — what a hit costs when no cost is given. |
 | `RateLimitedBacklogInfo` | interface | `{ pending, nonEmptyForMs }` passed to the doer's `onBacklog`. |
 | `MemoryStoreOptions` | interface | `{ sweepEvery?, idleMs? }` — tune `memoryStore` eviction. |
 | `Limiter` | interface | The object `limiter()` returns. |
@@ -190,6 +195,8 @@ interface RateLimitServerOptions<M extends AnyMiddleware> {
   readonly algorithm?: Dynamic<M, Algorithm>;
   /** Count rejected (over-limit) requests against the limit (default `false`) — fixed, or per request. */
   readonly countRejected?: Dynamic<M, boolean>;
+  /** What a request costs against the limit (default 1) — fixed, or per request. See "Weighted hits". */
+  readonly cost?: Dynamic<M, number>;
   /** Backend store (default an in-process `memoryStore`). */
   readonly store?: RateLimitStore;
   /** Key prefix/namespace (default `'rl:'`). */
@@ -395,8 +402,8 @@ plain handler, a worker, a CLI, or another framework.
 function limiter(opts: LimiterOptions): Limiter
 
 interface Limiter {
-  /** Record a hit for `key` (at `now`, default `Date.now()`) and return the decision. */
-  check(key: string, now?: number): MaybePromise<RateLimitResult>;
+  /** Record a hit for `key` and return the decision. */
+  check(key: string, hit?: RateHit): MaybePromise<RateLimitResult>;
   /** Clear all state for `key`. */
   reset(key: string): MaybePromise<void>;
   /** The rule this limiter enforces. */
@@ -420,6 +427,32 @@ await lim.reset(userId) // clear a key
 `check` may return a value or a promise depending on the store (`memoryStore` is sync,
 `redisStore` is async) — `await` it to handle both.
 
+### Weighted hits
+
+A hit can weigh more (or less) than one request, so a limit can count LLM tokens, bytes or money
+instead of calls. The limit and the costs share one unit; for money use whole small units such as
+micro-dollars so totals stay exact.
+
+```ts
+interface RateHit {
+  readonly now?: number;  // when (ms; default Date.now())
+  readonly cost?: number; // weight in the limit's units (default 1); 0 = report the state, record nothing
+}
+
+const spend = limiter({ limit: 5_000_000, window: 86_400_000 }) // 5 dollars a day, in micro-dollars
+const { allowed, remaining } = await spend.check(userId, { cost: 12_500 })
+```
+
+- A hit is allowed when the window's total plus its cost fits the limit (token-bucket: when the
+  bucket holds that many tokens); a refused hit records nothing unless `countRejected` is set.
+- A cost above the limit is never allowed. A negative or non-finite cost throws a `RangeError`
+  (`hitCost(cost)` is the check, exported).
+- `remaining` is exact for `fixed-window` and whole units (rounded down) for `sliding-window` and
+  `token-bucket`.
+- The middleware takes `cost` (fixed or `(io) => number`), and `rateLimitedDoer` takes a per-task
+  `cost` that counts against both its global and its group limit (`ayepi-rate-stores-doer.md`).
+- `memoryStore` and `redisStore` both support fractional costs (Redis via `INCRBYFLOAT`).
+
 ### `rateLimitResponse`
 
 ```ts

package/dist/index.cjs

@@ -42,14 +42,20 @@ const DEFAULT_STATUS = 429;
 const DEFAULT_PREFIX = "rl:";
 /** Default algorithm. */
 const DEFAULT_ALGORITHM = "fixed-window";
-/** Tokens consumed per request (token-bucket). */
-const TOKEN_COST = 1;
+/** What one hit costs when no cost is given: one request. */
+const DEFAULT_COST = 1;
 /** Milliseconds per second — `Retry-After` / `RateLimit-Reset` are expressed in seconds. */
 const MS_PER_SECOND = 1e3;
 /** Amortized cleanup: sweep expired in-memory entries once every this many `consume` calls. */
 const SWEEP_EVERY = 1e3;
 /** Drop an idle in-memory token bucket after this long with no activity (it refills to full anyway). */
 const BUCKET_IDLE_MS = 600 * 1e3;
+/** The cost of a hit: `cost` or {@link DEFAULT_COST}. Throws a `RangeError` for a negative or non-finite cost. */
+function hitCost(cost) {
+	const c = cost ?? 1;
+	if (!Number.isFinite(c) || c < 0) throw new RangeError(`rate-limit cost must be a finite number >= 0, got ${c}`);
+	return c;
+}
 /**
 * Create a standalone {@link Limiter} — the rate-limit primitive the
 * {@link rateLimit} middleware is built on. Use it anywhere you have a key: a
@@ -59,6 +65,10 @@ const BUCKET_IDLE_MS = 600 * 1e3;
 * 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`)
+*
+* // a budget: 5 dollars a day, counted in micro-dollars
+* const spend = limiter({ limit: 5_000_000, window: 86_400_000 })
+* const { allowed: affordable } = await spend.check(userId, { cost: 12_500 })
 * ```
 */
 function limiter(opts) {
@@ -72,7 +82,7 @@ function limiter(opts) {
 	const prefix = opts.prefix ?? "rl:";
 	return {
 		rule,
-		check: (key, now) => store.consume(prefix + key, rule, now ?? Date.now()),
+		check: (key, hit) => store.consume(prefix + key, rule, hit?.now ?? Date.now(), hitCost(hit?.cost)),
 		reset: (key) => Promise.resolve(store.reset?.(prefix + key))
 	};
 }
@@ -136,13 +146,19 @@ function rateLimit(opts) {
 }
 /** Minimum re-check delay when a deferred task has no explicit retry hint (ms). */
 const DOER_RETRY_FLOOR = 50;
+/** Whether `a` is admitted before `b` under `order`; equal ties keep insertion order (the earlier `seq`). */
+const admitsBefore = {
+	oldest: (a, b) => a.createdAt < b.createdAt,
+	priority: (a, b) => a.priority !== b.priority ? a.priority > b.priority : a.createdAt < b.createdAt
+};
 /**
 * 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**.
+* Excess tasks wait and are admitted oldest-first, or most urgent first with `order: 'priority'`; a
+* distributed store rate-limits **across a fleet**.
 *
 * ```ts
 * import { rateLimitedDoer } from '@ayepi/rate'
@@ -167,6 +183,7 @@ function rateLimitedDoer(opts) {
 	const inner = opts.doer ?? (0, _ayepi_core_doer.unlimitedDoer)();
 	const now = opts.now ?? Date.now;
 	const floor = opts.retryFloor ?? DOER_RETRY_FLOOR;
+	const before = admitsBefore[opts.order ?? "oldest"];
 	const keyOf = (o) => typeof opts.key === "function" ? opts.key(o ?? {}) : opts.key ?? "doer";
 	const groupStore = opts.groupStore ?? store;
 	const groupPrefix = (opts.prefix ?? "rl:") + "grp:";
@@ -232,14 +249,14 @@ function rateLimitedDoer(opts) {
 		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.
+	* The first pending task under `order` not skipped this round (a fresh scan, so tasks queued mid-drain are
+	* seen). `pending` is in insertion (seq) order, so equal 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;
+			if (!best || before(t, best)) best = t;
 		}
 		return best;
 	};
@@ -262,7 +279,7 @@ function rateLimitedDoer(opts) {
 				if (groupRule && gk !== void 0) {
 					let gr;
 					try {
-						gr = await groupStore.consume(groupPrefix + gk, groupRule, now());
+						gr = await groupStore.consume(groupPrefix + gk, groupRule, now(), hitCost(o?.cost));
 					} catch (err) {
 						report(err);
 						soonest = Math.min(soonest, floor);
@@ -276,7 +293,10 @@ function rateLimitedDoer(opts) {
 				}
 				let res;
 				try {
-					res = await lim.check(keyOf(o), now());
+					res = await lim.check(keyOf(o), {
+						now: now(),
+						cost: o?.cost
+					});
 				} catch (err) {
 					report(err);
 					soonest = Math.min(soonest, floor);
@@ -302,6 +322,7 @@ function rateLimitedDoer(opts) {
 			pending.push({
 				run: task,
 				opts: o,
+				priority: o?.priority ?? 0,
 				createdAt: o?.createdAt ?? now(),
 				seq: seq++
 			});
@@ -311,43 +332,57 @@ function rateLimitedDoer(opts) {
 		done: () => pending.length === 0 ? inner.done() : new Promise((r) => idle.push(() => void inner.done().then(r)))
 	};
 }
-function fixedWindow(counters, key, rule, now) {
-	let e = counters.get(key);
-	if (!e || e.reset <= now) {
-		e = {
-			count: 0,
-			reset: now + rule.window
-		};
-		counters.set(key, e);
+/**
+* Run one hit of weight `cost` for `key` under `rule` at `now` against `state`: the single implementation of all three
+* algorithms, which {@link memoryStore} runs on Maps and a database-backed {@link RateLimitStore} can run on rows
+* (inside one transaction, so the read and the write-back are atomic). Every changed cell is written back with `set`.
+*/
+function applyHit(state, key, rule, now, cost) {
+	switch (rule.algorithm) {
+		case "sliding-window": return slidingWindow(state.counters, key, rule, now, cost);
+		case "token-bucket": return tokenBucket(state.buckets, key, rule, now, cost);
+		default: return fixedWindow(state.counters, key, rule, now, cost);
 	}
-	const allowed = e.count < rule.limit;
-	if (allowed || rule.countRejected) e.count++;
+}
+function fixedWindow(counters, key, rule, now, cost) {
+	const found = counters.get(key);
+	const e = !found || found.reset <= now ? {
+		count: 0,
+		reset: now + rule.window
+	} : found;
+	const allowed = e.count + cost <= rule.limit;
+	const count = allowed || rule.countRejected ? e.count + cost : e.count;
+	counters.set(key, {
+		count,
+		reset: e.reset
+	});
 	const reset = e.reset - now;
 	return {
 		allowed,
 		limit: rule.limit,
-		remaining: Math.max(0, rule.limit - e.count),
+		remaining: Math.max(0, rule.limit - count),
 		reset,
 		retryAfter: allowed ? 0 : reset
 	};
 }
-function slidingWindow(counters, key, rule, now) {
+function slidingWindow(counters, key, rule, now, cost) {
 	const windowStart = Math.floor(now / rule.window) * rule.window;
 	const curKey = `${key}|${windowStart}`;
 	const prevKey = `${key}|${windowStart - rule.window}`;
-	let cur = counters.get(curKey);
-	if (!cur || cur.reset <= now) {
-		cur = {
-			count: 0,
-			reset: windowStart + rule.window
-		};
-		counters.set(curKey, cur);
-	}
+	const found = counters.get(curKey);
+	const cur = !found || found.reset <= now ? {
+		count: 0,
+		reset: windowStart + rule.window
+	} : found;
 	const prevCount = counters.get(prevKey)?.count ?? 0;
 	const weight = (rule.window - (now - windowStart)) / rule.window;
-	const allowed = prevCount * weight + cur.count + 1 <= rule.limit;
-	if (allowed || rule.countRejected) cur.count++;
-	const weighted = prevCount * weight + cur.count;
+	const allowed = prevCount * weight + cur.count + cost <= rule.limit;
+	const count = allowed || rule.countRejected ? cur.count + cost : cur.count;
+	counters.set(curKey, {
+		count,
+		reset: cur.reset
+	});
+	const weighted = prevCount * weight + count;
 	const reset = windowStart + rule.window - now;
 	return {
 		allowed,
@@ -357,31 +392,27 @@ function slidingWindow(counters, key, rule, now) {
 		retryAfter: allowed ? 0 : reset
 	};
 }
-function tokenBucket(buckets, key, rule, now) {
+function tokenBucket(buckets, key, rule, now, cost) {
 	const cap = rule.limit;
 	const refillPerMs = rule.limit / rule.window;
-	let b = buckets.get(key);
-	if (!b) b = {
+	const b = buckets.get(key) ?? {
 		tokens: cap,
 		ts: now
 	};
-	b.tokens = Math.min(cap, b.tokens + (now - b.ts) * refillPerMs);
-	b.ts = now;
-	const cost = TOKEN_COST;
-	let allowed = false;
-	if (b.tokens >= cost) {
-		b.tokens -= cost;
-		allowed = true;
-	}
-	buckets.set(key, b);
-	const remaining = Math.floor(b.tokens);
-	const retryAfter = allowed ? 0 : Math.ceil((cost - b.tokens) / refillPerMs);
-	const reset = Math.ceil((cap - b.tokens) / refillPerMs);
+	const level = Math.min(cap, b.tokens + (now - b.ts) * refillPerMs);
+	const allowed = level >= cost;
+	const tokens = allowed ? level - cost : level;
+	buckets.set(key, {
+		tokens,
+		ts: now
+	});
+	const remaining = Math.floor(tokens);
+	const retryAfter = allowed ? 0 : Math.ceil((cost - tokens) / refillPerMs);
 	return {
 		allowed,
 		limit: cap,
 		remaining,
-		reset,
+		reset: Math.ceil((cap - tokens) / refillPerMs),
 		retryAfter
 	};
 }
@@ -401,6 +432,10 @@ function memoryStore(opts = {}) {
 	const idleMs = opts.idleMs ?? BUCKET_IDLE_MS;
 	const counters = /* @__PURE__ */ new Map();
 	const buckets = /* @__PURE__ */ new Map();
+	const state = {
+		counters,
+		buckets
+	};
 	let ops = 0;
 	const sweep = (now) => {
 		if (++ops % sweepEvery !== 0) return;
@@ -408,13 +443,9 @@ function memoryStore(opts = {}) {
 		for (const [k, b] of buckets) if (now - b.ts > idleMs) buckets.delete(k);
 	};
 	return {
-		consume(key, rule, now) {
+		consume(key, rule, now, cost) {
 			sweep(now);
-			switch (rule.algorithm) {
-				case "sliding-window": return slidingWindow(counters, key, rule, now);
-				case "token-bucket": return tokenBucket(buckets, key, rule, now);
-				default: return fixedWindow(counters, key, rule, now);
-			}
+			return applyHit(state, key, rule, now, cost);
 		},
 		reset(key) {
 			counters.delete(key);
@@ -425,7 +456,10 @@ function memoryStore(opts = {}) {
 }
 //#endregion
 exports.DEFAULT_ALGORITHM = DEFAULT_ALGORITHM;
+exports.DEFAULT_COST = DEFAULT_COST;
 exports.DEFAULT_PREFIX = DEFAULT_PREFIX;
+exports.applyHit = applyHit;
+exports.hitCost = hitCost;
 exports.limiter = limiter;
 exports.memoryStore = memoryStore;
 exports.rateLimit = rateLimit;

package/dist/index.d.cts

@@ -7,13 +7,18 @@ import { Doer, DoerTaskOptions } from "@ayepi/core/doer";
 declare const DEFAULT_PREFIX = "rl:";
 /** Default algorithm. */
 declare const DEFAULT_ALGORITHM: Algorithm;
+/** What one hit costs when no cost is given: one request. */
+declare const DEFAULT_COST = 1;
 /** 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. */
+  /** The configured limit for the window, in cost units (requests by default). */
   readonly limit: number;
-  /** Requests (or tokens) remaining before the limit is hit. */
+  /**
+   * Cost units remaining before the limit is hit. Whole units for `sliding-window` and `token-bucket` (rounded down);
+   * exact for `fixed-window`.
+   */
   readonly remaining: number;
   /** Milliseconds until the window/bucket resets. */
   readonly reset: number;
@@ -45,8 +50,12 @@ interface RateLimitRule {
  * (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>;
+  /**
+   * Record a hit of weight `cost` for `key` under `rule` at time `now` (ms) and return the decision. The hit is
+   * allowed when the window's total plus `cost` stays within `rule.limit` (for `token-bucket`: when the bucket
+   * holds `cost` tokens). A cost of `0` records nothing and reports the current state.
+   */
+  consume(key: string, rule: RateLimitRule, now: number, cost: number): MaybePromise<RateLimitResult>;
   /** Clear all state for `key` (optional). */
   reset?(key: string): MaybePromise<void>;
 }
@@ -98,10 +107,23 @@ interface RateLimitDefOptions<R extends readonly AnyMiddleware[]> {
   /** Middleware name for docs/debugging (default `'rateLimit'`). */
   readonly name?: string;
 }
+/** One hit against a {@link Limiter}. */
+interface RateHit {
+  /** When the hit happens (ms; default `Date.now()`). */
+  readonly now?: number;
+  /**
+   * The hit's weight in the limit's units (default {@link DEFAULT_COST}, one request). Weight hits to make a limit
+   * count tokens, bytes or money instead of calls; for money, use whole small units (e.g. micro-dollars) so totals
+   * stay exact. `0` reports the current state without recording anything. A cost above the limit is never allowed.
+   */
+  readonly cost?: number;
+}
+/** The cost of a hit: `cost` or {@link DEFAULT_COST}. Throws a `RangeError` for a negative or non-finite cost. */
+declare function hitCost(cost: number | undefined): number;
 /** 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>;
+  /** Record a hit for `key` (see {@link RateHit}: when, and how much it costs) and return the decision. */
+  check(key: string, hit?: RateHit): MaybePromise<RateLimitResult>;
   /** Clear all state for `key`. */
   reset(key: string): MaybePromise<void>;
   /** The rule this limiter enforces. */
@@ -116,6 +138,10 @@ interface Limiter {
  * 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`)
+ *
+ * // a budget: 5 dollars a day, counted in micro-dollars
+ * const spend = limiter({ limit: 5_000_000, window: 86_400_000 })
+ * const { allowed: affordable } = await spend.check(userId, { cost: 12_500 })
  * ```
  */
 declare function limiter(opts: LimiterOptions): Limiter;
@@ -167,6 +193,11 @@ interface RateTaskOptions extends DoerTaskOptions {
   readonly groupWindow?: number;
   /** Algorithm for the group limit (default: the global `algorithm`). */
   readonly groupAlgorithm?: Algorithm;
+  /**
+   * The task's weight against both the global and the group limit (default {@link DEFAULT_COST}). A task waits
+   * until both limits have room for its whole cost; see {@link RateHit.cost}.
+   */
+  readonly cost?: number;
 }
 /** A {@link Doer} whose `do` accepts {@link RateTaskOptions} — i.e. a per-task group limit. */
 interface RateLimitedDoer extends Doer {
@@ -193,6 +224,12 @@ interface RateLimitedDoerOptions extends LimiterOptions {
    * pass a tuned store, e.g. `groupStore: memoryStore({ sweepEvery: 200, idleMs: 30_000 })`.
    */
   readonly groupStore?: RateLimitStore;
+  /**
+   * Which waiting task is admitted next: `'oldest'` (default) by `createdAt`, or `'priority'` — the highest
+   * {@link DoerTaskOptions.priority} first, then the oldest. With `'priority'` an urgent task never waits behind a
+   * backlog of less urgent ones held by the rate limit. Either way a task whose group is at its limit is skipped.
+   */
+  readonly order?: RateDoerOrder;
   /** Floor on the re-check delay for deferred tasks (ms, default 50). */
   readonly retryFloor?: number;
   /** Clock injection (default `Date.now`). */
@@ -217,13 +254,16 @@ interface RateLimitedDoerOptions extends LimiterOptions {
    */
   readonly onError?: (err: unknown) => void;
 }
+/** How {@link rateLimitedDoer} picks the next waiting task to admit; see {@link RateLimitedDoerOptions.order}. */
+type RateDoerOrder = 'oldest' | 'priority';
 /**
  * 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**.
+ * Excess tasks wait and are admitted oldest-first, or most urgent first with `order: 'priority'`; a
+ * distributed store rate-limits **across a fleet**.
  *
  * ```ts
  * import { rateLimitedDoer } from '@ayepi/rate'
@@ -240,6 +280,32 @@ interface RateLimitedDoerOptions extends LimiterOptions {
  * shared global bucket isn't spent on it. `group`/`groupLimit` are read at admission time.
  */
 declare function rateLimitedDoer(opts: RateLimitedDoerOptions): RateLimitedDoer;
+/** A window's running total (`fixed-window`, and each bucket of `sliding-window`), and when the window ends (epoch ms). */
+interface RateCounter {
+  readonly count: number;
+  readonly reset: number;
+}
+/** A token bucket's level, as of `ts` (epoch ms). */
+interface RateBucket {
+  readonly tokens: number;
+  readonly ts: number;
+}
+/** A per-key table of cells an algorithm reads and writes back. A `Map` is one. */
+interface RateCells<V> {
+  get(key: string): V | undefined;
+  set(key: string, value: V): void;
+}
+/** The cells {@link applyHit} works on: window counters and token buckets. */
+interface RateState {
+  readonly counters: RateCells<RateCounter>;
+  readonly buckets: RateCells<RateBucket>;
+}
+/**
+ * Run one hit of weight `cost` for `key` under `rule` at `now` against `state`: the single implementation of all three
+ * algorithms, which {@link memoryStore} runs on Maps and a database-backed {@link RateLimitStore} can run on rows
+ * (inside one transaction, so the read and the write-back are atomic). Every changed cell is written back with `set`.
+ */
+declare function applyHit(state: RateState, key: string, rule: RateLimitRule, now: number, cost: number): RateLimitResult;
 /** Options for {@link memoryStore}. */
 interface MemoryStoreOptions {
   /**
@@ -268,4 +334,4 @@ interface MemoryStoreOptions {
  */
 declare function memoryStore(opts?: MemoryStoreOptions): RateLimitStore;
 //#endregion
-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 };
+export { Algorithm, DEFAULT_ALGORITHM, DEFAULT_COST, DEFAULT_PREFIX, Limiter, LimiterOptions, MemoryStoreOptions, RateBucket, RateCells, RateCounter, RateDoerOrder, RateHit, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedBacklogInfo, RateLimitedDoer, RateLimitedDoerOptions, RateState, RateTaskOptions, applyHit, hitCost, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/index.d.ts

@@ -7,13 +7,18 @@ import { Doer, DoerTaskOptions } from "@ayepi/core/doer";
 declare const DEFAULT_PREFIX = "rl:";
 /** Default algorithm. */
 declare const DEFAULT_ALGORITHM: Algorithm;
+/** What one hit costs when no cost is given: one request. */
+declare const DEFAULT_COST = 1;
 /** 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. */
+  /** The configured limit for the window, in cost units (requests by default). */
   readonly limit: number;
-  /** Requests (or tokens) remaining before the limit is hit. */
+  /**
+   * Cost units remaining before the limit is hit. Whole units for `sliding-window` and `token-bucket` (rounded down);
+   * exact for `fixed-window`.
+   */
   readonly remaining: number;
   /** Milliseconds until the window/bucket resets. */
   readonly reset: number;
@@ -45,8 +50,12 @@ interface RateLimitRule {
  * (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>;
+  /**
+   * Record a hit of weight `cost` for `key` under `rule` at time `now` (ms) and return the decision. The hit is
+   * allowed when the window's total plus `cost` stays within `rule.limit` (for `token-bucket`: when the bucket
+   * holds `cost` tokens). A cost of `0` records nothing and reports the current state.
+   */
+  consume(key: string, rule: RateLimitRule, now: number, cost: number): MaybePromise<RateLimitResult>;
   /** Clear all state for `key` (optional). */
   reset?(key: string): MaybePromise<void>;
 }
@@ -98,10 +107,23 @@ interface RateLimitDefOptions<R extends readonly AnyMiddleware[]> {
   /** Middleware name for docs/debugging (default `'rateLimit'`). */
   readonly name?: string;
 }
+/** One hit against a {@link Limiter}. */
+interface RateHit {
+  /** When the hit happens (ms; default `Date.now()`). */
+  readonly now?: number;
+  /**
+   * The hit's weight in the limit's units (default {@link DEFAULT_COST}, one request). Weight hits to make a limit
+   * count tokens, bytes or money instead of calls; for money, use whole small units (e.g. micro-dollars) so totals
+   * stay exact. `0` reports the current state without recording anything. A cost above the limit is never allowed.
+   */
+  readonly cost?: number;
+}
+/** The cost of a hit: `cost` or {@link DEFAULT_COST}. Throws a `RangeError` for a negative or non-finite cost. */
+declare function hitCost(cost: number | undefined): number;
 /** 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>;
+  /** Record a hit for `key` (see {@link RateHit}: when, and how much it costs) and return the decision. */
+  check(key: string, hit?: RateHit): MaybePromise<RateLimitResult>;
   /** Clear all state for `key`. */
   reset(key: string): MaybePromise<void>;
   /** The rule this limiter enforces. */
@@ -116,6 +138,10 @@ interface Limiter {
  * 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`)
+ *
+ * // a budget: 5 dollars a day, counted in micro-dollars
+ * const spend = limiter({ limit: 5_000_000, window: 86_400_000 })
+ * const { allowed: affordable } = await spend.check(userId, { cost: 12_500 })
  * ```
  */
 declare function limiter(opts: LimiterOptions): Limiter;
@@ -167,6 +193,11 @@ interface RateTaskOptions extends DoerTaskOptions {
   readonly groupWindow?: number;
   /** Algorithm for the group limit (default: the global `algorithm`). */
   readonly groupAlgorithm?: Algorithm;
+  /**
+   * The task's weight against both the global and the group limit (default {@link DEFAULT_COST}). A task waits
+   * until both limits have room for its whole cost; see {@link RateHit.cost}.
+   */
+  readonly cost?: number;
 }
 /** A {@link Doer} whose `do` accepts {@link RateTaskOptions} — i.e. a per-task group limit. */
 interface RateLimitedDoer extends Doer {
@@ -193,6 +224,12 @@ interface RateLimitedDoerOptions extends LimiterOptions {
    * pass a tuned store, e.g. `groupStore: memoryStore({ sweepEvery: 200, idleMs: 30_000 })`.
    */
   readonly groupStore?: RateLimitStore;
+  /**
+   * Which waiting task is admitted next: `'oldest'` (default) by `createdAt`, or `'priority'` — the highest
+   * {@link DoerTaskOptions.priority} first, then the oldest. With `'priority'` an urgent task never waits behind a
+   * backlog of less urgent ones held by the rate limit. Either way a task whose group is at its limit is skipped.
+   */
+  readonly order?: RateDoerOrder;
   /** Floor on the re-check delay for deferred tasks (ms, default 50). */
   readonly retryFloor?: number;
   /** Clock injection (default `Date.now`). */
@@ -217,13 +254,16 @@ interface RateLimitedDoerOptions extends LimiterOptions {
    */
   readonly onError?: (err: unknown) => void;
 }
+/** How {@link rateLimitedDoer} picks the next waiting task to admit; see {@link RateLimitedDoerOptions.order}. */
+type RateDoerOrder = 'oldest' | 'priority';
 /**
  * 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**.
+ * Excess tasks wait and are admitted oldest-first, or most urgent first with `order: 'priority'`; a
+ * distributed store rate-limits **across a fleet**.
  *
  * ```ts
  * import { rateLimitedDoer } from '@ayepi/rate'
@@ -240,6 +280,32 @@ interface RateLimitedDoerOptions extends LimiterOptions {
  * shared global bucket isn't spent on it. `group`/`groupLimit` are read at admission time.
  */
 declare function rateLimitedDoer(opts: RateLimitedDoerOptions): RateLimitedDoer;
+/** A window's running total (`fixed-window`, and each bucket of `sliding-window`), and when the window ends (epoch ms). */
+interface RateCounter {
+  readonly count: number;
+  readonly reset: number;
+}
+/** A token bucket's level, as of `ts` (epoch ms). */
+interface RateBucket {
+  readonly tokens: number;
+  readonly ts: number;
+}
+/** A per-key table of cells an algorithm reads and writes back. A `Map` is one. */
+interface RateCells<V> {
+  get(key: string): V | undefined;
+  set(key: string, value: V): void;
+}
+/** The cells {@link applyHit} works on: window counters and token buckets. */
+interface RateState {
+  readonly counters: RateCells<RateCounter>;
+  readonly buckets: RateCells<RateBucket>;
+}
+/**
+ * Run one hit of weight `cost` for `key` under `rule` at `now` against `state`: the single implementation of all three
+ * algorithms, which {@link memoryStore} runs on Maps and a database-backed {@link RateLimitStore} can run on rows
+ * (inside one transaction, so the read and the write-back are atomic). Every changed cell is written back with `set`.
+ */
+declare function applyHit(state: RateState, key: string, rule: RateLimitRule, now: number, cost: number): RateLimitResult;
 /** Options for {@link memoryStore}. */
 interface MemoryStoreOptions {
   /**
@@ -268,4 +334,4 @@ interface MemoryStoreOptions {
  */
 declare function memoryStore(opts?: MemoryStoreOptions): RateLimitStore;
 //#endregion
-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 };
+export { Algorithm, DEFAULT_ALGORITHM, DEFAULT_COST, DEFAULT_PREFIX, Limiter, LimiterOptions, MemoryStoreOptions, RateBucket, RateCells, RateCounter, RateDoerOrder, RateHit, RateKeyIO, RateLimitDef, RateLimitDefOptions, RateLimitInfo, RateLimitResponseOptions, RateLimitResult, RateLimitRule, RateLimitStore, RateLimitedBacklogInfo, RateLimitedDoer, RateLimitedDoerOptions, RateState, RateTaskOptions, applyHit, hitCost, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/index.js

@@ -41,14 +41,20 @@ const DEFAULT_STATUS = 429;
 const DEFAULT_PREFIX = "rl:";
 /** Default algorithm. */
 const DEFAULT_ALGORITHM = "fixed-window";
-/** Tokens consumed per request (token-bucket). */
-const TOKEN_COST = 1;
+/** What one hit costs when no cost is given: one request. */
+const DEFAULT_COST = 1;
 /** Milliseconds per second — `Retry-After` / `RateLimit-Reset` are expressed in seconds. */
 const MS_PER_SECOND = 1e3;
 /** Amortized cleanup: sweep expired in-memory entries once every this many `consume` calls. */
 const SWEEP_EVERY = 1e3;
 /** Drop an idle in-memory token bucket after this long with no activity (it refills to full anyway). */
 const BUCKET_IDLE_MS = 600 * 1e3;
+/** The cost of a hit: `cost` or {@link DEFAULT_COST}. Throws a `RangeError` for a negative or non-finite cost. */
+function hitCost(cost) {
+	const c = cost ?? 1;
+	if (!Number.isFinite(c) || c < 0) throw new RangeError(`rate-limit cost must be a finite number >= 0, got ${c}`);
+	return c;
+}
 /**
 * Create a standalone {@link Limiter} — the rate-limit primitive the
 * {@link rateLimit} middleware is built on. Use it anywhere you have a key: a
@@ -58,6 +64,10 @@ const BUCKET_IDLE_MS = 600 * 1e3;
 * 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`)
+*
+* // a budget: 5 dollars a day, counted in micro-dollars
+* const spend = limiter({ limit: 5_000_000, window: 86_400_000 })
+* const { allowed: affordable } = await spend.check(userId, { cost: 12_500 })
 * ```
 */
 function limiter(opts) {
@@ -71,7 +81,7 @@ function limiter(opts) {
 	const prefix = opts.prefix ?? "rl:";
 	return {
 		rule,
-		check: (key, now) => store.consume(prefix + key, rule, now ?? Date.now()),
+		check: (key, hit) => store.consume(prefix + key, rule, hit?.now ?? Date.now(), hitCost(hit?.cost)),
 		reset: (key) => Promise.resolve(store.reset?.(prefix + key))
 	};
 }
@@ -135,13 +145,19 @@ function rateLimit(opts) {
 }
 /** Minimum re-check delay when a deferred task has no explicit retry hint (ms). */
 const DOER_RETRY_FLOOR = 50;
+/** Whether `a` is admitted before `b` under `order`; equal ties keep insertion order (the earlier `seq`). */
+const admitsBefore = {
+	oldest: (a, b) => a.createdAt < b.createdAt,
+	priority: (a, b) => a.priority !== b.priority ? a.priority > b.priority : a.createdAt < b.createdAt
+};
 /**
 * 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**.
+* Excess tasks wait and are admitted oldest-first, or most urgent first with `order: 'priority'`; a
+* distributed store rate-limits **across a fleet**.
 *
 * ```ts
 * import { rateLimitedDoer } from '@ayepi/rate'
@@ -166,6 +182,7 @@ function rateLimitedDoer(opts) {
 	const inner = opts.doer ?? unlimitedDoer();
 	const now = opts.now ?? Date.now;
 	const floor = opts.retryFloor ?? DOER_RETRY_FLOOR;
+	const before = admitsBefore[opts.order ?? "oldest"];
 	const keyOf = (o) => typeof opts.key === "function" ? opts.key(o ?? {}) : opts.key ?? "doer";
 	const groupStore = opts.groupStore ?? store;
 	const groupPrefix = (opts.prefix ?? "rl:") + "grp:";
@@ -231,14 +248,14 @@ function rateLimitedDoer(opts) {
 		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.
+	* The first pending task under `order` not skipped this round (a fresh scan, so tasks queued mid-drain are
+	* seen). `pending` is in insertion (seq) order, so equal 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;
+			if (!best || before(t, best)) best = t;
 		}
 		return best;
 	};
@@ -261,7 +278,7 @@ function rateLimitedDoer(opts) {
 				if (groupRule && gk !== void 0) {
 					let gr;
 					try {
-						gr = await groupStore.consume(groupPrefix + gk, groupRule, now());
+						gr = await groupStore.consume(groupPrefix + gk, groupRule, now(), hitCost(o?.cost));
 					} catch (err) {
 						report(err);
 						soonest = Math.min(soonest, floor);
@@ -275,7 +292,10 @@ function rateLimitedDoer(opts) {
 				}
 				let res;
 				try {
-					res = await lim.check(keyOf(o), now());
+					res = await lim.check(keyOf(o), {
+						now: now(),
+						cost: o?.cost
+					});
 				} catch (err) {
 					report(err);
 					soonest = Math.min(soonest, floor);
@@ -301,6 +321,7 @@ function rateLimitedDoer(opts) {
 			pending.push({
 				run: task,
 				opts: o,
+				priority: o?.priority ?? 0,
 				createdAt: o?.createdAt ?? now(),
 				seq: seq++
 			});
@@ -310,43 +331,57 @@ function rateLimitedDoer(opts) {
 		done: () => pending.length === 0 ? inner.done() : new Promise((r) => idle.push(() => void inner.done().then(r)))
 	};
 }
-function fixedWindow(counters, key, rule, now) {
-	let e = counters.get(key);
-	if (!e || e.reset <= now) {
-		e = {
-			count: 0,
-			reset: now + rule.window
-		};
-		counters.set(key, e);
+/**
+* Run one hit of weight `cost` for `key` under `rule` at `now` against `state`: the single implementation of all three
+* algorithms, which {@link memoryStore} runs on Maps and a database-backed {@link RateLimitStore} can run on rows
+* (inside one transaction, so the read and the write-back are atomic). Every changed cell is written back with `set`.
+*/
+function applyHit(state, key, rule, now, cost) {
+	switch (rule.algorithm) {
+		case "sliding-window": return slidingWindow(state.counters, key, rule, now, cost);
+		case "token-bucket": return tokenBucket(state.buckets, key, rule, now, cost);
+		default: return fixedWindow(state.counters, key, rule, now, cost);
 	}
-	const allowed = e.count < rule.limit;
-	if (allowed || rule.countRejected) e.count++;
+}
+function fixedWindow(counters, key, rule, now, cost) {
+	const found = counters.get(key);
+	const e = !found || found.reset <= now ? {
+		count: 0,
+		reset: now + rule.window
+	} : found;
+	const allowed = e.count + cost <= rule.limit;
+	const count = allowed || rule.countRejected ? e.count + cost : e.count;
+	counters.set(key, {
+		count,
+		reset: e.reset
+	});
 	const reset = e.reset - now;
 	return {
 		allowed,
 		limit: rule.limit,
-		remaining: Math.max(0, rule.limit - e.count),
+		remaining: Math.max(0, rule.limit - count),
 		reset,
 		retryAfter: allowed ? 0 : reset
 	};
 }
-function slidingWindow(counters, key, rule, now) {
+function slidingWindow(counters, key, rule, now, cost) {
 	const windowStart = Math.floor(now / rule.window) * rule.window;
 	const curKey = `${key}|${windowStart}`;
 	const prevKey = `${key}|${windowStart - rule.window}`;
-	let cur = counters.get(curKey);
-	if (!cur || cur.reset <= now) {
-		cur = {
-			count: 0,
-			reset: windowStart + rule.window
-		};
-		counters.set(curKey, cur);
-	}
+	const found = counters.get(curKey);
+	const cur = !found || found.reset <= now ? {
+		count: 0,
+		reset: windowStart + rule.window
+	} : found;
 	const prevCount = counters.get(prevKey)?.count ?? 0;
 	const weight = (rule.window - (now - windowStart)) / rule.window;
-	const allowed = prevCount * weight + cur.count + 1 <= rule.limit;
-	if (allowed || rule.countRejected) cur.count++;
-	const weighted = prevCount * weight + cur.count;
+	const allowed = prevCount * weight + cur.count + cost <= rule.limit;
+	const count = allowed || rule.countRejected ? cur.count + cost : cur.count;
+	counters.set(curKey, {
+		count,
+		reset: cur.reset
+	});
+	const weighted = prevCount * weight + count;
 	const reset = windowStart + rule.window - now;
 	return {
 		allowed,
@@ -356,31 +391,27 @@ function slidingWindow(counters, key, rule, now) {
 		retryAfter: allowed ? 0 : reset
 	};
 }
-function tokenBucket(buckets, key, rule, now) {
+function tokenBucket(buckets, key, rule, now, cost) {
 	const cap = rule.limit;
 	const refillPerMs = rule.limit / rule.window;
-	let b = buckets.get(key);
-	if (!b) b = {
+	const b = buckets.get(key) ?? {
 		tokens: cap,
 		ts: now
 	};
-	b.tokens = Math.min(cap, b.tokens + (now - b.ts) * refillPerMs);
-	b.ts = now;
-	const cost = TOKEN_COST;
-	let allowed = false;
-	if (b.tokens >= cost) {
-		b.tokens -= cost;
-		allowed = true;
-	}
-	buckets.set(key, b);
-	const remaining = Math.floor(b.tokens);
-	const retryAfter = allowed ? 0 : Math.ceil((cost - b.tokens) / refillPerMs);
-	const reset = Math.ceil((cap - b.tokens) / refillPerMs);
+	const level = Math.min(cap, b.tokens + (now - b.ts) * refillPerMs);
+	const allowed = level >= cost;
+	const tokens = allowed ? level - cost : level;
+	buckets.set(key, {
+		tokens,
+		ts: now
+	});
+	const remaining = Math.floor(tokens);
+	const retryAfter = allowed ? 0 : Math.ceil((cost - tokens) / refillPerMs);
 	return {
 		allowed,
 		limit: cap,
 		remaining,
-		reset,
+		reset: Math.ceil((cap - tokens) / refillPerMs),
 		retryAfter
 	};
 }
@@ -400,6 +431,10 @@ function memoryStore(opts = {}) {
 	const idleMs = opts.idleMs ?? BUCKET_IDLE_MS;
 	const counters = /* @__PURE__ */ new Map();
 	const buckets = /* @__PURE__ */ new Map();
+	const state = {
+		counters,
+		buckets
+	};
 	let ops = 0;
 	const sweep = (now) => {
 		if (++ops % sweepEvery !== 0) return;
@@ -407,13 +442,9 @@ function memoryStore(opts = {}) {
 		for (const [k, b] of buckets) if (now - b.ts > idleMs) buckets.delete(k);
 	};
 	return {
-		consume(key, rule, now) {
+		consume(key, rule, now, cost) {
 			sweep(now);
-			switch (rule.algorithm) {
-				case "sliding-window": return slidingWindow(counters, key, rule, now);
-				case "token-bucket": return tokenBucket(buckets, key, rule, now);
-				default: return fixedWindow(counters, key, rule, now);
-			}
+			return applyHit(state, key, rule, now, cost);
 		},
 		reset(key) {
 			counters.delete(key);
@@ -423,4 +454,4 @@ function memoryStore(opts = {}) {
 	};
 }
 //#endregion
-export { DEFAULT_ALGORITHM, DEFAULT_PREFIX, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };
+export { DEFAULT_ALGORITHM, DEFAULT_COST, DEFAULT_PREFIX, applyHit, hitCost, limiter, memoryStore, rateLimit, rateLimitHeaders, rateLimitResponse, rateLimitedDoer };

package/dist/redis.cjs

@@ -1,23 +1,21 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/redis.ts
-/** Tokens consumed per request (token-bucket). */
-const TOKEN_COST = 1;
 /** Keep bucketed keys for this many windows so the previous bucket is still readable. */
 const WINDOW_TTL_FACTOR = 2;
 /** The Lua scripts return 1 for an allowed request. */
 const LUA_ALLOWED = 1;
 const FIXED = `
-local c = redis.call('INCR', KEYS[1])
-if c == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
-if c > tonumber(ARGV[2]) and ARGV[3] ~= '1' then redis.call('DECR', KEYS[1]) end
-return {c, redis.call('PTTL', KEYS[1])}`;
+local c = tonumber(redis.call('INCRBYFLOAT', KEYS[1], ARGV[4]))
+if redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+if c > tonumber(ARGV[2]) and ARGV[3] ~= '1' then redis.call('INCRBYFLOAT', KEYS[1], -tonumber(ARGV[4])) end
+return {tostring(c), redis.call('PTTL', KEYS[1])}`;
 const SLIDING = `
-local cur = redis.call('INCR', KEYS[1])
-if cur == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local cur = tonumber(redis.call('INCRBYFLOAT', KEYS[1], ARGV[5]))
+if redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
 local prev = redis.call('GET', KEYS[2])
 prev = prev and tonumber(prev) or 0
-if prev * tonumber(ARGV[2]) + cur > tonumber(ARGV[3]) and ARGV[4] ~= '1' then redis.call('DECR', KEYS[1]) end
-return {cur, prev}`;
+if prev * tonumber(ARGV[2]) + cur > tonumber(ARGV[3]) and ARGV[4] ~= '1' then redis.call('INCRBYFLOAT', KEYS[1], -tonumber(ARGV[5])) end
+return {tostring(cur), tostring(prev)}`;
 const TOKEN = `
 local d = redis.call('HMGET', KEYS[1], 't', 's')
 local tokens = tonumber(d[1])
@@ -43,16 +41,16 @@ const num = (v) => typeof v === "number" ? v : Number(v);
 function redisStore(client, opts = {}) {
 	const ns = opts.prefix ?? "";
 	return {
-		async consume(key, rule, now) {
+		async consume(key, rule, now, cost) {
 			const k = ns + key;
 			if (rule.algorithm === "token-bucket") {
 				const cap = rule.limit;
 				const rate = rule.limit / rule.window;
 				const ttl = Math.ceil(rule.window * WINDOW_TTL_FACTOR);
-				const res = await client.eval(TOKEN, 1, k, cap, rate, now, ttl, TOKEN_COST);
+				const res = await client.eval(TOKEN, 1, k, cap, rate, now, ttl, cost);
 				const allowed = num(res[0]) === LUA_ALLOWED;
 				const tokens = num(res[1]);
-				const retryAfter = allowed ? 0 : Math.ceil((TOKEN_COST - tokens) / rate);
+				const retryAfter = allowed ? 0 : Math.ceil((cost - tokens) / rate);
 				const reset = Math.ceil((cap - tokens) / rate);
 				return {
 					allowed,
@@ -68,7 +66,7 @@ function redisStore(client, opts = {}) {
 				const curKey = `${k}|${windowStart}`;
 				const prevKey = `${k}|${windowStart - rule.window}`;
 				const weight = (rule.window - (now - windowStart)) / rule.window;
-				const res = await client.eval(SLIDING, 2, curKey, prevKey, rule.window * WINDOW_TTL_FACTOR, weight, rule.limit, countRejected);
+				const res = await client.eval(SLIDING, 2, curKey, prevKey, rule.window * WINDOW_TTL_FACTOR, weight, rule.limit, countRejected, cost);
 				const cur = num(res[0]);
 				const weighted = num(res[1]) * weight + cur;
 				const allowed = weighted <= rule.limit;
@@ -81,7 +79,7 @@ function redisStore(client, opts = {}) {
 					retryAfter: allowed ? 0 : reset
 				};
 			}
-			const res = await client.eval(FIXED, 1, k, rule.window, rule.limit, countRejected);
+			const res = await client.eval(FIXED, 1, k, rule.window, rule.limit, countRejected, cost);
 			const count = num(res[0]);
 			const ttl = num(res[1]);
 			const allowed = count <= rule.limit;

package/dist/redis.js

@@ -1,22 +1,20 @@
 //#region src/redis.ts
-/** Tokens consumed per request (token-bucket). */
-const TOKEN_COST = 1;
 /** Keep bucketed keys for this many windows so the previous bucket is still readable. */
 const WINDOW_TTL_FACTOR = 2;
 /** The Lua scripts return 1 for an allowed request. */
 const LUA_ALLOWED = 1;
 const FIXED = `
-local c = redis.call('INCR', KEYS[1])
-if c == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
-if c > tonumber(ARGV[2]) and ARGV[3] ~= '1' then redis.call('DECR', KEYS[1]) end
-return {c, redis.call('PTTL', KEYS[1])}`;
+local c = tonumber(redis.call('INCRBYFLOAT', KEYS[1], ARGV[4]))
+if redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+if c > tonumber(ARGV[2]) and ARGV[3] ~= '1' then redis.call('INCRBYFLOAT', KEYS[1], -tonumber(ARGV[4])) end
+return {tostring(c), redis.call('PTTL', KEYS[1])}`;
 const SLIDING = `
-local cur = redis.call('INCR', KEYS[1])
-if cur == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local cur = tonumber(redis.call('INCRBYFLOAT', KEYS[1], ARGV[5]))
+if redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
 local prev = redis.call('GET', KEYS[2])
 prev = prev and tonumber(prev) or 0
-if prev * tonumber(ARGV[2]) + cur > tonumber(ARGV[3]) and ARGV[4] ~= '1' then redis.call('DECR', KEYS[1]) end
-return {cur, prev}`;
+if prev * tonumber(ARGV[2]) + cur > tonumber(ARGV[3]) and ARGV[4] ~= '1' then redis.call('INCRBYFLOAT', KEYS[1], -tonumber(ARGV[5])) end
+return {tostring(cur), tostring(prev)}`;
 const TOKEN = `
 local d = redis.call('HMGET', KEYS[1], 't', 's')
 local tokens = tonumber(d[1])
@@ -42,16 +40,16 @@ const num = (v) => typeof v === "number" ? v : Number(v);
 function redisStore(client, opts = {}) {
 	const ns = opts.prefix ?? "";
 	return {
-		async consume(key, rule, now) {
+		async consume(key, rule, now, cost) {
 			const k = ns + key;
 			if (rule.algorithm === "token-bucket") {
 				const cap = rule.limit;
 				const rate = rule.limit / rule.window;
 				const ttl = Math.ceil(rule.window * WINDOW_TTL_FACTOR);
-				const res = await client.eval(TOKEN, 1, k, cap, rate, now, ttl, TOKEN_COST);
+				const res = await client.eval(TOKEN, 1, k, cap, rate, now, ttl, cost);
 				const allowed = num(res[0]) === LUA_ALLOWED;
 				const tokens = num(res[1]);
-				const retryAfter = allowed ? 0 : Math.ceil((TOKEN_COST - tokens) / rate);
+				const retryAfter = allowed ? 0 : Math.ceil((cost - tokens) / rate);
 				const reset = Math.ceil((cap - tokens) / rate);
 				return {
 					allowed,
@@ -67,7 +65,7 @@ function redisStore(client, opts = {}) {
 				const curKey = `${k}|${windowStart}`;
 				const prevKey = `${k}|${windowStart - rule.window}`;
 				const weight = (rule.window - (now - windowStart)) / rule.window;
-				const res = await client.eval(SLIDING, 2, curKey, prevKey, rule.window * WINDOW_TTL_FACTOR, weight, rule.limit, countRejected);
+				const res = await client.eval(SLIDING, 2, curKey, prevKey, rule.window * WINDOW_TTL_FACTOR, weight, rule.limit, countRejected, cost);
 				const cur = num(res[0]);
 				const weighted = num(res[1]) * weight + cur;
 				const allowed = weighted <= rule.limit;
@@ -80,7 +78,7 @@ function redisStore(client, opts = {}) {
 					retryAfter: allowed ? 0 : reset
 				};
 			}
-			const res = await client.eval(FIXED, 1, k, rule.window, rule.limit, countRejected);
+			const res = await client.eval(FIXED, 1, k, rule.window, rule.limit, countRejected, cost);
 			const count = num(res[0]);
 			const ttl = num(res[1]);
 			const allowed = count <= rule.limit;

package/dist/server.cjs

@@ -37,9 +37,10 @@ function rateLimitServer(def, opts) {
 			advertise(skipped);
 			return io.next({ ratelimit: skipped });
 		}
+		const cost = require_index.hitCost(opts.cost !== void 0 ? resolve(opts.cost, kio) : void 0);
 		let result;
 		try {
-			result = await store.consume(prefix + opts.key(kio), rule, Date.now());
+			result = await store.consume(prefix + opts.key(kio), rule, Date.now(), cost);
 		} catch (err) {
 			try {
 				opts.onError?.(err);

package/dist/server.d.cts

@@ -46,6 +46,11 @@ interface RateLimitServerOptions<M extends AnyMiddleware> {
    * request. Default `false`; see {@link RateLimitRule.countRejected}.
    */
   readonly countRejected?: Dynamic<M, boolean>;
+  /**
+   * What a request costs against the limit — fixed, or per request (default 1). Weight requests to limit by tokens,
+   * bytes or money (see `RateHit.cost` in `@ayepi/rate`).
+   */
+  readonly cost?: Dynamic<M, number>;
   /** Backend store (default an in-process memory store). */
   readonly store?: RateLimitStore;
   /** Key prefix/namespace (default `'rl:'`). */

package/dist/server.d.ts

@@ -46,6 +46,11 @@ interface RateLimitServerOptions<M extends AnyMiddleware> {
    * request. Default `false`; see {@link RateLimitRule.countRejected}.
    */
   readonly countRejected?: Dynamic<M, boolean>;
+  /**
+   * What a request costs against the limit — fixed, or per request (default 1). Weight requests to limit by tokens,
+   * bytes or money (see `RateHit.cost` in `@ayepi/rate`).
+   */
+  readonly cost?: Dynamic<M, number>;
   /** Backend store (default an in-process memory store). */
   readonly store?: RateLimitStore;
   /** Key prefix/namespace (default `'rl:'`). */

package/dist/server.js

@@ -1,4 +1,4 @@
-import { memoryStore, rateLimit as rateLimit$1, rateLimitHeaders, rateLimitResponse } from "./index.js";
+import { hitCost, memoryStore, rateLimit as rateLimit$1, rateLimitHeaders, rateLimitResponse } from "./index.js";
 //#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) {
@@ -36,9 +36,10 @@ function rateLimitServer(def, opts) {
 			advertise(skipped);
 			return io.next({ ratelimit: skipped });
 		}
+		const cost = hitCost(opts.cost !== void 0 ? resolve(opts.cost, kio) : void 0);
 		let result;
 		try {
-			result = await store.consume(prefix + opts.key(kio), rule, Date.now());
+			result = await store.consume(prefix + opts.key(kio), rule, Date.now(), cost);
 		} catch (err) {
 			try {
 				opts.onError?.(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayepi/rate",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Rate-limiting middleware for @ayepi/core — pluggable stores, multiple algorithms, customizable 429 responses",
   "license": "MIT",
   "publishConfig": {
@@ -59,7 +59,7 @@
   },
   "peerDependencies": {
     "ioredis": "^5",
-    "@ayepi/core": "^0.4.0"
+    "@ayepi/core": "^0.5.0"
   },
   "peerDependenciesMeta": {
     "ioredis": {
@@ -73,8 +73,8 @@
     "testcontainers": "^10.13.0",
     "tsdown": "^0.12.0",
     "vitest": "^2.1.8",
-    "zod": "^4.4.3",
-    "@ayepi/core": "0.4.0"
+    "zod": "^4.6.7",
+    "@ayepi/core": "0.5.0"
   },
   "keywords": [
     "ayepi",