Skip to content

Module: lib/util/publisher

The publisher module. Provides pub/sub functionality with extensive wildcard support and also content based filtering.

Version
1.5.1
Author
Frank Kudermann - alphanull
License
MIT
Source
publisher.js, line 1

Members

Global options for the publisher, can be changed by the setOptions method.

Type
publisher~globalOptions
Source
publisher.js, line 24

Internal value to create unique tokens. This is increased everytime you subscribe.

Type
number
Source
publisher.js, line 36

Object which contains all subscribers, using the token as key.

Properties
Name Type Description
subscriberObject publisher~subscriberObject

The subscriber object containing all necessary information.
Type
Map<publisher~subscriberObject>
Source
publisher.js, line 45

Object which contains a tree graph of all subscriptions.

Type
Map<Object>
Source
publisher.js, line 53

Object which contains persistent messages (published with the "persist" option).

Type
Map<Object>
Source
publisher.js, line 61

Methods

private, static deferExecution(fn)

Executes a function asynchronously, using the most performant available method. Falls back to setTimeout if no microtask queue is available.

Parameters:
Name Type Description
fn function

The function to execute.
Source
publisher.js, line 70

inner isUndefined(obj) → boolean

Checks if the given value is undefied.

Parameters:
Name Type Description
obj *

The value to check.
Returns

True if the value is undefined, false otherwise.

Type boolean
Source
publisher.js, line 81

static export configure(options)

Sets global options for the publisher. All subsequent actions use these options.

Parameters:
Name Type Description
options Object<publisher~globalOptions>

An object containing various options.
Source
publisher.js, line 92

static export publish(topic, dataopt, optionsopt) → boolean

Publishes a message to all matching subscribers.

Parameters:
Name Type Attributes Default Description
topic string

The topic of this message, may be separated with '/' for subtopics.
data Object optional

The data that should be sent along with the event. Can be basically any javascript object.
options Object optional {}

Additional options.

Parameters:
Name Type Attributes Description
async boolean optional

Specify if we should deliver this message directly or with a timeout. Overrides the global setting.
handleExceptions boolean optional

Specify if we should catch any exceptions while sending this message. Overrides the global setting.
persist boolean optional

If this is set to true, the messages is saved for later subscribers which want to be notified of persistent messages.
cancelable boolean optional

If set to "true" this message cannot be cancelled (when sending synchronously).
Returns

Returns false if a synchronous event was cancelled by a handler.

Type boolean
Throws

When trying to use a wildcard for publishing.

Type Error
Source
publisher.js, line 113

static export subscribe(topic, handler, optionsopt) → number

Subscribes to certain message(s).

Parameters:
Name Type Attributes Default Description
topic string

The topic in which the subscriber is interested. Note that you can use wildcards, ie. The topic "*" will subscribe to all messages.
handler function

The handler to execute when a matching message is found.
options Object optional {}

Additional options.

Parameters:
Name Type Attributes Default Description
async boolean optional

Specify if we should deliver this message directly or with a timeout. Overrides the global setting.
handleExceptions boolean optional

Specify if we should catch any exceptions while sending this message. Overrides the global setting.
persist boolean optional

If this is set to true, the subscriber is notified of any former, persistent messages.
condition function optional

A function which receives this topic and data just before execution, if present. If this returns anything but true, the message is not delivered.
priority number optional 0

Specifies with which priority the handler should be executed. The higher the number, the higher the priority. Default is "0", negative values are allowed.
invocations number optional

Specifies how many times the subscriptions should be executed after a matching event. If this value reaches "0", the handler is automatically unsubscribed.
Returns

The internal token of the new subscriber. Can be used for later unsubscribing.

Type number
Throws

If topic or handler are undefined.

Type Error
Source
publisher.js, line 168

static export unsubscribe(topicOrToken, handleropt, lenientUnsubscribeopt)

Unsubscribes one or more subscribers. Note that here, the second argument can mean either a handler or the "lenient" option.

Parameters:
Name Type Attributes Description
topicOrToken number | Array<number> | string

The token or the topic to unsubscribe. In the first case, these also can be in an Array to support multiple unsubscriptions.
handler function | boolean optional

If specified, the message is only unsubscribed if the handler also matches.
lenientUnsubscribe boolean optional

If set to true, unsubscribe won't throw an error if the handler or token is not found.
Throws

If no subscribers were found.

Type Error
Source
publisher.js, line 228

static export removePersistentMessage(topic)

Removes a previously added persistent message.

Parameters:
Name Type Description
topic string

The topic of the message to remove.
Source
publisher.js, line 290

private, static executeHandler(subscriber, topic, data, optionsopt) → any

This method actually executes the message handler.

Parameters:
Name Type Attributes Default Description
subscriber publisher~subscriberObject

The subscriber to execute.
topic string

The message topic.
data Object

The message data which should be passed to the handler.
options Object optional {}

Object which holds the publish options.
Returns

Returns the handlers result.

Type any
Source
publisher.js, line 308

private, static findSubscribers(topicArray, data, optionsopt, subscriptions, originalTopic, handlerArray) → Array<publisher~subscriberObject>

Internal Function to recursively walk the subscription graph according to the current topic scope. Any found subscribers are added to the return array.

Parameters:
Name Type Attributes Default Description
topicArray Array<string>

Hold eachs segments of the topic in an array, also reflecting the current scope.
data Object

The current data which was sent along the message.
options Object optional {}

Current publishing options.
subscriptions Object

Part of the subscriptions tree, reflecting the current scope.
originalTopic string

Original message topic.
handlerArray Array

array with all found handlers.
Returns

Array with matching subscribers.

Type Array<publisher~subscriberObject>
Source
publisher.js, line 346

private, static addSubscription(topicArray, subscriber, subscriptions)

Internal function to add a subscription to the subscriptions graph.

Parameters:
Name Type Description
topicArray Array<string>

Hold eachs segments of the topic in an array, also reflecting the current scope.
subscriber Object<publisher~subscriberObject>

The subscriber to add.
subscriptions Object

Part of the subscription graph, reflecting the current scope.
Source
publisher.js, line 398

private, static removeSubscription(topicArray, subscriber, subscriptions)

Internal Function to recursively walk the subscription graph according to the current topic scope.

Parameters:
Name Type Description
topicArray Array<string>

Hold eachs segments of the topic in an array, also reflecting the current scope.
subscriber Object<publisher~subscriberObject>

The subscriber to remove.
subscriptions Object

Part of the subscriptions tree, reflecting the current scope.
Source
publisher.js, line 442

Type Definitions

Options for the publisher. These can be changed on a global basis by the configure() method.

Properties
Name Type Attributes Default Description
async boolean optional true

If set to "false", messages are sent directly, otherwise with a timeout.
handleExceptions boolean optional false

If this is true, any exceptions are catched, so that a faulty handler cannot disturb further publishing.
lenientUnsubscribe boolean optional false

If this is true, unsubsribing a non-existant subscription or handler will not throw an error.
Type
Object
Source
publisher.js, line 470

Structure of a single Subscriber

Properties
Name Type Description
token string

The token of this subscriber.
topic string

The topic of this subscriber.
handler function

The handler to execute when a mathing publish event occurs.
timeOutId number

The ID of the timeout when using async publish. Used to clean up when unsubscribe occurs and the handler is still waiting.
options Object<publisher~subscriberOptions>

The various subscriber options.
Type
Object
Source
publisher.js, line 477

Options for the subscriber. These can be used by publish or subscribe commands, except when noted.

Properties
Name Type Attributes Description
async boolean optional

If set to "false", messages are sent directly to this subscriber, otherwise with a timeout.
handleExceptions boolean optional

If this is true, any exceptions are catched, so that a faulty handler cannot disturb further publishing.
condition function optional

A function to be evaluated before a matching subscriber is executed. Must return true to continue.
persist boolean optional

If this is set to true, the messages is saved for later subscribers which want to be notified of persistent messages.
priority number optional

Subscribe only: specifies with which priority the handler should be executed. The higher the number, the higher the priority. Default is "0", negative values are allowed.
Type
Object
Source
publisher.js, line 486