Consider returning undefined on cache miss in a future major version

[flyingsquirrel0419]

Related to #88.

Currently, cache.get() returns null on cache miss. This makes it difficult to distinguish between:

• a missing cache entry
• a cached value whose actual value is null

In 3.x, changing this behavior would be a breaking change, especially since 3.0.0 has already been released. For compatibility, the current plan is to keep cache.get() returning null on miss and support cacheNullValues as an opt-in escape hatch for users who need to cache null as a real value.

For a future major version, we should consider whether cache.get() should return undefined on miss instead, while allowing null to be treated as a regular cacheable value.

Questions to answer:

• Should cache.get() return undefined on miss in the next major version?
• Should cache.getOrThrow() behavior remain unchanged?
• How should mget() represent per-key misses?
• Do we need a separate API that returns { found, value } to avoid ambiguity?
• How should this interact with negativeCache and cacheNullValues?
• How should JSON and msgpack serializer behavior around undefined be documented or normalized?

This should not be changed in 3.x unless we intentionally decide to introduce a breaking change.

[niksy]

What is the status of this issue?

[flyingsquirrel0419]

This is still valid but intentionally deferred.

For 3.x, cache.get() should continue returning null on miss for backwards compatibility. The 3.1.1 changes do not alter that behavior; cacheNullValues and negativeCache remain the opt-in paths for null-related cases.

I would keep this open as a future major-version design issue, since changing miss semantics to undefined would be breaking and also needs decisions for mget(), getOrThrow(), serializers, and { found, value }-style APIs.

[flyingsquirrel0419]

For 4.0.0, I am considering resolving this by changing the public value-read APIs to use undefined for cache misses, while treating null as a regular cacheable value.

Proposed behavior:

1. cache.get(), cache.getOrSet(), cache.mget(), cache.wrap(), and namespace equivalents:

   • miss: undefined
   • stored null: null
   • fetcher returns undefined: not cached, returns undefined
   • fetcher returns null: cached as a regular value by default

2. getEntry(), inspect(), and ttl():

   • keep the current null miss/no-data semantics, since these APIs return structured metadata or non-value information.

3. getOrThrow():

   • throw only when get() would return undefined
   • return null if null is the stored or fetched value

4. negativeCache:

   • remain an explicit opt-in
   • if negativeCache: true is set and the fetcher returns null, keep the current negative/empty marker behavior instead of storing regular null

This would be a 4.0-only breaking change, not a 3.x change.

Does this match the intended 4.0 direction, or should getEntry() / inspect() also move to undefined on miss for full consistency?