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

package/README.md

@@ -6,7 +6,7 @@
 
 </a>
 
-<h3 align="center">Rate limiting: token-bucket / fixed-window / sliding-window algorithms, deny list, sharding, pluggable stores, and procedure middleware</h3>
+<h3 align="center">Rate limiting: token-bucket / fixed-window / sliding-window algorithms, deny list, pluggable stores, and procedure middleware</h3>
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
@@ -34,7 +34,7 @@
 
 ---
 
-Rate limiting for Lunora: token-bucket, fixed-window, and sliding-window algorithms, a deny list, optional sharding for hot limits, pluggable stores (in-memory, SQL, or the Lunora ORM), and procedure middleware that rides the `.use()` chain.
+Rate limiting for Lunora: token-bucket, fixed-window, and sliding-window algorithms, a deny list, pluggable stores (in-memory, SQL, or the Lunora ORM), and procedure middleware that rides the `.use()` chain.
 
 Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.
 
@@ -59,37 +59,68 @@ to a procedure's `.use(...)` chain. The procedure builders (`mutation`, …) com
 from your app's generated `_generated/server` module, not from a package.
 
 ```ts
-import { RateLimiter, rateLimit } from "@lunora/ratelimit";
+import { dbRateLimit } from "@lunora/ratelimit";
 
 import { mutation } from "./_generated/server";
 
-const limiter = new RateLimiter({
-    config: {
-        login: { kind: "fixed window", period: 60_000, rate: 5 },
-        send: { kind: "token bucket", period: 1_000, rate: 10 },
-    },
-});
-
+const config = {
+    login: { kind: "fixed window", period: 60_000, rate: 5 },
+    send: { kind: "token bucket", period: 1_000, rate: 10 },
+};
+
+// `dbRateLimit` builds the limiter per call, backed by a Lunora table via
+// `ctx.db`, so the count is durable. A `RateLimiter` built with no explicit
+// `store` falls back to `createMemoryStore` (a per-instance in-memory Map) —
+// fine for a limit that only ever needs to hold within one Durable Object
+// instance, but a limiter like `login` needs a durable store or it stops
+// enforcing the configured rate the moment the DO instance is sharded,
+// replicated, or recreated.
 // As procedure middleware — throws a structural LunoraError (429/403) on rejection.
-export const send = mutation.use(rateLimit(limiter, "send", { key: (ctx) => ctx.auth.userId })).mutation(async ({ ctx }) => {
+// `key` must resolve to a string — a resolver returning `undefined` throws
+// rather than silently sharing one bucket across every keyless caller.
+export const send = mutation.use(dbRateLimit(config, "send", { key: (ctx) => ctx.auth.userId ?? "anonymous" })).mutation(async ({ ctx }) => {
     // …
 });
 ```
 
-Or call the limiter directly:
+Or call the limiter directly, inside a mutation/action so `ctx.db` is available.
+A login limiter belongs in an **action**: a mutation's `ctx.db` writes ride its
+storage transaction, so a handler that throws (a wrong password) rolls the
+consumed unit back and every failed attempt is free. An action's writes commit
+on their own, so the charge stays whether or not the handler throws.
 
 ```ts
-const status = await limiter.limit("send", { key: userId });
+import { RateLimiter, RateLimitError, createDbStore } from "@lunora/ratelimit";
+
+import { action } from "./_generated/server";
 
-if (!status.ok) {
-    // status.retryAfter is milliseconds until the request would succeed.
-    // status.reason is "rate" or "deny".
-}
+export const login = action.action(async ({ ctx, args }) => {
+    const limiter = new RateLimiter({ config, store: createDbStore({ db: ctx.db }) });
+    const status = await limiter.limit("login", { key: args.email });
+
+    if (!status.ok) {
+        // Stop here — `limit` returns a failing status by default rather than
+        // throwing, so falling through authenticates the rejected attempt.
+        // status.retryAfter is milliseconds until the request would succeed.
+        // status.reason is "rate" or "deny".
+        throw new RateLimitError(status);
+    }
+
+    await authenticate(args);
+});
 ```
 
 For durable per-DO state inside a procedure, back the limiter with a Lunora
 table via `dbRateLimit(config, name, options)`, or supply a `store`
-(`createMemoryStore` / `createSqlStore` / `createDbStore`).
+(`createSqlStore` / `createDbStore`). `createMemoryStore` stays the default —
+correct inside a single Durable Object — but constructing a `RateLimiter` with
+no explicit `store` now warns once so that choice is visible instead of
+silent.
+
+A key that is an IPv6 address (for example `ctx.ip`) is bucketed by its /64
+prefix, and an IPv4-mapped address by the IPv4 address it wraps. An IPv6 client
+usually controls a whole /64, so a per-address bucket would let it pick a fresh
+address for every request. A deny-list IPv6 entry bans its /64.
 
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs)**.
 

package/dist/index.d.mts

@@ -19,18 +19,6 @@ interface RateLimitConfig {
   period: number;
   /** Tokens granted per `period`. */
   rate: number;
-  /**
-   * Split a hot limit across N independent sub-buckets to avoid a single
-   * contended key/Durable Object. Each shard enforces `rate / shards` (and
-   * `capacity / shards`); a request is routed to a shard via a deterministic
-   * hash of `(name, key)`, so the same key always lands on the same shard and
-   * a single key's effective throughput is exactly `rate / shards`. Aggregate
-   * throughput across many distinct keys approaches `rate` as keys spread
-   * uniformly across shards. Reserve it for high-volume limits where
-   * contention bites; leave unset (one bucket) otherwise. Must be a positive
-   * integer — `1` is equivalent to unset.
-   */
-  shards?: number;
   /**
    * Phase offset in epoch milliseconds for windowed algorithms — windows
    * align to `start + n * period`. Ignored by token buckets. Defaults to `0`.
@@ -135,11 +123,15 @@ interface RateLimiterOptions<Names extends string> {
   denyList?: Iterable<string>;
   /**
    * Optional key normalizer applied to every incoming `args.key` (the
-   * deny-list check, the storage key, and downstream shard selection all see
-   * the normalized form). Use for case-folding, trimming, or canonicalizing
-   * IPs/emails so equivalent inputs share a single bucket. The deny-list
+   * deny-list check and the storage key both see the normalized form). Use for case-folding, trimming, or canonicalizing
+   * emails so equivalent inputs share a single bucket. The deny-list
    * itself is consulted as-is; normalize the deny-list entries up front to
    * match.
+   *
+   * After it, a key that is an IPv6 address is always collapsed to its /64
+   * (`2001:db8:1:2::/64`) and an IPv4-mapped one to its IPv4 address, so a
+   * `ctx.ip`-keyed limit cannot be dodged by rotating addresses within one
+   * delegated prefix. A deny-list IPv6 entry therefore bans its whole /64.
    */
   normalize?: (key: string) => string;
   /** Clock injection for tests. Defaults to `Date.now`. */
@@ -166,9 +158,7 @@ declare class RateLimiter<Names extends string = string> {
    * Read the current config and the units admittable right now for a
    * `(name, key)` pair. The value is projected forward to the current clock
    * (token-bucket refill, fixed-window rollover, sliding-window decay), not
-   * the last persisted figure. For a sharded limit it reads only the single
-   * shard `limit()`/`run()` would route this key to — the sibling shards are
-   * never touched by this key, so summing them would over-report.
+   * the last persisted figure.
    */
   getValue(name: Names, args?: {
     key?: string;
@@ -183,6 +173,7 @@ declare class RateLimiter<Names extends string = string> {
   reset(name: Names, args?: {
     key?: string;
   }): Promise<void>;
+  private normalizeKey;
   private resolve;
   private run;
 }
@@ -202,7 +193,15 @@ interface RateLimitMiddlewareOptions<Context> {
    * — note that a failing limiter then permits every request through.
    */
   failOpen?: boolean;
-  /** Sub-key derived from `ctx` (per-user/IP). Omit for a global limit. */
+  /**
+   * Sub-key derived from `ctx` (per-user/IP). Omit for a global limit.
+   *
+   * A resolver that returns `undefined` is a config bug, not a global limit:
+   * the middleware throws `INTERNAL` rather than silently pooling every
+   * keyless caller (e.g. every anonymous user) into one shared bucket. Fold
+   * the absent case yourself — `ctx.auth.userId ?? "anonymous"` — so the
+   * shared bucket is a visible choice.
+   */
   key?: (context: Context) => string | undefined;
   /** Override the error message thrown on rejection. */
   message?: string;
@@ -211,7 +210,7 @@ interface RateLimitMiddlewareOptions<Context> {
  * Procedure middleware that enforces a named rate limit before the handler
  * runs. Attach it with `.use()`. On rejection it throws a structural
  * `LunoraError` (`TOO_MANY_REQUESTS`/429, or `FORBIDDEN`/403 for deny-list
- * hits) carrying `retryAfter` in milliseconds — the runtime maps it to the
+ * hits) carrying `data.retryAfterMs` — the runtime maps it to the
  * matching RPC/HTTP status without any import of `@lunora/server` at runtime.
  *
  * **Failure policy:** if resolving or invoking the limiter throws for a genuine
@@ -278,21 +277,33 @@ interface RateLimitDatabaseQuery {
   first: () => Promise<Record<string, unknown> | null>;
   withIndex: (indexName: string, range: (q: RateLimitDatabaseIndexRange) => RateLimitDatabaseIndexRange) => RateLimitDatabaseQuery;
 }
+/**
+ * The READ slice — everything the store needs to answer `RateLimiter.getValue`
+ * and `check`, which the docs describe as projecting the stored value forward to
+ * the current clock. A `QueryCtx`'s `ctx.db` is a reader and satisfies this.
+ *
+ * Split out because requiring the writer for a pure read meant "how many
+ * requests does this user have left" could not be answered from a query context
+ * at all — every remaining-quota display had to cast, and a cast that appears
+ * often enough stops carrying information. The distinction was already in the
+ * methods: `getValue`/`check` read, `limit`/`reset` write.
+ */
+interface RateLimitDatabaseReader {
+  query: (table: string) => RateLimitDatabaseQuery;
+}
 /**
  * The slice of the Lunora ORM writer (`ctx.db` on a mutation/action) the store
  * needs. The real `DatabaseWriter` is structurally assignable, so pass `ctx.db`
  * directly — declared here (rather than imported) to keep `@lunora/ratelimit`
  * free of a runtime dependency on `@lunora/server`.
  */
-interface RateLimitDatabase {
+interface RateLimitDatabase extends RateLimitDatabaseReader {
   delete: <T extends string>(id: Id<T>) => Promise<void>;
   insert: <T extends string>(table: T, document: Record<string, unknown>) => Promise<Id<T>>;
   patch: <T extends string>(id: Id<T>, patch: Record<string, unknown>) => Promise<void>;
-  query: (table: string) => RateLimitDatabaseQuery;
 }
-interface DatabaseStoreOptions {
-  /** The Lunora ORM writer — `ctx.db` inside a mutation or action. */
-  db: RateLimitDatabase;
+/** The table/column/index knobs shared by the read-only and read-write stores. */
+interface DatabaseStoreLocation {
   /** Index that resolves a row by its key column. Defaults to `by_key`. */
   index?: string;
   /** Column storing the opaque key. Defaults to `key`. */
@@ -300,6 +311,14 @@ interface DatabaseStoreOptions {
   /** Table holding one row per `(name, key)` pair. Defaults to `rateLimits`. */
   table?: string;
 }
+interface DatabaseStoreOptions extends DatabaseStoreLocation {
+  /** The Lunora ORM writer — `ctx.db` inside a mutation or action. */
+  db: RateLimitDatabase;
+}
+interface ReadOnlyDatabaseStoreOptions extends DatabaseStoreLocation {
+  /** The Lunora ORM reader — `ctx.db` inside a query. */
+  db: RateLimitDatabaseReader;
+}
 /**
  * Store backed by a Lunora table through `ctx.db`, for durable per-DO limits
  * inside a procedure (the procedure context exposes no raw SQL). Declare a
@@ -316,8 +335,29 @@ interface DatabaseStoreOptions {
  *
  * Each operation is a read-then-write; inside a mutation/action that pair runs
  * under the DO's input gate, so it is atomic against concurrent calls.
+ *
+ * **Consumption commits with the procedure.** A mutation's `ctx.db` writes ride
+ * its storage transaction, so a handler that throws after `limit()` rolls the
+ * consumed unit back with everything else — inside a mutation this store counts
+ * successful calls, not attempts. To charge every attempt (a login limiter),
+ * consume from an action, where each write commits on its own, or return a
+ * failure value from the mutation instead of throwing.
  */
 declare const createDatabaseStore: (options: DatabaseStoreOptions) => RateLimitStore;
+/**
+ * Read-only counterpart to {@link createDatabaseStore}, for a query context.
+ *
+ * `get` behaves identically — same table, index and key column — so
+ * `RateLimiter.getValue` / `check` report exactly what the writing store would.
+ * `set` and `delete` are the only difference: they throw rather than silently
+ * doing nothing, because a limiter that appears to consume budget and does not
+ * is worse than one that refuses.
+ *
+ * This mirrors the split Lunora already makes for `ctx.storage`, which is a
+ * `ReadOnlyStorage` in a query and a full `Storage` in an action — the
+ * capability difference is visible in the type instead of discovered at runtime.
+ */
+declare const createReadOnlyDatabaseStore: (options: ReadOnlyDatabaseStoreOptions) => RateLimitStore;
 /**
  * DB-backed rate-limit middleware sugar. Collapses the common
  *
@@ -336,6 +376,11 @@ declare const createDatabaseStore: (options: DatabaseStoreOptions) => RateLimitS
  * {@link rateLimit} unchanged. When `config` is precisely typed, `name`
  * autocompletes to its declared limit names.
  *
+ * On a mutation the consumed unit commits with the handler: a handler that
+ * throws rolls it back, so a failed call costs nothing. Attach it to an action
+ * (whose writes commit independently) when failed attempts must count — see
+ * {@link createDatabaseStore}.
+ *
  * Re-exported as `dbRateLimit` from the package root.
  *
  * ```ts
@@ -386,7 +431,7 @@ interface RatelimitApiContext<Context> {
  *
  * ```ts
  * const limiter = new RateLimiter({ config: { send: { kind: "token bucket", rate: 5, period: 60_000, capacity: 5 } } });
- * const c = initLunora.dataModel&lt;DataModel>().create();
+ * const c = initLunora.dataModel<DataModel>().create();
  * export const send = c.mutation
  *     .use(ratelimitPlugin(limiter).middleware!)
  *     .mutation(async ({ ctx, args }) => {
@@ -405,5 +450,50 @@ interface RatelimitApiContext<Context> {
  * `@lunora/server` a type-only dependency of `@lunora/ratelimit`.
  */
 declare const ratelimitPlugin: <Context = unknown>(limiter: LimiterResolver<Context>) => Plugin<Record<never, never>, Context, Context & RatelimitApiContext<Context>>;
+/** A budget bound to one named limit — check before the call, record after it. */
+interface TokenBudget {
+  /**
+   * Peek at the budget before spending. `ok: false` means it is exhausted:
+   * refuse the call, and `retryAfter` says when it refills. Consumes nothing.
+   */
+  check: (key: string) => Promise<RateLimitStatus>;
+  /**
+   * Charge the tokens a call actually used. Always call it, including when the
+   * call THREW — a failed generation that consumed input tokens still has to be
+   * paid for. `tokens` of `0` is a no-op, so a call that spent nothing costs
+   * nothing.
+   *
+   * The charge is a reservation, so it may take the bucket negative: the tokens
+   * are already spent, and refusing to record them would let a single oversized
+   * call escape the budget entirely.
+   */
+  record: (key: string, tokens: number) => Promise<RateLimitStatus>;
+}
+/**
+ * Bind a {@link TokenBudget} to one of a limiter's named limits.
+ *
+ * ```ts
+ * const budget = tokenBudget(limiter, "tokens");
+ * const allowed = await budget.check(userId);
+ *
+ * if (!allowed.ok) {
+ *     throw new LunoraError("RATE_LIMITED", `token budget exhausted; retry in ${String(allowed.retryAfter)}ms`);
+ * }
+ *
+ * try {
+ *     const { text, usage } = await generateText({ model: ctx.ai.model(), prompt });
+ *
+ *     await budget.record(userId, usage?.totalTokens ?? 0);
+ *
+ *     return text;
+ * } catch (error) {
+ *     // The prompt was still sent — charge what is known, then rethrow.
+ *     await budget.record(userId, estimatedInputTokens);
+ *
+ *     throw error;
+ * }
+ * ```
+ */
+declare const tokenBudget: <Names extends string>(limiter: RateLimiter<Names>, name: Names) => TokenBudget;
 declare const VERSION = "0.0.0";
-export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type SqlLike, type SqlStoreOptions, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin };
+export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, type RateLimitDatabaseReader as RateLimitDbReader, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type ReadOnlyDatabaseStoreOptions as ReadOnlyDbStoreOptions, type SqlLike, type SqlStoreOptions, type TokenBudget, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createReadOnlyDatabaseStore as createReadOnlyDbStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin, tokenBudget };

package/dist/index.d.ts

@@ -19,18 +19,6 @@ interface RateLimitConfig {
   period: number;
   /** Tokens granted per `period`. */
   rate: number;
-  /**
-   * Split a hot limit across N independent sub-buckets to avoid a single
-   * contended key/Durable Object. Each shard enforces `rate / shards` (and
-   * `capacity / shards`); a request is routed to a shard via a deterministic
-   * hash of `(name, key)`, so the same key always lands on the same shard and
-   * a single key's effective throughput is exactly `rate / shards`. Aggregate
-   * throughput across many distinct keys approaches `rate` as keys spread
-   * uniformly across shards. Reserve it for high-volume limits where
-   * contention bites; leave unset (one bucket) otherwise. Must be a positive
-   * integer — `1` is equivalent to unset.
-   */
-  shards?: number;
   /**
    * Phase offset in epoch milliseconds for windowed algorithms — windows
    * align to `start + n * period`. Ignored by token buckets. Defaults to `0`.
@@ -135,11 +123,15 @@ interface RateLimiterOptions<Names extends string> {
   denyList?: Iterable<string>;
   /**
    * Optional key normalizer applied to every incoming `args.key` (the
-   * deny-list check, the storage key, and downstream shard selection all see
-   * the normalized form). Use for case-folding, trimming, or canonicalizing
-   * IPs/emails so equivalent inputs share a single bucket. The deny-list
+   * deny-list check and the storage key both see the normalized form). Use for case-folding, trimming, or canonicalizing
+   * emails so equivalent inputs share a single bucket. The deny-list
    * itself is consulted as-is; normalize the deny-list entries up front to
    * match.
+   *
+   * After it, a key that is an IPv6 address is always collapsed to its /64
+   * (`2001:db8:1:2::/64`) and an IPv4-mapped one to its IPv4 address, so a
+   * `ctx.ip`-keyed limit cannot be dodged by rotating addresses within one
+   * delegated prefix. A deny-list IPv6 entry therefore bans its whole /64.
    */
   normalize?: (key: string) => string;
   /** Clock injection for tests. Defaults to `Date.now`. */
@@ -166,9 +158,7 @@ declare class RateLimiter<Names extends string = string> {
    * Read the current config and the units admittable right now for a
    * `(name, key)` pair. The value is projected forward to the current clock
    * (token-bucket refill, fixed-window rollover, sliding-window decay), not
-   * the last persisted figure. For a sharded limit it reads only the single
-   * shard `limit()`/`run()` would route this key to — the sibling shards are
-   * never touched by this key, so summing them would over-report.
+   * the last persisted figure.
    */
   getValue(name: Names, args?: {
     key?: string;
@@ -183,6 +173,7 @@ declare class RateLimiter<Names extends string = string> {
   reset(name: Names, args?: {
     key?: string;
   }): Promise<void>;
+  private normalizeKey;
   private resolve;
   private run;
 }
@@ -202,7 +193,15 @@ interface RateLimitMiddlewareOptions<Context> {
    * — note that a failing limiter then permits every request through.
    */
   failOpen?: boolean;
-  /** Sub-key derived from `ctx` (per-user/IP). Omit for a global limit. */
+  /**
+   * Sub-key derived from `ctx` (per-user/IP). Omit for a global limit.
+   *
+   * A resolver that returns `undefined` is a config bug, not a global limit:
+   * the middleware throws `INTERNAL` rather than silently pooling every
+   * keyless caller (e.g. every anonymous user) into one shared bucket. Fold
+   * the absent case yourself — `ctx.auth.userId ?? "anonymous"` — so the
+   * shared bucket is a visible choice.
+   */
   key?: (context: Context) => string | undefined;
   /** Override the error message thrown on rejection. */
   message?: string;
@@ -211,7 +210,7 @@ interface RateLimitMiddlewareOptions<Context> {
  * Procedure middleware that enforces a named rate limit before the handler
  * runs. Attach it with `.use()`. On rejection it throws a structural
  * `LunoraError` (`TOO_MANY_REQUESTS`/429, or `FORBIDDEN`/403 for deny-list
- * hits) carrying `retryAfter` in milliseconds — the runtime maps it to the
+ * hits) carrying `data.retryAfterMs` — the runtime maps it to the
  * matching RPC/HTTP status without any import of `@lunora/server` at runtime.
  *
  * **Failure policy:** if resolving or invoking the limiter throws for a genuine
@@ -278,21 +277,33 @@ interface RateLimitDatabaseQuery {
   first: () => Promise<Record<string, unknown> | null>;
   withIndex: (indexName: string, range: (q: RateLimitDatabaseIndexRange) => RateLimitDatabaseIndexRange) => RateLimitDatabaseQuery;
 }
+/**
+ * The READ slice — everything the store needs to answer `RateLimiter.getValue`
+ * and `check`, which the docs describe as projecting the stored value forward to
+ * the current clock. A `QueryCtx`'s `ctx.db` is a reader and satisfies this.
+ *
+ * Split out because requiring the writer for a pure read meant "how many
+ * requests does this user have left" could not be answered from a query context
+ * at all — every remaining-quota display had to cast, and a cast that appears
+ * often enough stops carrying information. The distinction was already in the
+ * methods: `getValue`/`check` read, `limit`/`reset` write.
+ */
+interface RateLimitDatabaseReader {
+  query: (table: string) => RateLimitDatabaseQuery;
+}
 /**
  * The slice of the Lunora ORM writer (`ctx.db` on a mutation/action) the store
  * needs. The real `DatabaseWriter` is structurally assignable, so pass `ctx.db`
  * directly — declared here (rather than imported) to keep `@lunora/ratelimit`
  * free of a runtime dependency on `@lunora/server`.
  */
-interface RateLimitDatabase {
+interface RateLimitDatabase extends RateLimitDatabaseReader {
   delete: <T extends string>(id: Id<T>) => Promise<void>;
   insert: <T extends string>(table: T, document: Record<string, unknown>) => Promise<Id<T>>;
   patch: <T extends string>(id: Id<T>, patch: Record<string, unknown>) => Promise<void>;
-  query: (table: string) => RateLimitDatabaseQuery;
 }
-interface DatabaseStoreOptions {
-  /** The Lunora ORM writer — `ctx.db` inside a mutation or action. */
-  db: RateLimitDatabase;
+/** The table/column/index knobs shared by the read-only and read-write stores. */
+interface DatabaseStoreLocation {
   /** Index that resolves a row by its key column. Defaults to `by_key`. */
   index?: string;
   /** Column storing the opaque key. Defaults to `key`. */
@@ -300,6 +311,14 @@ interface DatabaseStoreOptions {
   /** Table holding one row per `(name, key)` pair. Defaults to `rateLimits`. */
   table?: string;
 }
+interface DatabaseStoreOptions extends DatabaseStoreLocation {
+  /** The Lunora ORM writer — `ctx.db` inside a mutation or action. */
+  db: RateLimitDatabase;
+}
+interface ReadOnlyDatabaseStoreOptions extends DatabaseStoreLocation {
+  /** The Lunora ORM reader — `ctx.db` inside a query. */
+  db: RateLimitDatabaseReader;
+}
 /**
  * Store backed by a Lunora table through `ctx.db`, for durable per-DO limits
  * inside a procedure (the procedure context exposes no raw SQL). Declare a
@@ -316,8 +335,29 @@ interface DatabaseStoreOptions {
  *
  * Each operation is a read-then-write; inside a mutation/action that pair runs
  * under the DO's input gate, so it is atomic against concurrent calls.
+ *
+ * **Consumption commits with the procedure.** A mutation's `ctx.db` writes ride
+ * its storage transaction, so a handler that throws after `limit()` rolls the
+ * consumed unit back with everything else — inside a mutation this store counts
+ * successful calls, not attempts. To charge every attempt (a login limiter),
+ * consume from an action, where each write commits on its own, or return a
+ * failure value from the mutation instead of throwing.
  */
 declare const createDatabaseStore: (options: DatabaseStoreOptions) => RateLimitStore;
+/**
+ * Read-only counterpart to {@link createDatabaseStore}, for a query context.
+ *
+ * `get` behaves identically — same table, index and key column — so
+ * `RateLimiter.getValue` / `check` report exactly what the writing store would.
+ * `set` and `delete` are the only difference: they throw rather than silently
+ * doing nothing, because a limiter that appears to consume budget and does not
+ * is worse than one that refuses.
+ *
+ * This mirrors the split Lunora already makes for `ctx.storage`, which is a
+ * `ReadOnlyStorage` in a query and a full `Storage` in an action — the
+ * capability difference is visible in the type instead of discovered at runtime.
+ */
+declare const createReadOnlyDatabaseStore: (options: ReadOnlyDatabaseStoreOptions) => RateLimitStore;
 /**
  * DB-backed rate-limit middleware sugar. Collapses the common
  *
@@ -336,6 +376,11 @@ declare const createDatabaseStore: (options: DatabaseStoreOptions) => RateLimitS
  * {@link rateLimit} unchanged. When `config` is precisely typed, `name`
  * autocompletes to its declared limit names.
  *
+ * On a mutation the consumed unit commits with the handler: a handler that
+ * throws rolls it back, so a failed call costs nothing. Attach it to an action
+ * (whose writes commit independently) when failed attempts must count — see
+ * {@link createDatabaseStore}.
+ *
  * Re-exported as `dbRateLimit` from the package root.
  *
  * ```ts
@@ -386,7 +431,7 @@ interface RatelimitApiContext<Context> {
  *
  * ```ts
  * const limiter = new RateLimiter({ config: { send: { kind: "token bucket", rate: 5, period: 60_000, capacity: 5 } } });
- * const c = initLunora.dataModel&lt;DataModel>().create();
+ * const c = initLunora.dataModel<DataModel>().create();
  * export const send = c.mutation
  *     .use(ratelimitPlugin(limiter).middleware!)
  *     .mutation(async ({ ctx, args }) => {
@@ -405,5 +450,50 @@ interface RatelimitApiContext<Context> {
  * `@lunora/server` a type-only dependency of `@lunora/ratelimit`.
  */
 declare const ratelimitPlugin: <Context = unknown>(limiter: LimiterResolver<Context>) => Plugin<Record<never, never>, Context, Context & RatelimitApiContext<Context>>;
+/** A budget bound to one named limit — check before the call, record after it. */
+interface TokenBudget {
+  /**
+   * Peek at the budget before spending. `ok: false` means it is exhausted:
+   * refuse the call, and `retryAfter` says when it refills. Consumes nothing.
+   */
+  check: (key: string) => Promise<RateLimitStatus>;
+  /**
+   * Charge the tokens a call actually used. Always call it, including when the
+   * call THREW — a failed generation that consumed input tokens still has to be
+   * paid for. `tokens` of `0` is a no-op, so a call that spent nothing costs
+   * nothing.
+   *
+   * The charge is a reservation, so it may take the bucket negative: the tokens
+   * are already spent, and refusing to record them would let a single oversized
+   * call escape the budget entirely.
+   */
+  record: (key: string, tokens: number) => Promise<RateLimitStatus>;
+}
+/**
+ * Bind a {@link TokenBudget} to one of a limiter's named limits.
+ *
+ * ```ts
+ * const budget = tokenBudget(limiter, "tokens");
+ * const allowed = await budget.check(userId);
+ *
+ * if (!allowed.ok) {
+ *     throw new LunoraError("RATE_LIMITED", `token budget exhausted; retry in ${String(allowed.retryAfter)}ms`);
+ * }
+ *
+ * try {
+ *     const { text, usage } = await generateText({ model: ctx.ai.model(), prompt });
+ *
+ *     await budget.record(userId, usage?.totalTokens ?? 0);
+ *
+ *     return text;
+ * } catch (error) {
+ *     // The prompt was still sent — charge what is known, then rethrow.
+ *     await budget.record(userId, estimatedInputTokens);
+ *
+ *     throw error;
+ * }
+ * ```
+ */
+declare const tokenBudget: <Names extends string>(limiter: RateLimiter<Names>, name: Names) => TokenBudget;
 declare const VERSION = "0.0.0";
-export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type SqlLike, type SqlStoreOptions, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin };
+export { type DatabaseStoreOptions as DbStoreOptions, type EvaluateOptions, type EvaluateResult, type LimiterResolver, type RateLimitArgs, type RateLimitConfig, type RateLimitConfigMap, type RateLimitDatabase as RateLimitDb, type RateLimitDatabaseIndexRange as RateLimitDbIndexRange, type RateLimitDatabaseQuery as RateLimitDbQuery, type RateLimitDatabaseReader as RateLimitDbReader, RateLimitError, type RateLimitKind, type RateLimitMiddlewareOptions, type RateLimitReason, type RateLimitStatus, type RateLimitStore, type RateLimitValue, RateLimiter, type RateLimiterOptions, type RatelimitApiContext, type ReadOnlyDatabaseStoreOptions as ReadOnlyDbStoreOptions, type SqlLike, type SqlStoreOptions, type TokenBudget, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createReadOnlyDatabaseStore as createReadOnlyDbStore, createSqlStore, databaseRateLimit as dbRateLimit, evaluate, rateLimit, ratelimitPlugin, tokenBudget };

package/dist/index.mjs

@@ -1,11 +1 @@
-export { availableAt, evaluate } from './packem_shared/availableAt-DQcuVfSA.mjs';
-export { default as dbRateLimit } from './packem_shared/dbRateLimit-WTU-e0r6.mjs';
-export { default as RateLimitError } from './packem_shared/RateLimitError-CiLy3DsZ.mjs';
-export { rateLimit } from './packem_shared/rateLimit-BBdG9GFo.mjs';
-export { ratelimitPlugin } from './packem_shared/ratelimitPlugin-D5_-KV1T.mjs';
-export { RateLimiter } from './packem_shared/RateLimiter-rDCxu_Nx.mjs';
-export { createDbStore, createMemoryStore, createSqlStore } from './packem_shared/createDbStore-L1kD1g1n.mjs';
-
-const VERSION = "0.0.0";
-
-export { VERSION };
+import{availableAt as o,evaluate as a}from"./packem_shared/availableAt-BSKYrouo.mjs";import{default as i}from"./packem_shared/dbRateLimit-BuvEF1x0.mjs";import{default as l}from"./packem_shared/RateLimitError-9Y5OLxpl.mjs";import{rateLimit as x}from"./packem_shared/rateLimit-CWZur6XE.mjs";import{ratelimitPlugin as c}from"./packem_shared/ratelimitPlugin-CFnDs9rj.mjs";import{RateLimiter as u}from"./packem_shared/RateLimiter-Cbc67DNk.mjs";import{createDbStore as b,createMemoryStore as n,createReadOnlyDbStore as L,createSqlStore as s}from"./packem_shared/createDbStore-ve7GsO2i.mjs";import{tokenBudget as v}from"./packem_shared/tokenBudget-BRlWn1im.mjs";const e="0.0.0";export{l as RateLimitError,u as RateLimiter,e as VERSION,o as availableAt,b as createDbStore,n as createMemoryStore,L as createReadOnlyDbStore,s as createSqlStore,i as dbRateLimit,a as evaluate,x as rateLimit,c as ratelimitPlugin,v as tokenBudget};

package/dist/packem_shared/RateLimitError-9Y5OLxpl.mjs

@@ -0,0 +1 @@
+import{LunoraError as n}from"@lunora/errors";import{STATUS_BY_REASON as a}from"./rateLimit-CWZur6XE.mjs";const s=r=>r.reason==="deny"?"request denied (deny list)":Number.isFinite(r.retryAfter)?`rate limit exceeded; retry after ${String(Math.ceil(r.retryAfter))}ms`:"rate limit exceeded";class c extends n{reason;retryAfter;constructor(e,t){const{code:i,status:o}=a[e.reason??"rate"];super(i,t??s(e),{name:"RateLimitError",status:o}),this.reason=e.reason,this.retryAfter=e.retryAfter}}export{c as default};

package/dist/packem_shared/RateLimiter-Cbc67DNk.mjs

@@ -0,0 +1 @@
+import{LunoraError as l}from"@lunora/errors";import{availableAt as p,evaluate as y}from"./availableAt-BSKYrouo.mjs";import f from"./RateLimitError-9Y5OLxpl.mjs";import{createMemoryStore as v}from"./createDbStore-ve7GsO2i.mjs";const b=/^[\d.:a-f]+$/iu,w=i=>{const t=i.indexOf("%"),e=t===-1?i:i.slice(0,t);if(!e.includes(":")||!b.test(e))return i;let r;try{r=new URL(`http://[${e}]/`).hostname.slice(1,-1)}catch{return i}const[a="",s]=r.split("::"),n=a===""?[]:a.split(":"),h=s===void 0||s===""?[]:s.split(":"),c=[...n,...Array.from({length:8-n.length-h.length},()=>"0"),...h].map(o=>Number.parseInt(o,16));if(c.slice(0,5).every(o=>o===0)&&c[5]===65535){const[o=0,m=0]=c.slice(6);return[o>>8,o&255,m>>8,m&255].join(".")}return`${c.slice(0,4).map(o=>o.toString(16)).join(":")}::/64`},u=(i,t)=>t===void 0?encodeURIComponent(i):`${encodeURIComponent(i)}:${encodeURIComponent(t)}`,g=i=>i?t=>w(i(t)):w,N="@lunora/ratelimit: new RateLimiter() was built with no explicit `store`, so it falls back to `createMemoryStore()` — an in-process Map. That Map is durable and correctly shared only for calls that land on the same Durable Object instance; it is NOT shared across `.shardBy(...)` shards or `.global()` replicas, and it resets when the DO instance is evicted/restarted. For a limit that must hold across any of those, pass a durable `store` (`createDbStore` or `createSqlStore`) instead. Pass `store: createMemoryStore()` explicitly once you've confirmed the in-memory default is correct here, to silence this warning.";class S{config;denyList;normalize;now;store;constructor(t){this.config=t.config,this.normalize=g(t.normalize),this.denyList=new Set([...t.denyList??[]].flatMap(e=>[e,this.normalize(e)])),this.now=t.now??Date.now,t.store===void 0&&console.warn(N),this.store=t.store??v();for(const[e,r]of Object.entries(this.config)){if(Object.hasOwn(r,"shards"))throw new l("INTERNAL",`rate limit "${e}": \`shards\` is no longer supported — remove it; the limit now enforces its full \`rate\` (lower \`rate\` if you raised it to offset the split)`);if(!Number.isFinite(r.period)||r.period<=0)throw new l("INTERNAL",`rate limit "${e}": period must be a positive number`);if(!Number.isFinite(r.rate)||r.rate<=0)throw new l("INTERNAL",`rate limit "${e}": rate must be a positive number`);if(r.capacity!==void 0&&(!Number.isFinite(r.capacity)||r.capacity<0))throw new l("INTERNAL",`rate limit "${e}": capacity must be a non-negative number`)}}async check(t,e={}){return this.run(t,e,!1)}async getValue(t,e={}){const r=this.resolve(t),a=this.now(),s=u(t,this.normalizeKey(e.key)),n=p(r,await this.store.get(s),a);return{config:r,ts:n.ts,value:n.value}}async limit(t,e={}){return this.run(t,e,!0)}async reset(t,e={}){this.resolve(t),await Promise.resolve(this.store.delete(u(t,this.normalizeKey(e.key))))}normalizeKey(t){return t===void 0?void 0:this.normalize(t)}resolve(t){const e=this.config[t];if(!e)throw new l("INTERNAL",`rate limit "${t}" is not configured`);return e}async run(t,e,r){const a=this.resolve(t),s=this.normalizeKey(e.key);if(s!==void 0&&(this.denyList.has(s)||this.denyList.has(e.key))){const d={ok:!1,reason:"deny",retryAfter:Number.POSITIVE_INFINITY};if(e.throws)throw new f(d);return d}const n=e.count??1;if(!Number.isInteger(n)||n<=0)throw new l("INTERNAL",`rate limit "${t}": count must be a positive integer`);const h=u(t,s),c=await this.store.get(h),{status:o,value:m}=y(a,c,{consume:r,count:n,now:this.now(),reserve:e.reserve??!1});if(m!==void 0&&await this.store.set(h,m),!o.ok&&e.throws)throw new f(o);return o}}export{S as RateLimiter};

package/dist/packem_shared/availableAt-BSKYrouo.mjs

@@ -0,0 +1 @@
+import{LunoraError as b}from"@lunora/errors";const o=e=>e.capacity??e.rate,E=e=>e.kind==="sliding window"?e.rate:o(e),i=(e,r)=>{throw new b("INTERNAL",`@lunora/ratelimit: requested count ${String(e)} exceeds the limiter capacity ${String(r)}`)},M=(e,r,t)=>{const u=o(e),a=e.rate/e.period,s=r??{ts:t,value:u},c=Math.max(0,t-s.ts);return{available:Math.min(u,s.value+c*a),capacity:u,ratePerMs:a}},w=(e,r,t)=>{const u=e.start??0,a=u+Math.floor((t-u)/e.period)*e.period;if(!r)return{ts:a,value:o(e)};if(r.ts<a){let s=0,c=1;return(r.value<0||e.capacity!==void 0)&&(s=r.value,c=Math.max(1,Math.ceil((a-r.ts)/e.period))),{ts:a,value:Math.min(o(e),s+c*e.rate)}}return{ts:r.ts,value:r.value}},x=(e,r,t)=>{const u=e.start??0,a=u+Math.floor((t-u)/e.period)*e.period,s=t-a,c=(e.period-s)/e.period;let n=0,l=0;return r?.ts===a?(n=r.prev??0,l=r.value):r?.ts===a-e.period&&(n=r.value),{currentCount:l,elapsed:s,previousCount:n,weight:c,windowStart:a}},S=(e,r,t)=>{const{available:u,capacity:a,ratePerMs:s}=M(e,r,t.now);if(u>=t.count){const l={ts:t.now,value:u-t.count};return{status:{ok:!0,retryAfter:0},value:t.consume?l:void 0}}const c=t.count-u,n=Math.ceil(c/s);return t.consume&&t.reserve&&t.count<=a?{status:{ok:!0,retryAfter:n},value:{ts:t.now,value:u-t.count}}:(t.count>a&&i(t.count,a),{status:{ok:!1,reason:"rate",retryAfter:n},value:void 0})},y=(e,r,t,u,a,s)=>{const c=d=>w(e,r,t+d*e.period).value>=a;let l=u<0||e.capacity!==void 0?Math.max(1,Math.ceil((a-u)/e.rate)):1;for(let d=0;d<4&&l>1&&c(l-1);d+=1)l-=1;for(let d=0;d<4&&!c(l);d+=1)l+=1;return t+l*e.period-s},W=(e,r,t)=>{const u=o(e),a=w(e,r,t.now);if(a.value>=t.count){const s={ts:a.ts,value:a.value-t.count};return{status:{ok:!0,retryAfter:0},value:t.consume?s:void 0}}if(t.consume&&t.reserve&&t.count<=u){const s=a.value-t.count;return{status:{ok:!0,retryAfter:y(e,{ts:a.ts,value:s},a.ts,s,0,t.now)},value:{ts:a.ts,value:s}}}return t.count>u&&i(t.count,u),{status:{ok:!1,reason:"rate",retryAfter:y(e,r,a.ts,a.value,t.count,t.now)},value:void 0}},N=(e,r,t)=>{const u=e.rate,{period:a}=e,{currentCount:s,elapsed:c,previousCount:n,weight:l,windowStart:d}=x(e,r,t.now),m=n*l+s+t.count<=u,h=v=>{const k=u-v-t.count;if(n>0&&k>=0)return Math.ceil(a-c-k*a/n);const A=u-t.count,C=v>0?Math.max(0,a-A*a/v):0;return Math.ceil(a-c+C)};if(m||t.consume&&t.reserve&&t.count<=u){const v={prev:n,ts:d,value:s+t.count};return{status:{ok:!0,retryAfter:m?0:h(v.value)},value:t.consume?v:void 0}}return t.count>u&&i(t.count,u),{status:{ok:!1,reason:"rate",retryAfter:h(s)},value:void 0}},B=(e,r,t)=>{if(e.kind==="token bucket")return{ts:t,value:M(e,r,t).available};if(e.kind==="sliding window"){const{currentCount:u,previousCount:a,weight:s,windowStart:c}=x(e,r,t);return{ts:c,value:Math.max(0,e.rate-(a*s+u))}}return w(e,r,t)},L=(e,r,t)=>e.kind==="token bucket"?S(e,r,t):e.kind==="sliding window"?N(e,r,t):W(e,r,t);export{B as availableAt,E as enforcedCapacity,L as evaluate};

package/dist/packem_shared/createDbStore-ve7GsO2i.mjs

@@ -0,0 +1 @@
+import{LunoraError as E}from"@lunora/errors";const p=()=>{const t=new Map;return{delete:e=>{t.delete(e)},get:e=>t.get(e),set:(e,n)=>{t.set(e,n)}}},i=(t,e,...n)=>t.exec.call(t,e,...n).toArray(),T=t=>{const{sql:e}=t,n=t.table??"_lunora_rate_limits";return i(e,`CREATE TABLE IF NOT EXISTS "${n}" (k TEXT PRIMARY KEY, value REAL NOT NULL, ts INTEGER NOT NULL, prev REAL)`),{delete:s=>{i(e,`DELETE FROM "${n}" WHERE k = ?`,s)},get:s=>{const c=i(e,`SELECT value, ts, prev FROM "${n}" WHERE k = ?`,s)[0];if(!c)return;const d={ts:c.ts,value:c.value};return c.prev!==null&&(d.prev=c.prev),d},set:(s,l)=>{i(e,`INSERT INTO "${n}" (k, value, ts, prev) VALUES (?, ?, ?, ?) ON CONFLICT(k) DO UPDATE SET value = excluded.value, ts = excluded.ts, prev = excluded.prev`,s,l.value,l.ts,l.prev??null)}}},w=t=>{const{db:e}=t,n=t.table??"rateLimits",s=t.index??"by_key",l=t.keyField??"key",c=new Map,d=async a=>{const r=await e.query(n).withIndex(s,o=>o.eq(l,a)).first();return c.set(a,r?r._id:void 0),r},v=async a=>(c.has(a)||await d(a),c.get(a));return{delete:async a=>{const r=await v(a);r!==void 0&&await e.delete(r),c.delete(a)},get:async a=>{const r=await d(a);if(!r)return;const o={ts:r.ts,value:r.value};return r.prev!==null&&r.prev!==void 0&&(o.prev=r.prev),o},set:async(a,r)=>{const o=await v(a),u={[l]:a,ts:r.ts,value:r.value};r.prev!==void 0&&(u.prev=r.prev),o===void 0?c.set(a,await e.insert(n,u)):await e.patch(o,u)}}},S=t=>{const e=s=>{throw new E("INTERNAL",`@lunora/ratelimit: \`${s}\` needs a writable \`ctx.db\`, but this store was created with \`createReadOnlyDbStore\` (a query context). Use \`createDbStore\` from a mutation or action; a query can only call \`getValue\`/\`check\`.`)},n=w({...t,db:{delete:()=>e("delete"),insert:()=>e("insert"),patch:()=>e("patch"),query:t.db.query.bind(t.db)}});return{delete:()=>e("reset"),get:n.get,set:()=>e("limit")}};export{w as createDbStore,p as createMemoryStore,S as createReadOnlyDbStore,T as createSqlStore};

package/dist/packem_shared/dbRateLimit-BuvEF1x0.mjs

@@ -0,0 +1 @@
+import{rateLimit as o}from"./rateLimit-CWZur6XE.mjs";import{RateLimiter as m}from"./RateLimiter-Cbc67DNk.mjs";import{createDbStore as i}from"./createDbStore-ve7GsO2i.mjs";const f=(e,r,t={})=>o(a=>new m({config:e,store:i({db:a.db,...t.store})}),r,t);export{f as default};

package/dist/packem_shared/rateLimit-CWZur6XE.mjs

@@ -0,0 +1 @@
+import{isLunoraError as c,isInternalCode as l,LunoraError as n}from"@lunora/errors";import{tagPerDispatchMiddleware as f}from"@lunora/server";const v={deny:{code:"FORBIDDEN",status:403},rate:{code:"TOO_MANY_REQUESTS",status:429}},y=(r,t,e)=>t==="deny"?`request denied for "${r}"`:e===void 0?`rate limit "${r}" exceeded`:`rate limit "${r}" exceeded; retry after ${String(e)}ms`,w=(r,t,e)=>{if(!e)return;const a=e(t);if(a===void 0)throw new n("INTERNAL",`@lunora/ratelimit: rateLimit("${r}") key resolver returned undefined; return a fallback such as "anonymous" instead`);return a},h=(r,t,e={})=>f(async({ctx:a,next:d})=>{let i;try{i=await(typeof r=="function"?await r(a):r).limit(t,{count:e.count,key:w(t,a,e.key)})}catch(o){if(c(o)&&l(o.code))throw o;if(console.error(`@lunora/ratelimit: rateLimit("${t}") threw; ${e.failOpen?"failing open":"failing closed"}`,o),e.failOpen)return d();throw new n("SERVICE_UNAVAILABLE",`rate limiter unavailable for "${t}"`,{cause:o,status:503})}if(!i.ok){const o=i.reason??"rate",u=v[o],s=Number.isFinite(i.retryAfter)?Math.ceil(i.retryAfter):void 0;throw new n(u.code,e.message??y(t,o,s),{status:u.status,data:s===void 0?void 0:{retryAfterMs:s}})}return d()});export{v as STATUS_BY_REASON,h as rateLimit};

package/dist/packem_shared/ratelimitPlugin-CFnDs9rj.mjs

@@ -0,0 +1 @@
+const r=t=>({key:"ratelimit",middleware:async({ctx:e,next:i})=>{const n=typeof t=="function"?await t(e):t,a=e.api??{};return i({ctx:{api:{...a,ratelimit:n}}})}});export{r as ratelimitPlugin};

package/dist/packem_shared/tokenBudget-BRlWn1im.mjs

@@ -0,0 +1 @@
+import{enforcedCapacity as n}from"./availableAt-BSKYrouo.mjs";const h=(t,r)=>({check:async c=>t.check(r,{key:c}),record:async(c,a)=>{if(!Number.isFinite(a)||a<=0)return t.check(r,{key:c});const{config:e}=await t.getValue(r,{key:c}),o=Math.max(1,Math.floor(n(e)));return t.limit(r,{count:Math.min(Math.ceil(a),o),key:c,reserve:!0})}});export{h as tokenBudget};

package/package.json

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

package/dist/packem_shared/RateLimitError-CiLy3DsZ.mjs

@@ -1,21 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-import { STATUS_BY_REASON } from './rateLimit-BBdG9GFo.mjs';
-
-const describe = (status) => {
-  if (status.reason === "deny") {
-    return "request denied (deny list)";
-  }
-  return Number.isFinite(status.retryAfter) ? `rate limit exceeded; retry after ${String(Math.ceil(status.retryAfter))}ms` : "rate limit exceeded";
-};
-class RateLimitError extends LunoraError {
-  reason;
-  retryAfter;
-  constructor(status, message) {
-    const { code, status: httpStatus } = STATUS_BY_REASON[status.reason ?? "rate"];
-    super(code, message ?? describe(status), { name: "RateLimitError", status: httpStatus });
-    this.reason = status.reason;
-    this.retryAfter = status.retryAfter;
-  }
-}
-
-export { RateLimitError as default };

package/dist/packem_shared/RateLimiter-rDCxu_Nx.mjs

@@ -1,121 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-import { availableAt, evaluate } from './availableAt-DQcuVfSA.mjs';
-import RateLimitError from './RateLimitError-CiLy3DsZ.mjs';
-import { createMemoryStore } from './createDbStore-L1kD1g1n.mjs';
-
-const storageKeyFor = (name, key) => key === void 0 ? encodeURIComponent(name) : `${encodeURIComponent(name)}:${encodeURIComponent(key)}`;
-const hashToShard = (storageKey, shards) => {
-  let hash = 0;
-  for (let index = 0; index < storageKey.length; index += 1) {
-    hash = hash * 31 + storageKey.charCodeAt(index) | 0;
-  }
-  return Math.abs(hash) % shards;
-};
-const perShardConfig = (config, shards) => shards > 1 ? { ...config, capacity: (config.capacity ?? config.rate) / shards, rate: config.rate / shards } : config;
-const shardKeysFor = (name, key, shards) => {
-  const base = storageKeyFor(name, key);
-  return shards > 1 ? Array.from({ length: shards }, (_, shard) => `${base}#${String(shard)}`) : [base];
-};
-const routeStorageKey = (name, key, shards) => {
-  const base = storageKeyFor(name, key);
-  return shards > 1 ? `${base}#${String(hashToShard(base, shards))}` : base;
-};
-class RateLimiter {
-  config;
-  denyList;
-  normalize;
-  now;
-  store;
-  constructor(options) {
-    this.config = options.config;
-    this.denyList = new Set(options.denyList);
-    this.normalize = options.normalize ?? ((key) => key);
-    this.now = options.now ?? Date.now;
-    this.store = options.store ?? createMemoryStore();
-    for (const [name, config] of Object.entries(this.config)) {
-      if (config.shards !== void 0 && (!Number.isInteger(config.shards) || config.shards < 1)) {
-        throw new LunoraError("INTERNAL", `rate limit "${name}": shards must be a positive integer`);
-      }
-      if (!Number.isFinite(config.period) || config.period <= 0) {
-        throw new LunoraError("INTERNAL", `rate limit "${name}": period must be a positive number`);
-      }
-      if (!Number.isFinite(config.rate) || config.rate <= 0) {
-        throw new LunoraError("INTERNAL", `rate limit "${name}": rate must be a positive number`);
-      }
-      if (config.capacity !== void 0 && (!Number.isFinite(config.capacity) || config.capacity < 0)) {
-        throw new LunoraError("INTERNAL", `rate limit "${name}": capacity must be a non-negative number`);
-      }
-    }
-  }
-  /** Peek at whether a request would be permitted without consuming. */
-  async check(name, args = {}) {
-    return this.run(name, args, false);
-  }
-  /**
-   * Read the current config and the units admittable right now for a
-   * `(name, key)` pair. The value is projected forward to the current clock
-   * (token-bucket refill, fixed-window rollover, sliding-window decay), not
-   * the last persisted figure. For a sharded limit it reads only the single
-   * shard `limit()`/`run()` would route this key to — the sibling shards are
-   * never touched by this key, so summing them would over-report.
-   */
-  async getValue(name, args = {}) {
-    const config = this.resolve(name);
-    const shards = config.shards ?? 1;
-    const now = this.now();
-    const normalizedKey = args.key === void 0 ? void 0 : this.normalize(args.key);
-    const storageKey = routeStorageKey(name, normalizedKey, shards);
-    const current = availableAt(perShardConfig(config, shards), await this.store.get(storageKey), now);
-    return { config, ts: current.ts, value: current.value };
-  }
-  /** Consume capacity. Returns the outcome, or throws when `args.throws` is set. */
-  async limit(name, args = {}) {
-    return this.run(name, args, true);
-  }
-  /** Clear accounting for a `(name, key)` pair (e.g. on successful login). */
-  async reset(name, args = {}) {
-    const shards = this.resolve(name).shards ?? 1;
-    const normalizedKey = args.key === void 0 ? void 0 : this.normalize(args.key);
-    await Promise.all(shardKeysFor(name, normalizedKey, shards).map((storageKey) => Promise.resolve(this.store.delete(storageKey))));
-  }
-  resolve(name) {
-    const config = this.config[name];
-    if (!config) {
-      throw new LunoraError("INTERNAL", `rate limit "${name}" is not configured`);
-    }
-    return config;
-  }
-  async run(name, args, consume) {
-    const config = this.resolve(name);
-    const normalizedKey = args.key === void 0 ? void 0 : this.normalize(args.key);
-    if (normalizedKey !== void 0 && (this.denyList.has(normalizedKey) || this.denyList.has(args.key))) {
-      const status2 = { ok: false, reason: "deny", retryAfter: Number.POSITIVE_INFINITY };
-      if (args.throws) {
-        throw new RateLimitError(status2);
-      }
-      return status2;
-    }
-    const count = args.count ?? 1;
-    if (!Number.isInteger(count) || count <= 0) {
-      throw new LunoraError("INTERNAL", `rate limit "${name}": count must be a positive integer`);
-    }
-    const shards = config.shards ?? 1;
-    const storageKey = routeStorageKey(name, normalizedKey, shards);
-    const prior = await this.store.get(storageKey);
-    const { status, value } = evaluate(perShardConfig(config, shards), prior, {
-      consume,
-      count,
-      now: this.now(),
-      reserve: args.reserve ?? false
-    });
-    if (value !== void 0) {
-      await this.store.set(storageKey, value);
-    }
-    if (!status.ok && args.throws) {
-      throw new RateLimitError(status);
-    }
-    return status;
-  }
-}
-
-export { RateLimiter };

package/dist/packem_shared/availableAt-DQcuVfSA.mjs

@@ -1,114 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-
-const capacityOf = (config) => config.capacity ?? config.rate;
-const projectTokenBucket = (config, prior, now) => {
-  const capacity = capacityOf(config);
-  const ratePerMs = config.rate / config.period;
-  const base = prior ?? { ts: now, value: capacity };
-  const elapsed = Math.max(0, now - base.ts);
-  return { available: Math.min(capacity, base.value + elapsed * ratePerMs), capacity, ratePerMs };
-};
-const projectFixedWindow = (config, prior, now) => {
-  const start = config.start ?? 0;
-  const windowStart = start + Math.floor((now - start) / config.period) * config.period;
-  if (!prior || prior.ts < windowStart) {
-    let carry = 0;
-    if (prior && (prior.value < 0 || config.capacity !== void 0)) {
-      carry = prior.value;
-    }
-    return { ts: windowStart, value: Math.min(capacityOf(config), carry + config.rate) };
-  }
-  return { ts: prior.ts, value: prior.value };
-};
-const projectSlidingWindow = (config, prior, now) => {
-  const start = config.start ?? 0;
-  const windowStart = start + Math.floor((now - start) / config.period) * config.period;
-  const elapsed = now - windowStart;
-  const weight = (config.period - elapsed) / config.period;
-  let previousCount = 0;
-  let currentCount = 0;
-  if (prior?.ts === windowStart) {
-    previousCount = prior.prev ?? 0;
-    currentCount = prior.value;
-  } else if (prior?.ts === windowStart - config.period) {
-    previousCount = prior.value;
-  }
-  return { currentCount, elapsed, previousCount, weight, windowStart };
-};
-const tokenBucket = (config, prior, options) => {
-  const { available, capacity, ratePerMs } = projectTokenBucket(config, prior, options.now);
-  if (available >= options.count) {
-    const value = { ts: options.now, value: available - options.count };
-    return { status: { ok: true, retryAfter: 0 }, value: options.consume ? value : void 0 };
-  }
-  const deficit = options.count - available;
-  const retryAfter = Math.ceil(deficit / ratePerMs);
-  if (options.consume && options.reserve && options.count <= capacity) {
-    return { status: { ok: true, retryAfter }, value: { ts: options.now, value: available - options.count } };
-  }
-  if (options.count > capacity) {
-    throw new LunoraError("INTERNAL", `@lunora/ratelimit: requested count ${String(options.count)} exceeds the limiter capacity ${String(capacity)}`);
-  }
-  return { status: { ok: false, reason: "rate", retryAfter }, value: void 0 };
-};
-const fixedWindow = (config, prior, options) => {
-  const capacity = capacityOf(config);
-  const base = projectFixedWindow(config, prior, options.now);
-  if (base.value >= options.count) {
-    const value = { ts: base.ts, value: base.value - options.count };
-    return { status: { ok: true, retryAfter: 0 }, value: options.consume ? value : void 0 };
-  }
-  const retryAfter = base.ts + config.period - options.now;
-  if (options.consume && options.reserve && options.count <= capacity) {
-    return { status: { ok: true, retryAfter }, value: { ts: base.ts, value: base.value - options.count } };
-  }
-  if (options.count > capacity) {
-    throw new LunoraError("INTERNAL", `@lunora/ratelimit: requested count ${String(options.count)} exceeds the limiter capacity ${String(capacity)}`);
-  }
-  return { status: { ok: false, reason: "rate", retryAfter }, value: void 0 };
-};
-const slidingWindow = (config, prior, options) => {
-  const limit = config.rate;
-  const { period } = config;
-  const { currentCount, elapsed, previousCount, weight, windowStart } = projectSlidingWindow(config, prior, options.now);
-  const estimated = previousCount * weight + currentCount;
-  const admit = estimated + options.count <= limit;
-  const retryAfter = () => {
-    const headroomNow = limit - currentCount - options.count;
-    if (previousCount > 0 && headroomNow >= 0) {
-      return Math.ceil(period - elapsed - headroomNow * period / previousCount);
-    }
-    const headroomNext = limit - options.count;
-    const intoNext = currentCount > 0 ? Math.max(0, period - headroomNext * period / currentCount) : 0;
-    return Math.ceil(period - elapsed + intoNext);
-  };
-  if (admit || options.consume && options.reserve && options.count <= limit) {
-    const value = { prev: previousCount, ts: windowStart, value: currentCount + options.count };
-    return { status: { ok: true, retryAfter: admit ? 0 : retryAfter() }, value: options.consume ? value : void 0 };
-  }
-  if (options.count > limit) {
-    throw new LunoraError("INTERNAL", `@lunora/ratelimit: requested count ${String(options.count)} exceeds the limiter capacity ${String(limit)}`);
-  }
-  return { status: { ok: false, reason: "rate", retryAfter: retryAfter() }, value: void 0 };
-};
-const availableAt = (config, prior, now) => {
-  if (config.kind === "token bucket") {
-    return { ts: now, value: projectTokenBucket(config, prior, now).available };
-  }
-  if (config.kind === "sliding window") {
-    const { currentCount, previousCount, weight, windowStart } = projectSlidingWindow(config, prior, now);
-    return { ts: windowStart, value: Math.max(0, config.rate - (previousCount * weight + currentCount)) };
-  }
-  return projectFixedWindow(config, prior, now);
-};
-const evaluate = (config, prior, options) => {
-  if (config.kind === "token bucket") {
-    return tokenBucket(config, prior, options);
-  }
-  if (config.kind === "sliding window") {
-    return slidingWindow(config, prior, options);
-  }
-  return fixedWindow(config, prior, options);
-};
-
-export { availableAt, evaluate };

package/dist/packem_shared/createDbStore-L1kD1g1n.mjs

@@ -1,103 +0,0 @@
-const createMemoryStore = () => {
-  const map = /* @__PURE__ */ new Map();
-  return {
-    delete: (storageKey) => {
-      map.delete(storageKey);
-    },
-    get: (storageKey) => map.get(storageKey),
-    set: (storageKey, value) => {
-      map.set(storageKey, value);
-    }
-  };
-};
-const runSql = (sql, query, ...params) => {
-  const runner = sql.exec;
-  return runner.call(sql, query, ...params).toArray();
-};
-const createSqlStore = (options) => {
-  const { sql } = options;
-  const table = options.table ?? "_lunora_rate_limits";
-  runSql(sql, `CREATE TABLE IF NOT EXISTS "${table}" (k TEXT PRIMARY KEY, value REAL NOT NULL, ts INTEGER NOT NULL, prev REAL)`);
-  return {
-    delete: (storageKey) => {
-      runSql(sql, `DELETE FROM "${table}" WHERE k = ?`, storageKey);
-    },
-    get: (storageKey) => {
-      const rows = runSql(sql, `SELECT value, ts, prev FROM "${table}" WHERE k = ?`, storageKey);
-      const row = rows[0];
-      if (!row) {
-        return void 0;
-      }
-      const value = { ts: row.ts, value: row.value };
-      if (row.prev !== null) {
-        value.prev = row.prev;
-      }
-      return value;
-    },
-    set: (storageKey, value) => {
-      runSql(
-        sql,
-        `INSERT INTO "${table}" (k, value, ts, prev) VALUES (?, ?, ?, ?) ON CONFLICT(k) DO UPDATE SET value = excluded.value, ts = excluded.ts, prev = excluded.prev`,
-        storageKey,
-        value.value,
-        value.ts,
-        // SQL bind: a missing `prev` must bind as SQL NULL, not undefined.
-        // eslint-disable-next-line unicorn/no-null -- SQLite/D1 bind parameters require null for a NULL column
-        value.prev ?? null
-      );
-    }
-  };
-};
-const createDatabaseStore = (options) => {
-  const { db } = options;
-  const table = options.table ?? "rateLimits";
-  const index = options.index ?? "by_key";
-  const keyField = options.keyField ?? "key";
-  const idCache = /* @__PURE__ */ new Map();
-  const find = async (storageKey) => {
-    const row = await db.query(table).withIndex(index, (q) => q.eq(keyField, storageKey)).first();
-    idCache.set(storageKey, row ? row._id : void 0);
-    return row;
-  };
-  const resolveId = async (storageKey) => {
-    if (idCache.has(storageKey)) {
-      return idCache.get(storageKey);
-    }
-    await find(storageKey);
-    return idCache.get(storageKey);
-  };
-  return {
-    delete: async (storageKey) => {
-      const id = await resolveId(storageKey);
-      if (id !== void 0) {
-        await db.delete(id);
-      }
-      idCache.delete(storageKey);
-    },
-    get: async (storageKey) => {
-      const row = await find(storageKey);
-      if (!row) {
-        return void 0;
-      }
-      const value = { ts: row.ts, value: row.value };
-      if (row.prev !== null && row.prev !== void 0) {
-        value.prev = row.prev;
-      }
-      return value;
-    },
-    set: async (storageKey, value) => {
-      const id = await resolveId(storageKey);
-      const document = { [keyField]: storageKey, ts: value.ts, value: value.value };
-      if (value.prev !== void 0) {
-        document.prev = value.prev;
-      }
-      if (id === void 0) {
-        idCache.set(storageKey, await db.insert(table, document));
-      } else {
-        await db.patch(id, document);
-      }
-    }
-  };
-};
-
-export { createDatabaseStore as createDbStore, createMemoryStore, createSqlStore };

package/dist/packem_shared/dbRateLimit-WTU-e0r6.mjs

@@ -1,7 +0,0 @@
-import { rateLimit } from './rateLimit-BBdG9GFo.mjs';
-import { RateLimiter } from './RateLimiter-rDCxu_Nx.mjs';
-import { createDbStore as createDatabaseStore } from './createDbStore-L1kD1g1n.mjs';
-
-const databaseRateLimit = (config, name, options = {}) => rateLimit((context) => new RateLimiter({ config, store: createDatabaseStore({ db: context.db, ...options.store }) }), name, options);
-
-export { databaseRateLimit as default };

package/dist/packem_shared/rateLimit-BBdG9GFo.mjs

@@ -1,40 +0,0 @@
-import { isLunoraError, isInternalCode, LunoraError } from '@lunora/errors';
-
-const STATUS_BY_REASON = {
-  deny: { code: "FORBIDDEN", status: 403 },
-  rate: { code: "TOO_MANY_REQUESTS", status: 429 }
-};
-const defaultMessage = (name, reason, retryAfter) => {
-  if (reason === "deny") {
-    return `request denied for "${name}"`;
-  }
-  return retryAfter === void 0 ? `rate limit "${name}" exceeded` : `rate limit "${name}" exceeded; retry after ${String(retryAfter)}ms`;
-};
-const rateLimit = (limiter, name, options = {}) => async ({ ctx, next }) => {
-  let status;
-  try {
-    const resolved = typeof limiter === "function" ? await limiter(ctx) : limiter;
-    status = await resolved.limit(name, { count: options.count, key: options.key?.(ctx) });
-  } catch (error) {
-    if (isLunoraError(error) && isInternalCode(error.code)) {
-      throw error;
-    }
-    console.error(`@lunora/ratelimit: rateLimit("${name}") threw; ${options.failOpen ? "failing open" : "failing closed"}`, error);
-    if (options.failOpen) {
-      return next();
-    }
-    throw new LunoraError("SERVICE_UNAVAILABLE", `rate limiter unavailable for "${name}"`, { cause: error, status: 503 });
-  }
-  if (!status.ok) {
-    const reason = status.reason ?? "rate";
-    const mapped = STATUS_BY_REASON[reason];
-    const retryAfter = Number.isFinite(status.retryAfter) ? Math.ceil(status.retryAfter) : void 0;
-    throw new LunoraError(mapped.code, options.message ?? defaultMessage(name, reason, retryAfter), {
-      status: mapped.status,
-      data: retryAfter === void 0 ? void 0 : { retryAfter }
-    });
-  }
-  return next();
-};
-
-export { STATUS_BY_REASON, rateLimit };

package/dist/packem_shared/ratelimitPlugin-D5_-KV1T.mjs

@@ -1,12 +0,0 @@
-const ratelimitPlugin = (limiter) => {
-  return {
-    key: "ratelimit",
-    middleware: async ({ ctx, next }) => {
-      const resolved = typeof limiter === "function" ? await limiter(ctx) : limiter;
-      const existingApi = ctx.api ?? {};
-      return next({ ctx: { api: { ...existingApi, ratelimit: resolved } } });
-    }
-  };
-};
-
-export { ratelimitPlugin };