From fc5d69db2d74b8eb65f360e7b1f1a814d5f856a5 Mon Sep 17 00:00:00 2001 From: andromia3 Date: Tue, 14 Apr 2026 16:44:07 +0100 Subject: [PATCH] fix(hydrogen): remove wrong JSDoc @param/@returns on HydrogenCart delivery-address fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The four delivery-address fields on HydrogenCart (addDeliveryAddresses, removeDeliveryAddresses, updateDeliveryAddresses, replaceDeliveryAddresses) had JSDoc blocks copy-pasted from the factory functions in `packages/hydrogen/src/cart/queries/cartDeliveryAddresses*`. The factory functions take `(options: CartQueryOptions)` and return the invokable method, but the fields on HydrogenCart are the already-built methods — they take `(addresses, optionalParams?)` and return `Promise`. So every `@param {CartQueryOptions} options` and `@returns {...Function}` tag on these fields was describing the wrong function, and that wrong text surfaces in IDE hovers and in the Shopify.dev reference docs generated from this file. Removed the four wrong `@param`/`@returns` pairs. Kept the description paragraphs and `@example` blocks, which accurately describe the invokable methods. TypeScript's inferred types already provide the correct parameter/return info for IDE tooltips. Also updated the mirrored source text inside `packages/hydrogen/docs/generated/generated_docs_data.json` so the committed generated docs stay in sync with the source. The five remaining `"The options for the cart query"` strings in that file describe the factory functions themselves and are correct. --- .../hydrogen/docs/generated/generated_docs_data.json | 2 +- packages/hydrogen/src/cart/createCartHandler.ts | 12 ------------ 2 files changed, 1 insertion(+), 13 deletions(-) diff --git a/packages/hydrogen/docs/generated/generated_docs_data.json b/packages/hydrogen/docs/generated/generated_docs_data.json index 2a85f2f840..9e286cd085 100644 --- a/packages/hydrogen/docs/generated/generated_docs_data.json +++ b/packages/hydrogen/docs/generated/generated_docs_data.json @@ -24400,7 +24400,7 @@ "filePath": "src/cart/createCartHandler.ts", "syntaxKind": "TypeAliasDeclaration", "name": "HydrogenCart", - "value": "{\n get: ReturnType;\n getCartId: () => string | undefined;\n setCartId: (cartId: string) => Headers;\n create: ReturnType;\n addLines: ReturnType;\n updateLines: ReturnType;\n removeLines: ReturnType;\n updateDiscountCodes: ReturnType;\n updateGiftCardCodes: ReturnType;\n addGiftCardCodes: ReturnType;\n removeGiftCardCodes: ReturnType;\n updateBuyerIdentity: ReturnType;\n updateNote: ReturnType;\n updateSelectedDeliveryOption: ReturnType<\n typeof cartSelectedDeliveryOptionsUpdateDefault\n >;\n updateAttributes: ReturnType;\n setMetafields: ReturnType;\n deleteMetafield: ReturnType;\n /**\n * Adds delivery addresses to the cart.\n *\n * This function sends a mutation to the storefront API to add one or more delivery addresses to the cart.\n * It returns the result of the mutation, including any errors that occurred.\n *\n * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.\n * @returns {ReturnType} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.\n *\n * @example\n * const result = await cart.addDeliveryAddresses(\n * [\n * {\n * address1: '123 Main St',\n * city: 'Anytown',\n * countryCode: 'US'\n * }\n * ],\n * { someOptionalParam: 'value' }\n * );\n */\n addDeliveryAddresses: ReturnType;\n /**\n * Removes delivery addresses from the cart.\n *\n * This function sends a mutation to the storefront API to remove one or more delivery addresses from the cart.\n * It returns the result of the mutation, including any errors that occurred.\n *\n * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.\n * @returns {CartDeliveryAddressRemoveFunction} - A function that takes an array of address IDs and optional parameters, and returns the result of the API call.\n *\n * @example\n * const result = await cart.removeDeliveryAddresses([\n * \"gid://shopify//10079785100\"\n * ],\n * { someOptionalParam: 'value' });\n */\n\n removeDeliveryAddresses: ReturnType<\n typeof cartDeliveryAddressesRemoveDefault\n >;\n /**\n * Updates delivery addresses in the cart.\n *\n * This function sends a mutation to the storefront API to update one or more delivery addresses in the cart.\n * It returns the result of the mutation, including any errors that occurred.\n *\n * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.\n * @returns {CartDeliveryAddressUpdateFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.\n *\n * const result = await cart.updateDeliveryAddresses([\n {\n \"address\": {\n \"copyFromCustomerAddressId\": \"gid://shopify//10079785100\",\n \"deliveryAddress\": {\n \"address1\": \"\",\n \"address2\": \"\",\n \"city\": \"\",\n \"company\": \"\",\n \"countryCode\": \"AC\",\n \"firstName\": \"\",\n \"lastName\": \"\",\n \"phone\": \"\",\n \"provinceCode\": \"\",\n \"zip\": \"\"\n }\n },\n \"id\": \"gid://shopify//10079785100\",\n \"oneTimeUse\": true,\n \"selected\": true,\n \"validationStrategy\": \"COUNTRY_CODE_ONLY\"\n }\n ],{ someOptionalParam: 'value' });\n */\n updateDeliveryAddresses: ReturnType<\n typeof cartDeliveryAddressesUpdateDefault\n >;\n /**\n * Replaces all delivery addresses on the cart.\n *\n * This function sends a mutation to the storefront API to replace all delivery addresses on the cart\n * with the provided addresses. It returns the result of the mutation, including any errors that occurred.\n *\n * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.\n * @returns {CartDeliveryAddressesReplaceFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.\n *\n * @example\n * const result = await cart.replaceDeliveryAddresses([\n * {\n * address: {\n * deliveryAddress: {\n * address1: '123 Main St',\n * city: 'Anytown',\n * countryCode: 'US'\n * }\n * },\n * selected: true\n * }\n * ], { someOptionalParam: 'value' });\n */\n replaceDeliveryAddresses: ReturnType<\n typeof cartDeliveryAddressesReplaceDefault\n >;\n}", + "value": "{\n get: ReturnType;\n getCartId: () => string | undefined;\n setCartId: (cartId: string) => Headers;\n create: ReturnType;\n addLines: ReturnType;\n updateLines: ReturnType;\n removeLines: ReturnType;\n updateDiscountCodes: ReturnType;\n updateGiftCardCodes: ReturnType;\n addGiftCardCodes: ReturnType;\n removeGiftCardCodes: ReturnType;\n updateBuyerIdentity: ReturnType;\n updateNote: ReturnType;\n updateSelectedDeliveryOption: ReturnType<\n typeof cartSelectedDeliveryOptionsUpdateDefault\n >;\n updateAttributes: ReturnType;\n setMetafields: ReturnType;\n deleteMetafield: ReturnType;\n /**\n * Adds delivery addresses to the cart.\n *\n * This function sends a mutation to the storefront API to add one or more delivery addresses to the cart.\n * It returns the result of the mutation, including any errors that occurred.\n *\n * @example\n * const result = await cart.addDeliveryAddresses(\n * [\n * {\n * address1: '123 Main St',\n * city: 'Anytown',\n * countryCode: 'US'\n * }\n * ],\n * { someOptionalParam: 'value' }\n * );\n */\n addDeliveryAddresses: ReturnType;\n /**\n * Removes delivery addresses from the cart.\n *\n * This function sends a mutation to the storefront API to remove one or more delivery addresses from the cart.\n * It returns the result of the mutation, including any errors that occurred.\n *\n * @example\n * const result = await cart.removeDeliveryAddresses([\n * \"gid://shopify//10079785100\"\n * ],\n * { someOptionalParam: 'value' });\n */\n\n removeDeliveryAddresses: ReturnType<\n typeof cartDeliveryAddressesRemoveDefault\n >;\n /**\n * Updates delivery addresses in the cart.\n *\n * This function sends a mutation to the storefront API to update one or more delivery addresses in the cart.\n * It returns the result of the mutation, including any errors that occurred.\n *\n * const result = await cart.updateDeliveryAddresses([\n {\n \"address\": {\n \"copyFromCustomerAddressId\": \"gid://shopify//10079785100\",\n \"deliveryAddress\": {\n \"address1\": \"\",\n \"address2\": \"\",\n \"city\": \"\",\n \"company\": \"\",\n \"countryCode\": \"AC\",\n \"firstName\": \"\",\n \"lastName\": \"\",\n \"phone\": \"\",\n \"provinceCode\": \"\",\n \"zip\": \"\"\n }\n },\n \"id\": \"gid://shopify//10079785100\",\n \"oneTimeUse\": true,\n \"selected\": true,\n \"validationStrategy\": \"COUNTRY_CODE_ONLY\"\n }\n ],{ someOptionalParam: 'value' });\n */\n updateDeliveryAddresses: ReturnType<\n typeof cartDeliveryAddressesUpdateDefault\n >;\n /**\n * Replaces all delivery addresses on the cart.\n *\n * This function sends a mutation to the storefront API to replace all delivery addresses on the cart\n * with the provided addresses. It returns the result of the mutation, including any errors that occurred.\n *\n * @example\n * const result = await cart.replaceDeliveryAddresses([\n * {\n * address: {\n * deliveryAddress: {\n * address1: '123 Main St',\n * city: 'Anytown',\n * countryCode: 'US'\n * }\n * },\n * selected: true\n * }\n * ], { someOptionalParam: 'value' });\n */\n replaceDeliveryAddresses: ReturnType<\n typeof cartDeliveryAddressesReplaceDefault\n >;\n}", "description": "", "members": [ { diff --git a/packages/hydrogen/src/cart/createCartHandler.ts b/packages/hydrogen/src/cart/createCartHandler.ts index 4eeee7dc4a..910bb5d7a8 100644 --- a/packages/hydrogen/src/cart/createCartHandler.ts +++ b/packages/hydrogen/src/cart/createCartHandler.ts @@ -118,9 +118,6 @@ export type HydrogenCart = { * This function sends a mutation to the storefront API to add one or more delivery addresses to the cart. * It returns the result of the mutation, including any errors that occurred. * - * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment. - * @returns {ReturnType} - A function that takes an array of addresses and optional parameters, and returns the result of the API call. - * * @example * const result = await cart.addDeliveryAddresses( * [ @@ -140,9 +137,6 @@ export type HydrogenCart = { * This function sends a mutation to the storefront API to remove one or more delivery addresses from the cart. * It returns the result of the mutation, including any errors that occurred. * - * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment. - * @returns {CartDeliveryAddressRemoveFunction} - A function that takes an array of address IDs and optional parameters, and returns the result of the API call. - * * @example * const result = await cart.removeDeliveryAddresses([ * "gid://shopify//10079785100" @@ -159,9 +153,6 @@ export type HydrogenCart = { * This function sends a mutation to the storefront API to update one or more delivery addresses in the cart. * It returns the result of the mutation, including any errors that occurred. * - * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment. - * @returns {CartDeliveryAddressUpdateFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call. - * * const result = await cart.updateDeliveryAddresses([ { "address": { @@ -195,9 +186,6 @@ export type HydrogenCart = { * This function sends a mutation to the storefront API to replace all delivery addresses on the cart * with the provided addresses. It returns the result of the mutation, including any errors that occurred. * - * @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment. - * @returns {CartDeliveryAddressesReplaceFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call. - * * @example * const result = await cart.replaceDeliveryAddresses([ * {