import { TypeList } from "docs-ui"

How to Use Event Module

In this document, you’ll learn about the different methods in the Event Module's service and how to use them.

Resolve Event Module's Service

In your workflow's step, you can resolve the Event Module's service from the Medusa container:

import { Modules } from "@medusajs/framework/utils"
import { createStep } from "@medusajs/framework/workflows-sdk"

const step1 = createStep(
  "step-1",
  async ({}, { container }) => {
    const eventModuleService = container.resolve(
      Modules.EVENT_BUS
    )
    
    // TODO use eventModuleService
  } 
)

This will resolve the service of the configured Event Module, which is the Local Event Module by default.

You can then use the Event Module's service's methods in the step. The rest of this guide details these methods.

emit

This method emits one or more events. Subscribers listening to the event(s) are executed asynchronously.

Example

await eventModuleService.emit({
  name: "user.created",
  data: {
    user_id: "user_123"
  }
})

Type Parameters

Parameters

<TypeList types={[{"name":"data","type":"Message<T> \| Message<T>[]","description":"The details of the events to emit.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"name","type":"string","description":"The event's name.","optional":false,"defaultValue":"","example":"user.created","expandable":false,"children":[]},{"name":"data","type":"TData","description":"The data payload that subscribers receive. For example, the ID or IDs of the created user. (e.g. { id: "123" } or { ids: ["123", "456"] })","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"metadata","type":"EventMetadata","description":"Additional meadata to pass with the event.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"eventGroupId","type":"string","description":"The ID of the event's group. Grouped events are useful when you have distributed transactions\nwhere you need to explicitly group, release and clear events upon lifecycle events of a transaction.\n\nWhen set, you must release the grouped events using the Event Module's releaseGroupedEvents method to emit the events.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"options","type":"Record<string, unknown>","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"options","type":"Record<string, unknown>","description":"Additional options for the event.","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="emit"/>

Returns

<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"This method emits one or more events. Subscribers listening to the event(s) are executed asynchronously.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="emit"/>

This method adds a subscriber to an event. It's mainly used internally to register subscribers.

Example

eventModuleService.subscribe("user.created", async (data) => {
  console.log("User created", data)
})

Parameters

Returns

unsubscribe

This method removes a subscriber from an event. It's mainly used internally to unregister subscribers.

Example

eventModuleService.unsubscribe("user.created", async (data) => {
  console.log("User created", data)
})

Parameters

Returns

releaseGroupedEvents

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.

Example

await eventModuleService.releaseGroupedEvents("group_123")

Parameters

Returns

<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"This method emits all events in the specified group. Grouped events are useful when you have distributed transactions\nwhere you need to explicitly group, release and clear events upon lifecycle events of a transaction.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="releaseGroupedEvents"/>

clearGroupedEvents

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.

Example

await eventModuleService.clearGroupedEvents("group_123")

Parameters

Returns

<TypeList types={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"This method removes all events in the specified group. Grouped events are useful when you have distributed transactions\nwhere you need to explicitly group, release and clear events upon lifecycle events of a transaction.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="clearGroupedEvents"/>

addInterceptor

This method adds an interceptor to the event bus. This means that the interceptor will be called before the event is emitted.

Example

eventModuleService.addInterceptor((message, context) => {
  console.log("Interceptor", message, context)
})

Parameters

Returns

removeInterceptor

This method removes an interceptor from the event bus.

Example

eventModuleService.removeInterceptor((message, context) => {
  console.log("Interceptor", message, context)
})

Parameters