Merge branch 'develop' into docs/add-jsdoc-comments-to-usecategory

Marcin Kwiatkowski · web-flow · commit 2fd8decefc4f · 2022-04-11T06:37:59.000+02:00
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -92,6 +92,7 @@ module.exports = {
       {
         title: 'Composables',
         children: [
+          ['/api-reference/magento-theme.useaddresses', 'useAddresses()'],
           ['/api-reference/magento-theme.usecontent', 'useContent()'],
           ['/api-reference/magento-theme.usecategory', 'useCategory()'],
         ]
@@ -102,6 +103,10 @@ module.exports = {
           ['/api-reference/magento-api.cmsblocks', 'cmsBlocks'],
           ['/api-reference/magento-api.cmspage', 'cmsPage'],
           ['/api-reference/magento-api.categorylist', 'categoryList'],
+          ['/api-reference/magento-api.createcustomeraddress', 'createCustomerAddress'],
+          ['/api-reference/magento-api.deletecustomeraddress', 'deleteCustomerAddress'],
+          ['/api-reference/magento-api.getcustomeraddresses', 'getCustomerAddresses'],
+          ['/api-reference/magento-api.updatecustomeraddress', 'updateCustomerAddress'],
         ]
       },
       {
diff --git a/packages/api-client/src/api/createCustomerAddress/createCustomerAddress.ts b/packages/api-client/src/api/createCustomerAddress/createCustomerAddress.ts
@@ -1,5 +1,6 @@
 import gql from 'graphql-tag';
 
+/** GraphQL Mutation that creates new customer address. */
 export default gql`
   mutation createCustomerAddress($input: CustomerAddressInput!) {
     createCustomerAddress(input: $input) {
diff --git a/packages/api-client/src/api/createCustomerAddress/index.ts b/packages/api-client/src/api/createCustomerAddress/index.ts
@@ -1,23 +1,30 @@
 import { FetchResult } from '@apollo/client/core';
 import { CustomQuery } from '@vue-storefront/core';
-import createCustomerAddress from './createCustomerAddress';
+import createCustomerAddressMutation from './createCustomerAddress';
 import {
   CreateCustomerAddressMutation,
   CreateCustomerAddressMutationVariables,
   CustomerAddressInput,
 } from '../../types/GraphQL';
 import { Context } from '../../types/context';
 
-export default async (
+/**
+ * Creates a customer address.
+ *
+ * @param context VSF Context
+ * @param input new customer address data
+ * @param [customQuery] (optional) - custom GraphQL query that extends the default query
+ */
+export default async function createCustomerAddress(
   context: Context,
   input: CustomerAddressInput,
   customQuery: CustomQuery = { createCustomerAddress: 'createCustomerAddress' },
-): Promise<FetchResult<CreateCustomerAddressMutation>> => {
+): Promise<FetchResult<CreateCustomerAddressMutation>> {
   const { createCustomerAddress: createCustomerAddressGQL } = context.extendQuery(
     customQuery,
     {
       createCustomerAddress: {
-        query: createCustomerAddress,
+        query: createCustomerAddressMutation,
         variables: { input },
       },
     },
@@ -27,4 +34,4 @@ export default async (
     mutation: createCustomerAddressGQL.query,
     variables: createCustomerAddressGQL.variables,
   });
-};
+}
diff --git a/packages/api-client/src/api/deleteCustomerAddress/deleteCustomerAddress.ts b/packages/api-client/src/api/deleteCustomerAddress/deleteCustomerAddress.ts
@@ -1,5 +1,6 @@
 import gql from 'graphql-tag';
 
+/** GraphQL Mutation that deletes a customer address. */
 export default gql`
   mutation deleteCustomerAddress($id: Int!) {
     deleteCustomerAddress(id: $id)
diff --git a/packages/api-client/src/api/deleteCustomerAddress/index.ts b/packages/api-client/src/api/deleteCustomerAddress/index.ts
@@ -1,25 +1,33 @@
 import { ExecutionResult } from 'graphql';
 import { CustomQuery } from '@vue-storefront/core';
-import deleteCustomerAddress from './deleteCustomerAddress';
+import deleteCustomerAddressMutation from './deleteCustomerAddress';
 import { Context } from '../../types/context';
 import { DeleteCustomerAddressMutation, DeleteCustomerAddressMutationVariables } from '../../types/GraphQL';
 
-export default async (
+/**
+ * Deletes a customer address.
+ *
+ * @param context VSF Context
+ * @param addressId ID of the customer address to delete
+ * @param customQuery (optional) - custom GraphQL query that extends the default query
+ */
+export default async function deleteCustomerAddress(
   context: Context,
   addressId: number,
   customQuery: CustomQuery = { deleteCustomerAddress: 'deleteCustomerAddress' },
-): Promise<ExecutionResult<DeleteCustomerAddressMutation>> => {
+): Promise<ExecutionResult<DeleteCustomerAddressMutation>> {
   const { deleteCustomerAddress: deleteCustomerAddressGQL } = context.extendQuery(
     customQuery,
     {
       deleteCustomerAddress: {
-        query: deleteCustomerAddress,
+        query: deleteCustomerAddressMutation,
         variables: { id: addressId },
       },
     },
   );
+
   return context.client.mutate<DeleteCustomerAddressMutation, DeleteCustomerAddressMutationVariables>({
     mutation: deleteCustomerAddressGQL.query,
     variables: deleteCustomerAddressGQL.variables,
   });
-};
+}
diff --git a/packages/api-client/src/api/getCustomerAddresses/getCustomerAddresses.ts b/packages/api-client/src/api/getCustomerAddresses/getCustomerAddresses.ts
@@ -1,5 +1,6 @@
 import gql from 'graphql-tag';
 
+/** GraphQL Query that fetches customer addresses. */
 export default gql`
   query getCustomerAddresses {
     customer {
diff --git a/packages/api-client/src/api/getCustomerAddresses/index.ts b/packages/api-client/src/api/getCustomerAddresses/index.ts
@@ -4,24 +4,27 @@ import { GetCustomerAddressesQuery } from '../../types/GraphQL';
 import getCustomerAddressesQuery from './getCustomerAddresses';
 import { Context } from '../../types/context';
 
-export default async (
+/**
+ * Fetches customer addresses.
+ *
+ * @param context - VSF Context
+ * @param [customQuery] - (optional) - custom GraphQL query that extends the default query
+ */
+export default async function getCustomerAddresses(
   context: Context,
   customQuery: CustomQuery = { getCustomerAddresses: 'getCustomerAddresses' },
-): Promise<ApolloQueryResult<GetCustomerAddressesQuery>> => {
-  const { getCustomerAddresses } = context.extendQuery(
-    customQuery,
-    {
-      getCustomerAddresses: {
-        query: getCustomerAddressesQuery,
-      },
+): Promise<ApolloQueryResult<GetCustomerAddressesQuery>> {
+  const { getCustomerAddresses: getCustomerAddressesGQL } = context.extendQuery(customQuery, {
+    getCustomerAddresses: {
+      query: getCustomerAddressesQuery,
     },
-  );
+  });
 
   try {
     return await context.client.query<GetCustomerAddressesQuery>({
-      query: getCustomerAddresses.query,
+      query: getCustomerAddressesGQL.query,
     });
   } catch (error) {
     throw error.graphQLErrors?.[0].message || error.networkError?.result || error;
   }
-};
+}
diff --git a/packages/api-client/src/api/updateCustomerAddress/index.ts b/packages/api-client/src/api/updateCustomerAddress/index.ts
@@ -1,36 +1,40 @@
 import { FetchResult } from '@apollo/client/core';
 import { CustomQuery } from '@vue-storefront/core';
-import updateCustomerAddress from './updateCustomerAddress';
+import updateCustomerAddressMutation from './updateCustomerAddress';
 import {
   CustomerAddressInput,
   UpdateCustomerAddressMutation,
   UpdateCustomerAddressMutationVariables,
 } from '../../types/GraphQL';
 import { Context } from '../../types/context';
 
-export default async (
+/**
+ * Updates a customer address.
+ *
+ * @param context VSF Context
+ * @param params object with address identifier and the updated data
+ * @param [customQuery] (optional) custom GraphQL query that extends the default query
+ */
+export default async function updateCustomerAddress(
   context: Context,
   params: {
     addressId: number;
     input: CustomerAddressInput;
   },
   customQuery: CustomQuery = { updateCustomerAddress: 'updateCustomerAddress' },
-): Promise<FetchResult<UpdateCustomerAddressMutation>> => {
-  const { updateCustomerAddress: updateCustomerAddressGQL } = context.extendQuery(
-    customQuery,
-    {
-      updateCustomerAddress: {
-        query: updateCustomerAddress,
-        variables: {
-          id: params.addressId,
-          input: params.input,
-        },
+): Promise<FetchResult<UpdateCustomerAddressMutation>> {
+  const { updateCustomerAddress: updateCustomerAddressGQL } = context.extendQuery(customQuery, {
+    updateCustomerAddress: {
+      query: updateCustomerAddressMutation,
+      variables: {
+        id: params.addressId,
+        input: params.input,
       },
     },
-  );
+  });
 
   return context.client.mutate<UpdateCustomerAddressMutation, UpdateCustomerAddressMutationVariables>({
     mutation: updateCustomerAddressGQL.query,
     variables: updateCustomerAddressGQL.variables,
   });
-};
+}
diff --git a/packages/api-client/src/api/updateCustomerAddress/updateCustomerAddress.ts b/packages/api-client/src/api/updateCustomerAddress/updateCustomerAddress.ts
@@ -1,5 +1,6 @@
 import gql from 'graphql-tag';
 
+/** GraphQL Mutation that updates a customer address. */
 export default gql`
   mutation updateCustomerAddress($id: Int!, $input: CustomerAddressInput) {
     updateCustomerAddress(id: $id, input: $input) {
diff --git a/packages/theme/composables/index.ts b/packages/theme/composables/index.ts
@@ -31,7 +31,7 @@ export { default as useBilling } from './useBilling';
 export { default as useRelatedProducts } from './useRelatedProducts';
 export { default as useUpsellProducts } from './useUpsellProducts';
 export { default as usePaymentProvider } from './usePaymentProvider';
-export { default as useAddresses } from './useAddresses';
+export * from './useAddresses';
 export { default as useMakeOrder } from './useMakeOrder';
 export { default as useUserOrder } from './useUserOrder';
 export { default as useUserAddress } from './useUserAddress';
diff --git a/packages/theme/composables/useAddresses/index.ts b/packages/theme/composables/useAddresses/index.ts
@@ -1,10 +1,90 @@
 import { Ref, ref, useContext } from '@nuxtjs/composition-api';
 import { Logger } from '~/helpers/logger';
 import { transformUserCreateAddressInput, transformUserUpdateAddressInput } from '~/helpers/userAddressManipulator';
-import { ComposableFunctionArgs } from '~/composables/types';
-import { UseAddressesInterface, UseAddressesParamsInput, UseAddressesErrors } from '~/composables/useAddresses/useAddresses';
+import type { ComposableFunctionArgs } from '~/composables/types';
+import type { UseAddressesInterface, UseAddressesParamsInput, UseAddressesErrors } from './useAddresses';
 
-export const useAddresses = () : UseAddressesInterface => {
+/**
+ * @public
+ *
+ * The `useAddresses` composable provides functions and refs to handle customer
+ * addresses from Magento API. And in Magento, the customer addresses can be
+ * used for both billing and shipping.
+ *
+ * With `useAddresses` provided functions, we're able to:
+ *
+ * - Load the customer addresses;
+ *
+ * - Save new customer address;
+ *
+ * - Update an existing customer address;
+ *
+ * - Remove an existing customer address;
+ *
+ * @remarks
+ *
+ * Under the hood, it calls the following Server Middleware API methods:
+ *
+ * - {@link @vue-storefront/magento-api#getCustomerAddresses} for loading customer addresses;
+ *
+ * - {@link @vue-storefront/magento-api#createCustomerAddress} for saving new customer address;
+ *
+ * - {@link @vue-storefront/magento-api#updateCustomerAddress} for updating existing customer address;
+ *
+ * - {@link @vue-storefront/magento-api#deleteCustomerAddress} for removing existing customer address;
+ *
+ * @example
+ *
+ * Initialization in component:
+ *
+ * ```typescript
+ * import { useAddresses } from '~/composables';
+ *
+ * export default {
+ *   setup(props) {
+ *     const { load, save, update, remove, error, loading } = useAddresses();
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ *
+ * Load customer addresses and allow saving new ones:
+ *
+ * ```typescript
+ * import { useFetch, ref } from '@nuxtjs/composition-api';
+ * import { useAddresses, UseAddressesParamsInput } from '~/composables';
+ *
+ * export default {
+ *   setup(props) {
+ *     const { load, save, error, loading } = useAddresses();
+ *
+ *     const addresses = ref([]);
+ *
+ *     useFetch(async () => {
+ *       addresses.value = await load();
+ *
+ *       if (error.value.load) {
+ *         // handle loading error
+ *       }
+ *     });
+ *
+ *     const onSave = async (params: UseAddressesParamsInput) => {
+ *       const newAddress = await save(params);
+ *
+ *       if (error.value.save) {
+ *         // handle saving error
+ *       }
+ *
+ *       addresses.value.push(newAddress);
+ *     };
+ *
+ *     return { onSave, loading, addresses };
+ *   }
+ * }
+ * ```
+ */
+export function useAddresses(): UseAddressesInterface {
   const error: Ref<UseAddressesErrors> = ref({
     load: null,
     save: null,
@@ -41,9 +121,7 @@ export const useAddresses = () : UseAddressesInterface => {
 
     try {
       loading.value = true;
-      const { data } = await context.$magento.api.createCustomerAddress(
-        transformUserCreateAddressInput(saveParams),
-      );
+      const { data } = await context.$magento.api.createCustomerAddress(transformUserCreateAddressInput(saveParams));
       results = data?.createCustomerAddress ?? {};
       Logger.debug('[Magento] save user address results:', saveParams.address);
       error.value.save = null;
@@ -63,9 +141,7 @@ export const useAddresses = () : UseAddressesInterface => {
 
     try {
       loading.value = true;
-      const { data } = await context.$magento.api.updateCustomerAddress(
-        transformUserUpdateAddressInput(updateParams),
-      );
+      const { data } = await context.$magento.api.updateCustomerAddress(transformUserUpdateAddressInput(updateParams));
       results = data?.updateCustomerAddress ?? {};
       Logger.debug('[Magento] update user address results:', results);
       error.value.update = null;
@@ -85,9 +161,7 @@ export const useAddresses = () : UseAddressesInterface => {
 
     try {
       loading.value = true;
-      const { data } = await context.$magento.api.deleteCustomerAddress(
-        removeParams.address.id,
-      );
+      const { data } = await context.$magento.api.deleteCustomerAddress(removeParams.address.id);
       results = !!data.deleteCustomerAddress;
       Logger.debug('[Magento] remove user address results:', results);
       error.value.remove = null;
@@ -109,6 +183,8 @@ export const useAddresses = () : UseAddressesInterface => {
     update,
     remove,
   };
-};
+}
+
+export * from './useAddresses';
 
 export default useAddresses;
diff --git a/packages/theme/composables/useAddresses/useAddresses.ts b/packages/theme/composables/useAddresses/useAddresses.ts

Original file line number	Diff line number	Diff line change
`@@ -92,6 +92,7 @@ module.exports = {`
`92`	`92`	`{`
`93`	`93`	`title: 'Composables',`
`94`	`94`	`children: [`
	`95`	`+ ['/api-reference/magento-theme.useaddresses', 'useAddresses()'],`
`95`	`96`	`['/api-reference/magento-theme.usecontent', 'useContent()'],`
`96`	`97`	`['/api-reference/magento-theme.usecategory', 'useCategory()'],`
`97`	`98`	`]`
`@@ -102,6 +103,10 @@ module.exports = {`
`102`	`103`	`['/api-reference/magento-api.cmsblocks', 'cmsBlocks'],`
`103`	`104`	`['/api-reference/magento-api.cmspage', 'cmsPage'],`
`104`	`105`	`['/api-reference/magento-api.categorylist', 'categoryList'],`
	`106`	`+ ['/api-reference/magento-api.createcustomeraddress', 'createCustomerAddress'],`
	`107`	`+ ['/api-reference/magento-api.deletecustomeraddress', 'deleteCustomerAddress'],`
	`108`	`+ ['/api-reference/magento-api.getcustomeraddresses', 'getCustomerAddresses'],`
	`109`	`+ ['/api-reference/magento-api.updatecustomeraddress', 'updateCustomerAddress'],`
`105`	`110`	`]`
`106`	`111`	`},`
`107`	`112`	`{`