refactor-functions

Refactoring a tool Function in @commercetools/commerce-agent

This document outlines the steps taken to refactor a function in @commercetools/commerce-agent to connect to commercetools API.

The following steps are defining implementation of an example cart.read. So the (namespace) here refers to cart.

NOTES:

1. CRUD functions are read, update and create. do not add delete functions.
2. DO NOT MODIFY `parameters.ts` or `prompts.ts` or `tools.ts`
3. when creating update base functions, use get (by id or key) base functions to first fetch the entity, and use the version from the fetched entity in the update payload

Refactor steps

1. Create a base.functions.ts file in the namespace directory. This file will export a couple of basic CRUD functions that will be used inside other files in this namespace. you can extract this base functions from current functions.ts file in the namespace.

   • IMPORTANT: base functions should be generic as possible, e.g. instead of having a separate function for query cart for a specific user and another one for user in a store, we create one that accepts a "where" cluase.
   • Note: sometimes the commercetools SDK has different endpoint when a parameter is present, like query in store (look to the code sample below). in that case, we check that parameter inside the base function but keep the function as simple as possible and low complexity.
   • GOAL: the goal of this step is maximize reusability.
   • example: base functions created for 'cart.read' are: readCartById, readCartByKey, queryCart, queryCarts.
   • file example: typescript/src/shared/cart/base.functions.ts
   • code sample:

   const queryCart = async (
     apiRoot: ApiRoot,
     projectKey: string,
     queryArgs: any,
     storeKey?: string
   ) => {
     if (storeKey) {
       const carts = await apiRoot
         .withProjectKey({ projectKey })
         .inStoreKeyWithStoreKeyValue({ storeKey })
         .carts()
         .get({ queryArgs })
         .execute();
       return carts.body;
     }
     const carts = await apiRoot
       .withProjectKey({ projectKey })
       .carts()
       .get({ queryArgs })
       .execute();
     return carts.body;
   };