chore: document updated cartDeliveryAddressesUpdate empty array behavior

fredericoo · fredericoo · commit 1767edfb31b6 · 2026-01-20T12:52:16.000Z
diff --git a/.changeset/delivery-address-empty-array-docs.md b/.changeset/delivery-address-empty-array-docs.md
@@ -0,0 +1,85 @@
+---
+'@shopify/hydrogen': patch
+---
+
+Document `cartDeliveryAddressesUpdate` empty array behavior for API 2025-10+
+
+## Breaking Behavior Change in Storefront API 2025-10
+
+The `cartDeliveryAddressesUpdate` mutation now clears all delivery addresses when passed an empty array. This behavior was undefined in previous API versions.
+
+## What Changed
+
+**Before (API ≤ 2025-07):**
+Passing an empty array had undefined behavior (likely ignored or caused an error).
+
+**After (API ≥ 2025-10):**
+Passing an empty array explicitly clears all delivery addresses from the cart.
+
+## Usage Examples
+
+### Clearing All Delivery Addresses
+
+**New in 2025-10** - Use empty array to clear addresses:
+
+```typescript
+import {createCartHandler} from '@shopify/hydrogen';
+
+export async function action({context}) {
+  const cartHandler = createCartHandler({
+    storefront: context.storefront,
+    getCartId: context.cart.getCartId,
+  });
+
+  // Clear all delivery addresses from cart
+  const result = await cartHandler.updateDeliveryAddresses([]);
+
+  return result;
+}
+```
+
+### Updating Specific Addresses
+
+Standard usage remains unchanged:
+
+```typescript
+// Update delivery addresses with new address
+const result = await cartHandler.updateDeliveryAddresses([
+  {
+    id: 'gid://shopify/CartSelectableAddress/existing-address',
+    selected: true,
+    address: {
+      deliveryAddress: {
+        address1: '123 Main Street',
+        city: 'New York',
+        countryCode: 'US',
+        zip: '10001',
+      },
+    },
+  },
+]);
+```
+
+### Migration Guide
+
+**If you're passing empty arrays:**
+
+```typescript
+// BEFORE: This had undefined behavior
+await cartHandler.updateDeliveryAddresses([]);
+
+// AFTER (2025-10): This now clears all addresses
+await cartHandler.updateDeliveryAddresses([]);
+// ⚠️ Verify this is your intended behavior!
+```
+
+**If you want to clear addresses:**
+
+```typescript
+// BEFORE (workaround): Had to remove addresses individually
+const addressIds = cart.delivery.addresses.map((addr) => addr.id);
+await cartHandler.removeDeliveryAddresses(addressIds);
+
+// AFTER (2025-10): Simply pass empty array
+await cartHandler.updateDeliveryAddresses([]);
+```
diff --git a/packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.test.ts b/packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.test.ts
@@ -1,30 +1,277 @@
 import {describe, it, expect} from 'vitest';
 import {CART_ID, mockCreateStorefrontClient} from '../cart-test-helper';
-import {cartDeliveryAddressesUpdateDefault} from './cartDeliveryAddressesUpdateDefault';
+import {
+  cartDeliveryAddressesUpdateDefault,
+  CART_DELIVERY_ADDRESSES_UPDATE_MUTATION,
+} from './cartDeliveryAddressesUpdateDefault';
+import {CartSelectableAddressUpdateInput} from '@shopify/hydrogen-react/storefront-api-types';
 
 describe('cartDeliveryAddressesUpdateDefault', () => {
-  it('should return a default cart delivery address update implementation', async () => {
-    const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
-      storefront: mockCreateStorefrontClient(),
-      getCartId: () => CART_ID,
+  describe('empty array behavior (API 2025-10+)', () => {
+    it('should document that passing empty array clears all delivery addresses', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      const result = await updateDeliveryAddresses([]);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+    });
+
+    it('should accept empty array as valid input per API 2025-10 semantics', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      await expect(updateDeliveryAddresses([])).resolves.toBeDefined();
+    });
+  });
+
+  describe('with delivery addresses', () => {
+    it('should update delivery addresses when addresses provided', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      const mockAddress: CartSelectableAddressUpdateInput = {
+        id: 'gid://shopify/CartSelectableAddress/test-123',
+        selected: true,
+        address: {
+          deliveryAddress: {
+            address1: '123 Test Street',
+            city: 'Test City',
+            countryCode: 'US',
+            zip: '12345',
+          },
+        },
+      };
+
+      const result = await updateDeliveryAddresses([mockAddress]);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
     });
 
-    const result = await updateDeliveryAddresses([]);
+    it('should handle multiple addresses in single update', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
 
-    expect(result.cart).toHaveProperty('id', CART_ID);
+      const addresses: Array<CartSelectableAddressUpdateInput> = [
+        {
+          id: 'gid://shopify/CartSelectableAddress/addr-1',
+          selected: true,
+          address: {
+            deliveryAddress: {
+              address1: '123 Main St',
+              city: 'NYC',
+              countryCode: 'US',
+              zip: '10001',
+            },
+          },
+        },
+        {
+          id: 'gid://shopify/CartSelectableAddress/addr-2',
+          selected: false,
+          address: {
+            deliveryAddress: {
+              address1: '456 Broadway',
+              city: 'NYC',
+              countryCode: 'US',
+              zip: '10002',
+            },
+          },
+        },
+      ];
+
+      const result = await updateDeliveryAddresses(addresses);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+    });
   });
 
-  it('can override cartFragment', async () => {
-    const cartFragment = 'cartFragmentOverride';
-    const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
-      storefront: mockCreateStorefrontClient(),
-      getCartId: () => CART_ID,
-      cartFragment,
+  describe('cartFragment override', () => {
+    it('can override cartFragment for custom query fields', async () => {
+      const cartFragment = 'cartFragmentOverride';
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+        cartFragment,
+      });
+
+      const result = await updateDeliveryAddresses([]);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+      expect(result.userErrors?.[0]).toContain(cartFragment);
+    });
+  });
+
+  describe('mutation structure', () => {
+    it('should include required mutation fields for error and warning handling', () => {
+      const mutation = CART_DELIVERY_ADDRESSES_UPDATE_MUTATION();
+
+      expect(mutation).toContain('cartDeliveryAddressesUpdate');
+      expect(mutation).toContain('userErrors');
+      expect(mutation).toContain('warnings');
+      expect(mutation).toContain('CartApiError');
+      expect(mutation).toContain('CartApiWarning');
+    });
+
+    it('should include @inContext directive for internationalization', () => {
+      const mutation = CART_DELIVERY_ADDRESSES_UPDATE_MUTATION();
+
+      expect(mutation).toContain('@inContext');
+      expect(mutation).toContain('$country');
+      expect(mutation).toContain('$language');
+    });
+  });
+
+  describe('documentation completeness', () => {
+    it('should document empty array behavior in JSDoc', async () => {
+      const fs = await import('fs');
+      const path = await import('path');
+      const functionFile = fs.readFileSync(
+        path.join(__dirname, 'cartDeliveryAddressesUpdateDefault.tsx'),
+        'utf-8',
+      );
+
+      expect(functionFile).toContain('empty array');
+      expect(functionFile).toContain('clear');
+      expect(functionFile).toContain('2025-10');
     });
 
-    const result = await updateDeliveryAddresses([]);
+    it('should include example of clearing addresses with empty array', async () => {
+      const fs = await import('fs');
+      const path = await import('path');
+      const functionFile = fs.readFileSync(
+        path.join(__dirname, 'cartDeliveryAddressesUpdateDefault.tsx'),
+        'utf-8',
+      );
 
-    expect(result.cart).toHaveProperty('id', CART_ID);
-    expect(result.userErrors?.[0]).toContain(cartFragment);
+      expect(functionFile).toMatch(/example.*clear/i);
+      expect(functionFile).toContain('updateAddresses([])');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle address with only required fields', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      const minimalAddress: CartSelectableAddressUpdateInput = {
+        id: 'gid://shopify/CartSelectableAddress/minimal',
+        selected: true,
+        address: {
+          deliveryAddress: {
+            address1: '123 Main',
+            city: 'NYC',
+            countryCode: 'US',
+            zip: '10001',
+          },
+        },
+      };
+
+      const result = await updateDeliveryAddresses([minimalAddress]);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+    });
+
+    it('should handle address with copyFromCustomerAddressId instead of deliveryAddress', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      const customerAddress = {
+        id: 'gid://shopify/CartSelectableAddress/test',
+        selected: true,
+        address: {
+          copyFromCustomerAddressId:
+            'gid://shopify/MailingAddress/123?model_name=CustomerAddress',
+        },
+      };
+
+      const result = await updateDeliveryAddresses([customerAddress]);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+    });
+
+    it('should handle optional parameters like country and language', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      const result = await updateDeliveryAddresses([], {
+        country: 'CA',
+        language: 'FR',
+      });
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+    });
+
+    it('should handle single address update', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      const singleAddress = [
+        {
+          id: 'gid://shopify/CartSelectableAddress/single',
+          selected: true,
+          oneTimeUse: false,
+          address: {
+            deliveryAddress: {
+              address1: 'Single Street',
+              city: 'Solo City',
+              countryCode: 'US' as const,
+              zip: '99999',
+            },
+          },
+        },
+      ];
+
+      const result = await updateDeliveryAddresses(singleAddress);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+    });
+
+    it('should handle address with all optional fields', async () => {
+      const updateDeliveryAddresses = cartDeliveryAddressesUpdateDefault({
+        storefront: mockCreateStorefrontClient(),
+        getCartId: () => CART_ID,
+      });
+
+      const fullAddress: CartSelectableAddressUpdateInput = {
+        id: 'gid://shopify/CartSelectableAddress/full',
+        selected: true,
+        oneTimeUse: true,
+        validationStrategy: 'COUNTRY_CODE_ONLY',
+        address: {
+          deliveryAddress: {
+            firstName: 'John',
+            lastName: 'Doe',
+            company: 'Acme Corp',
+            address1: '123 Main St',
+            address2: 'Apt 4B',
+            city: 'New York',
+            provinceCode: 'NY',
+            countryCode: 'US',
+            zip: '10001',
+            phone: '+1234567890',
+          },
+        },
+      };
+
+      const result = await updateDeliveryAddresses([fullAddress]);
+
+      expect(result.cart).toHaveProperty('id', CART_ID);
+    });
   });
 });
diff --git a/packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.tsx b/packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.tsx
