refactor(utils): expose Stats per-key data as public trackedKeys map

[jaredwray]

Summary

Simplifies the Stats per-key tracking surface in @cacheable/utils:

• Renames the internal _keyCounts map to a public trackedKeys field. Consumers can now read per-key counters (and their .size) directly via stats.trackedKeys, instead of going through a dedicated accessor.
• Removes the redundant trackedKeyCount getter — stats.trackedKeys.size gives the same value.
• Exports the KeyCounters type (the map's value type: raw hits/misses/gets/sets/deletes per key), since it's now part of the public API.

const stats = new Stats({ enabled: true, trackKeys: true });
stats.recordKey("user:1", "hits", 2);

stats.trackedKeys.get("user:1"); // { hits: 2, misses: 0, gets: 0, sets: 0, deletes: 0 }
stats.trackedKeys.size;          // 1  (was: stats.trackedKeyCount)

Notes

• StatsSnapshot.trackedKeys (from toJSON()) is unchanged — it remains the count (a number) of unique tracked keys, which is the serializable equivalent of the live map's size.
• The higher-level helpers (recordKey, keyStats, mostUsedKeys, leastUsedKeys, clearKeys) are unchanged.

Testing

• pnpm --filter @cacheable/utils test — Biome clean, 230 tests pass, 100% coverage on stats.ts.
• pnpm --filter @cacheable/utils build — dual CJS/ESM + type declarations emit correctly (trackedKeys: Map<string, KeyCounters>, KeyCounters exported).

🤖 Generated with Claude Code

https://claude.ai/code/session_01SjsBvVfhc7vKeqPE4nWCUr

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request refactors the Stats class by exporting the KeyCounters type and replacing the private _keyCounts map and its public getter trackedKeyCount with a public trackedKeys map. The review feedback correctly points out that exposing a mutable Map directly as a public property breaks encapsulation, as external consumers could mutate the map and bypass internal logic such as pruning and size tracking. The reviewer recommends keeping the map private and exposing it publicly via a getter returning a ReadonlyMap instead.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (9178ad2) to head (fbf8a1e).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1660   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           29        29           
  Lines         3379      3379           
  Branches       763       777   +14     
=========================================
  Hits          3379      3379           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1ce9ad3ea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".