@bymax-one/nest-ai-tokens 1.0.0

package/dist/redis/index.d.ts

@@ -0,0 +1,98 @@
+import { Redis } from 'ioredis';
+
+/**
+ * @fileoverview The optional live cross-replica budget counter port (spec §15.1,
+ * §10.8). The fast path for budget enforcement; the DB conditional consume is the
+ * fallback. Values are serialized as int64 decimal strings. Implemented by the
+ * official Redis adapter (`./redis`).
+ * @layer server
+ */
+/** The live budget counter port. */
+interface IBudgetCounterStore {
+    /**
+     * Atomically increment `key` by `amount` iff the result stays `<= limit`,
+     * setting the TTL. Returns `false` when the increment would exceed the limit.
+     */
+    incrIfBelow(key: string, amount: bigint, limit: bigint, ttlSeconds: number): Promise<boolean>;
+    /** Decrement `key` by `amount` (release/reverse). */
+    decr(key: string, amount: bigint): Promise<void>;
+    /** Reset `key` (window rotation). */
+    reset(key: string): Promise<void>;
+}
+
+/**
+ * @fileoverview `RedisBudgetCounterStore` — the optional live cross-replica budget
+ * counter (`./redis` subpath, spec §10.8, §15.1). It makes budget enforcement cheap
+ * under high concurrency: `incrIfBelow` is a SINGLE atomic Lua script (increment,
+ * then undo and reject when the result would exceed the limit), so two racing
+ * replicas can never both pass a nearly-full budget. The DB conditional consume
+ * stays authoritative — this counter is the fast path, not the source of truth.
+ * Values are int64 (Redis native) written/compared as decimal strings; keys carry
+ * the caller's optional prefix. `ioredis` is an OPTIONAL peer: the constructor
+ * accepts a live `Redis` instance, or a connection URL that is lazily connected via
+ * a DYNAMIC import so the base library never statically depends on the client.
+ * Connection URLs (which may embed credentials) are never logged or placed on an
+ * exception.
+ * @layer redis
+ */
+
+/** Construction options for {@link RedisBudgetCounterStore}. */
+interface RedisBudgetCounterStoreOptions {
+    /** Prepended to every counter key (namespacing a shared Redis). */
+    keyPrefix?: string;
+}
+/**
+ * Signals that a counter operand or result falls outside the IEEE-754 safe-integer
+ * range (`±(2^53 − 1)`), where the Lua/Redis double arithmetic the fast path relies
+ * on would silently lose precision. It is thrown so `BudgetService` treats the counter
+ * as unavailable and falls back to the authoritative DB conditional consume, which
+ * compares int64 nano-USD exactly.
+ */
+declare class CounterValueOutOfRangeError extends Error {
+    readonly isCounterValueOutOfRange = true;
+    constructor();
+}
+/** The official Redis adapter for the live budget counter port. */
+declare class RedisBudgetCounterStore implements IBudgetCounterStore {
+    private readonly keyPrefix;
+    private readonly source;
+    private connecting;
+    /**
+     * @param redis A live `ioredis` client, or a connection URL to lazily connect.
+     * @param options Optional key prefix.
+     */
+    constructor(redis: Redis | string, options?: RedisBudgetCounterStoreOptions);
+    /**
+     * Atomically increment `key` by `amount` iff the result stays `<= limit`, setting
+     * the TTL. Returns `false` when the increment would exceed the limit.
+     *
+     * @param key The dimension counter key.
+     * @param amount The amount to add (int64 nano-USD or token/count units).
+     * @param limit The dimension limit.
+     * @param ttlSeconds The key TTL (window length + grace).
+     * @returns `true` when incremented within the limit, `false` when it would exceed it.
+     * @throws {CounterValueOutOfRangeError} when an operand or the resulting counter exceeds the safe-integer range.
+     */
+    incrIfBelow(key: string, amount: bigint, limit: bigint, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Decrement `key` by `amount`, flooring the stored value at zero (release/reverse).
+     *
+     * @param key The dimension counter key.
+     * @param amount The amount to subtract.
+     */
+    decr(key: string, amount: bigint): Promise<void>;
+    /**
+     * Reset (delete) `key` — used on window rotation.
+     *
+     * @param key The dimension counter key.
+     */
+    reset(key: string): Promise<void>;
+    /** Prepend the configured key prefix. */
+    private prefixed;
+    /** Resolve the live client, lazily connecting a URL via a dynamic `ioredis` import. */
+    private resolve;
+    /** Dynamically import `ioredis` and connect the given URL. */
+    private connect;
+}
+
+export { CounterValueOutOfRangeError, RedisBudgetCounterStore, type RedisBudgetCounterStoreOptions };

package/dist/redis/index.mjs

@@ -0,0 +1,107 @@
+// src/redis/index.ts
+var SAFE_INTEGER_MAX = "9007199254740991";
+var INCR_IF_BELOW_LUA = `
+local amount = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+if amount > ${SAFE_INTEGER_MAX} or amount < -${SAFE_INTEGER_MAX} or limit > ${SAFE_INTEGER_MAX} or limit < -${SAFE_INTEGER_MAX} then
+  return -1
+end
+local newValue = redis.call('INCRBY', KEYS[1], ARGV[1])
+if newValue > ${SAFE_INTEGER_MAX} or newValue < -${SAFE_INTEGER_MAX} then
+  redis.call('DECRBY', KEYS[1], ARGV[1])
+  return -1
+end
+if newValue > limit then
+  redis.call('DECRBY', KEYS[1], ARGV[1])
+  return 0
+end
+redis.call('PEXPIRE', KEYS[1], ARGV[3])
+return 1
+`;
+var DECR_FLOOR_LUA = `
+local newValue = redis.call('DECRBY', KEYS[1], ARGV[1])
+if newValue < 0 then
+  redis.call('SET', KEYS[1], '0')
+end
+return 1
+`;
+var CounterValueOutOfRangeError = class extends Error {
+  isCounterValueOutOfRange = true;
+  constructor() {
+    super("counter operand or result exceeds the safe-integer range");
+    this.name = "CounterValueOutOfRangeError";
+  }
+};
+var RedisBudgetCounterStore = class {
+  keyPrefix;
+  source;
+  connecting = null;
+  /**
+   * @param redis A live `ioredis` client, or a connection URL to lazily connect.
+   * @param options Optional key prefix.
+   */
+  constructor(redis, options = {}) {
+    this.keyPrefix = options.keyPrefix ?? "";
+    this.source = redis;
+  }
+  /**
+   * Atomically increment `key` by `amount` iff the result stays `<= limit`, setting
+   * the TTL. Returns `false` when the increment would exceed the limit.
+   *
+   * @param key The dimension counter key.
+   * @param amount The amount to add (int64 nano-USD or token/count units).
+   * @param limit The dimension limit.
+   * @param ttlSeconds The key TTL (window length + grace).
+   * @returns `true` when incremented within the limit, `false` when it would exceed it.
+   * @throws {CounterValueOutOfRangeError} when an operand or the resulting counter exceeds the safe-integer range.
+   */
+  async incrIfBelow(key, amount, limit, ttlSeconds) {
+    const client = await this.resolve();
+    const result = await client.eval(
+      INCR_IF_BELOW_LUA,
+      1,
+      this.prefixed(key),
+      amount.toString(),
+      limit.toString(),
+      Math.ceil(ttlSeconds * 1e3).toString()
+    );
+    if (result === -1) throw new CounterValueOutOfRangeError();
+    return result === 1;
+  }
+  /**
+   * Decrement `key` by `amount`, flooring the stored value at zero (release/reverse).
+   *
+   * @param key The dimension counter key.
+   * @param amount The amount to subtract.
+   */
+  async decr(key, amount) {
+    const client = await this.resolve();
+    await client.eval(DECR_FLOOR_LUA, 1, this.prefixed(key), amount.toString());
+  }
+  /**
+   * Reset (delete) `key` — used on window rotation.
+   *
+   * @param key The dimension counter key.
+   */
+  async reset(key) {
+    const client = await this.resolve();
+    await client.del(this.prefixed(key));
+  }
+  /** Prepend the configured key prefix. */
+  prefixed(key) {
+    return `${this.keyPrefix}${key}`;
+  }
+  /** Resolve the live client, lazily connecting a URL via a dynamic `ioredis` import. */
+  resolve() {
+    if (typeof this.source !== "string") return Promise.resolve(this.source);
+    this.connecting ??= this.connect(this.source);
+    return this.connecting;
+  }
+  /** Dynamically import `ioredis` and connect the given URL. */
+  async connect(url) {
+    const { default: RedisClient } = await import('ioredis');
+    return new RedisClient(url);
+  }
+};
+
+export { CounterValueOutOfRangeError, RedisBudgetCounterStore };