@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,6 @@
+//#region src/core/cache/key.d.ts
+type CacheKeyPrimitive = string | number | boolean | null;
+type CacheKey = string | readonly CacheKeyPrimitive[];
+//#endregion
+export { CacheKey };
+//# sourceMappingURL=key.d.mts.map

package/dist/core/cache/key.mjs

@@ -0,0 +1,27 @@
+//#region src/core/cache/key.ts
+const textEncoder = new TextEncoder();
+async function hashCacheKey(key) {
+	const serialized = typeof key === "string" ? `string:${key}` : `array:${serializeArrayKey(key)}`;
+	return `h2:${hexEncode(await crypto.subtle.digest("SHA-256", textEncoder.encode(serialized)))}`;
+}
+function serializeArrayKey(value) {
+	const values = [];
+	for (let index = 0; index < value.length; index++) {
+		if (!(index in value)) throw new TypeError("Cache key arrays cannot contain empty slots.");
+		values.push(serializeCacheKeyPrimitive(value[index]));
+	}
+	return `[${values.join(",")}]`;
+}
+function serializeCacheKeyPrimitive(value) {
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	throw new TypeError(`Cache key arrays must contain only primitive values. Received: ${typeof value}`);
+}
+function hexEncode(bytes) {
+	return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+//#endregion
+export { hashCacheKey };
+//# sourceMappingURL=key.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,36 @@
+import { CacheKey } from "./key.mjs";
+import { CachingStrategy } from "./strategies.mjs";
+import { KeyValueCacheLike, SerializableCacheValue, WebCacheLike } from "./store.mjs";
+
+//#region src/core/cache/run-with-cache.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type WaitUntil = (promise: Promise<unknown>) => void;
+type CacheInstance = WebCacheLike | KeyValueCacheLike;
+type CreateRunWithCacheOptions = {
+  cache: CacheInstance;
+  waitUntil?: WaitUntil;
+};
+type RunWithCacheOptions = {
+  key: CacheKey;
+  strategy: CachingStrategy;
+};
+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.
+   */
+  data: T;
+  shouldCache: boolean;
+};
+type RunWithCacheResult<T extends SerializableCacheValue> = {
+  data: T;
+  cacheStatus: "hit" | "miss" | "bypass";
+};
+type RunWithCache = <T extends SerializableCacheValue>(options: RunWithCacheOptions, run: () => MaybePromise<CacheDecision<T>>) => Promise<RunWithCacheResult<T>>;
+declare function createRunWithCache({
+  cache,
+  waitUntil
+}: CreateRunWithCacheOptions): RunWithCache;
+//#endregion
+export { CacheInstance, CreateRunWithCacheOptions, RunWithCache, WaitUntil, createRunWithCache };
+//# sourceMappingURL=run-with-cache.d.mts.map

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

@@ -0,0 +1,114 @@
+import { hashCacheKey } from "./key.mjs";
+import { NO_STORE, getCacheRetentionTtl } from "./strategies.mjs";
+import { createNormalizedCacheStore } from "./store.mjs";
+
+//#region src/core/cache/run-with-cache.ts
+/**
+* Internal control-flow error for adapters that need to escape the cache
+* pipeline without being interpreted as an origin failure. `staleIfError`
+* catches refresh failures, but it should not hide intentional bypasses.
+*/
+var StaleFallbackDisabledError = class extends Error {};
+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,
+			cacheStatus: "bypass"
+		};
+		const cacheKey = await hashCacheKey(options.key);
+		let cached;
+		try {
+			cached = await store.get(cacheKey);
+		} catch {}
+		if (cached) {
+			const state = getCacheState(cached, options.strategy);
+			if (state === "fresh") return {
+				data: cached.value,
+				cacheStatus: "hit"
+			};
+			if (state === "stale") {
+				revalidateInBackground(cacheKey, options, run);
+				return {
+					data: cached.value,
+					cacheStatus: "hit"
+				};
+			}
+			if (state === "stale-if-error") return refreshWithStaleFallback(cacheKey, cached.value, options, run);
+		}
+		return runAndMaybeStore(cacheKey, options, run).result;
+	};
+	function revalidateInBackground(cacheKey, options, run) {
+		schedule(runAndMaybeStore(cacheKey, options, run, { scheduleCacheWrite: false }).complete);
+	}
+	async function refreshWithStaleFallback(cacheKey, staleValue, options, run) {
+		try {
+			return await runAndMaybeStore(cacheKey, options, run).result;
+		} catch (error) {
+			if (!shouldFallbackToStale(error)) throw error;
+			return {
+				data: staleValue,
+				cacheStatus: "hit"
+			};
+		}
+	}
+	function runAndMaybeStore(key, options, run, { scheduleCacheWrite = true } = {}) {
+		let storePromise = Promise.resolve();
+		const result = Promise.resolve().then(async () => {
+			const decision = await runAndValidate(run);
+			if (!shouldStore(options.strategy, decision)) return {
+				data: decision.data,
+				cacheStatus: "miss"
+			};
+			storePromise = storeDecision(key, options, decision).catch(() => {});
+			if (waitUntil && scheduleCacheWrite) schedule(storePromise);
+			else if (!waitUntil) await storePromise;
+			return {
+				data: decision.data,
+				cacheStatus: "miss"
+			};
+		});
+		return {
+			result,
+			complete: result.then(() => storePromise, () => void 0).then(() => void 0)
+		};
+	}
+	async function storeDecision(key, options, decision) {
+		await store.set(key, {
+			version: 1,
+			value: decision.data,
+			storedAt: Date.now(),
+			strategy: options.strategy
+		}, { strategy: options.strategy });
+	}
+	function schedule(promise) {
+		try {
+			waitUntil?.(promise);
+		} catch {}
+	}
+}
+function shouldStore(strategy, decision) {
+	return decision.shouldCache && getCacheRetentionTtl(strategy) > 0;
+}
+function shouldFallbackToStale(error) {
+	return !(error instanceof StaleFallbackDisabledError);
+}
+async function runAndValidate(run) {
+	const decision = await run();
+	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;
+}
+function getCacheState(envelope, strategy) {
+	const age = Math.max(0, (Date.now() - envelope.storedAt) / 1e3);
+	const maxAge = strategy.maxAge ?? 0;
+	const staleWhileRevalidate = strategy.staleWhileRevalidate ?? 0;
+	const staleIfError = strategy.staleIfError ?? 0;
+	if (age <= maxAge) return "fresh";
+	if (age <= maxAge + staleWhileRevalidate) return "stale";
+	if (age <= maxAge + staleWhileRevalidate + staleIfError) return "stale-if-error";
+	return "expired";
+}
+
+//#endregion
+export { StaleFallbackDisabledError, createRunWithCache };
+//# sourceMappingURL=run-with-cache.mjs.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +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`.
+ */
+type SerializableCacheValue = Record<string, unknown>;
+type WebCacheLike = Pick<Cache, "match" | "put" | "delete">;
+type KeyValueCacheSetOptions = {
+  ttl?: number;
+};
+type KeyValueCacheLike = {
+  get(key: string): unknown | Promise<unknown>;
+  set(key: string, value: unknown, options?: KeyValueCacheSetOptions): unknown | Promise<unknown>;
+  delete?(key: string): unknown | Promise<unknown>;
+};
+//#endregion
+export { KeyValueCacheLike, SerializableCacheValue, WebCacheLike };
+//# sourceMappingURL=store.d.mts.map

package/dist/core/cache/store.mjs

@@ -0,0 +1,62 @@
+import { getCacheRetentionTtl, getPlatformCacheControlHeader } from "./strategies.mjs";
+
+//#region src/core/cache/store.ts
+function createNormalizedCacheStore(cache) {
+	if (isWebCacheLike(cache)) return createWebCacheStore(cache);
+	if (isKeyValueCacheLike(cache)) return createKeyValueCacheStore(cache);
+	throw new TypeError("Expected a Web Cache API compatible store or a key/value cache store.");
+}
+function createWebCacheStore(cache) {
+	return {
+		async get(key) {
+			const response = await cache.match(createCacheRequest(key));
+			if (!response) return void 0;
+			const envelope = JSON.parse(await response.text());
+			return isCacheEnvelope(envelope) ? envelope : void 0;
+		},
+		async set(key, envelope, { strategy }) {
+			const response = new Response(JSON.stringify(envelope), { headers: {
+				"cache-control": getPlatformCacheControlHeader(strategy),
+				"content-type": "application/json"
+			} });
+			await cache.put(createCacheRequest(key), response);
+		},
+		async delete(key) {
+			await cache.delete(createCacheRequest(key));
+		}
+	};
+}
+function createKeyValueCacheStore(cache) {
+	return {
+		async get(key) {
+			const envelope = await cache.get(key);
+			return isCacheEnvelope(envelope) ? envelope : void 0;
+		},
+		async set(key, envelope, { strategy }) {
+			const ttl = Math.ceil(getCacheRetentionTtl(strategy));
+			await cache.set(key, envelope, { ttl });
+		},
+		async delete(key) {
+			await cache.delete?.(key);
+		}
+	};
+}
+function createCacheRequest(key) {
+	return new Request(`https://hydrogen.cache/${key}`);
+}
+function isWebCacheLike(cache) {
+	return typeof cache === "object" && cache != null && "match" in cache && "put" in cache && typeof cache.match === "function" && typeof cache.put === "function";
+}
+function isKeyValueCacheLike(cache) {
+	return typeof cache === "object" && cache != null && "get" in cache && "set" in cache && typeof cache.get === "function" && typeof cache.set === "function";
+}
+function isCacheEnvelope(value) {
+	return typeof value === "object" && value != null && "version" in value && value.version === 1 && "storedAt" in value && typeof value.storedAt === "number" && "strategy" in value && Boolean(value.strategy) && "value" in value && isSerializableCacheValue(value.value);
+}
+function isSerializableCacheValue(value) {
+	return typeof value === "object" && value != null && !Array.isArray(value);
+}
+
+//#endregion
+export { createNormalizedCacheStore };
+//# sourceMappingURL=store.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,39 @@
+//#region src/core/cache/strategies.d.ts
+declare const NO_STORE = "no-store";
+declare const PUBLIC = "public";
+declare const PRIVATE = "private";
+type CacheMode = typeof PUBLIC | typeof PRIVATE | typeof NO_STORE;
+type ExpirableCacheMode = typeof PUBLIC | typeof PRIVATE;
+type CacheDuration = number | {
+  seconds?: number;
+  minutes?: number;
+  hours?: number;
+  days?: number;
+};
+interface CachingStrategy {
+  mode?: CacheMode;
+  maxAge?: number;
+  staleWhileRevalidate?: number;
+  staleIfError?: number;
+}
+type CacheOptions = {
+  mode?: ExpirableCacheMode;
+  maxAge?: CacheDuration;
+  staleWhileRevalidate?: CacheDuration;
+  staleIfError?: CacheDuration;
+};
+type NoStoreStrategy = CachingStrategy & {
+  mode: typeof NO_STORE;
+};
+declare const Cache: typeof createCache & {
+  none: typeof cacheNone;
+  short: typeof cacheShort;
+  long: typeof cacheLong;
+};
+declare function createCache(options: CacheOptions): CachingStrategy;
+declare function cacheNone(): NoStoreStrategy;
+declare function cacheShort(overrideOptions?: CacheOptions): CachingStrategy;
+declare function cacheLong(overrideOptions?: CacheOptions): CachingStrategy;
+//#endregion
+export { Cache, CacheOptions, CachingStrategy };
+//# sourceMappingURL=strategies.d.mts.map

package/dist/core/cache/strategies.mjs

@@ -0,0 +1,70 @@
+//#region src/core/cache/strategies.ts
+const NO_STORE = "no-store";
+const PUBLIC = "public";
+const PRIVATE = "private";
+const Cache = Object.assign(createCache, {
+	none: cacheNone,
+	short: cacheShort,
+	long: cacheLong
+});
+function getCacheRetentionTtl(strategy) {
+	if (strategy.mode === "no-store") return 0;
+	return Math.max(0, (strategy.maxAge ?? 0) + (strategy.staleWhileRevalidate ?? 0) + (strategy.staleIfError ?? 0));
+}
+function getPlatformCacheControlHeader(strategy) {
+	const ttl = getCacheRetentionTtl(strategy);
+	if (ttl <= 0) return NO_STORE;
+	return `${strategy.mode ?? PUBLIC}, max-age=${Math.ceil(ttl)}`;
+}
+function createCache(options) {
+	return normalizeCacheOptions(options);
+}
+function cacheNone() {
+	return { mode: NO_STORE };
+}
+function cacheShort(overrideOptions) {
+	return normalizeCacheOptions({
+		mode: PUBLIC,
+		maxAge: 1,
+		staleWhileRevalidate: 9
+	}, overrideOptions);
+}
+function cacheLong(overrideOptions) {
+	return normalizeCacheOptions({
+		mode: PUBLIC,
+		maxAge: 3600,
+		staleWhileRevalidate: 82800
+	}, overrideOptions);
+}
+function normalizeCacheOptions(defaultsOrOptions, overrideOptions) {
+	const options = {
+		...defaultsOrOptions,
+		...overrideOptions
+	};
+	return {
+		...normalizeMode(options),
+		...normalizeDurationOption("maxAge", options.maxAge),
+		...normalizeDurationOption("staleWhileRevalidate", options.staleWhileRevalidate),
+		...normalizeDurationOption("staleIfError", options.staleIfError)
+	};
+}
+function normalizeMode(options) {
+	if (options.mode && options.mode !== PUBLIC && options.mode !== PRIVATE) throw new Error("'mode' must be either 'public' or 'private'");
+	return { mode: options.mode ?? PUBLIC };
+}
+function normalizeDurationOption(name, duration) {
+	if (duration == null) return {};
+	return { [name]: normalizeDuration(duration) };
+}
+function normalizeDuration(duration) {
+	if (typeof duration === "number") return validateDuration(duration);
+	return validateDuration((duration.seconds ?? 0) + (duration.minutes ?? 0) * 60 + (duration.hours ?? 0) * 3600 + (duration.days ?? 0) * 86400);
+}
+function validateDuration(duration) {
+	if (!Number.isFinite(duration) || duration < 0) throw new Error("Cache durations must be finite, non-negative numbers.");
+	return Math.ceil(duration);
+}
+
+//#endregion
+export { Cache, NO_STORE, getCacheRetentionTtl, getPlatformCacheControlHeader };
+//# sourceMappingURL=strategies.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,50 @@
+//#region src/core/cart/actions.d.ts
+type CartAttributeInput = {
+  key: string;
+  value: string;
+};
+type CartLineAddInput = {
+  merchandiseId: string;
+  quantity: number;
+  attributes?: CartAttributeInput[];
+  sellingPlanId?: string;
+};
+type CartLineUpdateInput = {
+  id: string;
+  quantity: number;
+  attributes?: CartAttributeInput[];
+  sellingPlanId?: string;
+};
+type CartAction = {
+  intent: "add";
+  lines: CartLineAddInput[];
+} | {
+  intent: "update";
+  lines: CartLineUpdateInput[];
+} | {
+  intent: "remove";
+  lineIds: string[];
+} | {
+  intent: "discount-update";
+  discountCodes: string[];
+} | {
+  intent: "discount-apply";
+  code: string;
+} | {
+  intent: "discount-remove";
+  code: string;
+} | {
+  intent: "attributes-update";
+  attributes: CartAttributeInput[];
+} | {
+  intent: "note-update";
+  note: string;
+};
+type ParsedCartRequest = {
+  action: CartAction;
+  cartId: string | null;
+};
+declare function parseCartRequest(request: Request): Promise<ParsedCartRequest>;
+//#endregion
+export { CartAction, CartAttributeInput, CartLineAddInput, CartLineUpdateInput, parseCartRequest };
+//# sourceMappingURL=actions.d.mts.map