Skip to main content

realm.pubsub

Realms in Hivekit come with a handy publish/subscribe mechanism for simple and fast many-to-many messaging. You can use this mechanism to send any data that isn't directly part of the state of objects, areas, or instructions - e.g. event notifications, incoming messages, alerts, etc.

Hivekit also uses this mechanism to send server-side events, such as connectionStatusChanged, when a new data provider comes online.

Every connected client and backend process can send and receive messages using this mechanism - but you can also add id patterns if you want to permission clients to publish or receive only certain messages.

// client A subscribes to an event
myRealm.pubsub.subscribe('someEvent', data => {
    //data = {good: 'morning'}
})

// client B publishes a event
myRealm.pubsub.publish('someEvent', {good: 'morning'})

// client A unsubscribes from an event
myRealm.pubsub.unsubscribe('someEvent')

Using ID Patterns​

If you want more fine-grained control over message routing and permissions, you can add an id pattern to your publish and subscribe calls.

This is useful in scenarios where multiple subscribers need to react to subsets of events. Here's an example:

// both bikes and scooters need maintenance and emit a maintenanceRequired event.
// but you're using two different backend processes to process these.
// ID Patterns make it easy to route events to the right receiver

// backend process that handles bike maintenance
myRealm.pubsub.subscribe('maintenanceRequired', 'bike/*', data => {/*...*/ })

// backend process that handles scooter maintenance
myRealm.pubsub.subscribe('maintenanceRequired', 'scooter/*', data => {/*...*/ })

// process that handles all maintenanceRequired events
myRealm.pubsub.subscribe('maintenanceRequired', data => {/*...*/ })

// scooter publishing maintenanceRequired event
myRealm.pubsub.publish('maintenanceRequired', 'scooter/abc-123', { charge: 0.12 })

// bike publishing maintenanceRequired event
myRealm.pubsub.publish('maintenanceRequired', 'bike/def-456', { charge: 0.12 })

Methods​

subscribe(eventName, idPatternOrCallback, callback)​

Subscribes to receive messages for a given event name. Can be used with or without an id pattern.

  • eventName a string specifying the event you wish to receive messages for
  • idPatternOrCallback either a id pattern) string when invoked with three arguments or a callback if invoked with two.
  • callback a function that will be invoked with the event's data if a message is received. If the message contained an id that matched the registered pattern, the id will be passed as the second argument to the callback function
// usage with two arguments: eventName and callback
myRealm.pubsub.subscribe('someMessage', data => {/*...*/ })
// usage with three arguments
myRealm.pubsub.subscribe('maintenanceRequired', 'bike/*', (data, id) => {/*...*/ })

unsubscribe(eventName, idPattern)​

Notifies Hivekit that you are no longer interested in receiving messages for a given eventName and optional id pattern.

  • eventName a string specifying the event you wish to receive messages for
  • idPattern an optional id pattern) string. Only needed if the subscribe call specified the same id pattern.
// usage without id pattern
myRealm.pubsub.unsubscribe('someMessage')
// usage with id patterns
myRealm.pubsub.unsubscribe('maintenanceRequired', 'bike/*')

publish(eventName, idPatternOrData, data)​

Sends a message for the given event name and optional id pattern to all subscribers.

  • eventName a string specifying the event you wish to publish messages for
  • idPatternOrData an optional id pattern) string
  • data any json serializable data that you wish to sent to subscribers
// usage without id pattern or data
myRealm.pubsub.publish('someEvent')

// usage with data
myRealm.pubsub.publish('message', {
    msg: "Sorry, will be five minutes late."
})

// usage with id and data
myRealm.pubsub.publish('message',  'deliveryRider/johndoe', {
    msg: "Sorry, will be five minutes late.",
    sender: 'John Doe'
})