@bymax-one/nest-ai-tokens 1.0.4 → 1.1.1

package/CHANGELOG.md

@@ -6,7 +6,59 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 
 ---
 
-## [Unreleased]
+## [1.1.1] - 2026-10-23
+
+### Fixed
+
+- **A failed expired-hold scan no longer crashes the process.** `HoldReaper` read the
+  expired holds outside any `try`, and its interval callback discarded the promise
+  `sweep()` returned. A database error during that read — a failover or a dropped
+  connection — became an unhandled rejection, which terminates Node in every process that
+  loads the module. The scan is now guarded: a failure is logged once under the stable key
+  `ai_tokens.hold_reaper.scan_failed` with the error's `name`, `message` and string/number
+  `code` only, and the sweep ends; the next tick retries. Every timer-driven sweep also
+  carries a `catch` (logged as `ai_tokens.hold_reaper.sweep_failed`), so no rejection from
+  `sweep()` can escape the interval. Per-hold isolation, the multi-replica claim, `unref()`
+  and shutdown are unchanged. (#108)
+
+  **Apply to a derived backend:** a consumer that wrapped its store's `findExpiredHolds`
+  in a local guard (catching the error and returning `[]`) to survive this can drop that
+  guard once it runs 1.1.1. The reaper now absorbs and logs the failure itself.
+
+### Security
+
+- Advisories on transitive **dev** packages are cleared through `pnpm-workspace.yaml`
+  overrides: handlebars, proxy-addr, multer, undici, @grpc/grpc-js, fast-uri, js-yaml and
+  brace-expansion (#109); fast-uri and qs (#87); browserslist and mysql2 (#85);
+  deepmerge-ts (#80). osv-scanner reports no issues on the lockfile. None of these reach a
+  consumer install: the package has no runtime dependencies.
+
+### Changed
+
+- The budget counter-key construction moved to its own module, and its injectivity is
+  now asserted in tests: the keys are built from a caller-supplied `budgetId` and a
+  caller-chosen timestamp, and the specs fail if a field is reordered or a delimiter
+  changes. `COUNTER_DIMENSIONS` is the single runtime list the dimension type derives
+  from. No exported type or value changed. (#91)
+- Dev dependencies and CI actions updated (#79, #83, #111, and the pinned-action bumps). The
+  mutation gate now runs every spec rather than only Jest's related tests, which had silently
+  dropped specs reaching the code through helpers under `test/` (#112).
+- Published artifact: every `.d.ts` is byte-identical to 1.1.0, and so are the `shared`,
+  `prisma`, `redis` and `prices` bundles. Only the `server` bundle changed, from 38,204 to
+  38,417 B brotli, inside its 40,000 B budget.
+
+## [1.1.0] - 2026-08-11
+
+### Changed
+
+- **BREAKING: `ioredis` peer moved to `^6.0.0`** (was `^5.0.0`; the ranges are disjoint, so an
+  ioredis 5 consumer no longer satisfies the contract). It aligns the `./redis` budget counter
+  with `@bymax-one/nest-queue@1.2.0`, so a backend that consumes both resolves one shared `ioredis`.
+  ioredis 6 defaults to RESP3 but keeps `replyMapping: "legacy"`, leaving reply shapes unchanged at
+  runtime; the store's URL-only `new Redis(url)` construction is untouched by the RESP3 options
+  typing break, so no source changed.
+- **Mutation gate raised to a perfect score.** `stryker.config.json` now breaks below 100 (`break`,
+  `high` and `low` are all 100), so no surviving mutant can pass the gate.
 
 ## [1.0.4] - 2026-08-10
 
@@ -35,9 +87,9 @@ Remediation of a local audit's settlement findings (merged in #65). No API chang
 ### Fixed
 
 - **Every suppression reason was dropped from the mutation report.** All 249 `// Stryker
-  disable` directives in the source wrote their justification after `--`. Stryker reads a
+disable` directives in the source wrote their justification after `--`. Stryker reads a
   directive with one regular expression, `/^\s?Stryker (disable|restore)(?: (next-line))?
-  ([a-zA-Z, ]+)(?::(.+)?)?/`, whose mutator list accepts letters, commas and spaces only
+([a-zA-Z, ]+)(?::(.+)?)?/`, whose mutator list accepts letters, commas and spaces only
   and which captures the reason exclusively after a colon. A `-` therefore closed the
   mutator list and left the reason unmatched, so each directive still silenced its mutant
   but the report recorded Stryker's fallback text, `Ignored using a comment`. The README
@@ -71,14 +123,14 @@ Remediation of a local audit's settlement findings (merged in #65). No API chang
   implement `emitDecoratorMetadata` because it does not replicate TypeScript's type
   system — so the second key was never there. The first two parameters had neither, and
   the container threw `Nest can't resolve dependencies of the MeteringInterceptor
-  (?, +, Symbol(BYMAX_AI_TOKENS_OPTIONS))` before any provider was created. Both now
+(?, +, Symbol(BYMAX_AI_TOKENS_OPTIONS))` before any provider was created. Both now
   carry `@Inject`.
 
 ### Changed
 
 - `emitDecoratorMetadata` is `false` in `tsconfig.json`. It was `true`, which was never
   true of the artifact: tsup prints `You have emitDecoratorMetadata enabled but
-  @swc/core was not installed, skipping swc plugin` on every build, and that warning had
+@swc/core was not installed, skipping swc plugin` on every build, and that warning had
   been printed on every build of this package. Turning it off makes the source compile
   the way the bundle is built, so a parameter that depends on reflected types now fails
   where it is cheap to see.
@@ -139,7 +191,6 @@ have regressed from. They are kept because the reasoning is worth having.
 - **Zero runtime dependencies** — `"dependencies": {}`. All runtime functionality via peer dependencies.
 - **100% unit test coverage** — 804 tests; 10-scenario Testcontainers e2e suite; Stryker mutation gate at 100.00% (0 surviving mutants, break 95).
 
-
 - **Prisma 7 support, alongside Prisma 6.** The declared peer range has always
   been `>=6.0.0`, but nothing verified the claim; the end-to-end suite now runs
   against Prisma 7 and a real PostgreSQL, and it is what surfaced the conflict
@@ -155,7 +206,7 @@ have regressed from. They are kept because the reasoning is worth having.
 - **`pnpm check:exports`** runs `attw --pack . --profile strict` against the packed
   tarball, which is what surfaced both resolution defects above.
 - **`pnpm check:runtime`** packs the tarball, lays it out the way npm would, and
-  asserts in ESM *and* CommonJS that an error thrown by `PrismaAiTokensStore`
+  asserts in ESM _and_ CommonJS that an error thrown by `PrismaAiTokensStore`
   satisfies `instanceof AiTokensException` against the class the root exports. No
   source-based suite can observe this: the unit tests map the subpath specifiers to
   `src` and therefore see a single copy. Both gates run in CI.
@@ -215,6 +266,8 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.0.0]: https://github.com/bymaxone/nest-ai-tokens/releases/tag/v1.0.0
 [1.0.1]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.0...v1.0.1
 [1.0.2]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.1...v1.0.2
+[1.1.0]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.4...v1.1.0
+[1.1.1]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.0...v1.1.1
 [1.0.4]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.2...v1.0.3
-[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.4...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.1...HEAD

package/README.md

@@ -715,7 +715,7 @@ that reads a tenant id from request input lets a caller bill someone else.
 - **Runtime:** Node.js 24+
 - **Framework:** NestJS 11 (guard + interceptor, `ConfigurableModuleBuilder`, `Symbol()` tokens)
 - **Persistence:** `@prisma/client ^6 || ^7` (peer) over PostgreSQL — both majors supported
-- **Budget acceleration:** `ioredis ^5` (peer), optional
+- **Budget acceleration:** `ioredis ^6` (peer), optional
 - **Events:** `@nestjs/event-emitter >=2` (peer), optional
 - **Telemetry:** `@opentelemetry/api ^1.9` (peer), optional
 - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations
@@ -730,7 +730,7 @@ This library decides what a customer is charged, so the suite is held to a bar b
 tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **100% mutation score against a `break: 95` gate** — the gate is the floor a run must
+- ✅ **100% mutation score against a `break: 100` gate** — the gate is the floor a run must
   clear; the score the suite actually reaches is 100%, verified with
   [Stryker](https://stryker-mutator.io/) ([report](./docs/mutation_testing_results.md))
 - ✅ **Real PostgreSQL in e2e** — Testcontainers, so the unique constraint that prevents a
@@ -752,7 +752,7 @@ tests pass".
 pnpm test          # unit tests
 pnpm test:cov      # unit tests with the 100% coverage gate
 pnpm test:e2e      # end-to-end against PostgreSQL (requires Docker)
-pnpm mutation      # Stryker mutation testing (break: 95)
+pnpm mutation      # Stryker mutation testing (break: 100)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
 pnpm build && pnpm size   # bundle-size budgets

package/dist/server/index.cjs

@@ -3036,6 +3036,36 @@ function isWalletMissing(error) {
   return error.isWalletMissing === true;
 }
 
+// src/server/services/budget.keys.ts
+var COUNTER_GRACE_SECONDS = 3600;
+var TOTAL_WINDOW_TTL_SECONDS = 60 * 60 * 24 * 400;
+function windowKey(budgetId, windowStart) {
+  return `${budgetId}|${windowStart.toISOString()}`;
+}
+function counterKey(budgetId, windowStart, dimension) {
+  return `ai_tokens:budget:${budgetId}:${windowStart.toISOString()}:${dimension}`;
+}
+function counterTtlSeconds(windowStart, windowEnd) {
+  if (windowEnd === null) return TOTAL_WINDOW_TTL_SECONDS;
+  return Math.ceil((windowEnd.getTime() - windowStart.getTime()) / 1e3) + COUNTER_GRACE_SECONDS;
+}
+function dimensionSpends(spend) {
+  return { cost: spend.spentNanoUsd, tokens: BigInt(spend.spentTokens), count: BigInt(spend.spentCount) };
+}
+function counterDimensions(delta, limits) {
+  const dimensions = [];
+  if (limits.nanoUsd !== void 0 && delta.nanoUsd !== 0n) {
+    dimensions.push({ name: "cost", amount: delta.nanoUsd, limit: limits.nanoUsd });
+  }
+  if (limits.tokens !== void 0 && delta.tokens !== 0) {
+    dimensions.push({ name: "tokens", amount: BigInt(delta.tokens), limit: BigInt(limits.tokens) });
+  }
+  if (limits.count !== void 0 && delta.count !== 0) {
+    dimensions.push({ name: "count", amount: BigInt(delta.count), limit: BigInt(limits.count) });
+  }
+  return dimensions;
+}
+
 // src/server/services/budget-predicate.ts
 function recordConsumesBudget(record, budget, windowStart, windowEnd) {
   if (!record.enforced) return false;
@@ -3119,8 +3149,6 @@ var NOOP_BUDGET_HOOKS = {
   projectedExceeded: () => void 0,
   audit: () => void 0
 };
-var COUNTER_GRACE_SECONDS = 3600;
-var TOTAL_WINDOW_TTL_SECONDS = 60 * 60 * 24 * 400;
 var UNBOUNDED_COUNTER_LIMIT = 9223372036854775807n;
 exports.BudgetService = class BudgetService {
   /**
@@ -3654,32 +3682,6 @@ function buildStatus(budget, windowStart, resetsAt, spend) {
     usedFraction: usedFraction(spend, limits)
   };
 }
-function windowKey(budgetId, windowStart) {
-  return `${budgetId}|${windowStart.toISOString()}`;
-}
-function counterKey(budgetId, windowStart, dimension) {
-  return `ai_tokens:budget:${budgetId}:${windowStart.toISOString()}:${dimension}`;
-}
-function counterTtlSeconds(windowStart, windowEnd) {
-  if (windowEnd === null) return TOTAL_WINDOW_TTL_SECONDS;
-  return Math.ceil((windowEnd.getTime() - windowStart.getTime()) / 1e3) + COUNTER_GRACE_SECONDS;
-}
-function dimensionSpends(spend) {
-  return { cost: spend.spentNanoUsd, tokens: BigInt(spend.spentTokens), count: BigInt(spend.spentCount) };
-}
-function counterDimensions(delta, limits) {
-  const dimensions = [];
-  if (limits.nanoUsd !== void 0 && delta.nanoUsd !== 0n) {
-    dimensions.push({ name: "cost", amount: delta.nanoUsd, limit: limits.nanoUsd });
-  }
-  if (limits.tokens !== void 0 && delta.tokens !== 0) {
-    dimensions.push({ name: "tokens", amount: BigInt(delta.tokens), limit: BigInt(limits.tokens) });
-  }
-  if (limits.count !== void 0 && delta.count !== 0) {
-    dimensions.push({ name: "count", amount: BigInt(delta.count), limit: BigInt(limits.count) });
-  }
-  return dimensions;
-}
 function max0(value) {
   return value < 0n ? 0n : value;
 }
@@ -4078,6 +4080,14 @@ function writeHeader(response, name, value) {
 }
 var REAP_BATCH_SIZE = 100;
 var MS_PER_SECOND = 1e3;
+var SCAN_FAILED_LOG_KEY = "ai_tokens.hold_reaper.scan_failed";
+var SWEEP_FAILED_LOG_KEY = "ai_tokens.hold_reaper.sweep_failed";
+function describeError(error) {
+  if (!(error instanceof Error)) return "non-Error rejection";
+  const { code } = error;
+  const suffix = typeof code === "string" || typeof code === "number" ? ` code=${String(code)}` : "";
+  return `name=${error.name} message=${JSON.stringify(error.message)}${suffix}`;
+}
 var HoldReaper = class {
   /**
    * @param ledger The ledger service (expired-hold scan + atomic void claim).
@@ -4100,7 +4110,11 @@ var HoldReaper = class {
   /** Start the periodic sweep on module boot (interval `unref()`'d so it never blocks exit). */
   onApplicationBootstrap() {
     const intervalMs = this.options.holds.reaperIntervalSeconds * MS_PER_SECOND;
-    this.timer = setInterval(() => void this.sweep(), intervalMs);
+    this.timer = setInterval(() => {
+      void this.sweep().catch((error) => {
+        this.logger.warn(`${SWEEP_FAILED_LOG_KEY} ${describeError(error)}`);
+      });
+    }, intervalMs);
     this.timer.unref();
   }
   /** Stop the sweep on shutdown (no open handles left for Jest). */
@@ -4112,12 +4126,19 @@ var HoldReaper = class {
    * Reclaim one batch of expired pending holds. For each: win the atomic
    * `pending → released` claim (a `null` result means another replica won — skip),
    * then run the shared restoration + `hold.released` emission. A failure on one
-   * hold is logged and never aborts the batch (deterministic, idempotent, safe to
-   * run repeatedly).
+   * hold is logged and never aborts the batch; a failure of the expired-hold scan
+   * itself is logged and ends this sweep without throwing (deterministic, idempotent,
+   * safe to run repeatedly).
    */
   async sweep() {
     const cutoff = new Date(this.now().getTime() - this.options.holds.ttlSeconds * MS_PER_SECOND);
-    const expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
+    let expired;
+    try {
+      expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
+    } catch (error) {
+      this.logger.warn(`${SCAN_FAILED_LOG_KEY} ${describeError(error)}`);
+      return;
+    }
     for (const record of expired) {
       try {
         const claimed = await this.ledger.transition(record.id, "pending", "released");

package/dist/server/index.mjs

@@ -3034,6 +3034,36 @@ function isWalletMissing(error) {
   return error.isWalletMissing === true;
 }
 
+// src/server/services/budget.keys.ts
+var COUNTER_GRACE_SECONDS = 3600;
+var TOTAL_WINDOW_TTL_SECONDS = 60 * 60 * 24 * 400;
+function windowKey(budgetId, windowStart) {
+  return `${budgetId}|${windowStart.toISOString()}`;
+}
+function counterKey(budgetId, windowStart, dimension) {
+  return `ai_tokens:budget:${budgetId}:${windowStart.toISOString()}:${dimension}`;
+}
+function counterTtlSeconds(windowStart, windowEnd) {
+  if (windowEnd === null) return TOTAL_WINDOW_TTL_SECONDS;
+  return Math.ceil((windowEnd.getTime() - windowStart.getTime()) / 1e3) + COUNTER_GRACE_SECONDS;
+}
+function dimensionSpends(spend) {
+  return { cost: spend.spentNanoUsd, tokens: BigInt(spend.spentTokens), count: BigInt(spend.spentCount) };
+}
+function counterDimensions(delta, limits) {
+  const dimensions = [];
+  if (limits.nanoUsd !== void 0 && delta.nanoUsd !== 0n) {
+    dimensions.push({ name: "cost", amount: delta.nanoUsd, limit: limits.nanoUsd });
+  }
+  if (limits.tokens !== void 0 && delta.tokens !== 0) {
+    dimensions.push({ name: "tokens", amount: BigInt(delta.tokens), limit: BigInt(limits.tokens) });
+  }
+  if (limits.count !== void 0 && delta.count !== 0) {
+    dimensions.push({ name: "count", amount: BigInt(delta.count), limit: BigInt(limits.count) });
+  }
+  return dimensions;
+}
+
 // src/server/services/budget-predicate.ts
 function recordConsumesBudget(record, budget, windowStart, windowEnd) {
   if (!record.enforced) return false;
@@ -3117,8 +3147,6 @@ var NOOP_BUDGET_HOOKS = {
   projectedExceeded: () => void 0,
   audit: () => void 0
 };
-var COUNTER_GRACE_SECONDS = 3600;
-var TOTAL_WINDOW_TTL_SECONDS = 60 * 60 * 24 * 400;
 var UNBOUNDED_COUNTER_LIMIT = 9223372036854775807n;
 var BudgetService = class {
   /**
@@ -3652,32 +3680,6 @@ function buildStatus(budget, windowStart, resetsAt, spend) {
     usedFraction: usedFraction(spend, limits)
   };
 }
-function windowKey(budgetId, windowStart) {
-  return `${budgetId}|${windowStart.toISOString()}`;
-}
-function counterKey(budgetId, windowStart, dimension) {
-  return `ai_tokens:budget:${budgetId}:${windowStart.toISOString()}:${dimension}`;
-}
-function counterTtlSeconds(windowStart, windowEnd) {
-  if (windowEnd === null) return TOTAL_WINDOW_TTL_SECONDS;
-  return Math.ceil((windowEnd.getTime() - windowStart.getTime()) / 1e3) + COUNTER_GRACE_SECONDS;
-}
-function dimensionSpends(spend) {
-  return { cost: spend.spentNanoUsd, tokens: BigInt(spend.spentTokens), count: BigInt(spend.spentCount) };
-}
-function counterDimensions(delta, limits) {
-  const dimensions = [];
-  if (limits.nanoUsd !== void 0 && delta.nanoUsd !== 0n) {
-    dimensions.push({ name: "cost", amount: delta.nanoUsd, limit: limits.nanoUsd });
-  }
-  if (limits.tokens !== void 0 && delta.tokens !== 0) {
-    dimensions.push({ name: "tokens", amount: BigInt(delta.tokens), limit: BigInt(limits.tokens) });
-  }
-  if (limits.count !== void 0 && delta.count !== 0) {
-    dimensions.push({ name: "count", amount: BigInt(delta.count), limit: BigInt(limits.count) });
-  }
-  return dimensions;
-}
 function max0(value) {
   return value < 0n ? 0n : value;
 }
@@ -4076,6 +4078,14 @@ function writeHeader(response, name, value) {
 }
 var REAP_BATCH_SIZE = 100;
 var MS_PER_SECOND = 1e3;
+var SCAN_FAILED_LOG_KEY = "ai_tokens.hold_reaper.scan_failed";
+var SWEEP_FAILED_LOG_KEY = "ai_tokens.hold_reaper.sweep_failed";
+function describeError(error) {
+  if (!(error instanceof Error)) return "non-Error rejection";
+  const { code } = error;
+  const suffix = typeof code === "string" || typeof code === "number" ? ` code=${String(code)}` : "";
+  return `name=${error.name} message=${JSON.stringify(error.message)}${suffix}`;
+}
 var HoldReaper = class {
   /**
    * @param ledger The ledger service (expired-hold scan + atomic void claim).
@@ -4098,7 +4108,11 @@ var HoldReaper = class {
   /** Start the periodic sweep on module boot (interval `unref()`'d so it never blocks exit). */
   onApplicationBootstrap() {
     const intervalMs = this.options.holds.reaperIntervalSeconds * MS_PER_SECOND;
-    this.timer = setInterval(() => void this.sweep(), intervalMs);
+    this.timer = setInterval(() => {
+      void this.sweep().catch((error) => {
+        this.logger.warn(`${SWEEP_FAILED_LOG_KEY} ${describeError(error)}`);
+      });
+    }, intervalMs);
     this.timer.unref();
   }
   /** Stop the sweep on shutdown (no open handles left for Jest). */
@@ -4110,12 +4124,19 @@ var HoldReaper = class {
    * Reclaim one batch of expired pending holds. For each: win the atomic
    * `pending → released` claim (a `null` result means another replica won — skip),
    * then run the shared restoration + `hold.released` emission. A failure on one
-   * hold is logged and never aborts the batch (deterministic, idempotent, safe to
-   * run repeatedly).
+   * hold is logged and never aborts the batch; a failure of the expired-hold scan
+   * itself is logged and ends this sweep without throwing (deterministic, idempotent,
+   * safe to run repeatedly).
    */
   async sweep() {
     const cutoff = new Date(this.now().getTime() - this.options.holds.ttlSeconds * MS_PER_SECOND);
-    const expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
+    let expired;
+    try {
+      expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
+    } catch (error) {
+      this.logger.warn(`${SCAN_FAILED_LOG_KEY} ${describeError(error)}`);
+      return;
+    }
     for (const record of expired) {
       try {
         const claimed = await this.ledger.transition(record.id, "pending", "released");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-ai-tokens",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "AI token metering & usage-based billing for NestJS 11: provider usage normalizer (×9), versioned effective-dated pricing, immutable append-only ledger, prepaid wallets, multi-dimension budgets, and markup/margin. Zero runtime dependencies.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -106,7 +106,7 @@
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",
     "@prisma/client": "^6.0.0 || ^7.0.0",
-    "ioredis": "^5.0.0",
+    "ioredis": "^6.0.0",
     "@nestjs/event-emitter": ">=2.0.0",
     "@opentelemetry/api": "^1.9.0"
   },
@@ -158,7 +158,7 @@
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "fast-check": "^4.9.0",
-    "ioredis": "^5.4.2",
+    "ioredis": "^6.0.0",
     "jest": "^30.4.2",
     "prettier": "^3.9.6",
     "prisma": "^7.9.1",