Class DialCache

Wraps a function with the configured cache chain. Returned in-memory values are shared by reference and must be treated as immutable.

Returns exact process-scoped single-flight state for this instance.

Executes one inline loader through the configured cache chain. Unlike cached(), this method does not register the use case, so a stable use case can be declared repeatedly at the call site. Returned in-memory values are shared by reference and must be treated as immutable.

Writes a remote invalidation watermark for Redis-tracked entries.

Requires a Redis client in the DialCache configuration. If Redis is not configured, the call rejects rather than reporting an invalidation that did not occur.

This does not synchronously evict existing local cache hits or untracked Redis values. Call it only after the source mutation commits.

The invalidation watermark is the maximum of its prior value and the invalidating process's Date.now() + futureBufferMs. A tracked read serves a complete frame only when its writer timestamp is strictly greater than that watermark. A missing watermark is the natural zero baseline. Writes never read, create, or extend watermarks; every write is one native SET of a complete client-stamped frame.

Core caps tracked Redis values at one hour and reports a bounded metric error when a dispatched write is clamped. Invalidation keeps a watermark for at least two hours, or long enough to outlive its future window plus the one-hour value bound and a safety margin; longer and persistent existing TTLs are preserved. Watermarks are invalidation state and must not be evicted or lost during that interval. Losing one removes its read-time invalidation fence and can make an existing frame readable. Use noeviction or an equivalent guarantee when relying on the fence, and choose persistence and failover guarantees accordingly; DialCache does not issue WAIT.

futureBufferMs is application-owned. Size it through the point where a stale SET can become visible: source visibility lag, in-flight fallback and serialization work, bounded client queue/reconnect delay, network and Redis execution, plus the maximum writer-clock lead over the invalidator. DialCache reports future-dated tracked frames through optional metrics but does not calibrate clocks. A zero buffer fences only frames stamped no later than the invalidation; an undersized buffer can admit stale work, while an oversized one causes more tracked misses without delaying the returned fallback value.

When an invocation reaches the tracked Redis read/write path, its fallback is not published directly to process-local cache; a later validated Redis hit may warm it. Local-only, remote-policy-disabled, and ramped-down paths retain their local publication policy. Request-local memoization remains unconditional, and already-warm local entries are not evicted by this remote operation. Ramped-out invocations without shadow work do not consult Redis.