chore: added tsdocs for Stock Location Next Module (#6817)

packages/types/src/stock-location/common.ts

@@ -435,8 +435,22 @@ export type UpdateStockLocationInput = {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * @interface
+ *
+ * The attributes to update in a stock location.
+ */
 export type UpdateStockLocationNextInput = UpdateStockLocationInput & {
+  /**
+   * The ID of the stock location.
+   */
   id: string
 }
 
+/**
+ * @interface
+ *
+ * A stock location to create or update. If the `id` property isn't provided,
+ * the stock location is created. In that case, the `name` property is required.
+ */
 export type UpsertStockLocationInput = Partial<UpdateStockLocationNextInput>

packages/types/src/stock-location/service-next.ts

@@ -7,84 +7,58 @@ import {
   UpsertStockLocationInput,
 } from "./common"
 import { RestoreReturn, SoftDeleteReturn } from "../dal"
-
 import { Context } from "../shared-context"
 import { FindConfig } from "../common/common"
 import { IModuleService } from "../modules-sdk"
 
 /**
- * The main service interface for the stock location's module.
+ * The main service interface for the Stock Location Module.
  */
 export interface IStockLocationServiceNext extends IModuleService {
   /**
-   * This method is used to retrieve a paginated list of stock locations based on optional filters and configuration.
+   * This method retrieves a paginated list of stock locations based on optional filters and configuration.
    *
    * @param {FilterableStockLocationProps} selector - The filters to apply on the retrieved stock locations.
-   * @param {FindConfig<StockLocationDTO>} config -
+   * @param {FindConfig<StockLocationDTO>} config - The configurations determining how the stock location is retrieved. Its properties, such as `select` or `relations`, accept the
-   * The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a stock location.
    * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
-   * @return {Promise<StockLocationDTO[]>} The list of stock locations.
+   * @returns {Promise<StockLocationDTO[]>} The list of stock locations.
    *
    * @example
    * To retrieve a list of stock locations using their IDs:
    *
    * ```ts
-   * import {
+   * const stockLocations = await stockLocationModuleService.list({
-   *   initialize as initializeStockLocationModule,
+   *   id: ["sloc_123", "sloc_321"],
-   * } from "@medusajs/stock-location"
-   *
-   * async function listStockLocations (ids: string[]) {
-   *   const stockLocationModule = await initializeStockLocationModule({})
-   *
-   *   const stockLocations = await stockLocationModule.list({
-   *     id: ids
    * })
-   *
-   *   // do something with the stock locations or return them
-   * }
    * ```
    *
    * To specify relations that should be retrieved within the stock locations:
    *
    * ```ts
-   * import {
+   * const stockLocations = await stockLocationModuleService.list(
-   *   initialize as initializeStockLocationModule,
+   *   {
-   * } from "@medusajs/stock-location"
+   *     id: ["sloc_123", "sloc_321"],
-   *
+   *   },
-   * async function listStockLocations (ids: string[]) {
+   *   {
-   *   const stockLocationModule = await initializeStockLocationModule({})
+   *     relations: ["address"],
-   *
-   *   const stockLocations = await stockLocationModule.list({
-   *     id: ids
-   *   }, {
-   *     relations: ["address"]
-   *   })
-   *
-   *   // do something with the stock locations or return them
    *   }
+   * )
    * ```
    *
    * By default, only the first `10` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
    *
    * ```ts
-   * import {
+   * const stockLocations = await stockLocationModuleService.list(
-   *   initialize as initializeStockLocationModule,
+   *   {
-   * } from "@medusajs/stock-location"
+   *     id: ["sloc_123", "sloc_321"],
-   *
+   *   },
-   * async function listStockLocations (ids: string[], skip: number, take: number) {
+   *   {
-   *   const stockLocationModule = await initializeStockLocationModule({})
-   *
-   *   const stockLocations = await stockLocationModule.list({
-   *     id: ids
-   *   }, {
    *     relations: ["address"],
-   *     skip,
+   *     take: 20,
-   *     take
+   *     skip: 2,
-   *   })
-   *
-   *   // do something with the stock locations or return them
    *   }
+   * )
    * ```
    */
   list(
@@ -94,74 +68,52 @@ export interface IStockLocationServiceNext extends IModuleService {
   ): Promise<StockLocationDTO[]>
 
   /**
-   * This method is used to retrieve a paginated list of stock locations along with the total count of available stock locations satisfying the provided filters.
+   * This method retrieves a paginated list of stock locations along with the total count of available stock locations satisfying the provided filters.
    *
    * @param {FilterableStockLocationProps} selector - The filters to apply on the retrieved stock locations.
-   * @param {FindConfig<StockLocationDTO>} config -
+   * @param {FindConfig<StockLocationDTO>} config - The configurations determining how the stock location is retrieved. Its properties, such as `select` or `relations`, accept the
-   * The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a stock location.
    * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
-   * @return {Promise<[StockLocationDTO[], number]>} The list of stock locations along with the total count.
+   * @returns {Promise<[StockLocationDTO[], number]>} The list of stock locations along with their total count.
    *
    * @example
    * To retrieve a list of stock locations using their IDs:
    *
    * ```ts
-   * import {
+   * const [stockLocations, count] =
-   *   initialize as initializeStockLocationModule,
+   *   await stockLocationModuleService.list({
-   * } from "@medusajs/stock-location"
+   *     id: ["sloc_123", "sloc_321"],
-   *
-   * async function listStockLocations (ids: string[]) {
-   *   const stockLocationModule = await initializeStockLocationModule({})
-   *
-   *   const [stockLocations, count] = await stockLocationModule.listAndCount({
-   *     id: ids
    *   })
-   *
-   *   // do something with the stock locations or return them
-   * }
    * ```
    *
    * To specify relations that should be retrieved within the stock locations:
    *
    * ```ts
-   * import {
+   * const [stockLocations, count] =
-   *   initialize as initializeStockLocationModule,
+   *   await stockLocationModuleService.list(
-   * } from "@medusajs/stock-location"
+   *     {
-   *
+   *       id: ["sloc_123", "sloc_321"],
-   * async function listStockLocations (ids: string[]) {
+   *     },
-   *   const stockLocationModule = await initializeStockLocationModule({})
+   *     {
-   *
+   *       relations: ["address"],
-   *   const [stockLocations, count] = await stockLocationModule.listAndCount({
-   *     id: ids
-   *   }, {
-   *     relations: ["address"]
-   *   })
-   *
-   *   // do something with the stock locations or return them
    *     }
+   *   )
    * ```
    *
    * By default, only the first `10` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
    *
    * ```ts
-   * import {
+   * const [stockLocations, count] =
-   *   initialize as initializeStockLocationModule,
+   *   await stockLocationModuleService.list(
-   * } from "@medusajs/stock-location"
+   *     {
-   *
+   *       id: ["sloc_123", "sloc_321"],
-   * async function listStockLocations (ids: string[], skip: number, take: number) {
+   *     },
-   *   const stockLocationModule = await initializeStockLocationModule({})
+   *     {
-   *
-   *   const [stockLocations, count] = await stockLocationModule.listAndCount({
-   *     id: ids
-   *   }, {
    *       relations: ["address"],
-   *     skip,
+   *       take: 20,
-   *     take
+   *       skip: 2,
-   *   })
-   *
-   *   // do something with the stock locations or return them
    *     }
+   *   )
    * ```
    */
   listAndCount(
@@ -171,49 +123,17 @@ export interface IStockLocationServiceNext extends IModuleService {
   ): Promise<[StockLocationDTO[], number]>
 
   /**
-   * This method is used to retrieve a stock location by its ID
+   * This method retrieves a stock location by its ID.
    *
-   * @param {string} id - The ID of the stock location
+   * @param {string} id - The ID of the stock location.
-   * @param {FindConfig<StockLocationDTO>} config -
+   * @param {FindConfig<StockLocationDTO>} config - The configurations determining how the stock location is retrieved. Its properties, such as `select` or `relations`, accept the
-   * The configurations determining how the stock location is retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a stock location.
    * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<StockLocationDTO>} The stock location's details.
+   * @returns {Promise<StockLocationDTO>} The retrieved stock location.
    *
    * @example
-   * A simple example that retrieves a inventory item by its ID:
+   * const stockLocation =
-   *
+   *   await stockLocationModuleService.retrieve("sloc_123")
-   * ```ts
-   * import {
-   *   initialize as initializeStockLocationModule,
-   * } from "@medusajs/stock-location"
-   *
-   * async function retrieveStockLocation (id: string) {
-   *   const stockLocationModule = await initializeStockLocationModule({})
-   *
-   *   const stockLocation = await stockLocationModule.retrieve(id)
-   *
-   *   // do something with the stock location or return it
-   * }
-   * ```
-   *
-   * To specify relations that should be retrieved:
-   *
-   * ```ts
-   * import {
-   *   initialize as initializeStockLocationModule,
-   * } from "@medusajs/stock-location"
-   *
-   * async function retrieveStockLocation (id: string) {
-   *   const stockLocationModule = await initializeStockLocationModule({})
-   *
-   *   const stockLocation = await stockLocationModule.retrieve(id, {
-   *     relations: ["address"]
-   *   })
-   *
-   *   // do something with the stock location or return it
-   * }
-   * ```
    */
   retrieve(
     id: string,
@@ -222,73 +142,131 @@ export interface IStockLocationServiceNext extends IModuleService {
   ): Promise<StockLocationDTO>
 
   /**
-   * This method is used to create a stock location.
+   * This method creates a stock location.
    *
-   * @param {CreateStockLocationInput} input - The details of the stock location to create.
+   * @param {CreateStockLocationInput} input - The stock location to create.
    * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<StockLocationDTO>} The created stock location's details.
+   * @returns {Promise<StockLocationDTO>} The created stock location.
    *
    * @example
-   * import {
+   * const stockLocation = await stockLocationModuleService.create(
-   *   initialize as initializeStockLocationModule,
+   *   {
-   * } from "@medusajs/stock-location"
+   *     name: "Warehouse",
-   *
+   *     address: {
-   * async function createStockLocation (name: string) {
+   *       address_1: "1855 Powder Mill Rd",
-   *   const stockLocationModule = await initializeStockLocationModule({})
+   *       country_code: "us",
-   *
+   *     },
-   *   const stockLocation = await stockLocationModule.create({
-   *     name
-   *   })
-   *
-   *   // do something with the stock location or return it
    *   }
+   * )
    */
   create(
     input: CreateStockLocationInput,
     context?: Context
   ): Promise<StockLocationDTO>
+
+  /**
+   * This method creates stock locations.
+   *
+   * @param {CreateStockLocationInput[]} input - The stock locations to create.
+   * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<StockLocationDTO[]>} The created stock locations.
+   *
+   * @example
+   * const stockLocations =
+   *   await stockLocationModuleService.create([
+   *     {
+   *       name: "Warehouse",
+   *       address: {
+   *         address_1: "1855 Powder Mill Rd",
+   *         country_code: "us",
+   *       },
+   *     },
+   *     {
+   *       name: "Warehouse 2",
+   *       address_id: "laddr_123",
+   *     },
+   *   ])
+   */
   create(
     input: CreateStockLocationInput[],
     context?: Context
   ): Promise<StockLocationDTO[]>
 
+  /**
+   * This method updates or creates stock location service nexts if they don't exist.
+   *
+   * @param {Partial<UpdateStockLocationNextInput>[]} data - The list of Make all properties in t optional
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<StockLocationDTO[]>} The created or updated stock location service nexts.
+   *
+   * @example
+   * {example-code}
+   */
   upsert(
     data: UpsertStockLocationInput[],
     sharedContext?: Context
   ): Promise<StockLocationDTO[]>
+
+  /**
+   * This method updates or creates a stock location service next if it doesn't exist.
+   *
+   * @param {Partial<UpdateStockLocationNextInput>} data - Make all properties in T optional
+   * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<StockLocationDTO>} The created or updated stock location service next.
+   *
+   * @example
+   * {example-code}
+   */
   upsert(
     data: UpsertStockLocationInput,
     sharedContext?: Context
   ): Promise<StockLocationDTO>
 
   /**
-   * This method is used to update a stock location.
+   * This method updates existing stock locations.
    *
-   * @param {string} id - The ID of the stock location.
+   * @param {UpdateStockLocationNextInput[]} input - The attributes to update in the stock locations.
-   * @param {UpdateStockLocationInput} input - The attributes to update in the stock location.
    * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<StockLocationDTO>} The stock location's details.
+   * @returns {Promise<StockLocationDTO[]>} The updated stock locations.
    *
    * @example
-   * import {
+   * const stockLocations =
-   *   initialize as initializeStockLocationModule,
+   *   await stockLocationModuleService.update([
-   * } from "@medusajs/stock-location"
+   *     {
-   *
+   *       id: "sloc_123",
-   * async function updateStockLocation (id:string, name: string) {
+   *       name: "Warehouse",
-   *   const stockLocationModule = await initializeStockLocationModule({})
+   *     },
-   *
+   *     {
-   *   const stockLocation = await stockLocationModule.update(id, {
+   *       id: "sloc_321",
-   *     name
+   *       address_id: "laddr_123",
-   *   })
+   *     },
-   *
+   *   ])
-   *   // do something with the stock location or return it
-   * }
    */
   update(
     id: string,
     input: UpdateStockLocationInput,
     context?: Context
   ): Promise<StockLocationDTO>
+
+  /**
+   * This method updates existing stock locations matching the specified filters.
+   *
+   * @param {FilterableStockLocationProps} selector - The filters specifying which stock locations to update.
+   * @param {UpdateStockLocationInput} input - The attributes to update in the stock locations.
+   * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
+   * @returns {Promise<StockLocationDTO[]>} The updated stock locations.
+   *
+   * @example
+   * const stockLocations =
+   *   await stockLocationModuleService.update(
+   *     {
+   *       name: "Warehouse",
+   *     },
+   *     {
+   *       address_id: "laddr_123",
+   *     }
+   *   )
+   */
   update(
     selector: FilterableStockLocationProps,
     input: UpdateStockLocationInput,
@@ -296,30 +274,34 @@ export interface IStockLocationServiceNext extends IModuleService {
   ): Promise<StockLocationDTO[]>
 
   /**
-   * This method is used to delete a stock location.
+   * This method deletes a stock location by its ID.
    *
    * @param {string} id - The ID of the stock location.
    * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
-   * @returns {Promise<void>} Resolves when the stock location is successfully deleted.
+   * @returns {Promise<void>} Resolves when the stock location is deleted successfully.
    *
    * @example
-   * import {
+   * await stockLocationModuleService.delete("sloc_123")
-   *   initialize as initializeStockLocationModule,
-   * } from "@medusajs/stock-location"
-   *
-   * async function deleteStockLocation (id:string) {
-   *   const stockLocationModule = await initializeStockLocationModule({})
-   *
-   *   await stockLocationModule.delete(id)
-   * }
    */
   delete(id: string, context?: Context): Promise<void>
 
   /**
-   * Soft delete stock locations
+   * This method soft deletes stock locations by their IDs.
-   * @param stockLocationIds
+   *
-   * @param config
+   * @param {string[]} stockLocationIds - The IDs of the stock locations.
-   * @param sharedContext
+   * @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[]>>} An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated address.
+   * The object's keys are the ID attribute names of the stock location entity's relations, such as `address_id`, and its value is an array of strings, each being the ID of a record associated
+   * with the stock location through this relation, such as the IDs of associated address.
+   *
+   * If there are no related records, the promise resolves to `void`.
+   *
+   * @example
+   * await stockLocationModuleService.softDelete([
+   *   "sloc_123",
+   *   "sloc_321",
+   * ])
    */
   softDelete<TReturnableLinkableKeys extends string = string>(
     stockLocationIds: string[],
@@ -328,12 +310,24 @@ export interface IStockLocationServiceNext extends IModuleService {
   ): Promise<Record<string, string[]> | void>
 
   /**
-   * This method is used to restore a stock location or multiple stock locations that were previously deleted using the {@link softDelete} method.
+   * This method restores soft deleted stock locations by their IDs.
    *
-   * @param {string[]} stockLocationIds - The ID(s) of the stock location(s) to restore.
+   * @param {string[]} stockLocationIds - The IDs of the stock locations.
-   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Restore config
+   * @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the stock location. You can pass to its `returnLinkableKeys`
-   * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module.
+   * property any of the stock location's relation attribute names, such as `address`.
-   * @returns {Promise<void>} Resolves when the stock location(s) are successfully restored.
+   * @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 address.
+   * The object's keys are the ID attribute names of the stock location entity's relations, such as `address_id`,
+   * and its value is an array of strings, each being the ID of the record associated with the stock location through this relation,
+   * such as the ID of associated address.
+   *
+   * If there are no related records restored, the promise resolves to `void`.
+   *
+   * @example
+   * await stockLocationModuleService.restore([
+   *   "sloc_123",
+   *   "sloc_321",
+   * ])
    */
   restore<TReturnableLinkableKeys extends string = string>(
     stockLocationIds: string[],