219 lines
12 KiB
Plaintext
219 lines
12 KiB
Plaintext
---
|
||
slug: /references/event-service
|
||
tags:
|
||
- event
|
||
- server
|
||
- how to
|
||
sidebar_label: Use Event Module
|
||
keywords:
|
||
- event
|
||
- provider
|
||
- integration
|
||
---
|
||
|
||
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:
|
||
|
||
```ts
|
||
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
|
||
)
|
||
|
||
// TODO use eventModuleService
|
||
}
|
||
)
|
||
```
|
||
|
||
This will resolve the service of the configured Event Module, which is the [Local Event Module](https://docs.medusajs.com/resources/infrastructure-modules/event/local) 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
|
||
|
||
```ts
|
||
await eventModuleService.emit({
|
||
name: "user.created",
|
||
data: {
|
||
user_id: "user_123"
|
||
}
|
||
})
|
||
```
|
||
|
||
### Type Parameters
|
||
|
||
<TypeList types={[{"name":"T","type":"`object`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="emit"/>
|
||
|
||
### Parameters
|
||
|
||
<TypeList types={[{"name":"data","type":"[Message](../../../types/EventBusTypes/types/types.EventBusTypes.Message/page.mdx)<T> \\| [Message](../../../types/EventBusTypes/types/types.EventBusTypes.Message/page.mdx)<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":"","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](../../../types/EventBusTypes/types/types.EventBusTypes.EventMetadata/page.mdx)","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"/>
|
||
|
||
___
|
||
|
||
## subscribe
|
||
|
||
This method adds a subscriber to an event. It's mainly used internally to register subscribers.
|
||
|
||
### Example
|
||
|
||
```ts
|
||
eventModuleService.subscribe("user.created", async (data) => {
|
||
console.log("User created", data)
|
||
})
|
||
```
|
||
|
||
### Parameters
|
||
|
||
<TypeList types={[{"name":"eventName","type":"`string` \\| `symbol`","description":"The name of the event to subscribe to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"subscriber","type":"[Subscriber](../../../types/EventBusTypes/types/types.EventBusTypes.Subscriber/page.mdx)","description":"The subscriber function to execute when the event is emitted.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[SubscriberContext](../../../types/EventBusTypes/types/types.EventBusTypes.SubscriberContext/page.mdx)","description":"The context of the subscriber.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"subscriberId","type":"`string`","description":"The ID of the subscriber. Useful when retrying failed subscribers.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="subscribe"/>
|
||
|
||
### Returns
|
||
|
||
<TypeList types={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"The instance of the Event Module","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="subscribe"/>
|
||
|
||
___
|
||
|
||
## unsubscribe
|
||
|
||
This method removes a subscriber from an event. It's mainly used internally to unregister subscribers.
|
||
|
||
### Example
|
||
|
||
```ts
|
||
eventModuleService.unsubscribe("user.created", async (data) => {
|
||
console.log("User created", data)
|
||
})
|
||
```
|
||
|
||
### Parameters
|
||
|
||
<TypeList types={[{"name":"eventName","type":"`string` \\| `symbol`","description":"The name of the event to unsubscribe from.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"subscriber","type":"[Subscriber](../../../types/EventBusTypes/types/types.EventBusTypes.Subscriber/page.mdx)","description":"The subscriber function to remove.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"context","type":"[SubscriberContext](../../../types/EventBusTypes/types/types.EventBusTypes.SubscriberContext/page.mdx)","description":"The context of the subscriber.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"subscriberId","type":"`string`","description":"The ID of the subscriber. Useful when retrying failed subscribers.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="unsubscribe"/>
|
||
|
||
### Returns
|
||
|
||
<TypeList types={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"The instance of the Event Module","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="unsubscribe"/>
|
||
|
||
___
|
||
|
||
## 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
|
||
|
||
```ts
|
||
await eventModuleService.releaseGroupedEvents("group_123")
|
||
```
|
||
|
||
### Parameters
|
||
|
||
<TypeList types={[{"name":"eventGroupId","type":"`string`","description":"The ID of the event group.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="releaseGroupedEvents"/>
|
||
|
||
### 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
|
||
|
||
```ts
|
||
await eventModuleService.clearGroupedEvents("group_123")
|
||
```
|
||
|
||
### Parameters
|
||
|
||
<TypeList types={[{"name":"eventGroupId","type":"`string`","description":"The ID of the event group.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"options","type":"`object`","description":"Additional options for the event.","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"eventNames","type":"`string`[]","description":"The names of the events to clear. If not provided, The group will\nbe entirely cleared.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="clearGroupedEvents"/>
|
||
|
||
### 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
|
||
|
||
<BadgesList badges={[
|
||
{
|
||
"variant": "neutral",
|
||
"children": "optional"
|
||
}
|
||
]} className="mb-1" />
|
||
|
||
This method adds an interceptor to the event bus. This means that the interceptor will be
|
||
called before the event is emitted.
|
||
|
||
### Example
|
||
|
||
```ts
|
||
eventModuleService.addInterceptor((message, context) => {
|
||
console.log("Interceptor", message, context)
|
||
})
|
||
```
|
||
|
||
### Parameters
|
||
|
||
<TypeList types={[{"name":"interceptor","type":"[InterceptorSubscriber](../../../types/EventBusTypes/types/types.EventBusTypes.InterceptorSubscriber/page.mdx)","description":"The interceptor to add.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="addInterceptor"/>
|
||
|
||
### Returns
|
||
|
||
<TypeList types={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"The instance of the Event Module","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="addInterceptor"/>
|
||
|
||
___
|
||
|
||
## removeInterceptor
|
||
|
||
<BadgesList badges={[
|
||
{
|
||
"variant": "neutral",
|
||
"children": "optional"
|
||
}
|
||
]} className="mb-1" />
|
||
|
||
This method removes an interceptor from the event bus.
|
||
|
||
### Example
|
||
|
||
```ts
|
||
eventModuleService.removeInterceptor((message, context) => {
|
||
console.log("Interceptor", message, context)
|
||
})
|
||
```
|
||
|
||
### Parameters
|
||
|
||
<TypeList types={[{"name":"interceptor","type":"[InterceptorSubscriber](../../../types/EventBusTypes/types/types.EventBusTypes.InterceptorSubscriber/page.mdx)","description":"The interceptor to remove.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="removeInterceptor"/>
|
||
|
||
### Returns
|
||
|
||
<TypeList types={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"The instance of the Event Module","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="removeInterceptor"/>
|