diff --git a/packages/core/types/src/cache/service.ts b/packages/core/types/src/cache/service.ts index b96b41e57b..a55121a248 100644 --- a/packages/core/types/src/cache/service.ts +++ b/packages/core/types/src/cache/service.ts @@ -1,5 +1,32 @@ export interface ICacheService { + /** + * This method retrieves data from the cache. + * + * @param key - The key of the item to retrieve. + * @returns The item that was stored in the cache. If the item was not found, null is returned. + * + * @example + * const data = await cacheModuleService.get("my-key") + */ get(key: string): Promise + /** + * This method stores data in the cache. + * + * @param key - The key of the item to store. + * @param data - The data to store in the cache. + * @param ttl - The time-to-live (TTL) value in seconds. If not provided, the default TTL value is used. The default value is based on the used Cache Module. + * + * @example + * await cacheModuleService.set("my-key", { product_id: "prod_123" }, 60) + */ set(key: string, data: unknown, ttl?: number): Promise + /** + * This method removes an item from the cache. + * + * @param key - The key of the item to remove. + * + * @example + * await cacheModuleService.invalidate("my-key") + */ invalidate(key: string): Promise } diff --git a/packages/core/types/src/event-bus/common.ts b/packages/core/types/src/event-bus/common.ts index 85696ff213..744b13f909 100644 --- a/packages/core/types/src/event-bus/common.ts +++ b/packages/core/types/src/event-bus/common.ts @@ -3,6 +3,9 @@ import { Context } from "../shared-context" export type Subscriber = (data: Event) => Promise export type SubscriberContext = { + /** + * The ID of the subscriber. Useful when retrying failed subscribers. + */ subscriberId: string } @@ -12,15 +15,36 @@ export type SubscriberDescriptor = { } export type EventMetadata = Record & { + /** + * The ID of the event's group. Grouped events are useful when you have distributed transactions + * where you need to explicitly group, release and clear events upon lifecycle events of a transaction. + * + * When set, you must release the grouped events using the Event Module's `releaseGroupedEvents` method to emit the events. + */ eventGroupId?: string } export type Event = { + /** + * The event's name. + * + * @example + * user.created + */ name: string + /** + * Additional meadata to pass with the event. + */ metadata?: EventMetadata + /** + * The data payload that subscribers receive. For example, the ID of the created user. + */ data: TData } +/** + * The details of an event to emit. + */ export type Message = Event & { options?: Record } diff --git a/packages/core/types/src/event-bus/event-bus-module.ts b/packages/core/types/src/event-bus/event-bus-module.ts index 1ff808002c..5c09b33ac5 100644 --- a/packages/core/types/src/event-bus/event-bus-module.ts +++ b/packages/core/types/src/event-bus/event-bus-module.ts @@ -1,23 +1,81 @@ import { Message, Subscriber, SubscriberContext } from "./common" export interface IEventBusModuleService { + /** + * This method emits one or more events. Subscribers listening to the event(s) are executed asynchronously. + * + * @param data - The details of the events to emit. + * @param options - Additional options for the event. + * + * @example + * await eventModuleService.emit({ + * name: "user.created", + * data: { + * user_id: "user_123" + * } + * }) + */ emit( data: Message | Message[], options?: Record ): Promise + /** + * This method adds a subscriber to an event. It's mainly used internally to register subscribers. + * + * @param eventName - The name of the event to subscribe to. + * @param subscriber - The subscriber function to execute when the event is emitted. + * @param context - The context of the subscriber. + * @returns The instance of the Event Module + * + * @example + * eventModuleService.subscribe("user.created", async (data) => { + * console.log("User created", data) + * }) + */ subscribe( eventName: string | symbol, subscriber: Subscriber, context?: SubscriberContext ): this + /** + * This method removes a subscriber from an event. It's mainly used internally to unregister subscribers. + * + * @param eventName - The name of the event to unsubscribe from. + * @param subscriber - The subscriber function to remove. + * @param context - The context of the subscriber. + * @returns The instance of the Event Module + * + * @example + * eventModuleService.unsubscribe("user.created", async (data) => { + * console.log("User created", data) + * }) + */ unsubscribe( eventName: string | symbol, subscriber: Subscriber, context?: SubscriberContext ): this + /** + * This method emits all events in the specified group. Grouped events are useful when you have distributed transactions + * where you need to explicitly group, release and clear events upon lifecycle events of a transaction. + * + * @param eventGroupId - The ID of the event group. + * + * @example + * await eventModuleService.releaseGroupedEvents("group_123") + */ releaseGroupedEvents(eventGroupId: string): Promise + /** + * This method removes all events in the specified group. Grouped events are useful when you have distributed transactions + * where you need to explicitly group, release and clear events upon lifecycle events of a transaction. + * + * @param eventGroupId - The ID of the event group. + * + * @example + * await eventModuleService.clearGroupedEvents("group_123") + */ clearGroupedEvents(eventGroupId: string): Promise } diff --git a/packages/core/types/src/file/common.ts b/packages/core/types/src/file/common.ts index 4042a2a50d..b364d9379f 100644 --- a/packages/core/types/src/file/common.ts +++ b/packages/core/types/src/file/common.ts @@ -3,11 +3,12 @@ */ export interface FileDTO { /** - * The ID of the File. + * The ID of the file. You can use this ID later to + * retrieve or delete the file. */ id: string /** - * The URL of the File. + * The URL of the file. */ url: string } diff --git a/packages/core/types/src/file/mutations.ts b/packages/core/types/src/file/mutations.ts index e6fb3a871b..9b92e1848d 100644 --- a/packages/core/types/src/file/mutations.ts +++ b/packages/core/types/src/file/mutations.ts @@ -3,17 +3,20 @@ */ export interface CreateFileDTO { /** - * The filename of the uploaded file + * The name of the uploaded file */ filename: string /** * The mimetype of the uploaded file + * + * @example + * image/png */ mimeType: string /** - * The file content as a binary-encoded string + * The file content as a binary-encoded string (For example, base64). */ content: string diff --git a/packages/core/types/src/file/service.ts b/packages/core/types/src/file/service.ts index 8e98141e10..cb779b6689 100644 --- a/packages/core/types/src/file/service.ts +++ b/packages/core/types/src/file/service.ts @@ -4,9 +4,6 @@ import { FindConfig } from "../common" import { Context } from "../shared-context" import { CreateFileDTO } from "./mutations" -/** - * The main service interface for the File Module. - */ export interface IFileModuleService extends IModuleService { /** * This method uploads files to the designated file storage system. @@ -19,7 +16,7 @@ export interface IFileModuleService extends IModuleService { * const [file] = await fileModuleService.createFiles([{ * filename: "product.png", * mimeType: "image/png", - * content: "somecontent" + * content: "somecontent" // base64 encoded * }]) */ createFiles( @@ -38,7 +35,7 @@ export interface IFileModuleService extends IModuleService { * const file = await fileModuleService.createFiles({ * filename: "product.png", * mimeType: "image/png", - * content: "somecontent" + * content: "somecontent" // base64 encoded * }) */ @@ -87,15 +84,17 @@ export interface IFileModuleService extends IModuleService { ): Promise /** - * This method is used to retrieve a file by ID, similarly to `retrieve`. Enumeration of files is not supported, but the list method is in order to support remote queries + * This method is used to retrieve a file by ID, similarly to `retrieve`. It doesn't retrieve multiple files, but it's added to support retrieving files with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query). * * @param {FilterableFileProps} filters - The filters to apply on the retrieved files. * @param {FindConfig} config - * The configurations determining how the files are retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a file. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The list of files. In this particular case, it will either be at most one file. + * @returns {Promise} The list of files. In this case, it will have at most one file. * + * @example + * const files = await fileModuleService.listFiles({ id: "file_123" }) */ listFiles( filters?: FilterableFileProps, @@ -104,15 +103,17 @@ export interface IFileModuleService extends IModuleService { ): Promise /** - * This method is used to retrieve a file by ID, similarly to `retrieve`. Enumeration of files is not supported, but the listAndCount method is in order to support remote queries + * This method is used to retrieve a file by ID, similarly to `retrieve`. It doesn't retrieve multiple files, but it's added to support retrieving files with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query). * * @param {FilterableFileProps} filters - The filters to apply on the retrieved files. * @param {FindConfig} config - * The configurations determining how the files are retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a file. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise<[FileDTO[], number]>} The list of files and their count. In this particular case, it will either be at most one file. + * @returns {Promise<[FileDTO[], number]>} The list of files and their count. In this case, it will have at most one file. * + * @example + * const [files] = await fileModuleService.listAndCountFiles({ id: "file_123" }) */ listAndCountFiles( filters?: FilterableFileProps, diff --git a/packages/core/types/src/notification/mutations.ts b/packages/core/types/src/notification/mutations.ts index 004fdc4f53..416c7aafd3 100644 --- a/packages/core/types/src/notification/mutations.ts +++ b/packages/core/types/src/notification/mutations.ts @@ -12,7 +12,7 @@ export interface CreateNotificationDTO { */ to: string /** - * The channel through which the notification is sent, such as 'email' or 'sms' + * The channel through which the notification is sent, such as `email` or `sms`. */ channel: string /** @@ -32,11 +32,12 @@ export interface CreateNotificationDTO { */ trigger_type?: string | null /** - * The ID of the resource this notification is for, if applicable. Useful for displaying relevant information in the UI + * The ID of the resource this notification is for, if applicable. Useful for displaying relevant information in the UI. + * For example, the ID of the order if the notification is related to an order update. */ resource_id?: string | null /** - * The type of the resource this notification is for, if applicable, eg. "order" + * The type of the resource this notification is for, if applicable. For example, `order` if it's related to an order update. */ resource_type?: string | null /** @@ -44,7 +45,7 @@ export interface CreateNotificationDTO { */ receiver_id?: string | null /** - * The original notification, in case this is a retried notification. + * The original notification, in case this is a resent notification. */ original_notification_id?: string | null /** diff --git a/packages/core/types/src/notification/service.ts b/packages/core/types/src/notification/service.ts index 49ee65b4f2..9c5c4ea946 100644 --- a/packages/core/types/src/notification/service.ts +++ b/packages/core/types/src/notification/service.ts @@ -4,12 +4,9 @@ import { Context } from "../shared-context" import { FilterableNotificationProps, NotificationDTO } from "./common" import { CreateNotificationDTO } from "./mutations" -/** - * The main service interface for the Notification Module. - */ export interface INotificationModuleService extends IModuleService { /** - * This method is used to send multiple notifications, and store the requests in the DB. + * This method is used to send multiple notifications and store them in the database. * * @param {CreateNotificationDTO[]} data - The notifications to be sent. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. @@ -35,7 +32,7 @@ export interface INotificationModuleService extends IModuleService { ): Promise /** - * This method is used to send a notification, and store the request in the DB. + * This method is used to send a notification, and store the request in the database. * * @param {CreateNotificationDTO} data - The notification to be sent. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.