chore: added / improved tsdocs to cache, event, file, and notification modules (#11879)

* chore: added / improved tsdocs to cache, event, file, and notification modules

* small fixes

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<T>(key: string): Promise<T | null>
+  /**
+   * 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<void>
+  /**
+   * 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<void>
 }

packages/core/types/src/event-bus/common.ts

@@ -3,6 +3,9 @@ import { Context } from "../shared-context"
 export type Subscriber<TData = unknown> = (data: Event<TData>) => Promise<void>
 
 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<string, unknown> & {
+  /**
+   * 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<TData = unknown> = {
+  /**
+   * 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<TData = unknown> = Event<TData> & {
   options?: Record<string, unknown>
 }

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<T>(
     data: Message<T> | Message<T>[],
     options?: Record<string, unknown>
   ): Promise<void>
 
+  /**
+   * 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<void>
+  /**
+   * 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<void>
 }

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
 }

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
 

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<FileDTO>
 
   /**
-   * 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<FileDTO>} 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[]>} The list of files. In this particular case, it will either be at most one file.
+   * @returns {Promise<FileDTO[]>} 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<FileDTO[]>
 
   /**
-   * 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<FileDTO>} 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,

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
   /**

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<NotificationDTO[]>
 
   /**
-   * 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.