{"version":3,"file":"single-flight-cache-BPuGPdcN.mjs","names":[],"sources":["../src/utils/single-flight-cache.ts"],"sourcesContent":["/**\n * Global-scope async value cache with single-flight and poison-immunity.\n *\n * Built for the \"compute once for the lifetime of the JS global scope, read\n * on every request\" caches (site settings, search-health verification, ...).\n * That global scope is the process on Node and the isolate on Cloudflare\n * Workers — this helper is platform-neutral; the hazard it defends against is\n * specific to workerd but the cache itself is not.\n *\n * These caches must coalesce concurrent cold reads into one query — but the\n * obvious way to do that, caching the in-flight *promise* on a global and\n * awaiting it from later requests, is unsafe on workerd: if the request that\n * created the promise is cancelled mid-await (client disconnect, context\n * teardown), its continuation never runs, so the promise neither resolves nor\n * rejects. Every later request that awaits that shared promise then hangs\n * until the isolate is evicted (observed as 524s at the 100s wall, near-zero\n * CPU). A `.catch`/`.finally` that clears the cache doesn't help — a cancelled\n * request settles neither way.\n *\n * This cache stores the resolved *value* (not a promise) and coalesces via\n * `initWithLock`: one request becomes the owner and runs `fetch`, everyone\n * else polls for the published value and never awaits the owner's promise.\n * A cancelled owner can therefore never strand a waiter — the worst case is\n * the lock looks held until `deadlineMs`, then the next caller reclaims. The\n * owner's `fetch` is also anchored (waitUntil) so a cancelled originator's\n * query still completes and populates the cache, and bounded by\n * `ownerTimeoutMs` so a genuinely stuck fetch reclaims instead of hanging.\n *\n * Invalidation bumps `version`; reads compare against the version captured at\n * call time and refetch on mismatch.\n */\n\nimport { createInitLock, type InitLock, initWithLock } from \"./init-lock.js\";\n\nexport interface SingleFlightCache<T> {\n\t/** Last resolved value, valid only when `hasValue` is true. */\n\tvalue: T | null;\n\t/**\n\t * Presence flag, separate from `value` so that falsy/`undefined`/`void`\n\t * results cache correctly (a plain null check can't distinguish \"cached\n\t * undefined\" from \"never fetched\").\n\t */\n\thasValue: boolean;\n\t/** Invalidation counter; bumped by `invalidateSingleFlightCache`. */\n\tversion: number;\n\t/** The `version` the cached value was fetched at. */\n\tvalueVersion: number;\n\t/** Reclaimable single-flight lock (see init-lock.ts). */\n\tlock: InitLock;\n}\n\nexport function createSingleFlightCache<T>(): SingleFlightCache<T> {\n\treturn { value: null, hasValue: false, version: 0, valueVersion: -1, lock: createInitLock() };\n}\n\n/**\n * Force the next `singleFlightCached` call to refetch. An in-flight owner\n * fetched at the old version will not publish into the new version, so its\n * result is ignored by subsequent reads.\n */\nexport function invalidateSingleFlightCache(cache: SingleFlightCache<unknown>): void {\n\tcache.version++;\n\tcache.hasValue = false;\n\tcache.value = null;\n\tcache.valueVersion = -1;\n\t// Free the single-flight lock so a reader at the new version starts the\n\t// refetch immediately instead of waiting out a stale owner's deadline. A\n\t// still-running old-version owner can neither publish into the new version\n\t// (version gate) nor clobber a new owner (claim gate), so releasing here\n\t// is safe; the worst case is one brief duplicate fetch.\n\tcache.lock.ownerStartedAt = null;\n}\n\n/**\n * Headroom between the owner's own timeout and the waiter reclaim deadline.\n * The reclaim deadline must sit *above* `ownerTimeoutMs` so a slow-but-live\n * owner times out (and releases the lock) before a waiter would reclaim it —\n * otherwise a fetch slower than the deadline is superseded before it can\n * publish, and steady traffic turns that into a self-sustaining stampede.\n */\nconst RECLAIM_HEADROOM_MS = 5_000;\n\nexport interface SingleFlightCachedOptions {\n\t/**\n\t * Hand the in-flight fetch to the host's lifetime extender (waitUntil via\n\t * `after()`), so a cancelled originating request still drives it to\n\t * completion and populates the cache.\n\t */\n\tanchor?: (promise: Promise<void>) => void;\n\t/** Reclaim the single-flight lock if the owner holds it past this. */\n\tdeadlineMs?: number;\n\t/** Waiter poll interval. */\n\tpollMs?: number;\n\t/** Waiter gives up and throws after this long rather than hanging. */\n\tmaxWaitMs?: number;\n\t/**\n\t * Bound the owner's own `fetch`: if it doesn't settle within this, the\n\t * owner rejects (and releases the lock) instead of waiting indefinitely.\n\t * The anchored copy keeps running, so a slow-but-live fetch can still\n\t * publish for a later caller. Omit to leave the owner unbounded.\n\t */\n\townerTimeoutMs?: number;\n}\n\n/** Boxed cache hit so a `void`/falsy value is still distinguishable from a miss. */\ninterface Box<T> {\n\tv: T;\n}\n\nfunction withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {\n\treturn new Promise<T>((resolve, reject) => {\n\t\tconst timer = setTimeout(() => {\n\t\t\treject(new Error(`singleFlightCached: owner fetch exceeded ${ms}ms`));\n\t\t}, ms);\n\t\t// Settle from the underlying promise (whichever wins the race with the\n\t\t// timer), and always clear the timer so a resolved fetch doesn't leave\n\t\t// a pending timeout holding the isolate alive.\n\t\tpromise.then(resolve, reject).finally(() => {\n\t\t\tclearTimeout(timer);\n\t\t});\n\t});\n}\n\n/**\n * Return the cached value for `cache`, computing it via `fetch` under a\n * single-flight lock on a miss. Concurrent callers coalesce onto one fetch;\n * a cancelled owner cannot poison later callers (see file header).\n */\nexport function singleFlightCached<T>(\n\tcache: SingleFlightCache<T>,\n\tfetch: () => Promise<T>,\n\toptions: SingleFlightCachedOptions = {},\n): Promise<T> {\n\t// Capture the version once: a value published at this version satisfies\n\t// this call; an invalidation that lands mid-fetch makes the published\n\t// value stale for *later* calls (which captured the newer version) but\n\t// still valid for this one.\n\tconst versionAtCall = cache.version;\n\n\t// Ignore a non-positive / non-finite owner timeout rather than letting it\n\t// degenerate into an instant-reject (setTimeout coerces NaN/0 to ~0ms).\n\tconst ownerTimeoutMs =\n\t\toptions.ownerTimeoutMs !== undefined &&\n\t\tNumber.isFinite(options.ownerTimeoutMs) &&\n\t\toptions.ownerTimeoutMs > 0\n\t\t\t? options.ownerTimeoutMs\n\t\t\t: undefined;\n\n\t// Keep the reclaim deadline above the owner timeout (see RECLAIM_HEADROOM_MS):\n\t// the owner's own timeout, not a waiter reclaim, is the primary release.\n\tconst deadlineMs =\n\t\townerTimeoutMs === undefined\n\t\t\t? options.deadlineMs\n\t\t\t: Math.max(options.deadlineMs ?? 0, ownerTimeoutMs + RECLAIM_HEADROOM_MS);\n\n\treturn initWithLock<Box<T>>(\n\t\tcache.lock,\n\t\t() =>\n\t\t\tcache.hasValue && cache.valueVersion === versionAtCall\n\t\t\t\t? // eslint-disable-next-line typescript/no-unsafe-type-assertion -- hasValue gates that `value` holds a real T\n\t\t\t\t\t({ v: cache.value as T } satisfies Box<T>)\n\t\t\t\t: null,\n\t\t(isCurrentClaim) => {\n\t\t\t// The real work, anchored independently so a cancelled owner's\n\t\t\t// fetch still settles and publishes. Publication is gated on the\n\t\t\t// claim so a reclaimed slow owner can't clobber the reclaimer's\n\t\t\t// value (same contract as initWithLock's own callers).\n\t\t\tconst real = (async (): Promise<Box<T>> => {\n\t\t\t\tconst value = await fetch();\n\t\t\t\tif (isCurrentClaim()) {\n\t\t\t\t\tcache.value = value;\n\t\t\t\t\tcache.hasValue = true;\n\t\t\t\t\tcache.valueVersion = versionAtCall;\n\t\t\t\t}\n\t\t\t\treturn { v: value };\n\t\t\t})();\n\t\t\t// Anchor the real fetch (not the timeout race): this is what must\n\t\t\t// survive a cancelled owner and run to publication. initWithLock is\n\t\t\t// left to manage only the lock; we don't double-anchor.\n\t\t\toptions.anchor?.(\n\t\t\t\treal.then(\n\t\t\t\t\t() => undefined,\n\t\t\t\t\t() => undefined,\n\t\t\t\t),\n\t\t\t);\n\t\t\treturn ownerTimeoutMs === undefined ? real : withTimeout(real, ownerTimeoutMs);\n\t\t},\n\t\t{\n\t\t\tdeadlineMs,\n\t\t\tpollMs: options.pollMs,\n\t\t\tmaxWaitMs: options.maxWaitMs,\n\t\t},\n\t).then((box) => box.v);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,0BAAmD;AAClE,QAAO;EAAE,OAAO;EAAM,UAAU;EAAO,SAAS;EAAG,cAAc;EAAI,MAAM,gBAAgB;EAAE;;;;;;;AAQ9F,SAAgB,4BAA4B,OAAyC;AACpF,OAAM;AACN,OAAM,WAAW;AACjB,OAAM,QAAQ;AACd,OAAM,eAAe;AAMrB,OAAM,KAAK,iBAAiB;;;;;;;;;AAU7B,MAAM,sBAAsB;AA6B5B,SAAS,YAAe,SAAqB,IAAwB;AACpE,QAAO,IAAI,SAAY,SAAS,WAAW;EAC1C,MAAM,QAAQ,iBAAiB;AAC9B,0BAAO,IAAI,MAAM,4CAA4C,GAAG,IAAI,CAAC;KACnE,GAAG;AAIN,UAAQ,KAAK,SAAS,OAAO,CAAC,cAAc;AAC3C,gBAAa,MAAM;IAClB;GACD;;;;;;;AAQH,SAAgB,mBACf,OACA,OACA,UAAqC,EAAE,EAC1B;CAKb,MAAM,gBAAgB,MAAM;CAI5B,MAAM,iBACL,QAAQ,mBAAmB,UAC3B,OAAO,SAAS,QAAQ,eAAe,IACvC,QAAQ,iBAAiB,IACtB,QAAQ,iBACR;CAIJ,MAAM,aACL,mBAAmB,SAChB,QAAQ,aACR,KAAK,IAAI,QAAQ,cAAc,GAAG,iBAAiB,oBAAoB;AAE3E,QAAO,aACN,MAAM,YAEL,MAAM,YAAY,MAAM,iBAAiB,gBAEtC,EAAE,GAAG,MAAM,OAAY,GACvB,OACH,mBAAmB;EAKnB,MAAM,QAAQ,YAA6B;GAC1C,MAAM,QAAQ,MAAM,OAAO;AAC3B,OAAI,gBAAgB,EAAE;AACrB,UAAM,QAAQ;AACd,UAAM,WAAW;AACjB,UAAM,eAAe;;AAEtB,UAAO,EAAE,GAAG,OAAO;MAChB;AAIJ,UAAQ,SACP,KAAK,WACE,cACA,OACN,CACD;AACD,SAAO,mBAAmB,SAAY,OAAO,YAAY,MAAM,eAAe;IAE/E;EACC;EACA,QAAQ,QAAQ;EAChB,WAAW,QAAQ;EACnB,CACD,CAAC,MAAM,QAAQ,IAAI,EAAE"}