@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/development/core/analytics/utils/flatten-connection.d.mts

@@ -1,18 +1,20 @@
 //#region src/core/analytics/utils/flatten-connection.d.ts
-/**
- * Normalizes Shopify's GraphQL connection format into a flat array.
- *
- * Shopify's Storefront API returns list fields (like cart `lines`) in a
- * "connection" wrapper — either `{ nodes: [...] }` or `{ edges: [{ node: ... }] }`.
- * Hydrogen queries typically use `nodes`, but queries written with the `edges`
- * pattern are supported too.
- */
+/** A GraphQL connection in either the nodes shape or the edges shape. */
 type Connection<T> = {
-  nodes?: T[];
+  /** The connection's items as a flat list. */nodes?: T[]; /** The connection's items, each wrapped in an edge object. */
   edges?: Array<{
     node: T;
   }>;
 };
+/**
+ * Returns the items of a Storefront API connection, such as cart lines, as a flat array.
+ *
+ * The function accepts the `nodes` shape and the `edges` shape. For the `nodes` shape, the function returns the original array. Copy the result before you sort or change it. The function returns an empty array for `undefined`, `null`, or a connection with neither field. A `null` input also logs a warning.
+ *
+ * @param connection The Storefront API connection field to flatten.
+ * @returns The connection's items as a flat array, or an empty array when there are none.
+ * @publicDocs
+ */
 declare function flattenConnection<T>(connection?: Connection<T> | null): T[];
 //#endregion
 export { flattenConnection };

package/dist/development/core/analytics/utils/flatten-connection.mjs

@@ -1,15 +1,16 @@
 import { getLogger } from "../../logging/logging.mjs";
 
 //#region src/core/analytics/utils/flatten-connection.ts
+const log = getLogger("analytics");
 /**
-* Normalizes Shopify's GraphQL connection format into a flat array.
+* Returns the items of a Storefront API connection, such as cart lines, as a flat array.
+*
+* The function accepts the `nodes` shape and the `edges` shape. For the `nodes` shape, the function returns the original array. Copy the result before you sort or change it. The function returns an empty array for `undefined`, `null`, or a connection with neither field. A `null` input also logs a warning.
 *
-* Shopify's Storefront API returns list fields (like cart `lines`) in a
-* "connection" wrapper — either `{ nodes: [...] }` or `{ edges: [{ node: ... }] }`.
-* Hydrogen queries typically use `nodes`, but queries written with the `edges`
-* pattern are supported too.
+* @param connection The Storefront API connection field to flatten.
+* @returns The connection's items as a flat array, or an empty array when there are none.
+* @publicDocs
 */
-const log = getLogger("analytics");
 function flattenConnection(connection) {
 	if (!connection) {
 		if (connection === null) log.warn("received null connection; expected an object with `nodes` or `edges`");

package/dist/development/core/analytics/utils/flatten-connection.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"flatten-connection.mjs","names":[],"sources":["../../../../../src/core/analytics/utils/flatten-connection.ts"],"sourcesContent":["/**\n * Normalizes Shopify's GraphQL connection format into a flat array.\n *\n * Shopify's Storefront API returns list fields (like cart `lines`) in a\n * \"connection\" wrapper — either `{ nodes: [...] }` or `{ edges: [{ node: ... }] }`.\n * Hydrogen queries typically use `nodes`, but queries written with the `edges`\n * pattern are supported too.\n */\n\nimport { getLogger } from \"../../logging\";\n\nconst log = getLogger(\"analytics\");\n\ntype Connection<T> = {\n  nodes?: T[];\n  edges?: Array<{ node: T }>;\n};\n\nexport function flattenConnection<T>(connection?: Connection<T> | null): T[] {\n  if (!connection) {\n    if (connection === null) {\n      log.warn(\"received null connection; expected an object with `nodes` or `edges`\");\n    }\n    return [];\n  }\n\n  if (\"nodes\" in connection && connection.nodes) {\n    return connection.nodes;\n  }\n\n  if (\"edges\" in connection && Array.isArray(connection.edges)) {\n    return connection.edges.map((edge) => edge.node);\n  }\n\n  return [];\n}\n"],"mappings":";;;;;;;;;;;AAWA,MAAM,MAAM,UAAU,YAAY;AAOlC,SAAgB,kBAAqB,YAAwC;AAC3E,KAAI,CAAC,YAAY;AACf,MAAI,eAAe,KACjB,KAAI,KAAK,uEAAuE;AAElF,SAAO,EAAE;;AAGX,KAAI,WAAW,cAAc,WAAW,MACtC,QAAO,WAAW;AAGpB,KAAI,WAAW,cAAc,MAAM,QAAQ,WAAW,MAAM,CAC1D,QAAO,WAAW,MAAM,KAAK,SAAS,KAAK,KAAK;AAGlD,QAAO,EAAE"}
+{"version":3,"file":"flatten-connection.mjs","names":[],"sources":["../../../../../src/core/analytics/utils/flatten-connection.ts"],"sourcesContent":["import { getLogger } from \"../../logging\";\n\nconst log = getLogger(\"analytics\");\n\n/** A GraphQL connection in either the nodes shape or the edges shape. */\ntype Connection<T> = {\n  /** The connection's items as a flat list. */\n  nodes?: T[];\n  /** The connection's items, each wrapped in an edge object. */\n  edges?: Array<{ node: T }>;\n};\n\n/**\n * Returns the items of a Storefront API connection, such as cart lines, as a flat array.\n *\n * The function accepts the `nodes` shape and the `edges` shape. For the `nodes` shape, the function returns the original array. Copy the result before you sort or change it. The function returns an empty array for `undefined`, `null`, or a connection with neither field. A `null` input also logs a warning.\n *\n * @param connection The Storefront API connection field to flatten.\n * @returns The connection's items as a flat array, or an empty array when there are none.\n * @publicDocs\n */\nexport function flattenConnection<T>(connection?: Connection<T> | null): T[] {\n  if (!connection) {\n    if (connection === null) {\n      log.warn(\"received null connection; expected an object with `nodes` or `edges`\");\n    }\n    return [];\n  }\n\n  if (\"nodes\" in connection && connection.nodes) {\n    return connection.nodes;\n  }\n\n  if (\"edges\" in connection && Array.isArray(connection.edges)) {\n    return connection.edges.map((edge) => edge.node);\n  }\n\n  return [];\n}\n"],"mappings":";;;AAEA,MAAM,MAAM,UAAU,YAAY;;;;;;;;;;AAmBlC,SAAgB,kBAAqB,YAAwC;AAC3E,KAAI,CAAC,YAAY;AACf,MAAI,eAAe,KACjB,KAAI,KAAK,uEAAuE;AAElF,SAAO,EAAE;;AAGX,KAAI,WAAW,cAAc,WAAW,MACtC,QAAO,WAAW;AAGpB,KAAI,WAAW,cAAc,MAAM,QAAQ,WAAW,MAAM,CAC1D,QAAO,WAAW,MAAM,KAAK,SAAS,KAAK,KAAK;AAGlD,QAAO,EAAE"}

package/dist/development/core/cache/fetch-with-cache.d.mts

@@ -16,24 +16,44 @@ type FetchCacheResponseContext = {
   json?: () => Promise<unknown>;
 };
 type FetchCacheOptions = {
-  key: CacheKey;
-  strategy: CachingStrategy;
+  /** Identifies the cached response. */key: CacheKey; /** Sets how long the response stays fresh, stale while revalidating, and stale after an error. */
+  strategy: CachingStrategy; /** Set to `false` to leave the `Cache-Status` header off the response. */
   annotateCacheStatus?: boolean;
   /**
-   * Runs only for OK responses with text-serializable bodies. Non-OK responses
-   * and binary/streaming responses are never cached.
+   * Decides whether to cache an OK response with a text body. Return `false` to skip caching the
+   * response. Hydrogen never caches a response with an error status or a non-text body.
    */
   shouldCacheResponse?: (context: FetchCacheResponseContext) => MaybePromise<boolean>;
+  /**
+   * Creates the signal for a stale-while-revalidate refresh, which runs after
+   * the caller already has the stale response. Without it, the refresh reuses
+   * `init.signal`.
+   */
+  backgroundSignal?: () => AbortSignal;
 };
+/** A fetch function that caches the response when you pass cache options as the third argument. */
 type FetchWithCache = {
   (input: FetchInput, init?: FetchInit): Promise<Response>;
   (input: FetchInput, init: FetchInit | undefined, options: FetchCacheOptions): Promise<Response>;
 };
+/** Pass a cache and an optional `waitUntil` function, or pass `runWithCache` from `createRunWithCache` to share its cache. Set `fetch` to replace the global fetch function. */
 type CreateFetchWithCacheOptions = (CreateRunWithCacheOptions | {
   runWithCache: RunWithCache;
 }) & {
   fetch?: typeof fetch;
 };
+/**
+ * Creates a fetch function that caches responses from third-party APIs. Call the function like
+ * `fetch()`, and pass a `key` and `strategy` in the third argument to cache the response. Calls
+ * without the third argument skip the cache. Return `false` from a `shouldCacheResponse` option to
+ * skip caching one response.
+ *
+ * The function caches only OK responses with no body or with a JSON, text, XML, HTML, GraphQL, or JavaScript content type. Other responses skip the cache. The function removes the `set-cookie` and `server-timing` headers from each cached response, including the response that a cache miss returns. With `staleIfError`, the function serves a stale entry only after a `500`, `502`, `503`, or `504` status, or when the fetch throws.
+ *
+ * @param options - A cache, or the function from `createRunWithCache` to share its cache, plus an optional fetch function.
+ * @returns A fetch function that adds a `Cache-Status` header to calls with cache options, unless `annotateCacheStatus` is `false`.
+ * @publicDocs
+ */
 declare function createFetchWithCache({
   fetch: customFetch,
   ...options

package/dist/development/core/cache/fetch-with-cache.mjs

@@ -27,6 +27,18 @@ var ServerResponseError = class extends Error {
 		this.response = response;
 	}
 };
+/**
+* Creates a fetch function that caches responses from third-party APIs. Call the function like
+* `fetch()`, and pass a `key` and `strategy` in the third argument to cache the response. Calls
+* without the third argument skip the cache. Return `false` from a `shouldCacheResponse` option to
+* skip caching one response.
+*
+* The function caches only OK responses with no body or with a JSON, text, XML, HTML, GraphQL, or JavaScript content type. Other responses skip the cache. The function removes the `set-cookie` and `server-timing` headers from each cached response, including the response that a cache miss returns. With `staleIfError`, the function serves a stale entry only after a `500`, `502`, `503`, or `504` status, or when the fetch throws.
+*
+* @param options - A cache, or the function from `createRunWithCache` to share its cache, plus an optional fetch function.
+* @returns A fetch function that adds a `Cache-Status` header to calls with cache options, unless `annotateCacheStatus` is `false`.
+* @publicDocs
+*/
 function createFetchWithCache({ fetch: customFetch, ...options }) {
 	const resolvedFetch = customFetch ?? globalThis.fetch;
 	const runWithCache = "runWithCache" in options ? options.runWithCache : createRunWithCache(options);
@@ -39,8 +51,11 @@ function createFetchWithCache({ fetch: customFetch, ...options }) {
 			result = await runWithCache({
 				key: cacheOptions.key,
 				strategy: cacheOptions.strategy
-			}, async () => {
-				const response = await resolvedFetch(input, init);
+			}, async (context) => {
+				const response = await resolvedFetch(input, context?.background && cacheOptions.backgroundSignal ? {
+					...init,
+					signal: cacheOptions.backgroundSignal()
+				} : init);
 				if (!response.ok) {
 					if (isStaleIfErrorStatus(response.status)) {
 						if (!canSerializeBodyAsText(response)) {

package/dist/development/core/cache/fetch-with-cache.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-with-cache.mjs","names":[],"sources":["../../../../src/core/cache/fetch-with-cache.ts"],"sourcesContent":["import { HYDROGEN_CACHE_STATUS_PRODUCT } from \"./cache-status\";\nimport { type CacheKey } from \"./key\";\nimport {\n  type CreateRunWithCacheOptions,\n  type RunWithCache,\n  type RunWithCacheResult,\n  StaleFallbackDisabledError,\n  createRunWithCache,\n} from \"./run-with-cache\";\nimport { type SerializableCacheValue } from \"./store\";\nimport { NO_STORE, type CachingStrategy } from \"./strategies\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\ntype FetchInput = Parameters<typeof fetch>[0];\ntype FetchInit = Parameters<typeof fetch>[1];\n\ntype SerializableResponse = SerializableCacheValue & {\n  body: string;\n  cacheable: boolean;\n  headers: [string, string][];\n  status: number;\n  statusText: string;\n};\n\nexport type FetchCacheResponseContext = {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: Headers;\n  url: string;\n  text(): Promise<string>;\n  json?: () => Promise<unknown>;\n};\n\nexport type FetchCacheOptions = {\n  key: CacheKey;\n  strategy: CachingStrategy;\n  annotateCacheStatus?: boolean;\n  /**\n   * Runs only for OK responses with text-serializable bodies. Non-OK responses\n   * and binary/streaming responses are never cached.\n   */\n  shouldCacheResponse?: (context: FetchCacheResponseContext) => MaybePromise<boolean>;\n};\n\ntype FetchWithCache = {\n  (input: FetchInput, init?: FetchInit): Promise<Response>;\n  (input: FetchInput, init: FetchInit | undefined, options: FetchCacheOptions): Promise<Response>;\n};\n\ntype CreateFetchWithCacheOptions = (\n  | CreateRunWithCacheOptions\n  | {\n      runWithCache: RunWithCache;\n    }\n) & {\n  fetch?: typeof fetch;\n};\n\nconst excludedCachedResponseHeaders = new Set([\"set-cookie\", \"server-timing\"]);\nconst staleIfErrorStatuses = new Set([500, 502, 503, 504]);\n\nclass UnserializableResponseError extends StaleFallbackDisabledError {\n  constructor() {\n    super(\"Response body is not serializable for cache.\");\n  }\n}\n\nclass StaleFallbackEligibleResponseError extends Error {\n  constructor() {\n    super(\"Origin returned an unserializable response eligible for stale-if-error fallback.\");\n  }\n}\n\nclass ServerResponseError extends Error {\n  readonly response: SerializableResponse;\n\n  constructor(response: SerializableResponse) {\n    super(\"Origin returned a response eligible for stale-if-error fallback.\");\n    this.response = response;\n  }\n}\n\nexport function createFetchWithCache({\n  fetch: customFetch,\n  ...options\n}: CreateFetchWithCacheOptions): FetchWithCache {\n  const resolvedFetch = customFetch ?? globalThis.fetch;\n  const runWithCache =\n    \"runWithCache\" in options ? options.runWithCache : createRunWithCache(options);\n\n  return async function fetchWithCache(\n    input: FetchInput,\n    init?: FetchInit,\n    cacheOptions?: FetchCacheOptions,\n  ): Promise<Response> {\n    if (!cacheOptions) return resolvedFetch(input, init);\n\n    if (cacheOptions.strategy.mode === NO_STORE) {\n      return annotateResponse(\n        await resolvedFetch(input, init),\n        getCacheStatusHeader(\"fwd=bypass\"),\n        cacheOptions,\n      );\n    }\n\n    let passthroughResponse: Response | undefined;\n    let result: RunWithCacheResult<SerializableResponse>;\n\n    try {\n      result = await runWithCache<SerializableResponse>(\n        {\n          key: cacheOptions.key,\n          strategy: cacheOptions.strategy,\n        },\n        async () => {\n          const response = await resolvedFetch(input, init);\n\n          if (!response.ok) {\n            if (isStaleIfErrorStatus(response.status)) {\n              if (!canSerializeBodyAsText(response)) {\n                passthroughResponse = response;\n                throw new StaleFallbackEligibleResponseError();\n              }\n\n              throw new ServerResponseError(\n                await serializeResponse(response, {\n                  cacheable: false,\n                  fallbackOnError: true,\n                }),\n              );\n            }\n\n            return {\n              data: await serializeResponse(response, {\n                cacheable: false,\n                fallbackOnError: true,\n              }),\n              shouldCache: false,\n            };\n          }\n\n          if (!canSerializeBodyAsText(response)) {\n            passthroughResponse = response;\n\n            // Signal bypass so the original streaming response can be returned\n            // to this caller without attempting to serialize it for storage.\n            throw new UnserializableResponseError();\n          }\n\n          const bodyReader = createBodyReader(response);\n          const shouldCache = await shouldCacheResponse(response, bodyReader, cacheOptions);\n\n          if (!shouldCache) {\n            return {\n              data: await serializeResponse(response, {\n                bodyReader,\n                cacheable: false,\n                fallbackOnError: true,\n              }),\n              shouldCache: false,\n            };\n          }\n\n          const data = await serializeResponse(response, {\n            bodyReader,\n            cacheable: true,\n            fallbackOnError: true,\n          });\n\n          return {\n            data,\n            shouldCache: data.cacheable,\n          };\n        },\n      );\n    } catch (error) {\n      if (error instanceof ServerResponseError) {\n        return annotateResponse(\n          fromSerializableResponse(error.response),\n          getCacheStatusHeader(\"fwd=bypass\"),\n          cacheOptions,\n        );\n      }\n\n      if (error instanceof UnserializableResponseError) {\n        return annotateResponse(\n          // The raw Response body is not cache-serializable, so return the\n          // original response. Refetch defensively if the response was not kept.\n          passthroughResponse ?? (await resolvedFetch(input, init)),\n          getCacheStatusHeader(\"fwd=bypass\"),\n          cacheOptions,\n        );\n      }\n\n      if (error instanceof StaleFallbackEligibleResponseError) {\n        return annotateResponse(\n          // Return the original unserializable response. This error type can\n          // also trigger stale-if-error fallback when a stale entry exists.\n          passthroughResponse ?? (await resolvedFetch(input, init)),\n          getCacheStatusHeader(\"fwd=bypass\"),\n          cacheOptions,\n        );\n      }\n\n      throw error;\n    }\n\n    return annotateResponse(\n      fromSerializableResponse(result.data),\n      result.cacheStatus === \"hit\"\n        ? getCacheStatusHeader(\"hit\")\n        : getNonHitCacheStatusHeader(result.data.cacheable, result.cacheStatus),\n      cacheOptions,\n    );\n  };\n}\n\nfunction shouldCacheResponse(\n  response: Response,\n  bodyReader: BodyReader,\n  options: FetchCacheOptions,\n): MaybePromise<boolean> {\n  const context: FetchCacheResponseContext = {\n    ok: response.ok,\n    status: response.status,\n    statusText: response.statusText,\n    headers: new Headers(response.headers),\n    url: response.url,\n    text: bodyReader.text,\n  };\n\n  if (isJsonResponse(response)) {\n    context.json = bodyReader.json;\n  }\n\n  return options.shouldCacheResponse?.(context) ?? true;\n}\n\ntype BodyReader = {\n  text(): Promise<string>;\n  json(): Promise<unknown>;\n};\n\ntype SerializeResponseOptions = {\n  bodyReader?: BodyReader;\n  cacheable: boolean;\n  fallbackOnError?: boolean;\n};\n\nfunction createBodyReader(response: Response): BodyReader {\n  let bodyText: Promise<string> | undefined;\n  let bodyJson: Promise<unknown> | undefined;\n\n  const text = () => {\n    bodyText ??= response.text();\n    return bodyText;\n  };\n\n  return {\n    text,\n    json() {\n      bodyJson ??= text().then((value) => JSON.parse(value));\n      return bodyJson;\n    },\n  };\n}\n\nasync function serializeResponse(\n  response: Response,\n  { bodyReader, cacheable, fallbackOnError = false }: SerializeResponseOptions,\n): Promise<SerializableResponse> {\n  if (!canSerializeBodyAsText(response)) return emptySerializableResponse(response);\n\n  try {\n    return {\n      body: await (bodyReader ?? createBodyReader(response)).text(),\n      cacheable,\n      headers: getSerializableHeaders(response.headers, cacheable),\n      status: response.status,\n      statusText: response.statusText,\n    };\n  } catch (error) {\n    if (!fallbackOnError) throw error;\n    return emptySerializableResponse(response);\n  }\n}\n\nfunction fromSerializableResponse(response: SerializableResponse): Response {\n  return new Response(response.body, {\n    headers: response.headers,\n    status: response.status,\n    statusText: response.statusText,\n  });\n}\n\nfunction emptySerializableResponse(response: Response): SerializableResponse {\n  return {\n    body: \"\",\n    cacheable: false,\n    headers: [],\n    status: response.status,\n    statusText: response.statusText,\n  };\n}\n\nfunction getSerializableHeaders(headers: Headers, cacheable: boolean): [string, string][] {\n  if (!cacheable) return [...headers];\n\n  // Cacheable serialized responses can be returned to future requests, so\n  // per-request headers must not be copied.\n  return [...headers].filter(([key]) => !excludedCachedResponseHeaders.has(key.toLowerCase()));\n}\n\nfunction annotateResponse(\n  response: Response,\n  cacheStatus: string,\n  options: FetchCacheOptions,\n): Response {\n  if (options.annotateCacheStatus === false) return response;\n\n  const headers = new Headers(response.headers);\n  headers.append(\"Cache-Status\", cacheStatus);\n\n  return new Response(response.body, {\n    headers,\n    status: response.status,\n    statusText: response.statusText,\n  });\n}\n\nfunction getNonHitCacheStatusHeader(shouldCache: boolean, cacheStatus: \"miss\" | \"bypass\"): string {\n  if (cacheStatus === \"bypass\") return getCacheStatusHeader(\"fwd=bypass\");\n  return shouldCache\n    ? getCacheStatusHeader(\"fwd=uri-miss; stored\")\n    : getCacheStatusHeader(\"fwd=bypass\");\n}\n\nfunction getCacheStatusHeader(value: string): string {\n  return `${HYDROGEN_CACHE_STATUS_PRODUCT}; ${value}`;\n}\n\nfunction isJsonResponse(response: Response): boolean {\n  return response.headers.get(\"content-type\")?.toLowerCase().includes(\"json\") ?? false;\n}\n\nfunction isStaleIfErrorStatus(status: number): boolean {\n  return staleIfErrorStatuses.has(status);\n}\n\nfunction canSerializeBodyAsText(response: Response): boolean {\n  if (response.body == null) return true;\n\n  const contentType = response.headers.get(\"content-type\");\n  return contentType != null && /\\b(json|text|xml|html|graphql|javascript)\\b/i.test(contentType);\n}\n"],"mappings":"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"}
+{"version":3,"file":"fetch-with-cache.mjs","names":[],"sources":["../../../../src/core/cache/fetch-with-cache.ts"],"sourcesContent":["import { HYDROGEN_CACHE_STATUS_PRODUCT } from \"./cache-status\";\nimport { type CacheKey } from \"./key\";\nimport {\n  type CreateRunWithCacheOptions,\n  type RunWithCache,\n  type RunWithCacheResult,\n  StaleFallbackDisabledError,\n  createRunWithCache,\n} from \"./run-with-cache\";\nimport { type SerializableCacheValue } from \"./store\";\nimport { NO_STORE, type CachingStrategy } from \"./strategies\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\ntype FetchInput = Parameters<typeof fetch>[0];\ntype FetchInit = Parameters<typeof fetch>[1];\n\ntype SerializableResponse = SerializableCacheValue & {\n  body: string;\n  cacheable: boolean;\n  headers: [string, string][];\n  status: number;\n  statusText: string;\n};\n\nexport type FetchCacheResponseContext = {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: Headers;\n  url: string;\n  text(): Promise<string>;\n  json?: () => Promise<unknown>;\n};\n\nexport type FetchCacheOptions = {\n  /** Identifies the cached response. */\n  key: CacheKey;\n  /** Sets how long the response stays fresh, stale while revalidating, and stale after an error. */\n  strategy: CachingStrategy;\n  /** Set to `false` to leave the `Cache-Status` header off the response. */\n  annotateCacheStatus?: boolean;\n  /**\n   * Decides whether to cache an OK response with a text body. Return `false` to skip caching the\n   * response. Hydrogen never caches a response with an error status or a non-text body.\n   */\n  shouldCacheResponse?: (context: FetchCacheResponseContext) => MaybePromise<boolean>;\n  /**\n   * Creates the signal for a stale-while-revalidate refresh, which runs after\n   * the caller already has the stale response. Without it, the refresh reuses\n   * `init.signal`.\n   */\n  backgroundSignal?: () => AbortSignal;\n};\n\n/** A fetch function that caches the response when you pass cache options as the third argument. */\ntype FetchWithCache = {\n  (input: FetchInput, init?: FetchInit): Promise<Response>;\n  (input: FetchInput, init: FetchInit | undefined, options: FetchCacheOptions): Promise<Response>;\n};\n\n/** Pass a cache and an optional `waitUntil` function, or pass `runWithCache` from `createRunWithCache` to share its cache. Set `fetch` to replace the global fetch function. */\ntype CreateFetchWithCacheOptions = (\n  | CreateRunWithCacheOptions\n  | {\n      runWithCache: RunWithCache;\n    }\n) & {\n  fetch?: typeof fetch;\n};\n\nconst excludedCachedResponseHeaders = new Set([\"set-cookie\", \"server-timing\"]);\nconst staleIfErrorStatuses = new Set([500, 502, 503, 504]);\n\nclass UnserializableResponseError extends StaleFallbackDisabledError {\n  constructor() {\n    super(\"Response body is not serializable for cache.\");\n  }\n}\n\nclass StaleFallbackEligibleResponseError extends Error {\n  constructor() {\n    super(\"Origin returned an unserializable response eligible for stale-if-error fallback.\");\n  }\n}\n\nclass ServerResponseError extends Error {\n  readonly response: SerializableResponse;\n\n  constructor(response: SerializableResponse) {\n    super(\"Origin returned a response eligible for stale-if-error fallback.\");\n    this.response = response;\n  }\n}\n\n/**\n * Creates a fetch function that caches responses from third-party APIs. Call the function like\n * `fetch()`, and pass a `key` and `strategy` in the third argument to cache the response. Calls\n * without the third argument skip the cache. Return `false` from a `shouldCacheResponse` option to\n * skip caching one response.\n *\n * The function caches only OK responses with no body or with a JSON, text, XML, HTML, GraphQL, or JavaScript content type. Other responses skip the cache. The function removes the `set-cookie` and `server-timing` headers from each cached response, including the response that a cache miss returns. With `staleIfError`, the function serves a stale entry only after a `500`, `502`, `503`, or `504` status, or when the fetch throws.\n *\n * @param options - A cache, or the function from `createRunWithCache` to share its cache, plus an optional fetch function.\n * @returns A fetch function that adds a `Cache-Status` header to calls with cache options, unless `annotateCacheStatus` is `false`.\n * @publicDocs\n */\nexport function createFetchWithCache({\n  fetch: customFetch,\n  ...options\n}: CreateFetchWithCacheOptions): FetchWithCache {\n  const resolvedFetch = customFetch ?? globalThis.fetch;\n  const runWithCache =\n    \"runWithCache\" in options ? options.runWithCache : createRunWithCache(options);\n\n  return async function fetchWithCache(\n    input: FetchInput,\n    init?: FetchInit,\n    cacheOptions?: FetchCacheOptions,\n  ): Promise<Response> {\n    if (!cacheOptions) return resolvedFetch(input, init);\n\n    if (cacheOptions.strategy.mode === NO_STORE) {\n      return annotateResponse(\n        await resolvedFetch(input, init),\n        getCacheStatusHeader(\"fwd=bypass\"),\n        cacheOptions,\n      );\n    }\n\n    let passthroughResponse: Response | undefined;\n    let result: RunWithCacheResult<SerializableResponse>;\n\n    try {\n      result = await runWithCache<SerializableResponse>(\n        {\n          key: cacheOptions.key,\n          strategy: cacheOptions.strategy,\n        },\n        async (context) => {\n          const response = await resolvedFetch(\n            input,\n            context?.background && cacheOptions.backgroundSignal\n              ? { ...init, signal: cacheOptions.backgroundSignal() }\n              : init,\n          );\n\n          if (!response.ok) {\n            if (isStaleIfErrorStatus(response.status)) {\n              if (!canSerializeBodyAsText(response)) {\n                passthroughResponse = response;\n                throw new StaleFallbackEligibleResponseError();\n              }\n\n              throw new ServerResponseError(\n                await serializeResponse(response, {\n                  cacheable: false,\n                  fallbackOnError: true,\n                }),\n              );\n            }\n\n            return {\n              data: await serializeResponse(response, {\n                cacheable: false,\n                fallbackOnError: true,\n              }),\n              shouldCache: false,\n            };\n          }\n\n          if (!canSerializeBodyAsText(response)) {\n            passthroughResponse = response;\n\n            // Signal bypass so the original streaming response can be returned\n            // to this caller without attempting to serialize it for storage.\n            throw new UnserializableResponseError();\n          }\n\n          const bodyReader = createBodyReader(response);\n          const shouldCache = await shouldCacheResponse(response, bodyReader, cacheOptions);\n\n          if (!shouldCache) {\n            return {\n              data: await serializeResponse(response, {\n                bodyReader,\n                cacheable: false,\n                fallbackOnError: true,\n              }),\n              shouldCache: false,\n            };\n          }\n\n          const data = await serializeResponse(response, {\n            bodyReader,\n            cacheable: true,\n            fallbackOnError: true,\n          });\n\n          return {\n            data,\n            shouldCache: data.cacheable,\n          };\n        },\n      );\n    } catch (error) {\n      if (error instanceof ServerResponseError) {\n        return annotateResponse(\n          fromSerializableResponse(error.response),\n          getCacheStatusHeader(\"fwd=bypass\"),\n          cacheOptions,\n        );\n      }\n\n      if (error instanceof UnserializableResponseError) {\n        return annotateResponse(\n          // The raw Response body is not cache-serializable, so return the\n          // original response. Refetch defensively if the response was not kept.\n          passthroughResponse ?? (await resolvedFetch(input, init)),\n          getCacheStatusHeader(\"fwd=bypass\"),\n          cacheOptions,\n        );\n      }\n\n      if (error instanceof StaleFallbackEligibleResponseError) {\n        return annotateResponse(\n          // Return the original unserializable response. This error type can\n          // also trigger stale-if-error fallback when a stale entry exists.\n          passthroughResponse ?? (await resolvedFetch(input, init)),\n          getCacheStatusHeader(\"fwd=bypass\"),\n          cacheOptions,\n        );\n      }\n\n      throw error;\n    }\n\n    return annotateResponse(\n      fromSerializableResponse(result.data),\n      result.cacheStatus === \"hit\"\n        ? getCacheStatusHeader(\"hit\")\n        : getNonHitCacheStatusHeader(result.data.cacheable, result.cacheStatus),\n      cacheOptions,\n    );\n  };\n}\n\nfunction shouldCacheResponse(\n  response: Response,\n  bodyReader: BodyReader,\n  options: FetchCacheOptions,\n): MaybePromise<boolean> {\n  const context: FetchCacheResponseContext = {\n    ok: response.ok,\n    status: response.status,\n    statusText: response.statusText,\n    headers: new Headers(response.headers),\n    url: response.url,\n    text: bodyReader.text,\n  };\n\n  if (isJsonResponse(response)) {\n    context.json = bodyReader.json;\n  }\n\n  return options.shouldCacheResponse?.(context) ?? true;\n}\n\ntype BodyReader = {\n  text(): Promise<string>;\n  json(): Promise<unknown>;\n};\n\ntype SerializeResponseOptions = {\n  bodyReader?: BodyReader;\n  cacheable: boolean;\n  fallbackOnError?: boolean;\n};\n\nfunction createBodyReader(response: Response): BodyReader {\n  let bodyText: Promise<string> | undefined;\n  let bodyJson: Promise<unknown> | undefined;\n\n  const text = () => {\n    bodyText ??= response.text();\n    return bodyText;\n  };\n\n  return {\n    text,\n    json() {\n      bodyJson ??= text().then((value) => JSON.parse(value));\n      return bodyJson;\n    },\n  };\n}\n\nasync function serializeResponse(\n  response: Response,\n  { bodyReader, cacheable, fallbackOnError = false }: SerializeResponseOptions,\n): Promise<SerializableResponse> {\n  if (!canSerializeBodyAsText(response)) return emptySerializableResponse(response);\n\n  try {\n    return {\n      body: await (bodyReader ?? createBodyReader(response)).text(),\n      cacheable,\n      headers: getSerializableHeaders(response.headers, cacheable),\n      status: response.status,\n      statusText: response.statusText,\n    };\n  } catch (error) {\n    if (!fallbackOnError) throw error;\n    return emptySerializableResponse(response);\n  }\n}\n\nfunction fromSerializableResponse(response: SerializableResponse): Response {\n  return new Response(response.body, {\n    headers: response.headers,\n    status: response.status,\n    statusText: response.statusText,\n  });\n}\n\nfunction emptySerializableResponse(response: Response): SerializableResponse {\n  return {\n    body: \"\",\n    cacheable: false,\n    headers: [],\n    status: response.status,\n    statusText: response.statusText,\n  };\n}\n\nfunction getSerializableHeaders(headers: Headers, cacheable: boolean): [string, string][] {\n  if (!cacheable) return [...headers];\n\n  // Cacheable serialized responses can be returned to future requests, so\n  // per-request headers must not be copied.\n  return [...headers].filter(([key]) => !excludedCachedResponseHeaders.has(key.toLowerCase()));\n}\n\nfunction annotateResponse(\n  response: Response,\n  cacheStatus: string,\n  options: FetchCacheOptions,\n): Response {\n  if (options.annotateCacheStatus === false) return response;\n\n  const headers = new Headers(response.headers);\n  headers.append(\"Cache-Status\", cacheStatus);\n\n  return new Response(response.body, {\n    headers,\n    status: response.status,\n    statusText: response.statusText,\n  });\n}\n\nfunction getNonHitCacheStatusHeader(shouldCache: boolean, cacheStatus: \"miss\" | \"bypass\"): string {\n  if (cacheStatus === \"bypass\") return getCacheStatusHeader(\"fwd=bypass\");\n  return shouldCache\n    ? getCacheStatusHeader(\"fwd=uri-miss; stored\")\n    : getCacheStatusHeader(\"fwd=bypass\");\n}\n\nfunction getCacheStatusHeader(value: string): string {\n  return `${HYDROGEN_CACHE_STATUS_PRODUCT}; ${value}`;\n}\n\nfunction isJsonResponse(response: Response): boolean {\n  return response.headers.get(\"content-type\")?.toLowerCase().includes(\"json\") ?? false;\n}\n\nfunction isStaleIfErrorStatus(status: number): boolean {\n  return staleIfErrorStatuses.has(status);\n}\n\nfunction canSerializeBodyAsText(response: Response): boolean {\n  if (response.body == null) return true;\n\n  const contentType = response.headers.get(\"content-type\");\n  return contentType != null && /\\b(json|text|xml|html|graphql|javascript)\\b/i.test(contentType);\n}\n"],"mappings":"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"}

package/dist/development/core/cache/key.d.mts

@@ -1,5 +1,7 @@
 //#region src/core/cache/key.d.ts
+/** One entry in an array cache key. The number `1` and the string `"1"` produce different keys. */
 type CacheKeyPrimitive = string | number | boolean | null;
+/** Identifies a cache entry, as a string or an array of strings, numbers, booleans, and `null`. Include every value that changes the cached data. */
 type CacheKey = string | readonly CacheKeyPrimitive[];
 //#endregion
 export { CacheKey };

package/dist/development/core/cache/key.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"key.mjs","names":[],"sources":["../../../../src/core/cache/key.ts"],"sourcesContent":["export type CacheKeyPrimitive = string | number | boolean | null;\n\nexport type CacheKey = string | readonly CacheKeyPrimitive[];\n\nconst textEncoder = new TextEncoder();\n\nexport async function hashCacheKey(key: CacheKey): Promise<string> {\n  const serialized = typeof key === \"string\" ? `string:${key}` : `array:${serializeArrayKey(key)}`;\n  const bytes = await crypto.subtle.digest(\"SHA-256\", textEncoder.encode(serialized));\n\n  return `h2:${hexEncode(bytes)}`;\n}\n\nfunction serializeArrayKey(value: readonly unknown[]): string {\n  const values: string[] = [];\n  for (let index = 0; index < value.length; index++) {\n    if (!(index in value)) {\n      throw new TypeError(\"Cache key arrays cannot contain empty slots.\");\n    }\n\n    values.push(serializeCacheKeyPrimitive(value[index]));\n  }\n\n  return `[${values.join(\",\")}]`;\n}\n\nfunction serializeCacheKeyPrimitive(value: unknown): string {\n  if (value === null) return \"null\";\n  if (typeof value === \"string\") return JSON.stringify(value);\n  if (typeof value === \"number\" || typeof value === \"boolean\") {\n    return String(value);\n  }\n\n  throw new TypeError(\n    `Cache key arrays must contain only primitive values. Received: ${typeof value}`,\n  );\n}\n\nfunction hexEncode(bytes: ArrayBuffer): string {\n  return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, \"0\")).join(\"\");\n}\n"],"mappings":";AAIA,MAAM,cAAc,IAAI,aAAa;AAErC,eAAsB,aAAa,KAAgC;CACjE,MAAM,aAAa,OAAO,QAAQ,WAAW,UAAU,QAAQ,SAAS,kBAAkB,IAAI;AAG9F,QAAO,MAAM,UAAU,MAFH,OAAO,OAAO,OAAO,WAAW,YAAY,OAAO,WAAW,CAAC,CAEtD;;AAG/B,SAAS,kBAAkB,OAAmC;CAC5D,MAAM,SAAmB,EAAE;AAC3B,MAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;AACjD,MAAI,EAAE,SAAS,OACb,OAAM,IAAI,UAAU,+CAA+C;AAGrE,SAAO,KAAK,2BAA2B,MAAM,OAAO,CAAC;;AAGvD,QAAO,IAAI,OAAO,KAAK,IAAI,CAAC;;AAG9B,SAAS,2BAA2B,OAAwB;AAC1D,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,OAAO,UAAU,SAAU,QAAO,KAAK,UAAU,MAAM;AAC3D,KAAI,OAAO,UAAU,YAAY,OAAO,UAAU,UAChD,QAAO,OAAO,MAAM;AAGtB,OAAM,IAAI,UACR,kEAAkE,OAAO,QAC1E;;AAGH,SAAS,UAAU,OAA4B;AAC7C,QAAO,CAAC,GAAG,IAAI,WAAW,MAAM,CAAC,CAAC,KAAK,SAAS,KAAK,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,KAAK,GAAG"}
+{"version":3,"file":"key.mjs","names":[],"sources":["../../../../src/core/cache/key.ts"],"sourcesContent":["/** One entry in an array cache key. The number `1` and the string `\"1\"` produce different keys. */\nexport type CacheKeyPrimitive = string | number | boolean | null;\n\n/** Identifies a cache entry, as a string or an array of strings, numbers, booleans, and `null`. Include every value that changes the cached data. */\nexport type CacheKey = string | readonly CacheKeyPrimitive[];\n\nconst textEncoder = new TextEncoder();\n\nexport async function hashCacheKey(key: CacheKey): Promise<string> {\n  const serialized = typeof key === \"string\" ? `string:${key}` : `array:${serializeArrayKey(key)}`;\n  const bytes = await crypto.subtle.digest(\"SHA-256\", textEncoder.encode(serialized));\n\n  return `h2:${hexEncode(bytes)}`;\n}\n\nfunction serializeArrayKey(value: readonly unknown[]): string {\n  const values: string[] = [];\n  for (let index = 0; index < value.length; index++) {\n    if (!(index in value)) {\n      throw new TypeError(\"Cache key arrays cannot contain empty slots.\");\n    }\n\n    values.push(serializeCacheKeyPrimitive(value[index]));\n  }\n\n  return `[${values.join(\",\")}]`;\n}\n\nfunction serializeCacheKeyPrimitive(value: unknown): string {\n  if (value === null) return \"null\";\n  if (typeof value === \"string\") return JSON.stringify(value);\n  if (typeof value === \"number\" || typeof value === \"boolean\") {\n    return String(value);\n  }\n\n  throw new TypeError(\n    `Cache key arrays must contain only primitive values. Received: ${typeof value}`,\n  );\n}\n\nfunction hexEncode(bytes: ArrayBuffer): string {\n  return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, \"0\")).join(\"\");\n}\n"],"mappings":";AAMA,MAAM,cAAc,IAAI,aAAa;AAErC,eAAsB,aAAa,KAAgC;CACjE,MAAM,aAAa,OAAO,QAAQ,WAAW,UAAU,QAAQ,SAAS,kBAAkB,IAAI;AAG9F,QAAO,MAAM,UAAU,MAFH,OAAO,OAAO,OAAO,WAAW,YAAY,OAAO,WAAW,CAAC,CAEtD;;AAG/B,SAAS,kBAAkB,OAAmC;CAC5D,MAAM,SAAmB,EAAE;AAC3B,MAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;AACjD,MAAI,EAAE,SAAS,OACb,OAAM,IAAI,UAAU,+CAA+C;AAGrE,SAAO,KAAK,2BAA2B,MAAM,OAAO,CAAC;;AAGvD,QAAO,IAAI,OAAO,KAAK,IAAI,CAAC;;AAG9B,SAAS,2BAA2B,OAAwB;AAC1D,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,OAAO,UAAU,SAAU,QAAO,KAAK,UAAU,MAAM;AAC3D,KAAI,OAAO,UAAU,YAAY,OAAO,UAAU,UAChD,QAAO,OAAO,MAAM;AAGtB,OAAM,IAAI,UACR,kEAAkE,OAAO,QAC1E;;AAGH,SAAS,UAAU,OAA4B;AAC7C,QAAO,CAAC,GAAG,IAAI,WAAW,MAAM,CAAC,CAAC,KAAK,SAAS,KAAK,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,KAAK,GAAG"}

package/dist/development/core/cache/run-with-cache.d.mts

@@ -3,30 +3,78 @@ import { CachingStrategy } from "./strategies.mjs";
 import { KeyValueCacheLike, SerializableCacheValue, WebCacheLike } from "./store.mjs";
 
 //#region src/core/cache/run-with-cache.d.ts
+/** A value, or a promise that resolves to the value. */
 type MaybePromise<T> = T | Promise<T>;
-type WaitUntil = (promise: Promise<unknown>) => void;
+/**
+ * Keeps the runtime alive until a background cache write or refresh finishes, such as a worker's `waitUntil` function. Hydrogen ignores errors that the function throws.
+ */
+type WaitUntil =
+/**
+ * @param promise - The background cache write or refresh to wait for.
+ * @returns Nothing. Hydrogen ignores the return value.
+ */
+(promise: Promise<unknown>) => void;
+/** The cache that holds entries, either a Web Cache API cache or a key-value store. */
 type CacheInstance = WebCacheLike | KeyValueCacheLike;
+/** The cache and the background-work function for `createRunWithCache`. */
 type CreateRunWithCacheOptions = {
-  cache: CacheInstance;
+  /** The cache that holds entries. `createRunWithCache` throws a `TypeError` when the cache is neither a Web Cache API cache nor a key-value store. */cache: CacheInstance;
+  /**
+   * Keeps the runtime alive for background cache writes and refreshes. Without `waitUntil`, each call waits for its cache write before it resolves.
+   */
   waitUntil?: WaitUntil;
 };
+/** Options for one cached run. */
 type RunWithCacheOptions = {
-  key: CacheKey;
+  /**
+   * Identifies the cache entry. `runWithCache` throws a `TypeError` for an array key with empty slots or with entries other than strings, numbers, booleans, and `null`.
+   */
+  key: CacheKey; /** Sets how long the result stays fresh, how long the cache serves it stale while refreshing it, and how long the cache serves it stale after an error. */
   strategy: CachingStrategy;
 };
+/** The callback's return value, with the data and whether to cache the data. */
 type CacheDecision<T extends SerializableCacheValue> = {
   /**
-   * Must be a JSON-serializable object. The cache store may persist this value
-   * through `JSON.stringify`; nested serializability is the caller's contract.
+   * The data to return and cache. Web Cache stores save the data as JSON.
    */
-  data: T;
+  data: T; /** Set to `false` to return the data without storing it. */
   shouldCache: boolean;
 };
+/** The data, and whether the data came from the cache or the callback. */
 type RunWithCacheResult<T extends SerializableCacheValue> = {
-  data: T;
+  /** The cached data on a hit, or the callback's data otherwise. */data: T; /** `hit` when the data comes from the cache, `miss` when the callback runs, and `bypass` for a `no-store` strategy. */
   cacheStatus: "hit" | "miss" | "bypass";
 };
-type RunWithCache = <T extends SerializableCacheValue>(options: RunWithCacheOptions, run: () => MaybePromise<CacheDecision<T>>) => Promise<RunWithCacheResult<T>>;
+/** The context that `runWithCache` passes to its callback. */
+type RunWithCacheContext = {
+  /** `true` when the callback refreshes a stale entry after the cache already returned the stale value. */background: boolean;
+};
+/** Produces the data for a cached run and decides whether to cache the data. */
+type RunCallback<T extends SerializableCacheValue> =
+/**
+ * @param context - Tells the callback whether it refreshes a stale entry in the background.
+ * @returns The data and whether to cache the data, or a promise that resolves to both.
+ */
+(context?: RunWithCacheContext) => MaybePromise<CacheDecision<T>>;
+/**
+ * Returns cached data for the key, or runs the callback and caches the result. Resolves with the
+ * data and the cache status.
+ */
+type RunWithCache =
+/**
+ * @param options - The cache key and caching strategy for this call.
+ * @param run - Produces the data and decides whether to cache it. Runs whenever the cache has no fresh entry. The context's `background` field is `true` during a stale-while-revalidate refresh.
+ * @returns The data and the cache status.
+ */
+<T extends SerializableCacheValue>(options: RunWithCacheOptions, run: RunCallback<T>) => Promise<RunWithCacheResult<T>>;
+/**
+ * Creates a function that caches the result of any async work, such as data that several API calls
+ * produce together. For a single fetch response, use `createFetchWithCache`.
+ *
+ * @param options - The cache, and the function that keeps the runtime alive for background cache writes.
+ * @returns A function that returns cached data or runs your callback, and reports the cache status.
+ * @publicDocs
+ */
 declare function createRunWithCache({
   cache,
   waitUntil

package/dist/development/core/cache/run-with-cache.mjs

@@ -9,11 +9,19 @@ import { createNormalizedCacheStore } from "./store.mjs";
 * catches refresh failures, but it should not hide intentional bypasses.
 */
 var StaleFallbackDisabledError = class extends Error {};
+/**
+* Creates a function that caches the result of any async work, such as data that several API calls
+* produce together. For a single fetch response, use `createFetchWithCache`.
+*
+* @param options - The cache, and the function that keeps the runtime alive for background cache writes.
+* @returns A function that returns cached data or runs your callback, and reports the cache status.
+* @publicDocs
+*/
 function createRunWithCache({ cache, waitUntil }) {
 	const store = createNormalizedCacheStore(cache);
 	return async function runWithCache(options, run) {
 		if (options.strategy.mode === "no-store") return {
-			data: (await runAndValidate(run)).data,
+			data: (await runAndValidate(run, { background: false })).data,
 			cacheStatus: "bypass"
 		};
 		const cacheKey = await hashCacheKey(options.key);
@@ -39,7 +47,10 @@ function createRunWithCache({ cache, waitUntil }) {
 		return runAndMaybeStore(cacheKey, options, run).result;
 	};
 	function revalidateInBackground(cacheKey, options, run) {
-		schedule(runAndMaybeStore(cacheKey, options, run, { scheduleCacheWrite: false }).complete);
+		schedule(runAndMaybeStore(cacheKey, options, run, {
+			scheduleCacheWrite: false,
+			background: true
+		}).complete);
 	}
 	async function refreshWithStaleFallback(cacheKey, staleValue, options, run) {
 		try {
@@ -52,10 +63,10 @@ function createRunWithCache({ cache, waitUntil }) {
 			};
 		}
 	}
-	function runAndMaybeStore(key, options, run, { scheduleCacheWrite = true } = {}) {
+	function runAndMaybeStore(key, options, run, { scheduleCacheWrite = true, background = false } = {}) {
 		let storePromise = Promise.resolve();
 		const result = Promise.resolve().then(async () => {
-			const decision = await runAndValidate(run);
+			const decision = await runAndValidate(run, { background });
 			if (!shouldStore(options.strategy, decision)) return {
 				data: decision.data,
 				cacheStatus: "miss"
@@ -93,8 +104,8 @@ function shouldStore(strategy, decision) {
 function shouldFallbackToStale(error) {
 	return !(error instanceof StaleFallbackDisabledError);
 }
-async function runAndValidate(run) {
-	const decision = await run();
+async function runAndValidate(run, context) {
+	const decision = await run(context);
 	if (typeof decision !== "object" || decision == null || !("data" in decision) || !("shouldCache" in decision) || typeof decision.shouldCache !== "boolean") throw new TypeError("runWithCache callback must return {data, shouldCache}.");
 	return decision;
 }

package/dist/development/core/cache/run-with-cache.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run-with-cache.mjs","names":[],"sources":["../../../../src/core/cache/run-with-cache.ts"],"sourcesContent":["import { hashCacheKey, type CacheKey } from \"./key\";\nimport {\n  type CacheEnvelope,\n  type KeyValueCacheLike,\n  type SerializableCacheValue,\n  type WebCacheLike,\n  createNormalizedCacheStore,\n} from \"./store\";\nimport { NO_STORE, type CachingStrategy, getCacheRetentionTtl } from \"./strategies\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\nexport type WaitUntil = (promise: Promise<unknown>) => void;\n\nexport type CacheInstance = WebCacheLike | KeyValueCacheLike;\n\nexport type CreateRunWithCacheOptions = {\n  cache: CacheInstance;\n  waitUntil?: WaitUntil;\n};\n\nexport type RunWithCacheOptions = {\n  key: CacheKey;\n  strategy: CachingStrategy;\n};\n\nexport type CacheDecision<T extends SerializableCacheValue> = {\n  /**\n   * Must be a JSON-serializable object. The cache store may persist this value\n   * through `JSON.stringify`; nested serializability is the caller's contract.\n   */\n  data: T;\n  shouldCache: boolean;\n};\n\nexport type RunWithCacheResult<T extends SerializableCacheValue> = {\n  data: T;\n  cacheStatus: \"hit\" | \"miss\" | \"bypass\";\n};\n\nexport type RunWithCache = <T extends SerializableCacheValue>(\n  options: RunWithCacheOptions,\n  run: () => MaybePromise<CacheDecision<T>>,\n) => Promise<RunWithCacheResult<T>>;\n\ntype CacheState = \"fresh\" | \"stale\" | \"stale-if-error\" | \"expired\";\n\n/**\n * `result` resolves as soon as user data is available; `complete` also waits for\n * any cache write so background revalidation can be scheduled as one operation.\n */\ntype CacheOperation<T extends SerializableCacheValue = SerializableCacheValue> = {\n  result: Promise<RunWithCacheResult<T>>;\n  complete: Promise<void>;\n};\n\ntype RunAndMaybeStoreOptions = {\n  scheduleCacheWrite?: boolean;\n};\n\n/**\n * Internal control-flow error for adapters that need to escape the cache\n * pipeline without being interpreted as an origin failure. `staleIfError`\n * catches refresh failures, but it should not hide intentional bypasses.\n */\nexport class StaleFallbackDisabledError extends Error {}\n\nexport function createRunWithCache({ cache, waitUntil }: CreateRunWithCacheOptions): RunWithCache {\n  const store = createNormalizedCacheStore(cache);\n\n  return async function runWithCache<T extends SerializableCacheValue>(\n    options: RunWithCacheOptions,\n    run: () => MaybePromise<CacheDecision<T>>,\n  ): Promise<RunWithCacheResult<T>> {\n    if (options.strategy.mode === NO_STORE) {\n      return { data: (await runAndValidate(run)).data, cacheStatus: \"bypass\" };\n    }\n\n    const cacheKey = await hashCacheKey(options.key);\n\n    let cached: CacheEnvelope<T> | undefined;\n\n    try {\n      cached = await store.get<T>(cacheKey);\n    } catch {}\n\n    if (cached) {\n      const state = getCacheState(cached, options.strategy);\n\n      if (state === \"fresh\") return { data: cached.value, cacheStatus: \"hit\" };\n\n      if (state === \"stale\") {\n        revalidateInBackground(cacheKey, options, run);\n        return { data: cached.value, cacheStatus: \"hit\" };\n      }\n\n      if (state === \"stale-if-error\") {\n        return refreshWithStaleFallback(cacheKey, cached.value, options, run);\n      }\n    }\n\n    return runAndMaybeStore(cacheKey, options, run).result;\n  };\n\n  function revalidateInBackground<T extends SerializableCacheValue>(\n    cacheKey: string,\n    options: RunWithCacheOptions,\n    run: () => MaybePromise<CacheDecision<T>>,\n  ) {\n    const entry = runAndMaybeStore(cacheKey, options, run, { scheduleCacheWrite: false });\n    schedule(entry.complete);\n  }\n\n  async function refreshWithStaleFallback<T extends SerializableCacheValue>(\n    cacheKey: string,\n    staleValue: T,\n    options: RunWithCacheOptions,\n    run: () => MaybePromise<CacheDecision<T>>,\n  ): Promise<RunWithCacheResult<T>> {\n    try {\n      return await runAndMaybeStore(cacheKey, options, run).result;\n    } catch (error) {\n      if (!shouldFallbackToStale(error)) throw error;\n\n      return { data: staleValue, cacheStatus: \"hit\" };\n    }\n  }\n\n  function runAndMaybeStore<T extends SerializableCacheValue>(\n    key: string,\n    options: RunWithCacheOptions,\n    run: () => MaybePromise<CacheDecision<T>>,\n    { scheduleCacheWrite = true }: RunAndMaybeStoreOptions = {},\n  ): CacheOperation<T> {\n    // Assigned inside `result` once the callback has produced cacheable data.\n    // `complete` reads the same variable later, so it follows the actual write\n    // without making the foreground result wait when waitUntil is available.\n    let storePromise: Promise<void> = Promise.resolve();\n\n    const result = Promise.resolve().then(async (): Promise<RunWithCacheResult<T>> => {\n      const decision = await runAndValidate(run);\n      if (!shouldStore(options.strategy, decision)) {\n        return { data: decision.data, cacheStatus: \"miss\" };\n      }\n\n      storePromise = storeDecision(key, options, decision).catch(() => {});\n\n      if (waitUntil && scheduleCacheWrite) {\n        schedule(storePromise);\n      } else if (!waitUntil) {\n        await storePromise;\n      }\n\n      return { data: decision.data, cacheStatus: \"miss\" };\n    });\n\n    return {\n      result,\n      complete: result\n        .then(\n          () => storePromise,\n          () => undefined,\n        )\n        .then(() => undefined),\n    };\n  }\n\n  async function storeDecision<T extends SerializableCacheValue>(\n    key: string,\n    options: RunWithCacheOptions,\n    decision: CacheDecision<T>,\n  ) {\n    await store.set(\n      key,\n      {\n        version: 1,\n        value: decision.data,\n        storedAt: Date.now(),\n        strategy: options.strategy,\n      },\n      {\n        strategy: options.strategy,\n      },\n    );\n  }\n\n  function schedule(promise: Promise<unknown>) {\n    try {\n      waitUntil?.(promise);\n    } catch {}\n  }\n}\n\nfunction shouldStore<T extends SerializableCacheValue>(\n  strategy: CachingStrategy,\n  decision: CacheDecision<T>,\n): boolean {\n  return decision.shouldCache && getCacheRetentionTtl(strategy) > 0;\n}\n\nfunction shouldFallbackToStale(error: unknown): boolean {\n  return !(error instanceof StaleFallbackDisabledError);\n}\n\nasync function runAndValidate<T extends SerializableCacheValue>(\n  run: () => MaybePromise<CacheDecision<T>>,\n): Promise<CacheDecision<T>> {\n  const decision = await run();\n\n  if (\n    typeof decision !== \"object\" ||\n    decision == null ||\n    !(\"data\" in decision) ||\n    !(\"shouldCache\" in decision) ||\n    typeof decision.shouldCache !== \"boolean\"\n  ) {\n    throw new TypeError(\"runWithCache callback must return {data, shouldCache}.\");\n  }\n\n  return decision;\n}\n\nfunction getCacheState<T extends SerializableCacheValue>(\n  envelope: CacheEnvelope<T>,\n  strategy: CachingStrategy,\n): CacheState {\n  const age = Math.max(0, (Date.now() - envelope.storedAt) / 1000);\n  const maxAge = strategy.maxAge ?? 0;\n  const staleWhileRevalidate = strategy.staleWhileRevalidate ?? 0;\n  const staleIfError = strategy.staleIfError ?? 0;\n\n  if (age <= maxAge) return \"fresh\";\n  if (age <= maxAge + staleWhileRevalidate) return \"stale\";\n  if (age <= maxAge + staleWhileRevalidate + staleIfError) {\n    return \"stale-if-error\";\n  }\n\n  return \"expired\";\n}\n"],"mappings":"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"}
+{"version":3,"file":"run-with-cache.mjs","names":[],"sources":["../../../../src/core/cache/run-with-cache.ts"],"sourcesContent":["import { hashCacheKey, type CacheKey } from \"./key\";\nimport {\n  type CacheEnvelope,\n  type KeyValueCacheLike,\n  type SerializableCacheValue,\n  type WebCacheLike,\n  createNormalizedCacheStore,\n} from \"./store\";\nimport { NO_STORE, type CachingStrategy, getCacheRetentionTtl } from \"./strategies\";\n\n/** A value, or a promise that resolves to the value. */\ntype MaybePromise<T> = T | Promise<T>;\n\n/**\n * Keeps the runtime alive until a background cache write or refresh finishes, such as a worker's `waitUntil` function. Hydrogen ignores errors that the function throws.\n */\nexport type WaitUntil =\n  /**\n   * @param promise - The background cache write or refresh to wait for.\n   * @returns Nothing. Hydrogen ignores the return value.\n   */\n  (promise: Promise<unknown>) => void;\n\n/** The cache that holds entries, either a Web Cache API cache or a key-value store. */\nexport type CacheInstance = WebCacheLike | KeyValueCacheLike;\n\n/** The cache and the background-work function for `createRunWithCache`. */\nexport type CreateRunWithCacheOptions = {\n  /** The cache that holds entries. `createRunWithCache` throws a `TypeError` when the cache is neither a Web Cache API cache nor a key-value store. */\n  cache: CacheInstance;\n  /**\n   * Keeps the runtime alive for background cache writes and refreshes. Without `waitUntil`, each call waits for its cache write before it resolves.\n   */\n  waitUntil?: WaitUntil;\n};\n\n/** Options for one cached run. */\nexport type RunWithCacheOptions = {\n  /**\n   * Identifies the cache entry. `runWithCache` throws a `TypeError` for an array key with empty slots or with entries other than strings, numbers, booleans, and `null`.\n   */\n  key: CacheKey;\n  /** Sets how long the result stays fresh, how long the cache serves it stale while refreshing it, and how long the cache serves it stale after an error. */\n  strategy: CachingStrategy;\n};\n\n/** The callback's return value, with the data and whether to cache the data. */\nexport type CacheDecision<T extends SerializableCacheValue> = {\n  /**\n   * The data to return and cache. Web Cache stores save the data as JSON.\n   */\n  data: T;\n  /** Set to `false` to return the data without storing it. */\n  shouldCache: boolean;\n};\n\n/** The data, and whether the data came from the cache or the callback. */\nexport type RunWithCacheResult<T extends SerializableCacheValue> = {\n  /** The cached data on a hit, or the callback's data otherwise. */\n  data: T;\n  /** `hit` when the data comes from the cache, `miss` when the callback runs, and `bypass` for a `no-store` strategy. */\n  cacheStatus: \"hit\" | \"miss\" | \"bypass\";\n};\n\n/** The context that `runWithCache` passes to its callback. */\nexport type RunWithCacheContext = {\n  /** `true` when the callback refreshes a stale entry after the cache already returned the stale value. */\n  background: boolean;\n};\n\n// The context is optional so custom runners that call `run()` keep working.\n/** Produces the data for a cached run and decides whether to cache the data. */\ntype RunCallback<T extends SerializableCacheValue> =\n  /**\n   * @param context - Tells the callback whether it refreshes a stale entry in the background.\n   * @returns The data and whether to cache the data, or a promise that resolves to both.\n   */\n  (context?: RunWithCacheContext) => MaybePromise<CacheDecision<T>>;\n\n/**\n * Returns cached data for the key, or runs the callback and caches the result. Resolves with the\n * data and the cache status.\n */\nexport type RunWithCache =\n  /**\n   * @param options - The cache key and caching strategy for this call.\n   * @param run - Produces the data and decides whether to cache it. Runs whenever the cache has no fresh entry. The context's `background` field is `true` during a stale-while-revalidate refresh.\n   * @returns The data and the cache status.\n   */\n  <T extends SerializableCacheValue>(\n    options: RunWithCacheOptions,\n    run: RunCallback<T>,\n  ) => Promise<RunWithCacheResult<T>>;\n\ntype CacheState = \"fresh\" | \"stale\" | \"stale-if-error\" | \"expired\";\n\n/**\n * `result` resolves as soon as user data is available; `complete` also waits for\n * any cache write so background revalidation can be scheduled as one operation.\n */\ntype CacheOperation<T extends SerializableCacheValue = SerializableCacheValue> = {\n  result: Promise<RunWithCacheResult<T>>;\n  complete: Promise<void>;\n};\n\ntype RunAndMaybeStoreOptions = {\n  scheduleCacheWrite?: boolean;\n  background?: boolean;\n};\n\n/**\n * Internal control-flow error for adapters that need to escape the cache\n * pipeline without being interpreted as an origin failure. `staleIfError`\n * catches refresh failures, but it should not hide intentional bypasses.\n */\nexport class StaleFallbackDisabledError extends Error {}\n\n/**\n * Creates a function that caches the result of any async work, such as data that several API calls\n * produce together. For a single fetch response, use `createFetchWithCache`.\n *\n * @param options - The cache, and the function that keeps the runtime alive for background cache writes.\n * @returns A function that returns cached data or runs your callback, and reports the cache status.\n * @publicDocs\n */\nexport function createRunWithCache({ cache, waitUntil }: CreateRunWithCacheOptions): RunWithCache {\n  const store = createNormalizedCacheStore(cache);\n\n  return async function runWithCache<T extends SerializableCacheValue>(\n    options: RunWithCacheOptions,\n    run: RunCallback<T>,\n  ): Promise<RunWithCacheResult<T>> {\n    if (options.strategy.mode === NO_STORE) {\n      return {\n        data: (await runAndValidate(run, { background: false })).data,\n        cacheStatus: \"bypass\",\n      };\n    }\n\n    const cacheKey = await hashCacheKey(options.key);\n\n    let cached: CacheEnvelope<T> | undefined;\n\n    try {\n      cached = await store.get<T>(cacheKey);\n    } catch {}\n\n    if (cached) {\n      const state = getCacheState(cached, options.strategy);\n\n      if (state === \"fresh\") return { data: cached.value, cacheStatus: \"hit\" };\n\n      if (state === \"stale\") {\n        revalidateInBackground(cacheKey, options, run);\n        return { data: cached.value, cacheStatus: \"hit\" };\n      }\n\n      if (state === \"stale-if-error\") {\n        return refreshWithStaleFallback(cacheKey, cached.value, options, run);\n      }\n    }\n\n    return runAndMaybeStore(cacheKey, options, run).result;\n  };\n\n  function revalidateInBackground<T extends SerializableCacheValue>(\n    cacheKey: string,\n    options: RunWithCacheOptions,\n    run: RunCallback<T>,\n  ) {\n    const entry = runAndMaybeStore(cacheKey, options, run, {\n      scheduleCacheWrite: false,\n      background: true,\n    });\n    schedule(entry.complete);\n  }\n\n  async function refreshWithStaleFallback<T extends SerializableCacheValue>(\n    cacheKey: string,\n    staleValue: T,\n    options: RunWithCacheOptions,\n    run: RunCallback<T>,\n  ): Promise<RunWithCacheResult<T>> {\n    try {\n      return await runAndMaybeStore(cacheKey, options, run).result;\n    } catch (error) {\n      if (!shouldFallbackToStale(error)) throw error;\n\n      return { data: staleValue, cacheStatus: \"hit\" };\n    }\n  }\n\n  function runAndMaybeStore<T extends SerializableCacheValue>(\n    key: string,\n    options: RunWithCacheOptions,\n    run: RunCallback<T>,\n    { scheduleCacheWrite = true, background = false }: RunAndMaybeStoreOptions = {},\n  ): CacheOperation<T> {\n    // Assigned inside `result` once the callback has produced cacheable data.\n    // `complete` reads the same variable later, so it follows the actual write\n    // without making the foreground result wait when waitUntil is available.\n    let storePromise: Promise<void> = Promise.resolve();\n\n    const result = Promise.resolve().then(async (): Promise<RunWithCacheResult<T>> => {\n      const decision = await runAndValidate(run, { background });\n      if (!shouldStore(options.strategy, decision)) {\n        return { data: decision.data, cacheStatus: \"miss\" };\n      }\n\n      storePromise = storeDecision(key, options, decision).catch(() => {});\n\n      if (waitUntil && scheduleCacheWrite) {\n        schedule(storePromise);\n      } else if (!waitUntil) {\n        await storePromise;\n      }\n\n      return { data: decision.data, cacheStatus: \"miss\" };\n    });\n\n    return {\n      result,\n      complete: result\n        .then(\n          () => storePromise,\n          () => undefined,\n        )\n        .then(() => undefined),\n    };\n  }\n\n  async function storeDecision<T extends SerializableCacheValue>(\n    key: string,\n    options: RunWithCacheOptions,\n    decision: CacheDecision<T>,\n  ) {\n    await store.set(\n      key,\n      {\n        version: 1,\n        value: decision.data,\n        storedAt: Date.now(),\n        strategy: options.strategy,\n      },\n      {\n        strategy: options.strategy,\n      },\n    );\n  }\n\n  function schedule(promise: Promise<unknown>) {\n    try {\n      waitUntil?.(promise);\n    } catch {}\n  }\n}\n\nfunction shouldStore<T extends SerializableCacheValue>(\n  strategy: CachingStrategy,\n  decision: CacheDecision<T>,\n): boolean {\n  return decision.shouldCache && getCacheRetentionTtl(strategy) > 0;\n}\n\nfunction shouldFallbackToStale(error: unknown): boolean {\n  return !(error instanceof StaleFallbackDisabledError);\n}\n\nasync function runAndValidate<T extends SerializableCacheValue>(\n  run: RunCallback<T>,\n  context: RunWithCacheContext,\n): Promise<CacheDecision<T>> {\n  const decision = await run(context);\n\n  if (\n    typeof decision !== \"object\" ||\n    decision == null ||\n    !(\"data\" in decision) ||\n    !(\"shouldCache\" in decision) ||\n    typeof decision.shouldCache !== \"boolean\"\n  ) {\n    throw new TypeError(\"runWithCache callback must return {data, shouldCache}.\");\n  }\n\n  return decision;\n}\n\nfunction getCacheState<T extends SerializableCacheValue>(\n  envelope: CacheEnvelope<T>,\n  strategy: CachingStrategy,\n): CacheState {\n  const age = Math.max(0, (Date.now() - envelope.storedAt) / 1000);\n  const maxAge = strategy.maxAge ?? 0;\n  const staleWhileRevalidate = strategy.staleWhileRevalidate ?? 0;\n  const staleIfError = strategy.staleIfError ?? 0;\n\n  if (age <= maxAge) return \"fresh\";\n  if (age <= maxAge + staleWhileRevalidate) return \"stale\";\n  if (age <= maxAge + staleWhileRevalidate + staleIfError) {\n    return \"stale-if-error\";\n  }\n\n  return \"expired\";\n}\n\n/**\n * Returns cached data for the key, or runs the callback and caches the result.\n *\n * The callback returns an object with `data` and a boolean `shouldCache`. The function throws a `TypeError` for any other shape. During the `staleWhileRevalidate` window, the function returns the stale data right away and runs the callback in the background. During the `staleIfError` window, the function returns the stale data when the callback throws. A `no-store` strategy runs the callback and skips the cache.\n *\n * @publicDocs\n */\nexport type RunWithCacheForDocs =\n  /**\n   * @param options - The cache key and caching strategy for this call.\n   * @param run - Produces the data and decides whether to cache it. Runs whenever the cache has no fresh entry.\n   * @returns The data, and whether the data came from the cache, the callback, or a bypass.\n   */\n  (\n    options: RunWithCacheOptions,\n    run: () => MaybePromise<CacheDecision<SerializableCacheValue>>,\n  ) => Promise<RunWithCacheResult<SerializableCacheValue>>;\n"],"mappings":"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"}

package/dist/development/core/cache/store.d.mts

@@ -1,17 +1,19 @@
 //#region src/core/cache/store.d.ts
 /**
- * Cache values must be JSON-serializable because Web Cache stores serialize
- * envelopes before persistence. Callers are responsible for returning data that
- * can safely round-trip through `JSON.stringify`.
+ * The plain object that you cache. Web Cache stores save the object as JSON. Return data that
+ * survives a round trip through `JSON.stringify`.
  */
 type SerializableCacheValue = Record<string, unknown>;
+/** A cache with the `match()`, `put()`, and `delete()` methods of the Web Cache API, such as a cache from `caches.open()`. */
 type WebCacheLike = Pick<Cache, "match" | "put" | "delete">;
+/** Options that Hydrogen passes when it writes an entry to a key-value store. */
 type KeyValueCacheSetOptions = {
-  ttl?: number;
+  /** How many seconds to keep the entry. Hydrogen passes the sum of the strategy's `maxAge`, `staleWhileRevalidate`, and `staleIfError`, rounded up. */ttl?: number;
 };
+/** A key-value store with `get()`, `set()`, and an optional `delete()` method. Hydrogen passes each entry to `set()` as an object. Serialize the object in your store when the store saves only strings. */
 type KeyValueCacheLike = {
-  get(key: string): unknown | Promise<unknown>;
-  set(key: string, value: unknown, options?: KeyValueCacheSetOptions): unknown | Promise<unknown>;
+  /** Returns the value under the key. Hydrogen treats a value that it didn't write as a cache miss. */get(key: string): unknown | Promise<unknown>; /** Saves the value under the key. Expire the entry after the `ttl` option, in seconds. */
+  set(key: string, value: unknown, options?: KeyValueCacheSetOptions): unknown | Promise<unknown>; /** Removes the value under the key. */
   delete?(key: string): unknown | Promise<unknown>;
 };
 //#endregion

package/dist/development/core/cache/store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"store.mjs","names":[],"sources":["../../../../src/core/cache/store.ts"],"sourcesContent":["import {\n  type CachingStrategy,\n  getPlatformCacheControlHeader,\n  getCacheRetentionTtl,\n} from \"./strategies\";\n\n/**\n * Cache values must be JSON-serializable because Web Cache stores serialize\n * envelopes before persistence. Callers are responsible for returning data that\n * can safely round-trip through `JSON.stringify`.\n */\nexport type SerializableCacheValue = Record<string, unknown>;\n\nexport type CacheEnvelope<T extends SerializableCacheValue = SerializableCacheValue> = {\n  version: 1;\n  value: T;\n  storedAt: number;\n  strategy: CachingStrategy;\n};\n\nexport type WebCacheLike = Pick<Cache, \"match\" | \"put\" | \"delete\">;\n\nexport type KeyValueCacheSetOptions = {\n  ttl?: number;\n};\n\nexport type KeyValueCacheLike = {\n  get(key: string): unknown | Promise<unknown>;\n  set(key: string, value: unknown, options?: KeyValueCacheSetOptions): unknown | Promise<unknown>;\n  delete?(key: string): unknown | Promise<unknown>;\n};\n\ntype NormalizedCacheStore = {\n  get<T extends SerializableCacheValue>(key: string): Promise<CacheEnvelope<T> | undefined>;\n  set<T extends SerializableCacheValue>(\n    key: string,\n    envelope: CacheEnvelope<T>,\n    options: NormalizedCacheSetOptions,\n  ): Promise<void>;\n  delete?(key: string): Promise<void>;\n};\n\ntype NormalizedCacheSetOptions = {\n  strategy: CachingStrategy;\n};\n\nexport function createNormalizedCacheStore(\n  cache: WebCacheLike | KeyValueCacheLike,\n): NormalizedCacheStore {\n  if (isWebCacheLike(cache)) return createWebCacheStore(cache);\n  if (isKeyValueCacheLike(cache)) return createKeyValueCacheStore(cache);\n\n  throw new TypeError(\"Expected a Web Cache API compatible store or a key/value cache store.\");\n}\n\nfunction createWebCacheStore(cache: WebCacheLike): NormalizedCacheStore {\n  return {\n    async get<T extends SerializableCacheValue>(key: string) {\n      const response = await cache.match(createCacheRequest(key));\n      if (!response) return undefined;\n\n      const envelope: unknown = JSON.parse(await response.text());\n      return isCacheEnvelope<T>(envelope) ? envelope : undefined;\n    },\n\n    async set<T extends SerializableCacheValue>(\n      key: string,\n      envelope: CacheEnvelope<T>,\n      { strategy }: NormalizedCacheSetOptions,\n    ) {\n      const response = new Response(JSON.stringify(envelope), {\n        headers: {\n          \"cache-control\": getPlatformCacheControlHeader(strategy),\n          \"content-type\": \"application/json\",\n        },\n      });\n\n      await cache.put(createCacheRequest(key), response);\n    },\n\n    async delete(key) {\n      await cache.delete(createCacheRequest(key));\n    },\n  };\n}\n\nfunction createKeyValueCacheStore(cache: KeyValueCacheLike): NormalizedCacheStore {\n  return {\n    async get<T extends SerializableCacheValue>(key: string) {\n      const envelope = await cache.get(key);\n      return isCacheEnvelope<T>(envelope) ? envelope : undefined;\n    },\n\n    async set<T extends SerializableCacheValue>(\n      key: string,\n      envelope: CacheEnvelope<T>,\n      { strategy }: NormalizedCacheSetOptions,\n    ) {\n      const ttl = Math.ceil(getCacheRetentionTtl(strategy));\n\n      await cache.set(key, envelope, { ttl });\n    },\n\n    async delete(key) {\n      await cache.delete?.(key);\n    },\n  };\n}\n\nfunction createCacheRequest(key: string) {\n  return new Request(`https://hydrogen.cache/${key}`);\n}\n\nfunction isWebCacheLike(cache: unknown): cache is WebCacheLike {\n  return (\n    typeof cache === \"object\" &&\n    cache != null &&\n    \"match\" in cache &&\n    \"put\" in cache &&\n    typeof cache.match === \"function\" &&\n    typeof cache.put === \"function\"\n  );\n}\n\nfunction isKeyValueCacheLike(cache: unknown): cache is KeyValueCacheLike {\n  return (\n    typeof cache === \"object\" &&\n    cache != null &&\n    \"get\" in cache &&\n    \"set\" in cache &&\n    typeof cache.get === \"function\" &&\n    typeof cache.set === \"function\"\n  );\n}\n\nfunction isCacheEnvelope<T extends SerializableCacheValue>(\n  value: unknown,\n): value is CacheEnvelope<T> {\n  return (\n    typeof value === \"object\" &&\n    value != null &&\n    \"version\" in value &&\n    value.version === 1 &&\n    \"storedAt\" in value &&\n    typeof value.storedAt === \"number\" &&\n    // Freshness uses the call-site strategy, but stored envelopes should still\n    // look like the current shape so older or malformed entries do not become hits.\n    \"strategy\" in value &&\n    Boolean(value.strategy) &&\n    \"value\" in value &&\n    isSerializableCacheValue(value.value)\n  );\n}\n\nfunction isSerializableCacheValue(value: unknown): value is SerializableCacheValue {\n  return typeof value === \"object\" && value != null && !Array.isArray(value);\n}\n"],"mappings":";;;AA8CA,SAAgB,2BACd,OACsB;AACtB,KAAI,eAAe,MAAM,CAAE,QAAO,oBAAoB,MAAM;AAC5D,KAAI,oBAAoB,MAAM,CAAE,QAAO,yBAAyB,MAAM;AAEtE,OAAM,IAAI,UAAU,wEAAwE;;AAG9F,SAAS,oBAAoB,OAA2C;AACtE,QAAO;EACL,MAAM,IAAsC,KAAa;GACvD,MAAM,WAAW,MAAM,MAAM,MAAM,mBAAmB,IAAI,CAAC;AAC3D,OAAI,CAAC,SAAU,QAAO;GAEtB,MAAM,WAAoB,KAAK,MAAM,MAAM,SAAS,MAAM,CAAC;AAC3D,UAAO,gBAAmB,SAAS,GAAG,WAAW;;EAGnD,MAAM,IACJ,KACA,UACA,EAAE,YACF;GACA,MAAM,WAAW,IAAI,SAAS,KAAK,UAAU,SAAS,EAAE,EACtD,SAAS;IACP,iBAAiB,8BAA8B,SAAS;IACxD,gBAAgB;IACjB,EACF,CAAC;AAEF,SAAM,MAAM,IAAI,mBAAmB,IAAI,EAAE,SAAS;;EAGpD,MAAM,OAAO,KAAK;AAChB,SAAM,MAAM,OAAO,mBAAmB,IAAI,CAAC;;EAE9C;;AAGH,SAAS,yBAAyB,OAAgD;AAChF,QAAO;EACL,MAAM,IAAsC,KAAa;GACvD,MAAM,WAAW,MAAM,MAAM,IAAI,IAAI;AACrC,UAAO,gBAAmB,SAAS,GAAG,WAAW;;EAGnD,MAAM,IACJ,KACA,UACA,EAAE,YACF;GACA,MAAM,MAAM,KAAK,KAAK,qBAAqB,SAAS,CAAC;AAErD,SAAM,MAAM,IAAI,KAAK,UAAU,EAAE,KAAK,CAAC;;EAGzC,MAAM,OAAO,KAAK;AAChB,SAAM,MAAM,SAAS,IAAI;;EAE5B;;AAGH,SAAS,mBAAmB,KAAa;AACvC,QAAO,IAAI,QAAQ,0BAA0B,MAAM;;AAGrD,SAAS,eAAe,OAAuC;AAC7D,QACE,OAAO,UAAU,YACjB,SAAS,QACT,WAAW,SACX,SAAS,SACT,OAAO,MAAM,UAAU,cACvB,OAAO,MAAM,QAAQ;;AAIzB,SAAS,oBAAoB,OAA4C;AACvE,QACE,OAAO,UAAU,YACjB,SAAS,QACT,SAAS,SACT,SAAS,SACT,OAAO,MAAM,QAAQ,cACrB,OAAO,MAAM,QAAQ;;AAIzB,SAAS,gBACP,OAC2B;AAC3B,QACE,OAAO,UAAU,YACjB,SAAS,QACT,aAAa,SACb,MAAM,YAAY,KAClB,cAAc,SACd,OAAO,MAAM,aAAa,YAG1B,cAAc,SACd,QAAQ,MAAM,SAAS,IACvB,WAAW,SACX,yBAAyB,MAAM,MAAM;;AAIzC,SAAS,yBAAyB,OAAiD;AACjF,QAAO,OAAO,UAAU,YAAY,SAAS,QAAQ,CAAC,MAAM,QAAQ,MAAM"}
+{"version":3,"file":"store.mjs","names":[],"sources":["../../../../src/core/cache/store.ts"],"sourcesContent":["import {\n  type CachingStrategy,\n  getPlatformCacheControlHeader,\n  getCacheRetentionTtl,\n} from \"./strategies\";\n\n/**\n * The plain object that you cache. Web Cache stores save the object as JSON. Return data that\n * survives a round trip through `JSON.stringify`.\n */\nexport type SerializableCacheValue = Record<string, unknown>;\n\nexport type CacheEnvelope<T extends SerializableCacheValue = SerializableCacheValue> = {\n  version: 1;\n  value: T;\n  storedAt: number;\n  strategy: CachingStrategy;\n};\n\n/** A cache with the `match()`, `put()`, and `delete()` methods of the Web Cache API, such as a cache from `caches.open()`. */\nexport type WebCacheLike = Pick<Cache, \"match\" | \"put\" | \"delete\">;\n\n/** Options that Hydrogen passes when it writes an entry to a key-value store. */\nexport type KeyValueCacheSetOptions = {\n  /** How many seconds to keep the entry. Hydrogen passes the sum of the strategy's `maxAge`, `staleWhileRevalidate`, and `staleIfError`, rounded up. */\n  ttl?: number;\n};\n\n/** A key-value store with `get()`, `set()`, and an optional `delete()` method. Hydrogen passes each entry to `set()` as an object. Serialize the object in your store when the store saves only strings. */\nexport type KeyValueCacheLike = {\n  /** Returns the value under the key. Hydrogen treats a value that it didn't write as a cache miss. */\n  get(key: string): unknown | Promise<unknown>;\n  /** Saves the value under the key. Expire the entry after the `ttl` option, in seconds. */\n  set(key: string, value: unknown, options?: KeyValueCacheSetOptions): unknown | Promise<unknown>;\n  /** Removes the value under the key. */\n  delete?(key: string): unknown | Promise<unknown>;\n};\n\ntype NormalizedCacheStore = {\n  get<T extends SerializableCacheValue>(key: string): Promise<CacheEnvelope<T> | undefined>;\n  set<T extends SerializableCacheValue>(\n    key: string,\n    envelope: CacheEnvelope<T>,\n    options: NormalizedCacheSetOptions,\n  ): Promise<void>;\n  delete?(key: string): Promise<void>;\n};\n\ntype NormalizedCacheSetOptions = {\n  strategy: CachingStrategy;\n};\n\nexport function createNormalizedCacheStore(\n  cache: WebCacheLike | KeyValueCacheLike,\n): NormalizedCacheStore {\n  if (isWebCacheLike(cache)) return createWebCacheStore(cache);\n  if (isKeyValueCacheLike(cache)) return createKeyValueCacheStore(cache);\n\n  throw new TypeError(\"Expected a Web Cache API compatible store or a key/value cache store.\");\n}\n\nfunction createWebCacheStore(cache: WebCacheLike): NormalizedCacheStore {\n  return {\n    async get<T extends SerializableCacheValue>(key: string) {\n      const response = await cache.match(createCacheRequest(key));\n      if (!response) return undefined;\n\n      const envelope: unknown = JSON.parse(await response.text());\n      return isCacheEnvelope<T>(envelope) ? envelope : undefined;\n    },\n\n    async set<T extends SerializableCacheValue>(\n      key: string,\n      envelope: CacheEnvelope<T>,\n      { strategy }: NormalizedCacheSetOptions,\n    ) {\n      const response = new Response(JSON.stringify(envelope), {\n        headers: {\n          \"cache-control\": getPlatformCacheControlHeader(strategy),\n          \"content-type\": \"application/json\",\n        },\n      });\n\n      await cache.put(createCacheRequest(key), response);\n    },\n\n    async delete(key) {\n      await cache.delete(createCacheRequest(key));\n    },\n  };\n}\n\nfunction createKeyValueCacheStore(cache: KeyValueCacheLike): NormalizedCacheStore {\n  return {\n    async get<T extends SerializableCacheValue>(key: string) {\n      const envelope = await cache.get(key);\n      return isCacheEnvelope<T>(envelope) ? envelope : undefined;\n    },\n\n    async set<T extends SerializableCacheValue>(\n      key: string,\n      envelope: CacheEnvelope<T>,\n      { strategy }: NormalizedCacheSetOptions,\n    ) {\n      const ttl = Math.ceil(getCacheRetentionTtl(strategy));\n\n      await cache.set(key, envelope, { ttl });\n    },\n\n    async delete(key) {\n      await cache.delete?.(key);\n    },\n  };\n}\n\nfunction createCacheRequest(key: string) {\n  return new Request(`https://hydrogen.cache/${key}`);\n}\n\nfunction isWebCacheLike(cache: unknown): cache is WebCacheLike {\n  return (\n    typeof cache === \"object\" &&\n    cache != null &&\n    \"match\" in cache &&\n    \"put\" in cache &&\n    typeof cache.match === \"function\" &&\n    typeof cache.put === \"function\"\n  );\n}\n\nfunction isKeyValueCacheLike(cache: unknown): cache is KeyValueCacheLike {\n  return (\n    typeof cache === \"object\" &&\n    cache != null &&\n    \"get\" in cache &&\n    \"set\" in cache &&\n    typeof cache.get === \"function\" &&\n    typeof cache.set === \"function\"\n  );\n}\n\nfunction isCacheEnvelope<T extends SerializableCacheValue>(\n  value: unknown,\n): value is CacheEnvelope<T> {\n  return (\n    typeof value === \"object\" &&\n    value != null &&\n    \"version\" in value &&\n    value.version === 1 &&\n    \"storedAt\" in value &&\n    typeof value.storedAt === \"number\" &&\n    // Freshness uses the call-site strategy, but stored envelopes should still\n    // look like the current shape so older or malformed entries do not become hits.\n    \"strategy\" in value &&\n    Boolean(value.strategy) &&\n    \"value\" in value &&\n    isSerializableCacheValue(value.value)\n  );\n}\n\nfunction isSerializableCacheValue(value: unknown): value is SerializableCacheValue {\n  return typeof value === \"object\" && value != null && !Array.isArray(value);\n}\n"],"mappings":";;;AAoDA,SAAgB,2BACd,OACsB;AACtB,KAAI,eAAe,MAAM,CAAE,QAAO,oBAAoB,MAAM;AAC5D,KAAI,oBAAoB,MAAM,CAAE,QAAO,yBAAyB,MAAM;AAEtE,OAAM,IAAI,UAAU,wEAAwE;;AAG9F,SAAS,oBAAoB,OAA2C;AACtE,QAAO;EACL,MAAM,IAAsC,KAAa;GACvD,MAAM,WAAW,MAAM,MAAM,MAAM,mBAAmB,IAAI,CAAC;AAC3D,OAAI,CAAC,SAAU,QAAO;GAEtB,MAAM,WAAoB,KAAK,MAAM,MAAM,SAAS,MAAM,CAAC;AAC3D,UAAO,gBAAmB,SAAS,GAAG,WAAW;;EAGnD,MAAM,IACJ,KACA,UACA,EAAE,YACF;GACA,MAAM,WAAW,IAAI,SAAS,KAAK,UAAU,SAAS,EAAE,EACtD,SAAS;IACP,iBAAiB,8BAA8B,SAAS;IACxD,gBAAgB;IACjB,EACF,CAAC;AAEF,SAAM,MAAM,IAAI,mBAAmB,IAAI,EAAE,SAAS;;EAGpD,MAAM,OAAO,KAAK;AAChB,SAAM,MAAM,OAAO,mBAAmB,IAAI,CAAC;;EAE9C;;AAGH,SAAS,yBAAyB,OAAgD;AAChF,QAAO;EACL,MAAM,IAAsC,KAAa;GACvD,MAAM,WAAW,MAAM,MAAM,IAAI,IAAI;AACrC,UAAO,gBAAmB,SAAS,GAAG,WAAW;;EAGnD,MAAM,IACJ,KACA,UACA,EAAE,YACF;GACA,MAAM,MAAM,KAAK,KAAK,qBAAqB,SAAS,CAAC;AAErD,SAAM,MAAM,IAAI,KAAK,UAAU,EAAE,KAAK,CAAC;;EAGzC,MAAM,OAAO,KAAK;AAChB,SAAM,MAAM,SAAS,IAAI;;EAE5B;;AAGH,SAAS,mBAAmB,KAAa;AACvC,QAAO,IAAI,QAAQ,0BAA0B,MAAM;;AAGrD,SAAS,eAAe,OAAuC;AAC7D,QACE,OAAO,UAAU,YACjB,SAAS,QACT,WAAW,SACX,SAAS,SACT,OAAO,MAAM,UAAU,cACvB,OAAO,MAAM,QAAQ;;AAIzB,SAAS,oBAAoB,OAA4C;AACvE,QACE,OAAO,UAAU,YACjB,SAAS,QACT,SAAS,SACT,SAAS,SACT,OAAO,MAAM,QAAQ,cACrB,OAAO,MAAM,QAAQ;;AAIzB,SAAS,gBACP,OAC2B;AAC3B,QACE,OAAO,UAAU,YACjB,SAAS,QACT,aAAa,SACb,MAAM,YAAY,KAClB,cAAc,SACd,OAAO,MAAM,aAAa,YAG1B,cAAc,SACd,QAAQ,MAAM,SAAS,IACvB,WAAW,SACX,yBAAyB,MAAM,MAAM;;AAIzC,SAAS,yBAAyB,OAAiD;AACjF,QAAO,OAAO,UAAU,YAAY,SAAS,QAAQ,CAAC,MAAM,QAAQ,MAAM"}

package/dist/development/core/cache/strategies.d.mts

@@ -2,29 +2,54 @@
 declare const NO_STORE = "no-store";
 declare const PUBLIC = "public";
 declare const PRIVATE = "private";
+/** The cache mode of a strategy, `public`, `private`, or `no-store`. A `no-store` strategy skips the cache. */
 type CacheMode = typeof PUBLIC | typeof PRIVATE | typeof NO_STORE;
+/** The modes that a custom strategy accepts, `public` or `private`. `Cache` throws an error for any other mode. */
 type ExpirableCacheMode = typeof PUBLIC | typeof PRIVATE;
+/**
+ * A number of seconds, or an object such as `{ minutes: 10 }`. `Cache` throws an error for a duration that isn't a finite, non-negative number, and rounds fractional totals up to whole seconds.
+ */
 type CacheDuration = number | {
   seconds?: number;
   minutes?: number;
   hours?: number;
   days?: number;
 };
+/** A caching strategy, with every duration in whole seconds. Create a strategy with `Cache`. */
 interface CachingStrategy {
+  /** The cache mode. A `no-store` strategy skips the cache. */
   mode?: CacheMode;
+  /** How many seconds an entry stays fresh. */
   maxAge?: number;
+  /** How many seconds after the fresh window the cache serves a stale entry while it refreshes the entry in the background. */
   staleWhileRevalidate?: number;
+  /** How many seconds after the stale window the cache serves a stale entry when the refresh fails. */
   staleIfError?: number;
 }
+/**
+ * Options for a custom caching strategy. A duration that you leave out counts as zero seconds.
+ *
+ * @publicDocs
+ */
 type CacheOptions = {
-  mode?: ExpirableCacheMode;
-  maxAge?: CacheDuration;
+  /** The cache mode, `public` or `private`. Defaults to `public`. Web Cache stores receive the mode in the `cache-control` header. The Storefront API client throws an error for `private`. */mode?: ExpirableCacheMode; /** How long an entry stays fresh. */
+  maxAge?: CacheDuration; /** How long after the fresh window the cache serves a stale entry while it refreshes the entry in the background. */
   staleWhileRevalidate?: CacheDuration;
+  /**
+   * How long after the stale-while-revalidate window the cache serves a stale entry when a refresh fails.
+   */
   staleIfError?: CacheDuration;
 };
+/** A strategy that skips the cache. */
 type NoStoreStrategy = CachingStrategy & {
   mode: typeof NO_STORE;
 };
+/**
+ * Creates caching strategies for Storefront API queries, cached fetches, and cached runs. Call
+ * `Cache` with options for a custom strategy, or use the `none`, `short`, and `long` presets.
+ *
+ * @publicDocs
+ */
 declare const Cache: typeof createCache & {
   none: typeof cacheNone;
   short: typeof cacheShort;

package/dist/development/core/cache/strategies.mjs

@@ -2,6 +2,12 @@
 const NO_STORE = "no-store";
 const PUBLIC = "public";
 const PRIVATE = "private";
+/**
+* Creates caching strategies for Storefront API queries, cached fetches, and cached runs. Call
+* `Cache` with options for a custom strategy, or use the `none`, `short`, and `long` presets.
+*
+* @publicDocs
+*/
 const Cache = Object.assign(createCache, {
 	none: cacheNone,
 	short: cacheShort,