New release is coming soon! If you want to try out the latest features, simply run npm i -s moleculer@next. The docs for the latest version are available here.

Events

Broker has a built-in event bus to support Event-driven architecture and to send events to local and remote services.

Please note that built-in events are fire-and-forget meaning that if the service is offline, the event will be lost. For persistent, durable and reliable events please check moleculer-channels.

Balanced events

The event listeners are arranged to logical groups. It means that only one listener is triggered in every group.

Example: you have 2 main services: users & payments. Both subscribe to the user.created event. You start 3 instances of users service and 2 instances of payments service. When you emit the user.created event, only one users and one payments service instance will receive the event.

Balanced events diagram

The group name comes from the service name, but it can be overwritten in event definition in services.

Example

module.exports = {
name: "payment",
events: {
"order.created": {
// Register handler to the "other" group instead of "payment" group.
group: "other",
handler(ctx) {
console.log("Payload:", ctx.params);
console.log("Sender:", ctx.nodeID);
console.log("Metadata:", ctx.meta);
console.log("The called event name:", ctx.eventName);
}
}
}
}

Emit balanced events

Send balanced events with broker.emit function. The first parameter is the name of the event, the second parameter is the payload.
To send multiple values, wrap them into an Object.

// The `user` will be serialized to transportation.
broker.emit("user.created", user);

Specify which groups/services shall receive the event:

// Only the `mail` & `payments` services receives it
broker.emit("user.created", user, ["mail", "payments"]);

Broadcast event

The broadcast event is sent to all available local & remote services. It is not balanced, all service instances will receive it.

Broadcast events diagram

Send broadcast events with broker.broadcast method.

broker.broadcast("config.changed", config);

Specify which groups/services shall receive the event:

// Send to all "mail" service instances
broker.broadcast("user.created", { user }, "mail");

// Send to all "user" & "purchase" service instances.
broker.broadcast("user.created", { user }, ["user", "purchase"]);

Local broadcast event

Send broadcast events only to all local services with broker.broadcastLocal method.

broker.broadcastLocal("config.changed", config);

Subscribe to events

The v0.14 version supports Context-based event handlers. Event context is useful if you are using event-driven architecture and want to trace your events. If you are familiar with Action Context you will feel at home. The Event Context is very similar to Action Context, except for a few new event related properties. Check the complete list of properties

Legacy event handlers

You don’t have to rewrite all existing event handlers as Moleculer still supports legacy signature "user.created"(payload) { ... }. It is capable to detect different signatures of event handlers:

  • If it finds that the signature is "user.created"(ctx) { ... }, it will call it with Event Context.
  • If not, it will call with old arguments & the 4th argument will be the Event Context, like "user.created"(payload, sender, eventName, ctx) {...}
  • You can also force the usage of the new signature by setting context: true in the event declaration

Context-based event handler & emit a nested event

module.exports = {
name: "accounts",
events: {
"user.created"(ctx) {
console.log("Payload:", ctx.params);
console.log("Sender:", ctx.nodeID);
console.log("Metadata:", ctx.meta);
console.log("The called event name:", ctx.eventName);

ctx.emit("accounts.created", { user: ctx.params.user });
},

"user.removed": {
// Force to use context based signature
context: true,
handler(other) {
console.log(`${this.broker.nodeID}:${this.fullName}: Event '${other.eventName}' received. Payload:`, other.params, other.meta);
}
}
}
};

Subscribe to events in ‘events’ property of services. Use of wildcards (?, *, **) is available in event names.

module.exports = {
events: {
// Subscribe to `user.created` event
"user.created"(ctx) {
console.log("User created:", ctx.params);
},

// Subscribe to all `user` events, e.g. "user.created", or "user.removed"
"user.*"(ctx) {
console.log("User event:", ctx.params);
}
// Subscribe to every events
// Legacy event handler signature with context
"**"(payload, sender, event, ctx) {
console.log(`Event '${event}' received from ${sender} node:`, payload);
}
}
}

Event parameter validation

Similar to action parameter validation, the event parameter validation is supported.
Like in action definition, you should define params in event definition and the built-in Validator validates the parameters in events.

// mailer.service.js
module.exports = {
name: "mailer",
events: {
"send.mail": {
// Validation schema
params: {
from: "string|optional",
to: "email",
subject: "string"
},
handler(ctx) {
this.logger.info("Event received, parameters OK!", ctx.params);
}
}
}
};

The validation errors are not sent back to the caller, they are logged or you can catch them with the new global error handler.

Internal events

The broker broadcasts some internal events. These events always starts with $ prefix.

$services.changed

The broker sends this event if the local node or a remote node loads or destroys services.

Payload

Name Type Description
localService Boolean True if a local service changed.

$circuit-breaker.opened

The broker sends this event when the circuit breaker module change its state to open.

Payload

Name Type Description
nodeID String Node ID
action String Action name
failures Number Count of failures

$circuit-breaker.half-opened

The broker sends this event when the circuit breaker module change its state to half-open.

Payload

Name Type Description
nodeID String Node ID
action String Action name

$circuit-breaker.closed

The broker sends this event when the circuit breaker module change its state to closed.

Payload

Name Type Description
nodeID String Node ID
action String Action name

$node.connected

The broker sends this event when a node connected or reconnected.

Payload

Name Type Description
node Node Node info object
reconnected Boolean Is reconnected?

$node.updated

The broker sends this event when it has received an INFO message from a node, (i.e. a service is loaded or destroyed).

Payload

Name Type Description
node Node Node info object

$node.disconnected

The broker sends this event when a node disconnected (gracefully or unexpectedly).

Payload

Name Type Description
node Node Node info object
unexpected Boolean true - Not received heartbeat, false - Received DISCONNECT message from node.

$broker.started

The broker sends this event once broker.start() is called and all local services are started.

$broker.stopped

The broker sends this event once broker.stop() is called and all local services are stopped.

$transporter.connected

The transporter sends this event once the transporter is connected.

$transporter.disconnected

The transporter sends this event once the transporter is disconnected.

$broker.error

The broker emits this event when an error occurs in the broker.
Event payload

{
"error": "<the error object with all properties>"
"module": "broker" // Name of the module where the error happened
"type": "error-type" // Type of error. Full of error types: https://github.com/moleculerjs/moleculer/blob/master/src/constants.js
}

$transit.error

The broker emits this event when an error occurs in the transit module.
Event payload

{
"error": "<the error object with all properties>"
"module": "transit" // Name of the module where the error happened
"type": "error-type" // Type of error. Full of error types: https://github.com/moleculerjs/moleculer/blob/master/src/constants.js
}

$transporter.error

The broker emits this event when an error occurs in the transporter module.
Event payload

{
"error": "<the error object with all properties>"
"module": "transit" // Name of the module where the error happened
"type": "error-type" // Type of error. Full of error types: https://github.com/moleculerjs/moleculer/blob/master/src/constants.js
}

$cacher.error

The broker emits this event when an error occurs in the cacher module.
Event payload

{
"error": "<the error object with all properties>"
"module": "transit" // Name of the module where the error happened
"type": "error-type" // Type of error. Full of error types: https://github.com/moleculerjs/moleculer/blob/master/src/constants.js
}

$discoverer.error

The broker emits this event when an error occurs in the discoverer module.
Event payload

{
"error": "<the error object with all properties>"
"module": "transit" // Name of the module where the error happened
"type": "error-type" // Type of error. Full of error types: https://github.com/moleculerjs/moleculer/blob/master/src/constants.js
}