@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/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/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/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/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/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/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/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/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/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/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,

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

@@ -1 +1 @@
-{"version":3,"file":"strategies.mjs","names":[],"sources":["../../../src/core/cache/strategies.ts"],"sourcesContent":["export const NO_STORE = \"no-store\";\n\nconst PUBLIC = \"public\";\nconst PRIVATE = \"private\";\n\nexport type CacheMode = typeof PUBLIC | typeof PRIVATE | typeof NO_STORE;\nexport type ExpirableCacheMode = typeof PUBLIC | typeof PRIVATE;\n\nexport type CacheDuration =\n  | number\n  | {\n      seconds?: number;\n      minutes?: number;\n      hours?: number;\n      days?: number;\n    };\n\nexport interface CachingStrategy {\n  mode?: CacheMode;\n  maxAge?: number;\n  staleWhileRevalidate?: number;\n  staleIfError?: number;\n}\n\nexport type CacheOptions = {\n  mode?: ExpirableCacheMode;\n  maxAge?: CacheDuration;\n  staleWhileRevalidate?: CacheDuration;\n  staleIfError?: CacheDuration;\n};\n\ntype NoStoreStrategy = CachingStrategy & {\n  mode: typeof NO_STORE;\n};\n\nexport const Cache = Object.assign(createCache, {\n  none: cacheNone,\n  short: cacheShort,\n  long: cacheLong,\n});\n\nexport function getCacheRetentionTtl(strategy: CachingStrategy): number {\n  if (strategy.mode === NO_STORE) return 0;\n\n  return Math.max(\n    0,\n    (strategy.maxAge ?? 0) + (strategy.staleWhileRevalidate ?? 0) + (strategy.staleIfError ?? 0),\n  );\n}\n\nexport function getPlatformCacheControlHeader(strategy: CachingStrategy): string {\n  const ttl = getCacheRetentionTtl(strategy);\n  if (ttl <= 0) return NO_STORE;\n\n  return `${strategy.mode ?? PUBLIC}, max-age=${Math.ceil(ttl)}`;\n}\n\nfunction createCache(options: CacheOptions): CachingStrategy {\n  return normalizeCacheOptions(options);\n}\n\nfunction cacheNone(): NoStoreStrategy {\n  return { mode: NO_STORE };\n}\n\nfunction cacheShort(overrideOptions?: CacheOptions): CachingStrategy {\n  return normalizeCacheOptions(\n    {\n      mode: PUBLIC,\n      maxAge: 1,\n      staleWhileRevalidate: 9,\n    },\n    overrideOptions,\n  );\n}\n\nfunction cacheLong(overrideOptions?: CacheOptions): CachingStrategy {\n  return normalizeCacheOptions(\n    {\n      mode: PUBLIC,\n      maxAge: 3600,\n      staleWhileRevalidate: 82800,\n    },\n    overrideOptions,\n  );\n}\n\nfunction normalizeCacheOptions(\n  defaults: CacheOptions,\n  overrideOptions?: CacheOptions,\n): CachingStrategy;\nfunction normalizeCacheOptions(options: CacheOptions): CachingStrategy;\nfunction normalizeCacheOptions(\n  defaultsOrOptions: CacheOptions,\n  overrideOptions?: CacheOptions,\n): CachingStrategy {\n  const options = {\n    ...defaultsOrOptions,\n    ...overrideOptions,\n  };\n\n  return {\n    ...normalizeMode(options),\n    ...normalizeDurationOption(\"maxAge\", options.maxAge),\n    ...normalizeDurationOption(\"staleWhileRevalidate\", options.staleWhileRevalidate),\n    ...normalizeDurationOption(\"staleIfError\", options.staleIfError),\n  };\n}\n\nfunction normalizeMode(options: CacheOptions): Pick<CachingStrategy, \"mode\"> {\n  if (options.mode && options.mode !== PUBLIC && options.mode !== PRIVATE) {\n    throw new Error(\"'mode' must be either 'public' or 'private'\");\n  }\n\n  return { mode: options.mode ?? PUBLIC };\n}\n\nfunction normalizeDurationOption(\n  name: \"maxAge\" | \"staleWhileRevalidate\" | \"staleIfError\",\n  duration: CacheDuration | undefined,\n): Pick<CachingStrategy, typeof name> {\n  if (duration == null) return {};\n\n  return { [name]: normalizeDuration(duration) };\n}\n\nfunction normalizeDuration(duration: CacheDuration): number {\n  if (typeof duration === \"number\") return validateDuration(duration);\n\n  return validateDuration(\n    (duration.seconds ?? 0) +\n      (duration.minutes ?? 0) * 60 +\n      (duration.hours ?? 0) * 3600 +\n      (duration.days ?? 0) * 86400,\n  );\n}\n\nfunction validateDuration(duration: number): number {\n  if (!Number.isFinite(duration) || duration < 0) {\n    throw new Error(\"Cache durations must be finite, non-negative numbers.\");\n  }\n\n  return Math.ceil(duration);\n}\n"],"mappings":";AAAA,MAAa,WAAW;AAExB,MAAM,SAAS;AACf,MAAM,UAAU;AAgChB,MAAa,QAAQ,OAAO,OAAO,aAAa;CAC9C,MAAM;CACN,OAAO;CACP,MAAM;CACP,CAAC;AAEF,SAAgB,qBAAqB,UAAmC;AACtE,KAAI,SAAS,oBAAmB,QAAO;AAEvC,QAAO,KAAK,IACV,IACC,SAAS,UAAU,MAAM,SAAS,wBAAwB,MAAM,SAAS,gBAAgB,GAC3F;;AAGH,SAAgB,8BAA8B,UAAmC;CAC/E,MAAM,MAAM,qBAAqB,SAAS;AAC1C,KAAI,OAAO,EAAG,QAAO;AAErB,QAAO,GAAG,SAAS,QAAQ,OAAO,YAAY,KAAK,KAAK,IAAI;;AAG9D,SAAS,YAAY,SAAwC;AAC3D,QAAO,sBAAsB,QAAQ;;AAGvC,SAAS,YAA6B;AACpC,QAAO,EAAE,MAAM,UAAU;;AAG3B,SAAS,WAAW,iBAAiD;AACnE,QAAO,sBACL;EACE,MAAM;EACN,QAAQ;EACR,sBAAsB;EACvB,EACD,gBACD;;AAGH,SAAS,UAAU,iBAAiD;AAClE,QAAO,sBACL;EACE,MAAM;EACN,QAAQ;EACR,sBAAsB;EACvB,EACD,gBACD;;AAQH,SAAS,sBACP,mBACA,iBACiB;CACjB,MAAM,UAAU;EACd,GAAG;EACH,GAAG;EACJ;AAED,QAAO;EACL,GAAG,cAAc,QAAQ;EACzB,GAAG,wBAAwB,UAAU,QAAQ,OAAO;EACpD,GAAG,wBAAwB,wBAAwB,QAAQ,qBAAqB;EAChF,GAAG,wBAAwB,gBAAgB,QAAQ,aAAa;EACjE;;AAGH,SAAS,cAAc,SAAsD;AAC3E,KAAI,QAAQ,QAAQ,QAAQ,SAAS,UAAU,QAAQ,SAAS,QAC9D,OAAM,IAAI,MAAM,8CAA8C;AAGhE,QAAO,EAAE,MAAM,QAAQ,QAAQ,QAAQ;;AAGzC,SAAS,wBACP,MACA,UACoC;AACpC,KAAI,YAAY,KAAM,QAAO,EAAE;AAE/B,QAAO,GAAG,OAAO,kBAAkB,SAAS,EAAE;;AAGhD,SAAS,kBAAkB,UAAiC;AAC1D,KAAI,OAAO,aAAa,SAAU,QAAO,iBAAiB,SAAS;AAEnE,QAAO,kBACJ,SAAS,WAAW,MAClB,SAAS,WAAW,KAAK,MACzB,SAAS,SAAS,KAAK,QACvB,SAAS,QAAQ,KAAK,MAC1B;;AAGH,SAAS,iBAAiB,UAA0B;AAClD,KAAI,CAAC,OAAO,SAAS,SAAS,IAAI,WAAW,EAC3C,OAAM,IAAI,MAAM,wDAAwD;AAG1E,QAAO,KAAK,KAAK,SAAS"}
+{"version":3,"file":"strategies.mjs","names":[],"sources":["../../../src/core/cache/strategies.ts"],"sourcesContent":["export const NO_STORE = \"no-store\";\n\nconst PUBLIC = \"public\";\nconst PRIVATE = \"private\";\n\n/** The cache mode of a strategy, `public`, `private`, or `no-store`. A `no-store` strategy skips the cache. */\nexport type CacheMode = typeof PUBLIC | typeof PRIVATE | typeof NO_STORE;\n/** The modes that a custom strategy accepts, `public` or `private`. `Cache` throws an error for any other mode. */\nexport type ExpirableCacheMode = typeof PUBLIC | typeof PRIVATE;\n\n/**\n * 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.\n */\nexport type CacheDuration =\n  | number\n  | {\n      seconds?: number;\n      minutes?: number;\n      hours?: number;\n      days?: number;\n    };\n\n/** A caching strategy, with every duration in whole seconds. Create a strategy with `Cache`. */\nexport interface CachingStrategy {\n  /** The cache mode. A `no-store` strategy skips the cache. */\n  mode?: CacheMode;\n  /** How many seconds an entry stays fresh. */\n  maxAge?: number;\n  /** How many seconds after the fresh window the cache serves a stale entry while it refreshes the entry in the background. */\n  staleWhileRevalidate?: number;\n  /** How many seconds after the stale window the cache serves a stale entry when the refresh fails. */\n  staleIfError?: number;\n}\n\n/**\n * Options for a custom caching strategy. A duration that you leave out counts as zero seconds.\n *\n * @publicDocs\n */\nexport type CacheOptions = {\n  /** 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`. */\n  mode?: ExpirableCacheMode;\n  /** How long an entry stays fresh. */\n  maxAge?: CacheDuration;\n  /** How long after the fresh window the cache serves a stale entry while it refreshes the entry in the background. */\n  staleWhileRevalidate?: CacheDuration;\n  /**\n   * How long after the stale-while-revalidate window the cache serves a stale entry when a refresh fails.\n   */\n  staleIfError?: CacheDuration;\n};\n\n/** A strategy that skips the cache. */\ntype NoStoreStrategy = CachingStrategy & {\n  mode: typeof NO_STORE;\n};\n\n/**\n * Creates caching strategies for Storefront API queries, cached fetches, and cached runs. Call\n * `Cache` with options for a custom strategy, or use the `none`, `short`, and `long` presets.\n *\n * @publicDocs\n */\nexport const Cache = Object.assign(createCache, {\n  none: cacheNone,\n  short: cacheShort,\n  long: cacheLong,\n});\n\n/**\n * Creates caching strategies for Storefront API queries, cached fetches, and cached runs. Call `Cache` with options for a custom strategy, or use the `short`, `long`, and `none` presets.\n *\n * @publicDocs\n */\nexport type CacheForDocs = {\n  (options: CacheOptions): CachingStrategy;\n  /**\n   * Returns a strategy that skips the cache. The preset takes no options.\n   */\n  none: typeof cacheNone;\n  /**\n   * Keeps public entries fresh for 1 second, then serves stale entries for 9 more seconds while the cache refreshes them. Pass options to override the mode or either duration, or to add `staleIfError`.\n   */\n  short: typeof cacheShort;\n  /**\n   * Keeps public entries fresh for 1 hour, then serves stale entries for 23 more hours while the cache refreshes them. Pass options to override the mode or either duration, or to add `staleIfError`.\n   */\n  long: typeof cacheLong;\n};\n\nexport function getCacheRetentionTtl(strategy: CachingStrategy): number {\n  if (strategy.mode === NO_STORE) return 0;\n\n  return Math.max(\n    0,\n    (strategy.maxAge ?? 0) + (strategy.staleWhileRevalidate ?? 0) + (strategy.staleIfError ?? 0),\n  );\n}\n\nexport function getPlatformCacheControlHeader(strategy: CachingStrategy): string {\n  const ttl = getCacheRetentionTtl(strategy);\n  if (ttl <= 0) return NO_STORE;\n\n  return `${strategy.mode ?? PUBLIC}, max-age=${Math.ceil(ttl)}`;\n}\n\nfunction createCache(options: CacheOptions): CachingStrategy {\n  return normalizeCacheOptions(options);\n}\n\nfunction cacheNone(): NoStoreStrategy {\n  return { mode: NO_STORE };\n}\n\nfunction cacheShort(overrideOptions?: CacheOptions): CachingStrategy {\n  return normalizeCacheOptions(\n    {\n      mode: PUBLIC,\n      maxAge: 1,\n      staleWhileRevalidate: 9,\n    },\n    overrideOptions,\n  );\n}\n\nfunction cacheLong(overrideOptions?: CacheOptions): CachingStrategy {\n  return normalizeCacheOptions(\n    {\n      mode: PUBLIC,\n      maxAge: 3600,\n      staleWhileRevalidate: 82800,\n    },\n    overrideOptions,\n  );\n}\n\nfunction normalizeCacheOptions(\n  defaults: CacheOptions,\n  overrideOptions?: CacheOptions,\n): CachingStrategy;\nfunction normalizeCacheOptions(options: CacheOptions): CachingStrategy;\nfunction normalizeCacheOptions(\n  defaultsOrOptions: CacheOptions,\n  overrideOptions?: CacheOptions,\n): CachingStrategy {\n  const options = {\n    ...defaultsOrOptions,\n    ...overrideOptions,\n  };\n\n  return {\n    ...normalizeMode(options),\n    ...normalizeDurationOption(\"maxAge\", options.maxAge),\n    ...normalizeDurationOption(\"staleWhileRevalidate\", options.staleWhileRevalidate),\n    ...normalizeDurationOption(\"staleIfError\", options.staleIfError),\n  };\n}\n\nfunction normalizeMode(options: CacheOptions): Pick<CachingStrategy, \"mode\"> {\n  if (options.mode && options.mode !== PUBLIC && options.mode !== PRIVATE) {\n    throw new Error(\"'mode' must be either 'public' or 'private'\");\n  }\n\n  return { mode: options.mode ?? PUBLIC };\n}\n\nfunction normalizeDurationOption(\n  name: \"maxAge\" | \"staleWhileRevalidate\" | \"staleIfError\",\n  duration: CacheDuration | undefined,\n): Pick<CachingStrategy, typeof name> {\n  if (duration == null) return {};\n\n  return { [name]: normalizeDuration(duration) };\n}\n\nfunction normalizeDuration(duration: CacheDuration): number {\n  if (typeof duration === \"number\") return validateDuration(duration);\n\n  return validateDuration(\n    (duration.seconds ?? 0) +\n      (duration.minutes ?? 0) * 60 +\n      (duration.hours ?? 0) * 3600 +\n      (duration.days ?? 0) * 86400,\n  );\n}\n\nfunction validateDuration(duration: number): number {\n  if (!Number.isFinite(duration) || duration < 0) {\n    throw new Error(\"Cache durations must be finite, non-negative numbers.\");\n  }\n\n  return Math.ceil(duration);\n}\n"],"mappings":";AAAA,MAAa,WAAW;AAExB,MAAM,SAAS;AACf,MAAM,UAAU;;;;;;;AA4DhB,MAAa,QAAQ,OAAO,OAAO,aAAa;CAC9C,MAAM;CACN,OAAO;CACP,MAAM;CACP,CAAC;AAuBF,SAAgB,qBAAqB,UAAmC;AACtE,KAAI,SAAS,oBAAmB,QAAO;AAEvC,QAAO,KAAK,IACV,IACC,SAAS,UAAU,MAAM,SAAS,wBAAwB,MAAM,SAAS,gBAAgB,GAC3F;;AAGH,SAAgB,8BAA8B,UAAmC;CAC/E,MAAM,MAAM,qBAAqB,SAAS;AAC1C,KAAI,OAAO,EAAG,QAAO;AAErB,QAAO,GAAG,SAAS,QAAQ,OAAO,YAAY,KAAK,KAAK,IAAI;;AAG9D,SAAS,YAAY,SAAwC;AAC3D,QAAO,sBAAsB,QAAQ;;AAGvC,SAAS,YAA6B;AACpC,QAAO,EAAE,MAAM,UAAU;;AAG3B,SAAS,WAAW,iBAAiD;AACnE,QAAO,sBACL;EACE,MAAM;EACN,QAAQ;EACR,sBAAsB;EACvB,EACD,gBACD;;AAGH,SAAS,UAAU,iBAAiD;AAClE,QAAO,sBACL;EACE,MAAM;EACN,QAAQ;EACR,sBAAsB;EACvB,EACD,gBACD;;AAQH,SAAS,sBACP,mBACA,iBACiB;CACjB,MAAM,UAAU;EACd,GAAG;EACH,GAAG;EACJ;AAED,QAAO;EACL,GAAG,cAAc,QAAQ;EACzB,GAAG,wBAAwB,UAAU,QAAQ,OAAO;EACpD,GAAG,wBAAwB,wBAAwB,QAAQ,qBAAqB;EAChF,GAAG,wBAAwB,gBAAgB,QAAQ,aAAa;EACjE;;AAGH,SAAS,cAAc,SAAsD;AAC3E,KAAI,QAAQ,QAAQ,QAAQ,SAAS,UAAU,QAAQ,SAAS,QAC9D,OAAM,IAAI,MAAM,8CAA8C;AAGhE,QAAO,EAAE,MAAM,QAAQ,QAAQ,QAAQ;;AAGzC,SAAS,wBACP,MACA,UACoC;AACpC,KAAI,YAAY,KAAM,QAAO,EAAE;AAE/B,QAAO,GAAG,OAAO,kBAAkB,SAAS,EAAE;;AAGhD,SAAS,kBAAkB,UAAiC;AAC1D,KAAI,OAAO,aAAa,SAAU,QAAO,iBAAiB,SAAS;AAEnE,QAAO,kBACJ,SAAS,WAAW,MAClB,SAAS,WAAW,KAAK,MACzB,SAAS,SAAS,KAAK,QACvB,SAAS,QAAQ,KAAK,MAC1B;;AAGH,SAAS,iBAAiB,UAA0B;AAClD,KAAI,CAAC,OAAO,SAAS,SAAS,IAAI,WAAW,EAC3C,OAAM,IAAI,MAAM,wDAAwD;AAG1E,QAAO,KAAK,KAAK,SAAS"}

package/dist/core/cart/actions.d.mts

@@ -1,36 +1,39 @@
 //#region src/core/cart/actions.d.ts
-/** A key-value pair attached to the cart or an individual cart line. */
+/** A custom key-value pair for the cart or a cart line. */
 type CartAttributeInput = {
-  key: string;
+  /** The attribute name. parseCartRequest throws for an empty name in cart attributes and in form submissions. */key: string; /** The attribute value. */
   value: string;
 };
+/** Input for adding a line to the cart. */
 type CartLineAddInput = {
-  /** Storefront API GID of the product variant to add. */merchandiseId: string;
-  quantity: number;
-  attributes?: CartAttributeInput[]; /** Selling plan GID for subscription line items. */
+  /** The Storefront API GID of the product variant to add. */merchandiseId: string; /** Number of units to add. A form submission without a quantity adds `1`. */
+  quantity: number; /** Custom key-value attributes to set on the new line. */
+  attributes?: CartAttributeInput[]; /** The selling plan GID for a subscription line. */
   sellingPlanId?: string;
 };
-/** Input for updating an existing cart line. Setting `quantity` to `0` removes the line. */
+/** Input for updating an existing cart line. A quantity of `0` removes the line. */
 type CartLineUpdateInput = {
-  /** The `CartLine.id` of the line to update. */id: string;
-  quantity: number;
-  attributes?: CartAttributeInput[];
+  /** The ID of the cart line to update. */id: string; /** The GID of a product variant to swap the line to. */
+  merchandiseId?: string; /** The line's new quantity. */
+  quantity: number; /** Custom key-value attributes to set on the line. */
+  attributes?: CartAttributeInput[]; /** The selling plan GID to assign to the line for a subscription. */
   sellingPlanId?: string;
 };
 /**
- * Discriminated union of all cart mutation intents.
+ * A cart change that `parseCartRequest` reads from a JSON or form request.
  *
- * {@link parseCartRequest} normalizes both JSON and FormData requests into one
- * of these variants. The `intent` field determines the Storefront API mutation:
+ * The `intent` field names the change and the Storefront API mutation that applies the change:
  *
- * - `"add"` — add new lines (cartLinesAdd, or cartCreate when no cart exists)
- * - `"update"` — change quantity or attributes on existing lines (cartLinesUpdate)
- * - `"remove"` — remove lines by ID (cartLinesRemove)
- * - `"discount-update"` — replace all discount codes (cartDiscountCodesUpdate)
- * - `"discount-apply"` — add a single discount code (read-then-write via cartDiscountCodesUpdate)
- * - `"discount-remove"` — remove a single discount code (read-then-write via cartDiscountCodesUpdate)
- * - `"attributes-update"` — set cart-level attributes (cartAttributesUpdate)
- * - `"note-update"` — set the cart note (cartNoteUpdate)
+ * - `add` adds new lines with `cartLinesAdd`, or creates a cart with `cartCreate` when none exists.
+ * - `update` changes quantity, merchandise, or attributes on existing lines with `cartLinesUpdate`.
+ * - `remove` removes lines by ID with `cartLinesRemove`.
+ * - `discount-update` replaces all discount codes with `cartDiscountCodesUpdate`.
+ * - `discount-apply` adds one discount code. The handler reads the current codes, then writes the new list with `cartDiscountCodesUpdate`.
+ * - `discount-remove` removes one discount code with the same read-then-write approach.
+ * - `attributes-update` sets cart-level attributes with `cartAttributesUpdate`.
+ * - `note-update` sets the cart note with `cartNoteUpdate`.
+ *
+ * @publicDocs
  */
 type CartAction = {
   intent: "add";
@@ -57,23 +60,26 @@ type CartAction = {
   intent: "note-update";
   note: string;
 };
+/** The cart change and the cart ID that `parseCartRequest` reads from the request body. */
 type ParsedCartRequest = {
-  action: CartAction;
+  action: CartAction; /** The cart GID from a JSON body, or `null` for a form submission or a JSON body without a cart ID. The function adds the `gid://shopify/Cart/` prefix to a bare cart token. */
   cartId: string | null;
 };
 /**
- * Parses an incoming cart mutation request into a typed {@link CartAction}.
+ * Reads the cart change from a cart request body. Use the function in a custom cart route.
+ *
+ * The function accepts `application/json`, `application/x-www-form-urlencoded`, and
+ * `multipart/form-data` requests. A JSON request can replace every discount code, and a form submission applies or removes one code.
  *
- * Accepts `application/json` and `application/x-www-form-urlencoded` /
- * `multipart/form-data` content types. JSON and FormData each support a
- * different subset of intents — JSON produces `discount-update` while
- * FormData produces `discount-apply` / `discount-remove`.
+ * A form submission always returns a `null` cart ID. Read the cart ID for a form submission with `getCartId`.
  *
- * FormData requests always return `cartId: null` — the server handler
- * should fall back to the cart cookie.
+ * The function reads the request body, and you can't read the body again afterward. The function throws when the request has an unsupported content type, an unknown intent, or a missing required field, and when a JSON body combines more than one of `lines`, `discountCodes`, `attributes`, and `note`.
  *
- * @throws If the content-type is unsupported, the intent is unrecognized,
- * or required fields are missing.
+ * @param request The incoming cart request.
+ * @returns The cart change and, for a JSON body, the cart ID.
+ * @throws If the request has an unsupported content type, an unrecognized intent,
+ * or missing required fields, or if a JSON body combines more than one of
+ * `lines`, `discountCodes`, `attributes`, and `note`.
  *
  * @example
  * ```ts
@@ -87,6 +93,7 @@ type ParsedCartRequest = {
  *   // ...
  * }
  * ```
+ * @publicDocs
  */
 declare function parseCartRequest(request: Request): Promise<ParsedCartRequest>;
 //#endregion