fix(cache-with-ttl): close TOCTOU in getOrFetch inflight dedupe

`getOrFetch` did `const cached = await get(key)` *before* consulting the
inflight map. `get()` itself awaits a cacache disk read, so two callers
landing on a cold key could both suspend on the same I/O, both resolve
`cached === undefined`, both skip the inflight check, and both start a
fresh fetch. The `set()`-before-await comment was accurate but the
check ordering was the actual race — the inflight guarantee was
invisibly broken for every concurrent first-hit, defeating the feature
the map exists to provide.

Moves the inflight check before the persistent-cache lookup so a later
caller joins an in-flight fetch instead of racing it. Adds a second
check after the disk read for the case where a peer registered an
inflight entry while we were suspended. Regression test asserts
fetchCount === 1 for three parallel cold callers.

Author: jdalton

src/cache-with-ttl.ts

@@ -421,17 +421,28 @@ export function createTtlCache(options?: TtlCacheOptions): TtlCache {
     key: string,
     fetcher: () => Promise<T>,
   ): Promise<T> {
+    const fullKey = buildKey(key)
+
+    // Join an in-flight fetch before touching the persistent cache. If we
+    // did the `await get(key)` first, two concurrent callers on a cold
+    // key would both suspend on the same disk read, both see no cached
+    // value, both skip this check, and both fire `fetcher()` — the exact
+    // thundering-herd the inflight map is supposed to prevent.
+    const preexisting = inflightRequests.get(fullKey)
+    if (preexisting) {
+      return (await preexisting) as T
+    }
+
     const cached = await get<T>(key)
     if (cached !== undefined) {
       return cached
     }
 
-    const fullKey = buildKey(key)
-
-    // Check if another request is already in flight
-    const existing = inflightRequests.get(fullKey)
-    if (existing) {
-      return (await existing) as T
+    // Re-check after the await: another caller may have registered an
+    // in-flight fetch while we were reading the persistent cache.
+    const rechecked = inflightRequests.get(fullKey)
+    if (rechecked) {
+      return (await rechecked) as T
     }
 
     // Create promise with cleanup handlers
@@ -446,7 +457,7 @@ export function createTtlCache(options?: TtlCacheOptions): TtlCache {
       }
     })()
 
-    // Set the promise IMMEDIATELY before any await to prevent race
+    // Register before awaiting so subsequent callers join this fetch.
     inflightRequests.set(fullKey, promise)
 
     // Await and return (cleanup happens in finally block)

test/unit/cache-with-ttl.test.mts

@@ -554,8 +554,37 @@ describe.sequential('cache-with-ttl', () => {
 
       // All should return the value
       expect(results).toEqual(['value', 'value', 'value'])
-      // But fetcher might be called multiple times due to race conditions
-      expect(fetchCount).toBeGreaterThan(0)
+      // And the inflight map dedupes to a single upstream call.
+      // (Previously gated on `> 0` because getOrFetch let two concurrent
+      // cold-cache callers both fire fetcher — the check-then-inflight
+      // ordering was wrong. Tightened once the TOCTOU was closed.)
+      expect(fetchCount).toBe(1)
+    })
+
+    it('dedupes concurrent cold-cache fetches', async () => {
+      // Regression: previously `await get(key)` ran BEFORE the inflight
+      // map was consulted. Two callers could both suspend on the disk
+      // lookup, both see no cached value, and both start a fresh fetch.
+      let fetchCount = 0
+      let resolveFetcher: (value: string) => void = () => {}
+      const pendingValue = new Promise<string>(resolve => {
+        resolveFetcher = resolve
+      })
+      const fetcher = async () => {
+        fetchCount++
+        return pendingValue
+      }
+
+      const p1 = cache.getOrFetch('race-key', fetcher)
+      const p2 = cache.getOrFetch('race-key', fetcher)
+      const p3 = cache.getOrFetch('race-key', fetcher)
+      // Microtask gap so the first caller can register the inflight
+      // entry, even though its internal `await get()` is still pending.
+      await Promise.resolve()
+      resolveFetcher('joined')
+      const [v1, v2, v3] = await Promise.all([p1, p2, p3])
+      expect([v1, v2, v3]).toEqual(['joined', 'joined', 'joined'])
+      expect(fetchCount).toBe(1)
     })
   })