asyavee/medusa-store
1
0 Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Shahed Nasser authored and GitHub committed 2024-04-05 12:00:46 +02:00
1 parent f25d55bd4f
commit f65e1dedbc
2 files changed
+197 -189
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/types/src/stock-location/common.ts
+14
View File
@@ -435,8 +435,22 @@ export type UpdateStockLocationInput = {
metadata?: Record<string, unknown> metadata?: Record<string, unknown>
} }
/**
* @interface
*
* The attributes to update in a stock location.
*/
export type UpdateStockLocationNextInput = UpdateStockLocationInput & { export type UpdateStockLocationNextInput = UpdateStockLocationInput & {
/**
* The ID of the stock location.
*/
id: string 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> export type UpsertStockLocationInput = Partial<UpdateStockLocationNextInput>
packages/types/src/stock-location/service-next.ts
+183 -189
View File
@@ -7,84 +7,58 @@ import {
UpsertStockLocationInput, UpsertStockLocationInput,
} from "./common" } from "./common"
import { RestoreReturn, SoftDeleteReturn } from "../dal" import { RestoreReturn, SoftDeleteReturn } from "../dal"
import { Context } from "../shared-context" import { Context } from "../shared-context"
import { FindConfig } from "../common/common" import { FindConfig } from "../common/common"
import { IModuleService } from "../modules-sdk" 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 { 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 {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. * 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. * @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 * @example
* To retrieve a list of stock locations using their IDs: * To retrieve a list of stock locations using their IDs:
* *
* ```ts * ```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: * To specify relations that should be retrieved within the stock locations:
* *
* ```ts * ```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: * 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 * ```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"], * relations: ["address"],
* skip, * take: 20,
* take * skip: 2,
* }) * }
* * )
* // do something with the stock locations or return them
* }
* ``` * ```
*/ */
list( list(
@@ -94,74 +68,52 @@ export interface IStockLocationServiceNext extends IModuleService {
): Promise<StockLocationDTO[]> ): 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 {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. * 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. * @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 * @example
* To retrieve a list of stock locations using their IDs: * To retrieve a list of stock locations using their IDs:
* *
* ```ts * ```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: * To specify relations that should be retrieved within the stock locations:
* *
* ```ts * ```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: * 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 * ```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({}) * {
* * relations: ["address"],
* const [stockLocations, count] = await stockLocationModule.listAndCount({ * take: 20,
* id: ids * skip: 2,
* }, { * }
* relations: ["address"], * )
* skip,
* take
* })
*
* // do something with the stock locations or return them
* }
* ``` * ```
*/ */
listAndCount( listAndCount(
@@ -171,49 +123,17 @@ export interface IStockLocationServiceNext extends IModuleService {
): Promise<[StockLocationDTO[], number]> ): 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. * 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. * @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 * @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( retrieve(
id: string, id: string,
@@ -222,73 +142,131 @@ export interface IStockLocationServiceNext extends IModuleService {
): Promise<StockLocationDTO> ): 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. * @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 * @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( create(
input: CreateStockLocationInput, input: CreateStockLocationInput,
context?: Context context?: Context
): Promise<StockLocationDTO> ): 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( create(
input: CreateStockLocationInput[], input: CreateStockLocationInput[],
context?: Context context?: Context
): Promise<StockLocationDTO[]> ): 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( upsert(
data: UpsertStockLocationInput[], data: UpsertStockLocationInput[],
sharedContext?: Context sharedContext?: Context
): Promise<StockLocationDTO[]> ): 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( upsert(
data: UpsertStockLocationInput, data: UpsertStockLocationInput,
sharedContext?: Context sharedContext?: Context
): Promise<StockLocationDTO> ): 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. * @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 * @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( update(
id: string, id: string,
input: UpdateStockLocationInput, input: UpdateStockLocationInput,
context?: Context context?: Context
): Promise<StockLocationDTO> ): 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( update(
selector: FilterableStockLocationProps, selector: FilterableStockLocationProps,
input: UpdateStockLocationInput, input: UpdateStockLocationInput,
@@ -296,30 +274,34 @@ export interface IStockLocationServiceNext extends IModuleService {
): Promise<StockLocationDTO[]> ): 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 {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. * @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 * @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> 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>( softDelete<TReturnableLinkableKeys extends string = string>(
stockLocationIds: string[], stockLocationIds: string[],
@@ -328,12 +310,24 @@ export interface IStockLocationServiceNext extends IModuleService {
): Promise<Record<string, string[]> | void> ): 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>( restore<TReturnableLinkableKeys extends string = string>(
stockLocationIds: string[], stockLocationIds: string[],