feat(cacheable): support per-store TTL overrides via hooks

[jaredwray]

Summary

Follows up the operation-level per-store TTL feature (set('k','v', { ttl: { primary, secondary } })) by letting the same per-store override be expressed from a hook, with full backwards compatibility and thorough documentation of what happens when you override.

A BEFORE_SET hook can now assign item.ttl a per-store object so the primary and secondary stores expire at different rates:

cache.onHook(CacheableHooks.BEFORE_SET, (data) => {
  data.ttl = { primary: '10s', secondary: '5m' };
});

This automatically covers set(), getOrSet(), and wrap() (they all run through BEFORE_SET), and the same per-store object is now accepted by setMany items and the BEFORE_SET_MANY hook.

What changed

• set() resolution reworked into three branches — no override (today's behavior, byte-for-byte), scalar (applies to every store), per-store object (each field independent; an omitted field falls back to that store's normal cascade, including any operation-level per-store ttl).
• Write-tracking ttl accessor on the hook item: any assignment counts as an override, even assigning the same value — removing the old !== value-collision footgun. Leaving ttl untouched keeps each store on its own cascade.
• Normalization: after resolution item.ttl is collapsed to the effective primary number, so AFTER_SET handlers and sync replication always observe a number, never the per-store object.
• Full setMany symmetry: setManyKeyv resolves each store's field per item; setManyKeyTags now uses the longest store TTL.
• Shared maxStoreTtl helper consolidates the "tag snapshot must outlive the longest-lived copy" rule used by both set() and setManyKeyTags.
• maxTtl caps each store independently after the hook.
• CacheableHookItem<T> exported for opt-in hook-handler typing; CacheableSetItem.ttl widened to accept PerStoreTtl.
• README documents the override precedence (hook ?? operation ?? store default ?? instance ttl, then maxTtl), the scalar-vs-object semantics, the AFTER_SET/sync normalization, the tag-snapshot rule, and the backfill caveat. BEFORE_SECONDARY_SETS_PRIMARY is documented as primary-only / scalar (intentionally unchanged).

Backwards compatibility

The no-override path is unchanged. The one intentional behavior change (approved): a hook assigning a scalar equal to the resolved primary now counts as an override instead of a no-op — obscure, and no existing test depended on the old behavior.

Testing

• New test/per-store-ttl-hooks.test.ts (20 tests) covering per-store object/scalar/omitted-field/empty-object, maxTtl capping, no-secondary, tag-snapshot longevity (including the immortal-secondary case), AFTER_SET normalization, sync publish, write-tracking, and the full setMany / BEFORE_SET_MANY path.
• Full suite green with Redis services running: 281 passed, lint clean, index.ts at 100% statements/lines (the only flagged branch is the pre-existing set sync setter, untouched here).

Process

The design was audited and validated by adversarial critic sub-agents (correctness/backwards-compat, API design, documentation/semantics); their findings drove the write-tracking accessor, the setMany data-loss fix, the tag-TTL single-store guard, and the decision to keep BEFORE_SECONDARY_SETS_PRIMARY scalar-only.

🤖 Generated with Claude Code

https://claude.ai/code/session_018gcwQAcwjCjFP2Myh8kCMz

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request introduces support for overriding the time-to-live (TTL) on a per-store basis (primary and secondary) within the BEFORE_SET and BEFORE_SET_MANY hooks, as well as directly in setMany operations. It updates the documentation, types, and implementation to handle per-store TTL objects, ensuring that tag snapshots and sync replication are correctly managed. One critical issue was identified in the review: when checking if the overridden TTL is an object, typeof null will evaluate to "object", which would incorrectly treat an explicit null (immortal) TTL as a per-store configuration object. A suggestion was provided to guard against this by checking hookTtl !== null.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (51f6cea) to head (c34337d).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1657   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           29        29           
  Lines         3379      3410   +31     
  Branches       762       773   +11     
=========================================
+ Hits          3379      3410   +31     

☔ 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: 1365336848

ℹ️ 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".