@lunora/ratelimit 1.0.0-alpha.21 → 1.0.0-alpha.22

package/dist/index.d.mts

@@ -440,5 +440,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, 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, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createReadOnlyDatabaseStore as createReadOnlyDbStore, 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

@@ -440,5 +440,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, 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, VERSION, availableAt, createDatabaseStore as createDbStore, createMemoryStore, createReadOnlyDatabaseStore as createReadOnlyDbStore, 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 +1 @@
-import{availableAt as o,evaluate as a}from"./packem_shared/availableAt-BMlAt2U2.mjs";import{default as i}from"./packem_shared/dbRateLimit-e95-suu-.mjs";import{default as l}from"./packem_shared/RateLimitError-xJ2Iv-i7.mjs";import{rateLimit as x}from"./packem_shared/rateLimit-DLcwK-84.mjs";import{ratelimitPlugin as c}from"./packem_shared/ratelimitPlugin-D1QHZF9b.mjs";import{RateLimiter as b}from"./packem_shared/RateLimiter-CitqoGTI.mjs";import{createDbStore as u,createMemoryStore as L,createReadOnlyDbStore as n,createSqlStore as s}from"./packem_shared/createDbStore-CwJBMxDQ.mjs";const e="0.0.0";export{l as RateLimitError,b as RateLimiter,e as VERSION,o as availableAt,u as createDbStore,L as createMemoryStore,n as createReadOnlyDbStore,s as createSqlStore,i as dbRateLimit,a as evaluate,x as rateLimit,c as ratelimitPlugin};
+import{availableAt as o,evaluate as a}from"./packem_shared/availableAt-BMlAt2U2.mjs";import{default as i}from"./packem_shared/dbRateLimit-e95-suu-.mjs";import{default as l}from"./packem_shared/RateLimitError-xJ2Iv-i7.mjs";import{rateLimit as x}from"./packem_shared/rateLimit-DLcwK-84.mjs";import{ratelimitPlugin as c}from"./packem_shared/ratelimitPlugin-D1QHZF9b.mjs";import{RateLimiter as u}from"./packem_shared/RateLimiter-CitqoGTI.mjs";import{createDbStore as b,createMemoryStore as n,createReadOnlyDbStore as L,createSqlStore as s}from"./packem_shared/createDbStore-CwJBMxDQ.mjs";import{tokenBudget as v}from"./packem_shared/tokenBudget-BRZSEqNB.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/tokenBudget-BRZSEqNB.mjs

@@ -0,0 +1 @@
+const r=(c,t)=>({check:async e=>c.check(t,{key:e}),record:async(e,a)=>{if(!Number.isFinite(a)||a<=0)return c.check(t,{key:e});const{config:i}=await c.getValue(t,{key:e}),n=Math.max(1,Math.floor((i.capacity??i.rate)/(i.shards??1)));return c.limit(t,{count:Math.min(Math.ceil(a),n),key:e,reserve:!0})}});export{r as tokenBudget};

package/package.json

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