chore: add tsdocs for the Store Module resources (#6795)

* chore: add tsdocs to Store Module resources

* added examples

packages/types/src/store/common/store.ts

@@ -1,19 +1,72 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * The store details.
+ */
 export interface StoreDTO {
+  /**
+   * The ID of the store.
+   */
   id: string
+
+  /**
+   * The name of the store.
+   */
   name: string
+
+  /**
+   * The supported currency codes of the store.
+   */
   supported_currency_codes: string[]
+
+  /**
+   * The default currency code of the store.
+   */
   default_currency_code?: string
+
+  /**
+   * The associated default sales channel's ID.
+   */
   default_sales_channel_id?: string
+
+  /**
+   * The associated default region's ID.
+   */
   default_region_id?: string
+
+  /**
+   * The associated default location's ID.
+   */
   default_location_id?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata: Record<string, any> | null
+
+  /**
+   * The created at of the store.
+   */
   created_at: string
+
+  /**
+   * The updated at of the store.
+   */
   updated_at: string
 }
+
+/**
+ * The filters to apply on the retrieved stores.
+ */
 export interface FilterableStoreProps
   extends BaseFilterable<FilterableStoreProps> {
+  /**
+   * The IDs to filter the stores by.
+   */
   id?: string | string[]
+
+  /**
+   * Filter stores by their names.
+   */
   name?: string | string[]
 }

packages/types/src/store/mutations/store.ts

@@ -1,30 +1,124 @@
+/**
+ * The store to be created.
+ */
 export interface CreateStoreDTO {
+  /**
+   * The name of the store.
+   */
   name?: string
+
+  /**
+   * The supported currency codes of the store.
+   */
   supported_currency_codes?: string[]
+
+  /**
+   * The default currency code of the store.
+   */
   default_currency_code?: string
+
+  /**
+   * The associated default sales channel's ID.
+   */
   default_sales_channel_id?: string
+
+  /**
+   * The associated default region's ID.
+   */
   default_region_id?: string
+
+  /**
+   * The associated default location's ID.
+   */
   default_location_id?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, any>
 }
 
+/**
+ * The attributes in the store to be created or updated.
+ */
 export interface UpsertStoreDTO {
+  /**
+   * The ID of the store.
+   */
   id?: string
+
+  /**
+   * The name of the store.
+   */
   name?: string
+
+  /**
+   * The supported currency codes of the store.
+   */
   supported_currency_codes?: string[]
+
+  /**
+   * The default currency code of the store.
+   */
   default_currency_code?: string
+
+  /**
+   * The associated default sales channel's ID.
+   */
   default_sales_channel_id?: string
+
+  /**
+   * The associated default region's ID.
+   */
   default_region_id?: string
+
+  /**
+   * The associated default location's ID.
+   */
   default_location_id?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, any>
 }
 
+/**
+ * The attributes to update in the store.
+ */
 export interface UpdateStoreDTO {
+  /**
+   * The name of the store.
+   */
   name?: string
+
+  /**
+   * The supported currency codes of the store.
+   */
   supported_currency_codes?: string[]
+
+  /**
+   * The default currency code of the store.
+   */
   default_currency_code?: string
+
+  /**
+   * The associated default sales channel's ID.
+   */
   default_sales_channel_id?: string
+
+  /**
+   * The associated default region's ID.
+   */
   default_region_id?: string
+
+  /**
+   * The associated default location's ID.
+   */
   default_location_id?: string
+
+  /**
+   * Holds custom data in key-value pairs.
+   */
   metadata?: Record<string, any>
 }

packages/types/src/store/service.ts

@@ -6,7 +6,7 @@ import { FilterableStoreProps, StoreDTO } from "./common"
 import { CreateStoreDTO, UpdateStoreDTO, UpsertStoreDTO } from "./mutations"
 
 /**
- * The main service interface for the store module.
+ * The main service interface for the Store Module.
  */
 export interface IStoreModuleService extends IModuleService {
   /**
@@ -17,7 +17,18 @@ export interface IStoreModuleService extends IModuleService {
    * @returns {Promise<StoreDTO[]>} The created stores.
    *
    * @example
-   * {example-code}
+   * const stores = await storeModuleService.create([
+   *   {
+   *     name: "Acme",
+   *     supported_currency_codes: ["usd", "eur"],
+   *     default_currency_code: "usd",
+   *   },
+   *   {
+   *     name: "Acme 2",
+   *     supported_currency_codes: ["usd"],
+   *     default_currency_code: "usd",
+   *   },
+   * ])
    */
   create(data: CreateStoreDTO[], sharedContext?: Context): Promise<StoreDTO[]>
 
@@ -29,39 +40,63 @@ export interface IStoreModuleService extends IModuleService {
    * @returns {Promise<StoreDTO>} The created store.
    *
    * @example
-   * {example-code}
+   * const store = await storeModuleService.create({
+   *   name: "Acme",
+   *   supported_currency_codes: ["usd", "eur"],
+   *   default_currency_code: "usd",
+   * })
    */
   create(data: CreateStoreDTO, sharedContext?: Context): Promise<StoreDTO>
 
   /**
-   * This method updates existing stores, or creates new ones if they don't exist.
+   * This method updates or creates stores if they don't exist.
    *
-   * @param {UpsertStoreDTO[]} data - The attributes to update or create in each store.
+   * @param {UpsertStoreDTO[]} data - The attributes in the stores to be created or updated.
-   * @returns {Promise<StoreDTO[]>} The updated and created stores.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<StoreDTO[]>} The created or updated stores.
    *
    * @example
-   * {example-code}
+   * const stores = await storeModuleService.upsert([
+   *   {
+   *     id: "store_123",
+   *     name: "Acme",
+   *   },
+   *   {
+   *     name: "Acme 2",
+   *     supported_currency_codes: ["usd"],
+   *     default_currency_code: "usd",
+   *   },
+   * ])
    */
   upsert(data: UpsertStoreDTO[], sharedContext?: Context): Promise<StoreDTO[]>
 
   /**
-   * This method updates an existing store, or creates a new one if it doesn't exist.
+   * This method updates or creates a store if it doesn't exist.
    *
-   * @param {UpsertStoreDTO} data - The attributes to update or create for the store.
+   * @param {UpsertStoreDTO} data - The attributes in the store to be created or updated.
-   * @returns {Promise<StoreDTO>} The updated or created store.
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<StoreDTO>} The created or updated store.
    *
    * @example
-   * {example-code}
+   * const store = await storeModuleService.upsert({
+   *   id: "store_123",
+   *   name: "Acme",
+   * })
    */
   upsert(data: UpsertStoreDTO, sharedContext?: Context): Promise<StoreDTO>
 
   /**
    * This method updates an existing store.
    *
-   * @param {string} id - The store's ID.
+   * @param {string} id - The ID of the store.
-   * @param {UpdateStoreDTO} data - The details to update in the store.
+   * @param {UpdateStoreDTO} data - The attributes to update in the store.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<StoreDTO>} The updated store.
+   *
+   * @example
+   * const store = await storeModuleService.update("store_123", {
+   *   name: "Acme",
+   * })
    */
   update(
     id: string,
@@ -70,15 +105,22 @@ export interface IStoreModuleService extends IModuleService {
   ): Promise<StoreDTO>
 
   /**
-   * This method updates existing stores.
+   * This method updates existing stores matching the specified filters.
    *
-   * @param {FilterableStoreProps} selector - The filters to specify which stores should be updated.
+   * @param {FilterableStoreProps} selector - The filters specifying which stores to update.
-   * @param {UpdateStoreDTO} data - The details to update in the stores.
+   * @param {UpdateStoreDTO} data - The attributes to update in the store.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<StoreDTO[]>} The updated stores.
    *
    * @example
-   * {example-code}
+   * const store = await storeModuleService.update(
+   *   {
+   *     name: ["Acme"],
+   *   },
+   *   {
+   *     default_currency_code: "usd",
+   *   }
+   * )
    */
   update(
     selector: FilterableStoreProps,
@@ -89,12 +131,12 @@ export interface IStoreModuleService extends IModuleService {
   /**
    * This method deletes stores by their IDs.
    *
-   * @param {string[]} ids - The list of IDs of stores to delete.
+   * @param {string[]} ids - The IDs of the stores.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<void>} Resolves when the stores are deleted.
+   * @returns {Promise<void>} Resolves when the stores are deleted successfully.
    *
    * @example
-   * {example-code}
+   * await storeModuleService.delete(["store_123", "store_321"])
    */
   delete(ids: string[], sharedContext?: Context): Promise<void>
 
@@ -103,36 +145,24 @@ export interface IStoreModuleService extends IModuleService {
    *
    * @param {string} id - The ID of the store.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<void>} Resolves when the store is deleted.
+   * @returns {Promise<void>} Resolves when the store is deleted successfully.
    *
    * @example
-   * {example-code}
+   * await storeModuleService.delete("store_123")
    */
   delete(id: string, sharedContext?: Context): Promise<void>
 
   /**
    * This method retrieves a store by its ID.
    *
-   * @param {string} id - The ID of the retrieve.
+   * @param {string} id - The ID of the store.
    * @param {FindConfig<StoreDTO>} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a store.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<StoreDTO>} The retrieved store.
    *
    * @example
-   * A simple example that retrieves a {type name} by its ID:
+   * const store = await storeModuleService.retrieve("store_123")
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   * To specify relations that should be retrieved:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   retrieve(
     id: string,
@@ -143,32 +173,34 @@ export interface IStoreModuleService extends IModuleService {
   /**
    * This method retrieves a paginated list of stores based on optional filters and configuration.
    *
-   * @param {FilterableStoreProps} filters - The filters to apply on the retrieved store.
+   * @param {FilterableStoreProps} filters - The filters to apply on the retrieved stores.
    * @param {FindConfig<StoreDTO>} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a store.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<StoreDTO[]>} The list of stores.
    *
    * @example
-   * To retrieve a list of {type name} using their IDs:
+   * To retrieve a list of stores using their IDs:
    *
    * ```ts
-   * {example-code}
+   * const stores = await storeModuleService.list({
+   *   id: ["store_123", "store_321"],
+   * })
    * ```
    *
-   * To specify relations that should be retrieved within the {type name}:
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
    *
    * ```ts
-   * {example-code}
+   * const stores = await storeModuleService.list(
+   *   {
+   *     id: ["store_123", "store_321"],
+   *   },
+   *   {
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
    * ```
-   *
-   * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   list(
     filters?: FilterableStoreProps,
@@ -179,32 +211,36 @@ export interface IStoreModuleService extends IModuleService {
   /**
    * This method retrieves a paginated list of stores along with the total count of available stores satisfying the provided filters.
    *
-   * @param {FilterableStoreProps} filters - The filters to apply on the retrieved store.
+   * @param {FilterableStoreProps} filters - The filters to apply on the retrieved stores.
    * @param {FindConfig<StoreDTO>} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a store.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<[StoreDTO[], number]>} The list of stores along with their total count.
    *
    * @example
-   * To retrieve a list of {type name} using their IDs:
+   * To retrieve a list of stores using their IDs:
    *
    * ```ts
-   * {example-code}
+   * const [stores, count] = await storeModuleService.listAndCount(
+   *   {
+   *     id: ["store_123", "store_321"],
+   *   }
+   * )
    * ```
    *
-   * To specify relations that should be retrieved within the {type name}:
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
    *
    * ```ts
-   * {example-code}
+   * const [stores, count] = await storeModuleService.listAndCount(
+   *   {
+   *     id: ["store_123", "store_321"],
+   *   },
+   *   {
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
    * ```
-   *
-   * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
-   *
-   * ```ts
-   * {example-code}
-   * ```
-   *
-   *
    */
   listAndCount(
     filters?: FilterableStoreProps,
@@ -213,15 +249,19 @@ export interface IStoreModuleService extends IModuleService {
   ): Promise<[StoreDTO[], number]>
 
   /**
-   * This method soft deletes stores by their IDs.
+   * This method soft deletes a store by its IDs.
    *
-   * @param {string[]} storeIds - The list of IDs of stores to soft delete.
+   * @param {string[]} storeIds - The IDs of the stores.
    * @param {SoftDeleteReturn<TReturnableLinkableKeys>} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<void | Record<string, string[]>>} Resolves successfully when the stores are soft-deleted.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were also soft deleted.
+   * If there are no related records, the promise resolves to `void`.
    *
    * @example
-   * {example-code}
+   * await storeModuleService.softDelete([
+   *   "store_123",
+   *   "store_321",
+   * ])
    */
   softDelete<TReturnableLinkableKeys extends string = string>(
     storeIds: string[],
@@ -230,19 +270,17 @@ export interface IStoreModuleService extends IModuleService {
   ): Promise<Record<string, string[]> | void>
 
   /**
-   * This method restores soft deleted stores by their IDs.
+   * This method restores a soft deleted store by its IDs.
    *
-   * @param {string[]} storeIds - The list of IDs of stores to restore.
+   * @param {string[]} storeIds - The IDs of the stores.
-   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the stores. You can pass to its `returnLinkableKeys`
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the store. You can pass to its `returnLinkableKeys`
-   * property any of the stores's relation attribute names, such as `currency`.
+   * property any of the store's relation attribute names.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were restored, such as the ID of associated currency.
+   * @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were restored.
-   * The object's keys are the ID attribute names of the stores entity's relations, such as `currency_code`,
+   * If there are no related records restored, the promise resolves to `void`.
-   * and its value is an array of strings, each being the ID of the record associated with the store through this relation,
-   * such as the IDs of associated currency.
    *
    * @example
-   * {example-code}
+   * await storeModuleService.restore(["store_123", "store_321"])
    */
   restore<TReturnableLinkableKeys extends string = string>(
     storeIds: string[],