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

chore: add tsdocs for the Sales Channel Module (#6794)

Browse Source 
Add/update TSDocs to the Sales Channel Module's resources
This commit is contained in:
Shahed Nasser
2024-03-27 18:24:00 +00:00
committed by GitHub
parent ff84f749d5
commit 5e53b917f7
2 changed files with 139 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/types/src/sales-channel/mutations.ts
+5 -1
View File
@@ -42,6 +42,9 @@ export interface UpdateSalesChannelDTO {
metadata?: Record<string, unknown>
}
/**
* The attributes in the sales channel to be created or updated.
*/
export interface UpsertSalesChannelDTO {
/**
* The ID of the sales channel.
@@ -49,7 +52,8 @@ export interface UpsertSalesChannelDTO {
id?: string
/**
* The name of the sales channel.
* The name of the sales channel. Required
* when creating a sales channel.
*/
name?: string
packages/types/src/sales-channel/service.ts
+134 -63
View File
@@ -3,21 +3,29 @@ import { RestoreReturn, SoftDeleteReturn } from "../dal"
import { IModuleService } from "../modules-sdk"
import { Context } from "../shared-context"
import { FilterableSalesChannelProps, SalesChannelDTO } from "./common"
import { CreateSalesChannelDTO, UpdateSalesChannelDTO, UpsertSalesChannelDTO } from "./mutations"
import {
CreateSalesChannelDTO,
UpdateSalesChannelDTO,
UpsertSalesChannelDTO,
} from "./mutations"
/**
* The main service interface for the sales channel module.
* The main service interface for the Sales Channel Module.
*/
export interface ISalesChannelModuleService extends IModuleService {
/**
* This method creates sales channels.
*
* @param {CreateSalesChannelDTO[]} data - The sales channel to be created.
* @param {CreateSalesChannelDTO[]} data - The sales channels to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<SalesChannelDTO[]>} The created sales channels.
*
* @example
* {example-code}
* const salesChannels = await salesChannelModuleService.create([
* {
* name: "B2B",
* },
* ])
*/
create(
data: CreateSalesChannelDTO[],
@@ -29,45 +37,113 @@ export interface ISalesChannelModuleService extends IModuleService {
*
* @param {CreateSalesChannelDTO} data - The sales channel to be created.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<SalesChannelDTO>} The created a sales channel.
* @returns {Promise<SalesChannelDTO>} The created sales channel.
*
* @example
* {example-code}
* const salesChannel = await salesChannelModuleService.create({
* name: "B2B",
* })
*/
create(
data: CreateSalesChannelDTO,
sharedContext?: Context
): Promise<SalesChannelDTO>
/**
* This method updates an existing sales channel.
*
* @param {string} channelId - The sales channel's ID.
* @param {UpdateSalesChannelDTO} data - The attributes to update in the sales channel.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<SalesChannelDTO>} The updated sales channel.
*
* @example
* const salesChannel = await salesChannelModuleService.update(
* "sc_123",
* {
* description: "Sales channel for B2B customers",
* }
* )
*/
update(
channelId: string,
data: UpdateSalesChannelDTO,
sharedContext?: Context
): Promise<SalesChannelDTO>
/**
* This method updates existing sales channels matching the specified filters
*
* @param {FilterableSalesChannelProps} selector - The filters specifying which sales channels to update.
* @param {UpdateSalesChannelDTO} data - The attributes to update in the sales channel.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<SalesChannelDTO[]>} The updated sales channels.
*
* @example
* const salesChannels = await salesChannelModuleService.update(
* {
* name: "B2B",
* },
* {
* description: "Sales channel for B2B customers",
* }
* )
*/
update(
selector: FilterableSalesChannelProps,
data: UpdateSalesChannelDTO,
sharedContext?: Context
): Promise<SalesChannelDTO[]>
/**
* This method updates or creates a sales channel if it doesn't exist.
*
* @param {UpsertSalesChannelDTO} data - The attributes in the sales channel 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<SalesChannelDTO>} The created or updated sales channel.
*
* @example
* const salesChannel = await salesChannelModuleService.upsert({
* name: "B2B",
* })
*/
upsert(
data: UpsertSalesChannelDTO,
sharedContext?: Context
): Promise<SalesChannelDTO>
/**
* This method updates or creates sales channels if they don't exist.
*
* @param {UpsertSalesChannelDTO[]} data - The attributes in the sales channels 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<SalesChannelDTO[]>} The created or updated sales channels.
*
* @example
* const salesChannels = await salesChannelModuleService.upsert([
* {
* name: "B2B",
* },
* {
* id: "sc_123",
* description: "Sales channel for B2B customers",
* },
* ])
*/
upsert(
data: UpsertSalesChannelDTO[],
sharedContext?: Context
): Promise<SalesChannelDTO[]>
/**
* This method deletes sales channels by their IDs.
* This method deletes sales channel by their IDs.
*
* @param {string[]} ids - The list of IDs of sales channels to delete.
* @param {string[]} ids - The IDs of the sales channel.
* @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 sales channels are deleted.
* @returns {Promise<void>} Resolves when the sales channels are deleted successfully.
*
* @example
* {example-code}
* await salesChannelModuleService.delete(["sc_123", "sc_321"])
*/
delete(ids: string[], sharedContext?: Context): Promise<void>
@@ -76,36 +152,25 @@ export interface ISalesChannelModuleService extends IModuleService {
*
* @param {string} id - The ID of the sales channel.
* @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 sales channel is deleted.
* @returns {Promise<void>} Resolves when the sales channel is deleted successfully.
*
* @example
* {example-code}
* await salesChannelModuleService.delete("sc_123")
*/
delete(id: string, sharedContext?: Context): Promise<void>
/**
* This method retrieves a sales channel by its ID.
*
* @param {string} id - The ID of the retrieve.
* @param {string} id - The ID of the sales channel.
* @param {FindConfig<SalesChannelDTO>} config - The configurations determining how the sales channel is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a sales channel.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<SalesChannelDTO>} The retrieved sales channels.
* @returns {Promise<SalesChannelDTO>} The retrieved sales channel.
*
* @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 salesChannel =
* await salesChannelModuleService.retrieve("sc_123")
*/
retrieve(
id: string,
@@ -116,32 +181,34 @@ export interface ISalesChannelModuleService extends IModuleService {
/**
* This method retrieves a paginated list of sales channels based on optional filters and configuration.
*
* @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channel.
* @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channels.
* @param {FindConfig<SalesChannelDTO>} config - The configurations determining how the sales channel is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a sales channel.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<SalesChannelDTO[]>} The list of sales channels.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of sales channels using their IDs:
*
* ```ts
* {example-code}
* const salesChannels = await salesChannelModuleService.list({
* id: ["sc_123", "sc_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 salesChannels = await salesChannelModuleService.list(
* {
* id: ["sc_123", "sc_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?: FilterableSalesChannelProps,
@@ -152,32 +219,36 @@ export interface ISalesChannelModuleService extends IModuleService {
/**
* This method retrieves a paginated list of sales channels along with the total count of available sales channels satisfying the provided filters.
*
* @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channel.
* @param {FilterableSalesChannelProps} filters - The filters to apply on the retrieved sales channels.
* @param {FindConfig<SalesChannelDTO>} config - The configurations determining how the sales channel is retrieved. Its properties, such as `select` or `relations`, accept the
* attributes or relations associated with a sales channel.
* @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
* @returns {Promise<[SalesChannelDTO[], number]>} The list of sales channels along with their total count.
*
* @example
* To retrieve a list of {type name} using their IDs:
* To retrieve a list of sales channels using their IDs:
*
* ```ts
* {example-code}
* const [salesChannels, count] =
* await salesChannelModuleService.listAndCount({
* id: ["sc_123", "sc_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 [salesChannels, count] =
* await salesChannelModuleService.listAndCount(
* {
* id: ["sc_123", "sc_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?: FilterableSalesChannelProps,
@@ -188,13 +259,14 @@ export interface ISalesChannelModuleService extends IModuleService {
/**
* This method soft deletes sales channels by their IDs.
*
* @param {string[]} salesChannelIds - The list of IDs of sales channels to soft delete.
* @param {string[]} salesChannelIds - The sales channels' ID.
* @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 when the sales channels 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 salesChannelModuleService.delete(["sc_123", "sc_321"])
*/
softDelete<TReturnableLinkableKeys extends string = string>(
salesChannelIds: string[],
@@ -203,18 +275,17 @@ export interface ISalesChannelModuleService extends IModuleService {
): Promise<Record<string, string[]> | void>
/**
* This method restores soft deleted sales channels by their IDs.
* This method restores a soft deleted sales channel by its IDs.
*
* @param {string[]} salesChannelIds - The list of IDs of sales channels to restore.
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the sales channels. You can pass to its `returnLinkableKeys`
* property any of the sales channels's relation attribute names.
* @param {string[]} salesChannelIds - The list of {summary}
* @param {RestoreReturn<TReturnableLinkableKeys>} config - Configurations determining which relations to restore along with each of the sales channel. You can pass to its `returnLinkableKeys`
* property any of the sales channel'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.
* The object's keys are the ID attribute names of the sales channels entity's relations,
* and its value is an array of strings, each being the ID of the record associated with the sales channel through this relation.
* If there are no related records restored, the promise resolves to `void`.
*
* @example
* {example-code}
* await salesChannelModuleService.restore(["sc_123", "sc_321"])
*/
restore<TReturnableLinkableKeys extends string = string>(
salesChannelIds: string[],