API

The Turms package is a single object that provides access to constructor functions for Message, Subscriber and Hub objects.

Message(options)

Message is a factory function that returns a Message object. It takes an options object as an argument.

Valid options peroperties are type, data, delay and recipient. Their values will be used to populate the Message object.

The Message object is a container object with type, data, delay and recipient fields. The type field is required, the others are optional.

• type:

  A string that defines the type of the message message. Used by the Hub when defining subscriptions or routing messages.

• data:

  The content of the message that can be acted on by a Subscriber in its receiveMessage method. Can be a String, Object, Number, etc..

• delay:

  The delay, in ms, that should pass before this message is sent. If not passed the message will be sent immediately.

• recipient:

  A specific object that should be the only recipient of the message being sent. The recipient object should have a receiveMessage method and be subscribed to the Message.type at the same Hub the Message is sent through.

Subscriber()

Subscriber is a factory function that returns a Subscriber object.

A Subscriber has only one function, receiveMessage, which will be called by a Hub when a Message has been sent that a registered Subscriber listens to.

Since Subscriber doesn't do anything besides receive messages, typical usages involves extending the Subscriber object returned from the factory, or by adding receiveMessage to obj with Object.assign(obj, Turms.Subscriber()).

• receiveMessage(action, message)

  receiveMessage calls the action defined in a Subscription with the Subscriber set as thisArg for the function stored in action.

  receiveMessage could also be called directly on a Subscriber.

Hub()

Hub is factory function that returns a Hubobject.

Most of Turms logic takes place inside a Hub. A Subscriber can subscribe with a Hub via addSubscription. A subscription object will be returned by addSubscription, and this can later be used to unsubscribe by passing it to removeSubscription.

• addSubscription(subscriber, messageType, action):

  Takes a Subscriber object and registers it to listen for any Message whose type field corresponds to the messageType parameter.

The action is a callback that will be called by the by Subscriber.receiveMessage. When called, action will see the Subscriber as this and takes the Message being sent as its argument, making the Message and Subscriber accessible inside action.

addSubscriptionReturns the created Subscription object, which can be used with removeSubscription.

• removeSubscription(subscription):

  Removes a Subscription from the Hub.

  Returns true if a Subscription was successfully removed, false if not.

• sendMessage(message):

  Sends a Message to all Subscribers listening to message.type. If the message has delay it will be queued. Pass the return value of Message(options) or another object with the same properties.

  Returns a Receipt. If message has delay, the Receipt will store an active Timer, otherwise it will have only message.

• queueMessage(message):

  Queues a Message to be passed to sendMessage after a delay defined in message.delay. Called internally by sendMessage if message has a delay. Could also be used externally.

  Returns a Receipt containing message and an active Timer. The Receipt can be used to cancel a queued Message.

• cancelMessage(receipt):

  Cancels a queued Message stored in the receipt parameter's message property. Returns true if a Message was canceled, false if not.