cacheable - feat: support per-store TTL per operation

[jaredwray]

Summary

Closes #1654.

cacheable runs a two-layer cache (a primary in-memory store and an optional secondary distributed store). Until now, overriding the ttl on a single operation applied that one value to both stores, so there was no way to say "keep this key 10s in memory but 5min in Redis."

This adds per-store, per-operation TTL: the ttl accepted by set, getOrSet, and wrap may now be, in addition to the existing number | string, a per-store object:

await cache.set('key', 'value', { ttl: { primary: '10s', secondary: '5m' } });

Each field accepts a number (ms) or a shorthand string ('10s', '5m', …). Behavior:

• Scalar TTL (number | string) is unchanged — applied to every store.
• A per-store object resolves primary and secondary independently.
• An omitted field falls back to that store's own default TTL resolution (storage-adapter TTL, then the instance TTL), preserving the existing cascade.
• maxTtl continues to cap each store independently.
• The existing BEFORE_SET hook override precedence is unchanged.

Implementation

• @cacheable/utils: added a PerStoreTtl type and a small, unit-tested resolvePerStoreTtl helper (lives alongside the existing primary/secondary getCascadingTtl logic). Widened the shared ttl field on GetOrSetFunctionOptions, WrapFunctionOptions, and the CacheInstance/CacheSyncInstance set signatures so the object form can flow through getOrSet/wrap untouched — these are type-only pass-throughs.
• cacheable: Cacheable.set now resolves an explicit TTL per store and feeds each through the existing cascade/cap logic. getOrSet/wrap need no logic change beyond their cache adapters wrapping the value as { ttl } so the object isn't mistaken for SetOptions. SetOptions.ttl widened and PerStoreTtl re-exported as public API.
• Scope is cacheable only; cache-manager is untouched.

Tests

• packages/utils/test/ttl.test.ts: unit tests for resolvePerStoreTtl (scalar, shorthand, undefined, per-store object, partial object).
• packages/cacheable/test/ttl.test.ts: distinct-TTL-per-store, omitted-field fallback, scalar regression, maxTtl capping per store, and per-store TTL via getOrSet and wrap.

All non-Redis tests pass locally with 100% coverage on the changed code. Redis-backed integration tests were not run here (no Docker/Redis in the environment); CI will exercise those.

Docs

Added a "Per-Store TTL per Operation" section to the cacheable README and updated the documented option types.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HjpVjtgWd5wyw17rsywLb8

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request introduces support for per-store TTL overrides per operation, allowing multi-layer caches to have different expiration rates for primary and secondary stores. It updates the Cacheable class, getOrSet, and wrap methods to accept a PerStoreTtl object containing primary and secondary fields, and falls back to store defaults if fields are omitted. Feedback was provided to improve the robustness of the resolvePerStoreTtl utility by explicitly handling null and undefined inputs to prevent potential runtime errors.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (639e42c) to head (1ae44d1).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1656   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           27        27           
  Lines         3069      3079   +10     
  Branches       693       684    -9     
=========================================
+ Hits          3069      3079   +10     

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

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