From f65e1dedbc255ec1ad87df6131b1362cb1c96359 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 5 Apr 2024 13:00:46 +0300 Subject: [PATCH] chore: added tsdocs for Stock Location Next Module (#6817) --- packages/types/src/stock-location/common.ts | 14 + .../types/src/stock-location/service-next.ts | 372 +++++++++--------- 2 files changed, 197 insertions(+), 189 deletions(-) diff --git a/packages/types/src/stock-location/common.ts b/packages/types/src/stock-location/common.ts index 6dca9c20a2..48d7dab682 100644 --- a/packages/types/src/stock-location/common.ts +++ b/packages/types/src/stock-location/common.ts @@ -435,8 +435,22 @@ export type UpdateStockLocationInput = { metadata?: Record } +/** + * @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 diff --git a/packages/types/src/stock-location/service-next.ts b/packages/types/src/stock-location/service-next.ts index 6b3744e73d..8fb1cc4e79 100644 --- a/packages/types/src/stock-location/service-next.ts +++ b/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} config - - * The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the + * @param {FindConfig} config - 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. - * @return {Promise} The list of stock locations. + * @returns {Promise} The list of stock locations. * * @example * To retrieve a list of stock locations using their IDs: * * ```ts - * import { - * initialize as initializeStockLocationModule, - * } 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 - * } + * const stockLocations = await stockLocationModuleService.list({ + * id: ["sloc_123", "sloc_321"], + * }) * ``` * * To specify relations that should be retrieved within the stock locations: * * ```ts - * import { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * async function listStockLocations (ids: string[]) { - * const stockLocationModule = await initializeStockLocationModule({}) - * - * const stockLocations = await stockLocationModule.list({ - * id: ids - * }, { - * relations: ["address"] - * }) - * - * // do something with the stock locations or return them - * } + * const stockLocations = await stockLocationModuleService.list( + * { + * id: ["sloc_123", "sloc_321"], + * }, + * { + * relations: ["address"], + * } + * ) * ``` * * 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 { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * async function listStockLocations (ids: string[], skip: number, take: number) { - * const stockLocationModule = await initializeStockLocationModule({}) - * - * const stockLocations = await stockLocationModule.list({ - * id: ids - * }, { + * const stockLocations = await stockLocationModuleService.list( + * { + * id: ["sloc_123", "sloc_321"], + * }, + * { * relations: ["address"], - * skip, - * take - * }) - * - * // do something with the stock locations or return them - * } + * take: 20, + * skip: 2, + * } + * ) * ``` */ list( @@ -94,74 +68,52 @@ export interface IStockLocationServiceNext extends IModuleService { ): Promise /** - * 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} config - - * The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the + * @param {FindConfig} config - 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. - * @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 { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * async function listStockLocations (ids: string[]) { - * const stockLocationModule = await initializeStockLocationModule({}) - * - * const [stockLocations, count] = await stockLocationModule.listAndCount({ - * id: ids + * const [stockLocations, count] = + * await stockLocationModuleService.list({ + * id: ["sloc_123", "sloc_321"], * }) - * - * // do something with the stock locations or return them - * } * ``` * * To specify relations that should be retrieved within the stock locations: * * ```ts - * import { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * async function listStockLocations (ids: string[]) { - * const stockLocationModule = await initializeStockLocationModule({}) - * - * const [stockLocations, count] = await stockLocationModule.listAndCount({ - * id: ids - * }, { - * relations: ["address"] - * }) - * - * // do something with the stock locations or return them - * } + * const [stockLocations, count] = + * await stockLocationModuleService.list( + * { + * id: ["sloc_123", "sloc_321"], + * }, + * { + * relations: ["address"], + * } + * ) * ``` * * 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 { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * 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 - * }) - * - * // do something with the stock locations or return them - * } + * const [stockLocations, count] = + * await stockLocationModuleService.list( + * { + * id: ["sloc_123", "sloc_321"], + * }, + * { + * relations: ["address"], + * take: 20, + * skip: 2, + * } + * ) * ``` */ 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 {FindConfig} config - - * The configurations determining how the stock location is retrieved. Its properties, such as `select` or `relations`, accept the + * @param {string} id - The ID of the stock location. + * @param {FindConfig} config - 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} The stock location's details. + * @returns {Promise} The retrieved stock location. * * @example - * A simple example that retrieves a inventory item by its ID: - * - * ```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 - * } - * ``` + * const stockLocation = + * await stockLocationModuleService.retrieve("sloc_123") */ retrieve( id: string, @@ -222,73 +142,131 @@ export interface IStockLocationServiceNext extends IModuleService { ): Promise /** - * 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} The created stock location's details. + * @returns {Promise} The created stock location. * * @example - * import { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * async function createStockLocation (name: string) { - * const stockLocationModule = await initializeStockLocationModule({}) - * - * const stockLocation = await stockLocationModule.create({ - * name - * }) - * - * // do something with the stock location or return it - * } + * const stockLocation = await stockLocationModuleService.create( + * { + * name: "Warehouse", + * address: { + * address_1: "1855 Powder Mill Rd", + * country_code: "us", + * }, + * } + * ) */ create( input: CreateStockLocationInput, context?: Context ): Promise + + /** + * 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} 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 + /** + * This method updates or creates stock location service nexts if they don't exist. + * + * @param {Partial[]} 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} The created or updated stock location service nexts. + * + * @example + * {example-code} + */ upsert( data: UpsertStockLocationInput[], sharedContext?: Context ): Promise + + /** + * This method updates or creates a stock location service next if it doesn't exist. + * + * @param {Partial} 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} The created or updated stock location service next. + * + * @example + * {example-code} + */ upsert( data: UpsertStockLocationInput, sharedContext?: Context ): Promise /** - * 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 {UpdateStockLocationInput} input - The attributes to update in the stock location. + * @param {UpdateStockLocationNextInput[]} 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} The stock location's details. + * @returns {Promise} The updated stock locations. * * @example - * import { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * async function updateStockLocation (id:string, name: string) { - * const stockLocationModule = await initializeStockLocationModule({}) - * - * const stockLocation = await stockLocationModule.update(id, { - * name - * }) - * - * // do something with the stock location or return it - * } + * const stockLocations = + * await stockLocationModuleService.update([ + * { + * id: "sloc_123", + * name: "Warehouse", + * }, + * { + * id: "sloc_321", + * address_id: "laddr_123", + * }, + * ]) */ update( id: string, input: UpdateStockLocationInput, context?: Context ): Promise + + /** + * 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} 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 /** - * 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} Resolves when the stock location is successfully deleted. + * @returns {Promise} Resolves when the stock location is deleted successfully. * * @example - * import { - * initialize as initializeStockLocationModule, - * } from "@medusajs/stock-location" - * - * async function deleteStockLocation (id:string) { - * const stockLocationModule = await initializeStockLocationModule({}) - * - * await stockLocationModule.delete(id) - * } + * await stockLocationModuleService.delete("sloc_123") */ delete(id: string, context?: Context): Promise /** - * Soft delete stock locations - * @param stockLocationIds - * @param config - * @param sharedContext + * This method soft deletes stock locations by their IDs. + * + * @param {string[]} stockLocationIds - The IDs of the stock locations. + * @param {SoftDeleteReturn} 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>} 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( stockLocationIds: string[], @@ -328,12 +310,24 @@ export interface IStockLocationServiceNext extends IModuleService { ): Promise | 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 {RestoreReturn} config - Restore config - * @param {Context} context - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the stock location(s) are successfully restored. + * @param {string[]} stockLocationIds - The IDs of the stock locations. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the stock location. You can pass to its `returnLinkableKeys` + * property any of the stock location's relation attribute names, such as `address`. + * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise>} 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( stockLocationIds: string[],