@shopify/hydrogen 2026.4.4 → 2026.10.0-preview.1

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

package/dist/core/cart/actions.mjs

@@ -0,0 +1,240 @@
+import { normalizeCartId } from "./cookie.mjs";
+import { getCartAttributeFormEntries } from "./form.mjs";
+
+//#region src/core/cart/actions.ts
+var CartActionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CartActionError";
+	}
+};
+async function parseCartRequest(request) {
+	const contentType = request.headers.get("content-type") ?? "";
+	if (contentType.includes("application/json")) return parseJsonBody(await request.json());
+	if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) return {
+		action: parseFormData(await request.formData()),
+		cartId: null
+	};
+	throw new CartActionError(`Unsupported content-type: "${contentType}". Expected application/json or form data.`);
+}
+function parseJsonBody(body) {
+	assertObject(body);
+	const cartId = typeof body.cartId === "string" ? normalizeCartId(body.cartId) : null;
+	if ("note" in body && typeof body.note === "string") return {
+		action: {
+			intent: "note-update",
+			note: body.note
+		},
+		cartId
+	};
+	if ("discountCodes" in body && Array.isArray(body.discountCodes)) {
+		for (const code of body.discountCodes) assertString(code, "discountCodes entries");
+		return {
+			action: {
+				intent: "discount-update",
+				discountCodes: body.discountCodes
+			},
+			cartId
+		};
+	}
+	if ("attributes" in body && Array.isArray(body.attributes)) return {
+		action: {
+			intent: "attributes-update",
+			attributes: parseAttributes(body.attributes)
+		},
+		cartId
+	};
+	if (!("lines" in body) || !Array.isArray(body.lines)) throw new CartActionError("Request body must contain \"lines\", \"discountCodes\", \"attributes\", or \"note\".");
+	const lines = body.lines;
+	if (lines.length === 0) throw new CartActionError("Lines array must not be empty.");
+	return {
+		action: partitionLines(lines),
+		cartId
+	};
+}
+function partitionLines(rawLines) {
+	const adds = [];
+	const updates = [];
+	const removeIds = [];
+	for (const raw of rawLines) {
+		assertObject(raw);
+		const line = raw;
+		const hasId = "id" in line && typeof line.id === "string" && line.id !== "";
+		const hasMerchandiseId = "merchandiseId" in line && typeof line.merchandiseId === "string" && line.merchandiseId !== "";
+		assertNonNegativeInteger(line.quantity, "quantity");
+		const quantity = line.quantity;
+		if (!hasId && !hasMerchandiseId) throw new CartActionError("Each line must have either \"id\" (for update/remove) or \"merchandiseId\" (for add).");
+		if (hasId && line.id === "") throw new CartActionError("Line \"id\" must not be empty.");
+		const optionalFields = extractOptionalLineFields(line);
+		if (!hasId && hasMerchandiseId) adds.push({
+			merchandiseId: line.merchandiseId,
+			quantity,
+			...optionalFields
+		});
+		else if (hasId && quantity === 0) removeIds.push(line.id);
+		else if (hasId) updates.push({
+			id: line.id,
+			quantity,
+			...optionalFields
+		});
+	}
+	if ([
+		adds.length,
+		updates.length,
+		removeIds.length
+	].filter((n) => n > 0).length > 1) throw new CartActionError("Mixed line operations are not allowed. Separate add, update, and remove into distinct requests.");
+	if (adds.length > 0) return {
+		intent: "add",
+		lines: adds
+	};
+	if (updates.length > 0) return {
+		intent: "update",
+		lines: updates
+	};
+	return {
+		intent: "remove",
+		lineIds: removeIds
+	};
+}
+function extractOptionalLineFields(line) {
+	const result = {};
+	if ("attributes" in line && Array.isArray(line.attributes)) result.attributes = line.attributes;
+	if ("sellingPlanId" in line && typeof line.sellingPlanId === "string") result.sellingPlanId = line.sellingPlanId;
+	return result;
+}
+const LINE_INTENTS = new Set([
+	"increase",
+	"decrease",
+	"remove",
+	"set"
+]);
+const DISCOUNT_INTENTS = new Set(["discount-apply", "discount-remove"]);
+function parseFormData(form) {
+	const intent = formString(form, "intent");
+	const merchandiseId = formString(form, "merchandiseId");
+	if (!intent && merchandiseId) return parseAddIntent(form, merchandiseId);
+	if (intent === "add") {
+		if (!merchandiseId) throw new CartActionError("Intent \"add\" requires a \"merchandiseId\" field.");
+		return parseAddIntent(form, merchandiseId);
+	}
+	if (!intent) throw new CartActionError("FormData must include an \"intent\" field or a \"merchandiseId\" field.");
+	if (LINE_INTENTS.has(intent)) return parseLineIntent(intent, form);
+	if (DISCOUNT_INTENTS.has(intent)) return parseDiscountIntent(intent, form);
+	if (intent === "note-update") return parseNoteIntent(form);
+	if (intent === "attributes-update") return parseAttributesIntent(form);
+	throw new CartActionError(`Unknown intent "${intent}". Expected one of: add, increase, decrease, remove, set, discount-apply, discount-remove, attributes-update, note-update.`);
+}
+function parseLineIntent(intent, form) {
+	const lineId = formString(form, "lineId");
+	if (!lineId) throw new CartActionError(`Intent "${intent}" requires a "lineId" field.`);
+	if (intent === "remove") return {
+		intent: "remove",
+		lineIds: [lineId]
+	};
+	const quantity = formInt(form, "quantity");
+	if (quantity === null) throw new CartActionError(`Intent "${intent}" requires a "quantity" field.`);
+	if (intent === "set") {
+		if (quantity <= 0) return {
+			intent: "remove",
+			lineIds: [lineId]
+		};
+		return {
+			intent: "update",
+			lines: [{
+				id: lineId,
+				quantity
+			}]
+		};
+	}
+	if (intent === "increase") return {
+		intent: "update",
+		lines: [{
+			id: lineId,
+			quantity: quantity + 1
+		}]
+	};
+	const decremented = quantity - 1;
+	if (decremented <= 0) return {
+		intent: "remove",
+		lineIds: [lineId]
+	};
+	return {
+		intent: "update",
+		lines: [{
+			id: lineId,
+			quantity: decremented
+		}]
+	};
+}
+function parseDiscountIntent(intent, form) {
+	const code = formString(form, "discountCode");
+	if (!code) throw new CartActionError(`Intent "${intent}" requires a "discountCode" field.`);
+	return {
+		intent,
+		code
+	};
+}
+function parseAddIntent(form, merchandiseId) {
+	const quantity = formInt(form, "quantity") ?? 1;
+	const sellingPlanId = formString(form, "sellingPlanId");
+	const line = {
+		merchandiseId,
+		quantity
+	};
+	if (sellingPlanId) line.sellingPlanId = sellingPlanId;
+	return {
+		intent: "add",
+		lines: [line]
+	};
+}
+function parseNoteIntent(form) {
+	const noteValue = form.get("note");
+	if (noteValue === null) throw new CartActionError("Intent \"note-update\" requires a \"note\" field.");
+	return {
+		intent: "note-update",
+		note: String(noteValue)
+	};
+}
+function parseAttributesIntent(form) {
+	return {
+		intent: "attributes-update",
+		attributes: parseAttributes(getCartAttributeFormEntries(form))
+	};
+}
+function parseAttributes(values) {
+	return values.map((value, index) => {
+		assertObject(value);
+		assertString(value.key, `attributes[${index}].key`);
+		assertString(value.value, `attributes[${index}].value`);
+		if (!value.key) throw new CartActionError(`Expected "attributes[${index}].key" not to be empty.`);
+		return {
+			key: value.key,
+			value: value.value
+		};
+	});
+}
+function assertObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new CartActionError("Expected an object.");
+}
+function assertString(value, label) {
+	if (typeof value !== "string") throw new CartActionError(`Expected "${label}" to be a string.`);
+}
+function assertNonNegativeInteger(value, label) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new CartActionError(`Expected "${label}" to be a non-negative integer, got ${JSON.stringify(value)}.`);
+}
+function formString(form, key) {
+	const value = form.get(key);
+	if (value === null || typeof value !== "string") return null;
+	return value || null;
+}
+function formInt(form, key) {
+	const raw = form.get(key);
+	if (raw === null || typeof raw !== "string") return null;
+	const parsed = parseInt(raw, 10);
+	if (Number.isNaN(parsed)) return null;
+	return parsed;
+}
+
+//#endregion
+export { parseCartRequest };
+//# sourceMappingURL=actions.mjs.map