feat: event aggregator (#6218)

What:
- Event Aggregator Util
- Preparation for normalizing event in a new format (backward compatible with the current format)
- GQL Schema to joiner config and some Entities configured
- Link modules emmiting events

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

@@ -1,25 +1,51 @@
 export type Subscriber<T = unknown> = (
-    data: T,
-    eventName: string
-  ) => Promise<void>
-  
-  export type SubscriberContext = {
-    subscriberId: string
+  data: T,
+  eventName: string
+) => Promise<void>
+
+export type SubscriberContext = {
+  subscriberId: string
+}
+
+export type SubscriberDescriptor = {
+  id: string
+  subscriber: Subscriber
+}
+
+export type EventHandler<T = unknown> = (
+  data: T,
+  eventName: string
+) => Promise<void>
+
+export type EmitData<T = unknown> = {
+  eventName: string
+  data: T
+  options?: Record<string, unknown>
+}
+
+export type MessageBody<T = unknown> = {
+  metadata: {
+    service: string
+    action: string
+    object: string
+    eventGroupId?: string
   }
-  
-  export type SubscriberDescriptor = {
-    id: string
-    subscriber: Subscriber
+  data: T
+}
+
+export type Message<T = unknown> = {
+  eventName: string
+  body: MessageBody<T>
+  options?: Record<string, unknown>
+}
+
+export type MessageFormat<T = unknown> = {
+  eventName: string
+  metadata: {
+    service: string
+    action: string
+    object: string
+    eventGroupId?: string
   }
-  
-  export type EventHandler<T = unknown> = (
-    data: T,
-    eventName: string
-  ) => Promise<void>
-  
-  export type EmitData<T = unknown> = {
-    eventName: string
-    data: T
-    options?: Record<string, unknown>
-  }
-  
+  data: T | T[]
+}

packages/types/src/event-bus/event-bus-module.ts

@@ -1,4 +1,4 @@
-import { EmitData, Subscriber, SubscriberContext } from "./common"
+import { EmitData, Message, Subscriber, SubscriberContext } from "./common"
 
 export interface IEventBusModuleService {
   emit<T>(
@@ -7,6 +7,7 @@ export interface IEventBusModuleService {
     options?: Record<string, unknown>
   ): Promise<void>
   emit<T>(data: EmitData<T>[]): Promise<void>
+  emit<T>(data: Message<T>[]): Promise<void>
 
   subscribe(
     eventName: string | symbol,

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

@@ -1,5 +1,5 @@
-import { Subscriber, SubscriberContext } from "."
-import { ITransactionBaseService } from "../transaction-base/transaction-base"
+import { ITransactionBaseService } from "../transaction-base"
+import { EmitData, Message, Subscriber, SubscriberContext } from "./common"
 
 export interface IEventBusService extends ITransactionBaseService {
   subscribe(
@@ -13,5 +13,8 @@ export interface IEventBusService extends ITransactionBaseService {
     subscriber: Subscriber,
     context?: SubscriberContext
   ): this
+
   emit<T>(event: string, data: T, options?: unknown): Promise<unknown | void>
+  emit<T>(data: EmitData<T>[]): Promise<unknown | void>
+  emit<T>(data: Message<T>[]): Promise<unknown | void>
 }

packages/types/src/link-modules/index.ts

@@ -1,11 +1,9 @@
 import { FindConfig } from "../common"
 import { RestoreReturn, SoftDeleteReturn } from "../dal"
-import { ModuleJoinerConfig } from "../modules-sdk"
+import { IModuleService } from "../modules-sdk"
 import { Context } from "../shared-context"
 
-export interface ILinkModule {
-  __joinerConfig(): ModuleJoinerConfig
-
+export interface ILinkModule extends IModuleService {
   list(
     filters?: Record<string, unknown>,
     config?: FindConfig<unknown>,

packages/types/src/pricing/service.ts

@@ -45,16 +45,11 @@ import {
 } from "./common"
 
 import { FindConfig } from "../common"
-import { ModuleJoinerConfig } from "../modules-sdk"
-import { Context } from "../shared-context"
 import { RestoreReturn, SoftDeleteReturn } from "../dal"
+import { IModuleService } from "../modules-sdk"
+import { Context } from "../shared-context"
 
-export interface IPricingModuleService {
-  /**
-   * @ignore
-   */
-  __joinerConfig(): ModuleJoinerConfig
-
+export interface IPricingModuleService extends IModuleService {
   /**
    * This method is used to calculate prices based on the provided filters and context.
    *

packages/types/src/product/service.ts

@@ -1,3 +1,4 @@
+import { RestoreReturn, SoftDeleteReturn } from "../dal"
 import {
   CreateProductCategoryDTO,
   CreateProductCollectionDTO,
@@ -28,18 +29,12 @@ import {
   UpdateProductTypeDTO,
   UpdateProductVariantDTO,
 } from "./common"
-import { RestoreReturn, SoftDeleteReturn } from "../dal"
 
-import { Context } from "../shared-context"
 import { FindConfig } from "../common"
-import { ModuleJoinerConfig } from "../modules-sdk"
-
-export interface IProductModuleService {
-  /**
-   * @ignore
-   */
-  __joinerConfig(): ModuleJoinerConfig
+import { IModuleService } from "../modules-sdk"
+import { Context } from "../shared-context"
 
+export interface IProductModuleService extends IModuleService {
   /**
    * This method is used to retrieve a product by its ID
    *

packages/types/src/shared-context.ts

@@ -1,6 +1,8 @@
 import { EntityManager } from "typeorm"
+import { Message } from "./event-bus"
 
 /**
+ * @deprecated use `Context` instead
  * @interface
  *
  * A context used to share resources, such as transaction manager, between the application and the module.
@@ -16,9 +18,19 @@ export type SharedContext = {
   manager?: EntityManager
 }
 
+export interface MessageAggregatorFormat {
+  groupBy?: string[]
+  sortBy?: { [key: string]: string[] | string | number }
+}
+
+export interface IMessageAggregator {
+  save(msg: Message | Message[]): void
+  getMessages(format?: MessageAggregatorFormat): Record<string, Message[]>
+  clearMessages(): void
+}
+
 /**
  * @interface
- *
  * A context used to share resources, such as transaction manager, between the application and the module.
  */
 export type Context<TManager = unknown> = {
@@ -39,11 +51,20 @@ export type Context<TManager = unknown> = {
    * A boolean value indicating whether nested transactions are enabled.
    */
   enableNestedTransactions?: boolean
+  /**
+   * A string indicating the ID of the group to aggregate the events to be emitted at a later point.
+   */
+  eventGroupId?: string
   /**
    * A string indicating the ID of the current transaction.
    */
   transactionId?: string
 
+  /**
+   * An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.
+   */
+  messageAggregator?: IMessageAggregator
+
   /**
    * A string indicating the ID of the current request.
    */

packages/types/src/stock-location/service.ts

@@ -6,74 +6,69 @@ import {
 } from "./common"
 
 import { FindConfig } from "../common/common"
-import { ModuleJoinerConfig } from "../modules-sdk"
+import { IModuleService } from "../modules-sdk"
 import { SharedContext } from "../shared-context"
 
-export interface IStockLocationService {
-  /**
-   * @ignore
-   */
-  __joinerConfig(): ModuleJoinerConfig
-
+export interface IStockLocationService extends IModuleService {
   /**
    * This method is used to retrieve 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 - 
+   * @param {FindConfig<StockLocationDTO>} config -
    * The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a stock location.
    * @param {SharedContext} 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.
-   * 
+   *
    * @example
    * To retrieve a list of stock locations using their IDs:
-   * 
+   *
    * ```ts
-   * import { 
+   * 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
    * }
    * ```
-   * 
+   *
    * To specify relations that should be retrieved within the stock locations:
-   * 
+   *
    * ```ts
-   * import { 
+   * 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
    * }
    * ```
-   * 
+   *
    * 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 { 
+   * 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
    *   }, {
@@ -81,7 +76,7 @@ export interface IStockLocationService {
    *     skip,
    *     take
    *   })
-   *   
+   *
    *   // do something with the stock locations or return them
    * }
    * ```
@@ -94,63 +89,63 @@ export interface IStockLocationService {
 
   /**
    * 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.
-   * 
+   *
    * @param {FilterableStockLocationProps} selector - The filters to apply on the retrieved stock locations.
-   * @param {FindConfig<StockLocationDTO>} config - 
+   * @param {FindConfig<StockLocationDTO>} config -
    * The configurations determining how the stock locations are retrieved. Its properties, such as `select` or `relations`, accept the
    * attributes or relations associated with a stock location.
    * @param {SharedContext} 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.
-   * 
+   *
    * @example
    * To retrieve a list of stock locations using their IDs:
-   * 
+   *
    * ```ts
-   * import { 
+   * 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
    *   })
-   *   
+   *
    *   // do something with the stock locations or return them
    * }
    * ```
-   * 
+   *
    * To specify relations that should be retrieved within the stock locations:
-   * 
+   *
    * ```ts
-   * import { 
+   * 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
    * }
    * ```
-   * 
+   *
    * 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 { 
+   * 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
    *   }, {
@@ -158,7 +153,7 @@ export interface IStockLocationService {
    *     skip,
    *     take
    *   })
-   *   
+   *
    *   // do something with the stock locations or return them
    * }
    * ```
@@ -171,45 +166,45 @@ export interface IStockLocationService {
 
   /**
    * This method is used to retrieve a stock location by its ID
-   * 
+   *
    * @param {string} id - The ID of the stock location
-   * @param {FindConfig<StockLocationDTO>} config - 
+   * @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 {SharedContext} 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.
-   * 
+   *
    * @example
    * A simple example that retrieves a inventory item by its ID:
-   * 
+   *
    * ```ts
-   * import { 
+   * 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 { 
+   * 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
    * }
    * ```
@@ -222,23 +217,23 @@ export interface IStockLocationService {
 
   /**
    * This method is used to create a stock location.
-   * 
+   *
    * @param {CreateStockLocationInput} input - The details of the stock location to create.
    * @param {SharedContext} 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.
-   * 
+   *
    * @example
-   * import { 
+   * 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
    * }
    */
@@ -249,24 +244,24 @@ export interface IStockLocationService {
 
   /**
    * This method is used to update a stock location.
-   * 
+   *
    * @param {string} id - The ID of the stock location.
    * @param {UpdateStockLocationInput} input - The attributes to update in the stock location.
    * @param {SharedContext} 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.
-   * 
+   *
    * @example
-   * import { 
+   * 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
    * }
    */
@@ -278,19 +273,19 @@ export interface IStockLocationService {
 
   /**
    * This method is used to delete a stock location.
-   * 
+   *
    * @param {string} id - The ID of the stock location.
    * @param {SharedContext} 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.
-   * 
+   *
    * @example
-   * import { 
+   * import {
    *   initialize as initializeStockLocationModule,
    * } from "@medusajs/stock-location"
-   * 
+   *
    * async function deleteStockLocation (id:string) {
    *   const stockLocationModule = await initializeStockLocationModule({})
-   * 
+   *
    *   await stockLocationModule.delete(id)
    * }
    */