@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/cart/cart.mjs

@@ -23,15 +23,17 @@ const EMPTY_QUANTITY = 0;
 const FNV1A_OFFSET_BASIS = 2166136261;
 const FNV1A_PRIME = 16777619;
 const CART_REVALIDATION_ERROR_MESSAGE = "Something went wrong refreshing your cart. Please try again.";
-/** Timeout (in milliseconds) for cart loads and mutations. */
+/** The timeout in milliseconds for cart loads and mutations. */
 const STANDARD_ACTION_TIMEOUT_IN_MS = 3e4;
 /**
-* Error thrown when the cart endpoint responds with a non-2xx status.
+* The error that a cart load or cart change throws when your cart endpoint responds with a non-2xx status. Read `status` to handle specific failures.
 *
-* Carries the HTTP {@link CartNetworkError.status | status} code so callers
-* can distinguish transient failures from permanent ones.
+* Without a cart endpoint from `configureCartEndpoint`, cart requests fail with other error types.
+*
+* @publicDocs
 */
 var CartNetworkError = class extends Error {
+	/** The HTTP status code that the cart endpoint returned. */
 	status;
 	constructor(status) {
 		super("Something went wrong updating your cart. Please try again.");
@@ -554,10 +556,11 @@ function getAddErrorKeys(payload, lineIds, failure) {
 }
 function mergeServerLine(previous, next) {
 	if (!previous) return next;
-	const merchandise = next.merchandise ? {
+	const swapped = previous.merchandise?.id !== void 0 && next.merchandise?.id !== void 0 && previous.merchandise.id !== next.merchandise.id;
+	const merchandise = next.merchandise && !swapped ? {
 		...previous.merchandise,
 		...next.merchandise
-	} : previous.merchandise;
+	} : next.merchandise ?? previous.merchandise;
 	return {
 		...previous,
 		...next,
@@ -677,17 +680,21 @@ const CART_TRANSACTION_TYPES = defineTransactionTypes({
 				data: reconcileCartLines(state.data, lines)
 			};
 		},
-		projectPromise: (state, result, payload, addError) => {
+		projectPromise: (state, result, payload, addError, options) => {
 			if (hasProjectedErrors(result)) addError((current, timestampMs) => projectLineErrors(current, result, [payload.lineId], timestampMs));
 			if (!result.cart) return state;
-			const serverLines = getLines(cartResponseFromStandardEvent(result.cart));
-			const matching = serverLines.find((line) => line.id === payload.lineId);
+			const cart = cartResponseFromStandardEvent(result.cart);
+			const matching = getLines(cart).find((line) => line.id === payload.lineId);
+			if (!matching && payload.quantity > 0 && options.mergeServerCart) return {
+				...state,
+				data: adoptServerLines(state.data, cart)
+			};
 			const previous = getLines(state.data);
-			let lines = previous.filter((line) => line.id !== payload.lineId);
+			let lines = previous;
 			if (matching) {
 				const prior = previous.find((line) => line.id === payload.lineId);
 				lines = previous.map((line) => line.id === payload.lineId ? mergeServerLine(prior, matching) : line);
-			} else if (payload.quantity > 0 && previous.length === 1 && serverLines.length === 1) lines = [mergeServerLine(previous[0], serverLines[0])];
+			} else if (payload.quantity === 0) lines = previous.filter((line) => line.id !== payload.lineId);
 			return {
 				...state,
 				data: reconcileCartLines(state.data, lines)
@@ -718,14 +725,11 @@ const CART_TRANSACTION_TYPES = defineTransactionTypes({
 			if (hasProjectedErrors(result)) addError((current, timestampMs) => projectDiscountErrors(current, result, payload.discountCodes, timestampMs, resolvedCodes));
 			if (!result.cart) return state;
 			const cart = cartResponseFromStandardEvent(result.cart);
-			if (options.mergeServerCart) return {
-				...state,
-				data: mergeAuthoritativeCartData(state.data, cart)
-			};
+			const data = options.mergeServerCart ? adoptServerLines(state.data, cart) : state.data;
 			return {
 				...state,
 				data: {
-					...state.data,
+					...data,
 					discountCodes: cart.discountCodes
 				}
 			};
@@ -872,16 +876,14 @@ function trimPendingTransaction(store, type, definition, payload, promise, ident
 }
 function addSnapshotFields(state, result) {
 	if (!result.cart) return state;
-	const cart = cartResponseFromStandardEvent(result.cart);
+	const { lines: _lines, checkoutUrl, updatedAt, ...fields } = cartResponseFromStandardEvent(result.cart);
 	return {
 		...state,
 		data: {
 			...state.data,
-			id: cart.id,
-			checkoutUrl: cart.checkoutUrl ?? state.data.checkoutUrl,
-			updatedAt: cart.updatedAt ?? state.data.updatedAt,
-			totalQuantity: cart.totalQuantity,
-			cost: cart.cost
+			...fields,
+			checkoutUrl: checkoutUrl ?? state.data.checkoutUrl,
+			updatedAt: updatedAt ?? state.data.updatedAt
 		}
 	};
 }
@@ -1377,11 +1379,9 @@ function loadCartInStore(store, cartPromise) {
 	return promise;
 }
 /**
-* Creates a new {@link CartStore} for the given initial data.
+* Creates a cart store that holds the cart and applies cart changes before the server responds.
 *
-* The store is inert until {@link CartStore.connect} is called — no network
-* requests are made and no event listeners are attached at creation time.
-* Framework adapters call `connect()` on mount and `destroy()` on unmount.
+* Call `connect()` to start the store and `destroy()` to stop it. The React and Vue cart providers call both for you.
 *
 * @example
 * ```ts
@@ -1398,6 +1398,9 @@ function loadCartInStore(store, cartPromise) {
 * // Empty — loads the cart on connect()
 * const store = createCartStore();
 * ```
+* @param options The cart that the server loaded for the first render.
+* @returns The cart store. Read the cart with `getState()` and listen for changes with `subscribe()`.
+* @publicDocs
 */
 function createCartStore(options = {}) {
 	const initialData = options.initialData;
@@ -1552,15 +1555,17 @@ async function handleFormSubmitInStore(store, handlers, event, eventDetail) {
 	throw new Error(`Unknown cart form intent: "${intent}"`);
 }
 /**
-* Routes cart loads and mutations to a custom endpoint instead of the
-* Standard Actions default handler.
+* Sends every cart load and cart change on the page to your cart endpoint. Without an endpoint, Standard Actions handles cart requests with its default handler.
 *
-* Logs a warning if called again with a different endpoint.
+* Call the function before you connect a cart store. The first cart load then goes to your endpoint. A later call with a different endpoint replaces the first endpoint and logs a warning. In React, `CartProvider` sets the endpoint to `/api/cart` when the provider mounts.
 *
+* @param endpoint The URL path of your cart route.
+* @returns Nothing. Later cart loads and changes on the page go to the endpoint.
 * @example
 * ```ts
 * configureCartEndpoint("/storefront/cart");
 * ```
+* @publicDocs
 */
 function configureCartEndpoint(endpoint) {
 	if (configuredCartEndpoint === endpoint) return;
@@ -1642,6 +1647,18 @@ function fetchCartData(cartId, signal) {
 		attributes: cart.attributes ?? []
 	} : null);
 }
+function adoptServerLines(previous, authoritative) {
+	const previousLines = new Map(getLines(previous).map((line) => [line.id, line]));
+	const nodes = getLines(authoritative).map((line) => mergeServerLine(previousLines.get(line.id), line));
+	return {
+		...previous,
+		lines: {
+			...previous.lines,
+			...authoritative.lines,
+			nodes
+		}
+	};
+}
 function mergeAuthoritativeCartData(previous, authoritative) {
 	const previousLines = new Map(getLines(previous).map((line) => [line.id, line]));
 	const lines = getLines(authoritative).map((line) => mergeServerLine(previousLines.get(line.id), line));