Migration Notes

Upgrading from earlier versions. All changes are additive and existing call sites compile unchanged.

From pre-cascadeTTL / pre-safety / pre-scoped-clear versions

1. No code changes are required. All three features are additive. Existing call sites compile and run unchanged.
2. clearAllCache now uses SCAN + UNLINK when keyPrefix is set. If a test fixture relied on it wiping the entire DB, either unset the prefix for that test or call FLUSHDB directly via the raw client. Application code is unaffected.
3. Set a prefix if you share Redis. For any production deployment sharing Redis with another app or environment, configure redis.keyPrefix to isolate this cache's keyspace and make clearAllCache safe by construction.
4. safety.productionMode defaults from NODE_ENV at cache construction time. Library consumers should pass it explicitly to drop the env coupling.
5. Adopt cascadeTTL: true selectivelyon writes where the parent's TTL is meaningfully longer than its embedded reference data. The simplest alternative is to raise the schema TTL of the reference entity to match the longest-lived parent.

From pre-atomic implementation

1. Existing cached values stay readable. Compression is opt-in and the new connection pool defaults to 1 (single client).
2. clearAllCache() now requires explicit confirmation. Update any test fixtures that called it without arguments.
3. invalidateEntity() now returns a number (the count of tracked lists the entity was removed from). Existing await cache.invalidateEntity(...) calls that ignore the return value continue to work.
4. getMetrics() returns real numbers. If you had asserts on the old hardcoded zeros, update them.
5. List values that were written without TTL keep working until manually deleted. New writes apply the schema's ttl (or cache.defaultTTL) automatically.
6. selectiveFields now actually restricts the output. Any code that was relying on the old broken behaviour (where the option was a no-op) needs review.
7. Circular references now emit a $ref marker rather than silently dropping data. Hydration consumers should handle the $ref field if they walk relation graphs.

Recommended adoption order