diff --git a/packages/types/src/stock-location/common.ts b/packages/types/src/stock-location/common.ts index 67e41e227c..219477755c 100644 --- a/packages/types/src/stock-location/common.ts +++ b/packages/types/src/stock-location/common.ts @@ -151,6 +151,14 @@ export type StockLocationExpandedDTO = StockLocationDTO & { sales_channels?: any[] // TODO: SalesChannel type } +/** + * @interface + * + * The filters to apply on the retrieved stock locations. + * + * @prop id - The IDs to filter stock locations by. + * @prop name - The names to filter stock locations by. + */ export type FilterableStockLocationProps = { id?: string | string[] name?: string | string[] | StringComparisonOperator diff --git a/packages/types/src/stock-location/service.ts b/packages/types/src/stock-location/service.ts index 68db9f6227..4e52770d40 100644 --- a/packages/types/src/stock-location/service.ts +++ b/packages/types/src/stock-location/service.ts @@ -10,35 +10,289 @@ import { ModuleJoinerConfig } from "../modules-sdk" import { SharedContext } from "../shared-context" export interface IStockLocationService { + /** + * @ignore + */ __joinerConfig(): ModuleJoinerConfig + + /** + * This method is used to retrieve 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 + * attributes or relations associated with a stock location. + * @param {SharedContext} context - A context used to share resources, such as transaction manager, between the application and the module. + * @return {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 + * } + * ``` + * + * 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 + * } + * ``` + * + * 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 + * }, { + * relations: ["address"], + * skip, + * take + * }) + * + * // do something with the stock locations or return them + * } + * ``` + */ list( selector: FilterableStockLocationProps, config?: FindConfig, context?: SharedContext ): 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. + * + * @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 + * attributes or relations associated with a stock location. + * @param {SharedContext} 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. + * + * @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 + * }) + * + * // 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 + * } + * ``` + * + * 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 + * } + * ``` + */ listAndCount( selector: FilterableStockLocationProps, config?: FindConfig, context?: SharedContext ): Promise<[StockLocationDTO[], number]> + /** + * This method is used to retrieve 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 + * attributes or relations associated with a stock location. + * @param {SharedContext} context - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The stock location's details. + * + * @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 + * } + * ``` + */ retrieve( id: string, config?: FindConfig, context?: SharedContext ): Promise + /** + * This method is used to create a stock location. + * + * @param {CreateStockLocationInput} input - The details of the stock location to create. + * @param {SharedContext} 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. + * + * @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 + * } + */ create( input: CreateStockLocationInput, context?: SharedContext ): Promise + /** + * This method is used to update a stock location. + * + * @param {string} id - The ID of the stock location. + * @param {UpdateStockLocationInput} input - The attributes to update in the stock location. + * @param {SharedContext} context - A context used to share resources, such as transaction manager, between the application and the module. + * @returns {Promise} The stock location's details. + * + * @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 + * } + */ update( id: string, input: UpdateStockLocationInput, context?: SharedContext ): Promise + /** + * This method is used to delete a stock location. + * + * @param {string} id - The ID of the stock location. + * @param {SharedContext} 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. + * + * @example + * import { + * initialize as initializeStockLocationModule, + * } from "@medusajs/stock-location" + * + * async function deleteStockLocation (id:string) { + * const stockLocationModule = await initializeStockLocationModule({}) + * + * await stockLocationModule.delete(id) + * } + */ delete(id: string, context?: SharedContext): Promise }