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
2024-04-05 13:00:46 +03:00
committed by GitHub
parent f25d55bd4f
commit f65e1dedbc
2 changed files with 197 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/types/src/stock-location/common.ts
+14
View File
@@ -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
+183 -189
View File
@@ -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 -
* The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the
* @param {FindConfig<StockLocationDTO>} 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[]>} 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 {
* 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<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 -
* The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the
* @param {FindConfig<StockLocationDTO>} 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<StockLocationDTO>} 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<StockLocationDTO>} 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<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:
*
* ```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<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 {
* 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<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 {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<StockLocationDTO>} The stock location's details.
* @returns {Promise<StockLocationDTO[]>} 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<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 {
* 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<void>
/**
* 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<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 {RestoreReturn<TReturnableLinkableKeys>} config - Restore config
* @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(s) are successfully restored.
* @param {string[]} stockLocationIds - The IDs of the stock locations.
* @param {RestoreReturn<TReturnableLinkableKeys>} 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<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[],