@shopify/hydrogen 2026.4.4 → 2026.10.0-preview.1

package/dist/core/analytics/types.d.mts

@@ -0,0 +1,143 @@
+import { AnalyticsEventName } from "./events.mjs";
+import { ShopifyScriptsShop } from "../shopify-scripts/types.mjs";
+
+//#region src/core/analytics/types.d.ts
+type ShopAnalyticsBase = Pick<ShopifyScriptsShop, "shopId">;
+type ShopAnalyticsChannel = "hydrogen" | "headless";
+type ShopAnalytics = (ShopAnalyticsBase & {
+  channel: "hydrogen";
+  storefrontId: ShopifyScriptsShop["storefrontId"];
+}) | (ShopAnalyticsBase & {
+  channel: "headless";
+  storefrontId?: never;
+});
+type ConsentConfig = {
+  mode?: "default-banner" | "custom-banner" | "no-banner";
+};
+type AnalyticsCartLine = {
+  id: string;
+  quantity: number;
+  merchandise: {
+    id: string;
+    title: string;
+    price: {
+      amount: string;
+      currencyCode?: string;
+    };
+    sku?: string | null;
+    product: {
+      id: string;
+      title: string;
+      vendor: string;
+      productType?: string;
+      handle?: string;
+    };
+  };
+};
+type AnalyticsCart = {
+  id: string;
+  updatedAt: string;
+  cost?: {
+    subtotalAmount?: {
+      currencyCode?: string;
+    };
+    totalAmount?: {
+      currencyCode?: string;
+    };
+  };
+  lines: {
+    nodes?: AnalyticsCartLine[];
+    edges?: Array<{
+      node: AnalyticsCartLine;
+    }>;
+  };
+  [key: string]: unknown;
+};
+type OtherData = {
+  [key: string]: unknown;
+};
+type BasePayload = {
+  shop?: ShopAnalytics | null;
+  customData?: Record<string, unknown>;
+};
+type UrlPayload = {
+  url?: string;
+};
+type ProductPayload = {
+  id: string;
+  title: string;
+  price: string;
+  vendor: string;
+  variantId: string;
+  variantTitle: string;
+  quantity: number;
+  sku?: string | null;
+  productType?: string;
+};
+type ProductsPayload = {
+  products: Array<ProductPayload & OtherData>;
+};
+type CollectionPayload = {
+  collection: {
+    id: string;
+    handle: string;
+  };
+};
+type SearchPayload = {
+  searchTerm: string;
+  searchResults?: unknown;
+};
+type CartPayload = {
+  cart: AnalyticsCart | null;
+};
+type CartChangePayload = CartPayload & {
+  prevCart: AnalyticsCart | null;
+};
+type CartLinePayload = {
+  prevLine?: AnalyticsCartLine;
+  currentLine?: AnalyticsCartLine;
+};
+type PageViewPayload = UrlPayload & BasePayload;
+type ProductViewPayload = ProductsPayload & UrlPayload & BasePayload;
+type CollectionViewPayload = CollectionPayload & UrlPayload & BasePayload;
+type CartViewPayload = CartPayload & UrlPayload & BasePayload;
+type SearchViewPayload = SearchPayload & UrlPayload & BasePayload;
+type CartUpdatePayload = CartChangePayload & BasePayload & OtherData;
+type CartLineUpdatePayload = CartLinePayload & CartChangePayload & BasePayload & OtherData;
+type EventPayloads = PageViewPayload | ProductViewPayload | CollectionViewPayload | CartViewPayload | SearchViewPayload | CartUpdatePayload | CartLineUpdatePayload;
+interface AnalyticsEventMap {
+  page_viewed: PageViewPayload;
+  product_viewed: ProductViewPayload;
+  collection_viewed: CollectionViewPayload;
+  cart_viewed: CartViewPayload;
+  search_viewed: SearchViewPayload;
+  cart_updated: CartUpdatePayload;
+  product_added_to_cart: CartLineUpdatePayload;
+  product_removed_from_cart: CartLineUpdatePayload;
+}
+/** Resolves the payload type for a supported analytics event name. */
+type PayloadFor<E extends AnalyticsEventName> = AnalyticsEventMap[E];
+type PublishPayloadArgs<E extends AnalyticsEventName> = {} extends PayloadFor<E> ? [payload?: PayloadFor<E>] : [payload: PayloadFor<E>];
+type StorefrontAnalyticsConfig = {
+  shop: ShopAnalytics | null;
+  consent: ConsentConfig;
+  customData?: Record<string, unknown>;
+};
+type StorefrontAnalyticsDestinationSetupContext = {
+  subscribe: <E extends AnalyticsEventName>(event: E, callback: (payload: PayloadFor<E>) => void) => () => void;
+  getConfig: () => StorefrontAnalyticsConfig;
+};
+type StorefrontAnalyticsDestination = {
+  name: string;
+  setup: (context: StorefrontAnalyticsDestinationSetupContext) => void | (() => void) | Promise<void | (() => void)>;
+};
+type StorefrontAnalytics = {
+  publish: <E extends AnalyticsEventName>(event: E, ...payload: PublishPayloadArgs<E>) => void; /** Listen for live analytics events. Destination integrations should use `addDestination()`. */
+  subscribe: <E extends AnalyticsEventName>(event: E, callback: (payload: PayloadFor<E>) => void) => () => void;
+  addDestination: (destination: StorefrontAnalyticsDestination) => () => void;
+  destroy: () => void;
+  getConfig: () => StorefrontAnalyticsConfig;
+};
+//#endregion
+export { AnalyticsCart, AnalyticsCartLine, AnalyticsEventMap, CartLineUpdatePayload, CartUpdatePayload, CartViewPayload, CollectionViewPayload, ConsentConfig, EventPayloads, OtherData, PageViewPayload, PayloadFor, ProductPayload, ProductViewPayload, SearchViewPayload, ShopAnalytics, ShopAnalyticsChannel, StorefrontAnalytics, StorefrontAnalyticsConfig, StorefrontAnalyticsDestination, StorefrontAnalyticsDestinationSetupContext };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1,19 @@
+//#region src/core/analytics/utils/flatten-connection.d.ts
+/**
+ * Normalizes Shopify's GraphQL connection format into a flat array.
+ *
+ * Shopify's Storefront API returns list fields (like cart `lines`) in a
+ * "connection" wrapper — either `{ nodes: [...] }` or `{ edges: [{ node: ... }] }`.
+ * Hydrogen queries typically use `nodes`, but queries written with the `edges`
+ * pattern are supported too.
+ */
+type Connection<T> = {
+  nodes?: T[];
+  edges?: Array<{
+    node: T;
+  }>;
+};
+declare function flattenConnection<T>(connection?: Connection<T> | null): T[];
+//#endregion
+export { flattenConnection };
+//# sourceMappingURL=flatten-connection.d.mts.map

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

@@ -0,0 +1,25 @@
+import { getLogger } from "../../logging/logging.mjs";
+
+//#region src/core/analytics/utils/flatten-connection.ts
+/**
+* Normalizes Shopify's GraphQL connection format into a flat array.
+*
+* Shopify's Storefront API returns list fields (like cart `lines`) in a
+* "connection" wrapper — either `{ nodes: [...] }` or `{ edges: [{ node: ... }] }`.
+* Hydrogen queries typically use `nodes`, but queries written with the `edges`
+* pattern are supported too.
+*/
+const log = getLogger("analytics");
+function flattenConnection(connection) {
+	if (!connection) {
+		if (connection === null) log.warn("received null connection; expected an object with `nodes` or `edges`");
+		return [];
+	}
+	if ("nodes" in connection && connection.nodes) return connection.nodes;
+	if ("edges" in connection && Array.isArray(connection.edges)) return connection.edges.map((edge) => edge.node);
+	return [];
+}
+
+//#endregion
+export { flattenConnection };
+//# sourceMappingURL=flatten-connection.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flatten-connection.mjs","names":[],"sources":["../../../../src/core/analytics/utils/flatten-connection.ts"],"sourcesContent":["/**\n * Normalizes Shopify's GraphQL connection format into a flat array.\n *\n * Shopify's Storefront API returns list fields (like cart `lines`) in a\n * \"connection\" wrapper — either `{ nodes: [...] }` or `{ edges: [{ node: ... }] }`.\n * Hydrogen queries typically use `nodes`, but queries written with the `edges`\n * pattern are supported too.\n */\n\nimport { getLogger } from \"../../logging\";\n\nconst log = getLogger(\"analytics\");\n\ntype Connection<T> = {\n  nodes?: T[];\n  edges?: Array<{ node: T }>;\n};\n\nexport function flattenConnection<T>(connection?: Connection<T> | null): T[] {\n  if (!connection) {\n    if (connection === null) {\n      log.warn(\"received null connection; expected an object with `nodes` or `edges`\");\n    }\n    return [];\n  }\n\n  if (\"nodes\" in connection && connection.nodes) {\n    return connection.nodes;\n  }\n\n  if (\"edges\" in connection && Array.isArray(connection.edges)) {\n    return connection.edges.map((edge) => edge.node);\n  }\n\n  return [];\n}\n"],"mappings":";;;;;;;;;;;AAWA,MAAM,MAAM,UAAU,YAAY;AAOlC,SAAgB,kBAAqB,YAAwC;AAC3E,KAAI,CAAC,YAAY;AACf,MAAI,eAAe,KACjB,KAAI,KAAK,uEAAuE;AAElF,SAAO,EAAE;;AAGX,KAAI,WAAW,cAAc,WAAW,MACtC,QAAO,WAAW;AAGpB,KAAI,WAAW,cAAc,MAAM,QAAQ,WAAW,MAAM,CAC1D,QAAO,WAAW,MAAM,KAAK,SAAS,KAAK,KAAK;AAGlD,QAAO,EAAE"}

package/dist/core/cache/cache-status.mjs

@@ -0,0 +1,17 @@
+//#region src/core/cache/cache-status.ts
+const HYDROGEN_CACHE_STATUS_PRODUCT = "Hydrogen";
+function getHydrogenCacheStatus(headers) {
+	const cacheStatus = headers.get("cache-status");
+	if (!cacheStatus) return void 0;
+	for (const member of cacheStatus.split(",")) {
+		const [product, ...parameters] = member.split(";").map((part) => part.trim());
+		if (product !== "Hydrogen") continue;
+		if (parameters.includes("hit")) return "hit";
+		if (parameters.some((parameter) => parameter.startsWith("fwd=bypass"))) return "bypass";
+		if (parameters.some((parameter) => parameter.startsWith("fwd="))) return "miss";
+	}
+}
+
+//#endregion
+export { HYDROGEN_CACHE_STATUS_PRODUCT, getHydrogenCacheStatus };
+//# sourceMappingURL=cache-status.mjs.map

package/dist/core/cache/cache-status.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-status.mjs","names":[],"sources":["../../../src/core/cache/cache-status.ts"],"sourcesContent":["export const HYDROGEN_CACHE_STATUS_PRODUCT = \"Hydrogen\";\n\ntype HydrogenCacheStatus = \"hit\" | \"miss\" | \"bypass\";\n\nexport function getHydrogenCacheStatus(headers: Headers): HydrogenCacheStatus | undefined {\n  const cacheStatus = headers.get(\"cache-status\");\n  if (!cacheStatus) return undefined;\n\n  for (const member of cacheStatus.split(\",\")) {\n    const [product, ...parameters] = member.split(\";\").map((part) => part.trim());\n    if (product !== HYDROGEN_CACHE_STATUS_PRODUCT) continue;\n\n    if (parameters.includes(\"hit\")) return \"hit\";\n    if (parameters.some((parameter) => parameter.startsWith(\"fwd=bypass\"))) return \"bypass\";\n    if (parameters.some((parameter) => parameter.startsWith(\"fwd=\"))) return \"miss\";\n  }\n\n  return undefined;\n}\n"],"mappings":";AAAA,MAAa,gCAAgC;AAI7C,SAAgB,uBAAuB,SAAmD;CACxF,MAAM,cAAc,QAAQ,IAAI,eAAe;AAC/C,KAAI,CAAC,YAAa,QAAO;AAEzB,MAAK,MAAM,UAAU,YAAY,MAAM,IAAI,EAAE;EAC3C,MAAM,CAAC,SAAS,GAAG,cAAc,OAAO,MAAM,IAAI,CAAC,KAAK,SAAS,KAAK,MAAM,CAAC;AAC7E,MAAI,uBAA2C;AAE/C,MAAI,WAAW,SAAS,MAAM,CAAE,QAAO;AACvC,MAAI,WAAW,MAAM,cAAc,UAAU,WAAW,aAAa,CAAC,CAAE,QAAO;AAC/E,MAAI,WAAW,MAAM,cAAc,UAAU,WAAW,OAAO,CAAC,CAAE,QAAO"}

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

@@ -0,0 +1,43 @@
+import { CacheKey } from "./key.mjs";
+import { CachingStrategy } from "./strategies.mjs";
+import { CreateRunWithCacheOptions, RunWithCache } from "./run-with-cache.mjs";
+
+//#region src/core/cache/fetch-with-cache.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type FetchInput = Parameters<typeof fetch>[0];
+type FetchInit = Parameters<typeof fetch>[1];
+type FetchCacheResponseContext = {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  url: string;
+  text(): Promise<string>;
+  json?: () => Promise<unknown>;
+};
+type FetchCacheOptions = {
+  key: CacheKey;
+  strategy: CachingStrategy;
+  annotateCacheStatus?: boolean;
+  /**
+   * Runs only for OK responses with text-serializable bodies. Non-OK responses
+   * and binary/streaming responses are never cached.
+   */
+  shouldCacheResponse?: (context: FetchCacheResponseContext) => MaybePromise<boolean>;
+};
+type FetchWithCache = {
+  (input: FetchInput, init?: FetchInit): Promise<Response>;
+  (input: FetchInput, init: FetchInit | undefined, options: FetchCacheOptions): Promise<Response>;
+};
+type CreateFetchWithCacheOptions = (CreateRunWithCacheOptions | {
+  runWithCache: RunWithCache;
+}) & {
+  fetch?: typeof fetch;
+};
+declare function createFetchWithCache({
+  fetch: customFetch,
+  ...options
+}: CreateFetchWithCacheOptions): FetchWithCache;
+//#endregion
+export { createFetchWithCache };
+//# sourceMappingURL=fetch-with-cache.d.mts.map

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

@@ -0,0 +1,188 @@
+import { HYDROGEN_CACHE_STATUS_PRODUCT } from "./cache-status.mjs";
+import { NO_STORE } from "./strategies.mjs";
+import { StaleFallbackDisabledError, createRunWithCache } from "./run-with-cache.mjs";
+
+//#region src/core/cache/fetch-with-cache.ts
+const excludedCachedResponseHeaders = new Set(["set-cookie", "server-timing"]);
+const staleIfErrorStatuses = new Set([
+	500,
+	502,
+	503,
+	504
+]);
+var UnserializableResponseError = class extends StaleFallbackDisabledError {
+	constructor() {
+		super("Response body is not serializable for cache.");
+	}
+};
+var StaleFallbackEligibleResponseError = class extends Error {
+	constructor() {
+		super("Origin returned an unserializable response eligible for stale-if-error fallback.");
+	}
+};
+var ServerResponseError = class extends Error {
+	response;
+	constructor(response) {
+		super("Origin returned a response eligible for stale-if-error fallback.");
+		this.response = response;
+	}
+};
+function createFetchWithCache({ fetch: customFetch, ...options }) {
+	const resolvedFetch = customFetch ?? globalThis.fetch;
+	const runWithCache = "runWithCache" in options ? options.runWithCache : createRunWithCache(options);
+	return async function fetchWithCache(input, init, cacheOptions) {
+		if (!cacheOptions) return resolvedFetch(input, init);
+		if (cacheOptions.strategy.mode === "no-store") return annotateResponse(await resolvedFetch(input, init), getCacheStatusHeader("fwd=bypass"), cacheOptions);
+		let passthroughResponse;
+		let result;
+		try {
+			result = await runWithCache({
+				key: cacheOptions.key,
+				strategy: cacheOptions.strategy
+			}, async () => {
+				const response = await resolvedFetch(input, init);
+				if (!response.ok) {
+					if (isStaleIfErrorStatus(response.status)) {
+						if (!canSerializeBodyAsText(response)) {
+							passthroughResponse = response;
+							throw new StaleFallbackEligibleResponseError();
+						}
+						throw new ServerResponseError(await serializeResponse(response, {
+							cacheable: false,
+							fallbackOnError: true
+						}));
+					}
+					return {
+						data: await serializeResponse(response, {
+							cacheable: false,
+							fallbackOnError: true
+						}),
+						shouldCache: false
+					};
+				}
+				if (!canSerializeBodyAsText(response)) {
+					passthroughResponse = response;
+					throw new UnserializableResponseError();
+				}
+				const bodyReader = createBodyReader(response);
+				if (!await shouldCacheResponse(response, bodyReader, cacheOptions)) return {
+					data: await serializeResponse(response, {
+						bodyReader,
+						cacheable: false,
+						fallbackOnError: true
+					}),
+					shouldCache: false
+				};
+				const data = await serializeResponse(response, {
+					bodyReader,
+					cacheable: true,
+					fallbackOnError: true
+				});
+				return {
+					data,
+					shouldCache: data.cacheable
+				};
+			});
+		} catch (error) {
+			if (error instanceof ServerResponseError) return annotateResponse(fromSerializableResponse(error.response), getCacheStatusHeader("fwd=bypass"), cacheOptions);
+			if (error instanceof UnserializableResponseError) return annotateResponse(passthroughResponse ?? await resolvedFetch(input, init), getCacheStatusHeader("fwd=bypass"), cacheOptions);
+			if (error instanceof StaleFallbackEligibleResponseError) return annotateResponse(passthroughResponse ?? await resolvedFetch(input, init), getCacheStatusHeader("fwd=bypass"), cacheOptions);
+			throw error;
+		}
+		return annotateResponse(fromSerializableResponse(result.data), result.cacheStatus === "hit" ? getCacheStatusHeader("hit") : getNonHitCacheStatusHeader(result.data.cacheable, result.cacheStatus), cacheOptions);
+	};
+}
+function shouldCacheResponse(response, bodyReader, options) {
+	const context = {
+		ok: response.ok,
+		status: response.status,
+		statusText: response.statusText,
+		headers: new Headers(response.headers),
+		url: response.url,
+		text: bodyReader.text
+	};
+	if (isJsonResponse(response)) context.json = bodyReader.json;
+	return options.shouldCacheResponse?.(context) ?? true;
+}
+function createBodyReader(response) {
+	let bodyText;
+	let bodyJson;
+	const text = () => {
+		bodyText ??= response.text();
+		return bodyText;
+	};
+	return {
+		text,
+		json() {
+			bodyJson ??= text().then((value) => JSON.parse(value));
+			return bodyJson;
+		}
+	};
+}
+async function serializeResponse(response, { bodyReader, cacheable, fallbackOnError = false }) {
+	if (!canSerializeBodyAsText(response)) return emptySerializableResponse(response);
+	try {
+		return {
+			body: await (bodyReader ?? createBodyReader(response)).text(),
+			cacheable,
+			headers: getSerializableHeaders(response.headers, cacheable),
+			status: response.status,
+			statusText: response.statusText
+		};
+	} catch (error) {
+		if (!fallbackOnError) throw error;
+		return emptySerializableResponse(response);
+	}
+}
+function fromSerializableResponse(response) {
+	return new Response(response.body, {
+		headers: response.headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+function emptySerializableResponse(response) {
+	return {
+		body: "",
+		cacheable: false,
+		headers: [],
+		status: response.status,
+		statusText: response.statusText
+	};
+}
+function getSerializableHeaders(headers, cacheable) {
+	if (!cacheable) return [...headers];
+	return [...headers].filter(([key]) => !excludedCachedResponseHeaders.has(key.toLowerCase()));
+}
+function annotateResponse(response, cacheStatus, options) {
+	if (options.annotateCacheStatus === false) return response;
+	const headers = new Headers(response.headers);
+	headers.append("Cache-Status", cacheStatus);
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+function getNonHitCacheStatusHeader(shouldCache, cacheStatus) {
+	if (cacheStatus === "bypass") return getCacheStatusHeader("fwd=bypass");
+	return shouldCache ? getCacheStatusHeader("fwd=uri-miss; stored") : getCacheStatusHeader("fwd=bypass");
+}
+function getCacheStatusHeader(value) {
+	return `${HYDROGEN_CACHE_STATUS_PRODUCT}; ${value}`;
+}
+function isJsonResponse(response) {
+	return response.headers.get("content-type")?.toLowerCase().includes("json") ?? false;
+}
+function isStaleIfErrorStatus(status) {
+	return staleIfErrorStatuses.has(status);
+}
+function canSerializeBodyAsText(response) {
+	if (response.body == null) return true;
+	const contentType = response.headers.get("content-type");
+	return contentType != null && /\b(json|text|xml|html|graphql|javascript)\b/i.test(contentType);
+}
+
+//#endregion
+export { createFetchWithCache };
+//# sourceMappingURL=fetch-with-cache.mjs.map

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