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

chore: add tsdocs for the Store Module resources (#6795)

Browse Source 
* chore: add tsdocs to Store Module resources

* added examples
This commit is contained in:
Shahed Nasser
2024-04-05 12:58:53 +03:00
committed by GitHub
parent eadc5e8a79
commit 8901e32dba
3 changed files with 260 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
packages/types/src/store/common/store.ts
View File

@@ -1,19 +1,72 @@
import { BaseFilterable } from "../../dal"
/**
* The store details.
*/
export interface StoreDTO {
/**
* The ID of the store.
*/
id: string
/**
* The name of the store.
*/
name: string
/**
* The supported currency codes of the store.
*/
supported_currency_codes: string[]
/**
* The default currency code of the store.
*/
default_currency_code?: string
/**
* The associated default sales channel's ID.
*/
default_sales_channel_id?: string
/**
* The associated default region's ID.
*/
default_region_id?: string
/**
* The associated default location's ID.
*/
default_location_id?: string
/**
* Holds custom data in key-value pairs.
*/
metadata: Record<string, any> | null
/**
* The created at of the store.
*/
created_at: string
/**
* The updated at of the store.
*/
updated_at: string
}
/**
* The filters to apply on the retrieved stores.
*/
export interface FilterableStoreProps
extends BaseFilterable<FilterableStoreProps> {
/**
* The IDs to filter the stores by.
*/
id?: string | string[]
/**
* Filter stores by their names.
*/
name?: string | string[]
}

94
packages/types/src/store/mutations/store.ts
View File

@@ -1,30 +1,124 @@
/**
* The store to be created.
*/
export interface CreateStoreDTO {
/**
* The name of the store.
*/
name?: string
/**
* The supported currency codes of the store.
*/
supported_currency_codes?: string[]
/**
* The default currency code of the store.
*/
default_currency_code?: string
/**
* The associated default sales channel's ID.
*/
default_sales_channel_id?: string
/**
* The associated default region's ID.
*/
default_region_id?: string
/**
* The associated default location's ID.
*/
default_location_id?: string
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, any>
}
/**
* The attributes in the store to be created or updated.
*/
export interface UpsertStoreDTO {
/**
* The ID of the store.
*/
id?: string
/**
* The name of the store.
*/
name?: string
/**
* The supported currency codes of the store.
*/
supported_currency_codes?: string[]
/**
* The default currency code of the store.
*/
default_currency_code?: string
/**
* The associated default sales channel's ID.
*/
default_sales_channel_id?: string
/**
* The associated default region's ID.
*/
default_region_id?: string
/**
* The associated default location's ID.
*/
default_location_id?: string
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, any>
}
/**
* The attributes to update in the store.
*/
export interface UpdateStoreDTO {
/**
* The name of the store.
*/
name?: string
/**
* The supported currency codes of the store.
*/
supported_currency_codes?: string[]
/**
* The default currency code of the store.
*/
default_currency_code?: string
/**
* The associated default sales channel's ID.
*/
default_sales_channel_id?: string
/**
* The associated default region's ID.
*/
default_region_id?: string
/**
* The associated default location's ID.
*/
default_location_id?: string
/**
* Holds custom data in key-value pairs.
*/
metadata?: Record<string, any>
}

188
packages/types/src/store/service.ts
View File

@@ -6,7 +6,7 @@ import { FilterableStoreProps, StoreDTO } from "./common"
import { CreateStoreDTO, UpdateStoreDTO, UpsertStoreDTO } from "./mutations"
/**
* The main service interface for the store module.
* The main service interface for the Store Module.
*/
export interface IStoreModuleService extends IModuleService {
/**
@@ -17,7 +17,18 @@ export interface IStoreModuleService extends IModuleService {
* @returns {Promise<StoreDTO[]>} The created stores.
*
* @example
* {example-code}
* const stores = await storeModuleService.create([
* {
* name: "Acme",
* supported_currency_codes: ["usd", "eur"],
* default_currency_code: "usd",
* },
* {
* name: "Acme 2",
* supported_currency_codes: ["usd"],
* default_currency_code: "usd",
* },
* ])
*/
create(data: CreateStoreDTO[], sharedContext?: Context): Promise<StoreDTO[]>
@@ -29,39 +40,63 @@ export interface IStoreModuleService extends IModuleService {
* @returns {Promise<StoreDTO>} The created store.
*
* @example
* {example-code}
* const store = await storeModuleService.create({
* name: "Acme",
* supported_currency_codes: ["usd", "eur"],
* default_currency_code: "usd",
* })
*/
create(data: CreateStoreDTO, sharedContext?: Context): Promise<StoreDTO>
/**
* This method updates existing stores, or creates new ones if they don't exist.
* This method updates or creates stores if they don't exist.
*
* @param {UpsertStoreDTO[]} data - The attributes to update or create in each store.
* @returns {Promise<StoreDTO[]>} The updated and created stores.
* @param {UpsertStoreDTO[]} data - The attributes in the stores to be created or updated.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<StoreDTO[]>} The created or updated stores.
*
* @example
* {example-code}
* const stores = await storeModuleService.upsert([
* {
* id: "store_123",
* name: "Acme",
* },
* {
* name: "Acme 2",
* supported_currency_codes: ["usd"],
* default_currency_code: "usd",
* },
* ])
*/
upsert(data: UpsertStoreDTO[], sharedContext?: Context): Promise<StoreDTO[]>
/**
* This method updates an existing store, or creates a new one if it doesn't exist.
* This method updates or creates a store if it doesn't exist.
*
* @param {UpsertStoreDTO} data - The attributes to update or create for the store.
* @returns {Promise<StoreDTO>} The updated or created store.
* @param {UpsertStoreDTO} data - The attributes in the store to be created or updated.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<StoreDTO>} The created or updated store.
*
* @example
* {example-code}
* const store = await storeModuleService.upsert({
* id: "store_123",
* name: "Acme",
* })
*/
upsert(data: UpsertStoreDTO, sharedContext?: Context): Promise<StoreDTO>
/**
* This method updates an existing store.
*
* @param {string} id - The store's ID.
* @param {UpdateStoreDTO} data - The details to update in the store.
* @param {string} id - The ID of the store.
* @param {UpdateStoreDTO} data - The attributes to update in the store.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<StoreDTO>} The updated store.
*
* @example
* const store = await storeModuleService.update("store_123", {
* name: "Acme",
* })
*/
update(
id: string,
@@ -70,15 +105,22 @@ export interface IStoreModuleService extends IModuleService {
): Promise<StoreDTO>
/**
* This method updates existing stores.
* This method updates existing stores matching the specified filters.
*
* @param {FilterableStoreProps} selector - The filters to specify which stores should be updated.
* @param {UpdateStoreDTO} data - The details to update in the stores.
* @param {FilterableStoreProps} selector - The filters specifying which stores to update.
* @param {UpdateStoreDTO} data - The attributes to update in the store.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<StoreDTO[]>} The updated stores.
*
* @example
* {example-code}
* const store = await storeModuleService.update(
* {
* name: ["Acme"],
* },
* {
* default_currency_code: "usd",
* }
* )
*/
update(
selector: FilterableStoreProps,
@@ -89,12 +131,12 @@ export interface IStoreModuleService extends IModuleService {
/**
* This method deletes stores by their IDs.
*
* @param {string[]} ids - The list of IDs of stores to delete.
* @param {string[]} ids - The IDs of the stores.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the stores are deleted.
* @returns {Promise<void>} Resolves when the stores are deleted successfully.
*
* @example
* {example-code}
* await storeModuleService.delete(["store_123", "store_321"])
*/
delete(ids: string[], sharedContext?: Context): Promise<void>
@@ -103,36 +145,24 @@ export interface IStoreModuleService extends IModuleService {
*
* @param {string} id - The ID of the store.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<void>} Resolves when the store is deleted.
* @returns {Promise<void>} Resolves when the store is deleted successfully.
*
* @example
* {example-code}
* await storeModuleService.delete("store_123")
*/
delete(id: string, sharedContext?: Context): Promise<void>
/**
* This method retrieves a store by its ID.
*
* @param {string} id - The ID of the retrieve.
* @param {string} id - The ID of the store.
* @param {FindConfig<StoreDTO>} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a store.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<StoreDTO>} The retrieved store.
*
* @example
* A simple example that retrieves a {type name} by its ID:
*
* ```ts
* {example-code}
* ```
*
* To specify relations that should be retrieved:
*
* ```ts
* {example-code}
* ```
*
*
* const store = await storeModuleService.retrieve("store_123")
*/
retrieve(
id: string,
@@ -143,32 +173,34 @@ export interface IStoreModuleService extends IModuleService {
/**
* This method retrieves a paginated list of stores based on optional filters and configuration.
*
* @param {FilterableStoreProps} filters - The filters to apply on the retrieved store.
* @param {FilterableStoreProps} filters - The filters to apply on the retrieved stores.
* @param {FindConfig<StoreDTO>} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a store.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<StoreDTO[]>} The list of stores.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of stores using their IDs:
*
* ```ts
* {example-code}
* const stores = await storeModuleService.list({
* id: ["store_123", "store_321"],
* })
* ```
*
* To specify relations that should be retrieved within the {type name}:
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* const stores = await storeModuleService.list(
* {
* id: ["store_123", "store_321"],
* },
* {
* take: 20,
* skip: 2,
* }
* )
* ```
*
* By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* ```
*
*
*/
list(
filters?: FilterableStoreProps,
@@ -179,32 +211,36 @@ export interface IStoreModuleService extends IModuleService {
/**
* This method retrieves a paginated list of stores along with the total count of available stores satisfying the provided filters.
*
* @param {FilterableStoreProps} filters - The filters to apply on the retrieved store.
* @param {FilterableStoreProps} filters - The filters to apply on the retrieved stores.
* @param {FindConfig<StoreDTO>} config - The configurations determining how the store is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a store.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<[StoreDTO[], number]>} The list of stores along with their total count.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of stores using their IDs:
*
* ```ts
* {example-code}
* const [stores, count] = await storeModuleService.listAndCount(
* {
* id: ["store_123", "store_321"],
* }
* )
* ```
*
* To specify relations that should be retrieved within the {type name}:
* By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* const [stores, count] = await storeModuleService.listAndCount(
* {
* id: ["store_123", "store_321"],
* },
* {
* take: 20,
* skip: 2,
* }
* )
* ```
*
* By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
*
* ```ts
* {example-code}
* ```
*
*
*/
listAndCount(
filters?: FilterableStoreProps,
@@ -213,15 +249,19 @@ export interface IStoreModuleService extends IModuleService {
): Promise<[StoreDTO[], number]>
/**
* This method soft deletes stores by their IDs.
* This method soft deletes a store by its IDs.
*
* @param {string[]} storeIds - The list of IDs of stores to soft delete.
* @param {string[]} storeIds - The IDs of the stores.
* @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[]>>} Resolves successfully when the stores are soft-deleted.
* @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were also soft deleted.
* If there are no related records, the promise resolves to `void`.
*
* @example
* {example-code}
* await storeModuleService.softDelete([
* "store_123",
* "store_321",
* ])
*/
softDelete<TReturnableLinkableKeys extends string = string>(
storeIds: string[],
@@ -230,19 +270,17 @@ export interface IStoreModuleService extends IModuleService {
): Promise<Record<string, string[]> | void>
/**
* This method restores soft deleted stores by their IDs.
* This method restores a soft deleted store by its IDs.
*
* @param {string[]} storeIds - The list of IDs of stores to restore.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the stores. You can pass to its `returnLinkableKeys`
* property any of the stores's relation attribute names, such as `currency`.
* @param {string[]} storeIds - The IDs of the stores.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the store. You can pass to its `returnLinkableKeys`
* property any of the store's relation attribute names.
* @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 currency.
* The object's keys are the ID attribute names of the stores entity's relations, such as `currency_code`,
* and its value is an array of strings, each being the ID of the record associated with the store through this relation,
* such as the IDs of associated currency.
* @returns {Promise<void | Record<string, string[]>>} An object that includes the IDs of related records that were restored.
* If there are no related records restored, the promise resolves to `void`.
*
* @example
* {example-code}
* await storeModuleService.restore(["store_123", "store_321"])
*/
restore<TReturnableLinkableKeys extends string = string>(
storeIds: string[],