Custom Events

In some cases you might want to send events that are not about changing the state of a resource. It can be a notification that a new message has arrived, or that it is time to take a break.

Whatever it is, you can do that with custom events.

Custom events

A custom event¹ is like sending any other event. It has the following subject pattern:

event.<resource>.<name>

Where resource is the resource ID on which the event is sent, and name is your alphanumeric (no dots!) event name.

The only restriction is that the event name may not be any of the following predefined events: change, add, remove, unsubscribe, reaccess, query, or delete.

Event message

There are no restrictions on the event message. It may even be null. The event with its payload will be sent unaltered to any client subscribing to the resource.

Example

In code it could look like this:

nats.publish("event.example.foo.break", JSON.stringify({
	"message": "Time to take a break!"
}));

Note

Custom events are not persisted anywhere. If the client misses the event due to a disconnect, it may not be retrieved.

If it is important that events are not lost, consider using a collection instead, where the “events” are added as messages to the collection, as described in Chapter 5 - Collection events.