Class: Pubst

Pubst()

new Pubst()

A slightly opinionated pub/sub utility for Javascript

Creates a new Pubst instance. The instance is ready to use immediately with default settings. Call `await configure()` if you need to customize the logger, store, or pre-register topics.

Source:
Example
const pubst = new Pubst();
await pubst.configure({ showWarnings: false });

Methods

(async) addTopic(newTopicConfig) → {Promise.<Object>}

Configure a new topic.

Allows you to configure a new topic in pubst. Available options are:

  • `name` (REQUIRED) - A string representing the name of the topic.
  • `default` (default: undefined) - The default value presented to subscribers when the topic is undefined or null. This can be overridden by subscribers.
  • `eventOnly` (default: false) - Set this to true if this topic will not have payload data.
  • `doPrime` (default: true) - Should new subscribers automatically receive the last published value on the topic? If no valid value is present, new subscribers will be primed with the default value (if configured). This can be overridden by subscribers.
  • `allowRepeats` (default: false) - Alert subscribers of all publish events, even if the value is equal (by strict comparison) to the last value sent. This can be overridden by subscribers.
  • `storeConfig` (default: {}) - Store-specific configuration that is passed through to the store's `registerTopic` method. This allows custom store implementations to receive topic-level configuration (e.g. persistence keys, TTL settings, etc.).

Parameters:
Name Type Description
newTopicConfig TopicConfig Topic configuration
Source:
Returns:
Resolves with the result of registering the topic in the store.
Type
Promise.<Object>

(async) addTopics(topics) → {Promise.<void>}

Configure new topics.

Allows you to configure new topics. This will call `addTopic` with each item passed. Topics are registered sequentially. For available options, see `addTopic`.

Parameters:
Name Type Description
topics Array.<TopicConfig> Topic configurations
Source:
Returns:
Type
Promise.<void>

(async) clear(topic) → {Promise.<void>}

Clears a given topic.

Clears the topic by publishing a `null` to it.
Parameters:
Name Type Description
topic string The topic to clear
Source:
Returns:
Type
Promise.<void>

(async) clearAll() → {Promise.<void>}

Clears all known topics.

Source:
Returns:
Type
Promise.<void>

(async) configure(userConfig) → {Promise.<void>}

Set Pubst configuration.

Available options are:

  • `logger` (default: ConsoleLogger) - Logger to send warning messages to.
  • `showWarnings` - If logger isn't provided, this option switches between the use of ConsoleLogger and SilentLogger
  • `store` (default: InMemoryStore) - A store implementation for persisting topic values. Custom stores must implement the same async interface as InMemoryStore: `registerTopic`, `getValue`, `setValue`, `clearValue`, and `getTopicNames`.
  • `topics` - An array of topic configurations. (See: `addTopic` for topic configuration options)

Parameters:
Name Type Description
userConfig PubstConfig Your configuration
Source:
Returns:
Type
Promise.<void>

(async) currentVal(topic, defopt) → {Promise.<*>}

Get the current value of a topic.

Parameters:
Name Type Attributes Description
topic string The topic to get the value of.
def * <optional>
 (Optional) a value to return if the topic is empty.
Source:
Returns:
- Resolves with the current value or the default
Type
Promise.<*>

(async) publish(topic, payload) → {Promise.<void>}

Publish to a topic

Parameters:
Name Type Description
topic string The topic to publish to
payload * The payload to publish
Source:
Returns:
Type
Promise.<void>

subscribe(topic, handler, defopt) → {function}

Subscribe to one or more topics

The first argument may be a string or a matcher function. If a string is provided, the handler will be called for all updates for that topic. If a function is provided, it will be called with each topic name and should return a truthy value to indicate that the subscriber wishes to receive updates for that topic. If the matcher function throws, the error is logged as a warning and the subscriber will not receive the update for that topic.

The second argument may be a function or an object. The object is necessary if you want to provide configuration options for this subscription. Available options are:

  • `default` - (Default: undefined) - Default value for this sub.
  • `doPrime` - (Default: true) - Should the handler be primed with the last value?
  • `allowRepeats` - (Default: false) - Should the handler be called when the value doesn't change?
  • `handler` - (Required) - The handler to call.

The handler will be called on topic updates. It will be passed the new value of the topic as the first argument, and the name of the topic as the second argument.

Note: Subscribe is synchronous and returns an unsubscribe function immediately. Priming of subscribers with existing values happens asynchronously via the store.

Parameters:
Name Type Attributes Description
topic string | function The topic to receive updates for. If a string is provided, the handler will be called for all updates for that topic. If a function is provided, it will be used as a matcher: it receives a topic name string and should return a truthy value if the subscriber should receive updates for that topic. If the matcher function throws an error, the error is logged as a warning and the match is skipped.
handler function | SubscriptionConfig Either your handler function or a subscription configuration object
def * <optional>
 (Optional) Value to send when topic is empty
Source:
Returns:
- A function that will remove this subscription from getting further updates.
Type
function