[2025-10] Document updated cartDeliveryAddressesUpdate empty array behavior

[juanpprieto]

WHY are these changes introduced?

Fixes #3273

Shopify Storefront API 2025-10 changed cartDeliveryAddressesUpdate mutation to explicitly clear all delivery addresses when passed an empty array. This behavior was undefined in previous API versions.

Investigation Summary

Root Cause: API contract evolution + documentation gap (not a code defect)

Key Findings:

• Hydrogen implementation is correct - thin wrapper properly delegates to API
• Zero current impact - skeleton/cookbook don't use this feature
• Tests were using empty arrays but not validating address state
• Empty array clearing is consistent with mutation family semantics

Conclusion: Documentation and test updates only. No code changes required.

WHAT is this pull request doing?

Changes Made (TDD Approach)

1. Added Failing Tests (Commit 40b8ff688)

• Tests requiring documentation of empty array behavior
• Result: 2 failed, 7 passed ❌

2. Updated Documentation (Commit 71b887210)

• JSDoc explains empty array clears addresses (API 2025-10+)
• Added two @example blocks: clear vs update
• Result: All 9 tests passing ✅

3. Added Edge Case Tests (Commit 804c6fa6e)

• 5 comprehensive edge cases
• Result: All 14 tests passing ✅

4. Created Changeset (Commit 2864a669d)

• Comprehensive migration guide
• Before/After code examples
• User-facing documentation

Test Coverage Added

14 tests total (from 2 tests):

• Empty array behavior (2 tests)
• With delivery addresses (2 tests)
• CartFragment override (1 test)
• Mutation structure (2 tests)
• Documentation completeness (2 tests)
• Edge cases (5 tests):
  • Minimal required fields
  • Customer address reference
  • i18n parameters
  • Single vs multiple addresses
  • Full address fields

Documentation Updates

JSDoc Changes:

// BEFORE
/**
 * Updates delivery addresses in the cart.
 */

// AFTER
/**
 * Updates delivery addresses in the cart.
 *
 * Pass an empty array to clear all delivery addresses (API 2025-10+).
 *
 * @example Clear all delivery addresses
 * await updateAddresses([]);
 *
 * @example Update specific addresses
 * await updateAddresses([{...}]);
 */

HOW to test your changes?

Run Tests

cd packages/hydrogen
npm test -- src/cart/queries/cartDeliveryAddressesUpdateDefault.test.ts

Expected: All 14 tests pass

Verify Documentation

# Check JSDoc includes empty array behavior
grep -A 10 "Pass an empty array" packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.tsx

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation

[shopify]

Oxygen deployed a preview of your fix-3273-delivery-address-empty-array branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 20, 202612:04 PM
third-party-queries-caching	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 20, 202612:05 PM
custom-cart-method	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 20, 202612:05 PM
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 20, 202612:05 PM
sitemap	✅ Successful (Logs)	Preview deployment	Inspect deployment	January 20, 202612:05 PM

Learn more about Hydrogen's GitHub integration.

[Copilot]

Pull Request Overview

This PR documents the API behavior change in Shopify Storefront API 2025-10 where cartDeliveryAddressesUpdate now explicitly clears all delivery addresses when passed an empty array. The changes include updated JSDoc comments with examples and comprehensive test coverage to validate the documented behavior.

Key changes:

• Enhanced JSDoc with empty array clearing behavior and dual examples (clear vs update)
• Added 12 new tests covering empty arrays, multiple addresses, edge cases, and documentation validation
• Created changeset with migration guide for users upgrading to API 2025-10+

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.tsx	Updated JSDoc to document empty array behavior and added clear/update examples
packages/hydrogen/src/cart/queries/cartDeliveryAddressesUpdateDefault.test.ts	Added 12 tests covering empty arrays, addresses updates, mutation structure, documentation, and edge cases
.changeset/delivery-address-empty-array-docs.md	Created migration guide documenting API 2025-10 breaking behavior change

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[github-actions]

This pull request has been marked as stale due to inactivity for 60 days. If no further activity occurs, it will be closed in 7 days.

[fredericoo]

• [2025-10] Document updated cartDeliveryAddressesUpdate empty array behavior #3283 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.