tiny-rx-hub

Tiny-rx-hub is a lightweight pub/sub hub, based on RxJS.

• How to install
• Simple Pub/Sub example
• TopicSets
• Using wildcards
  • Single level wildcard
  • Multi level wildcard
• Handle publishing and subscribing to a topic asynchronously
• Buffering
• Sharing a topic within a group (sharedTopic)
• Sealing the Broker or a Channel
• Methods
  • Broker
  • Channel
  • Topic
  • TopicSet
• Options
  • TopicOptions
  • TopicSubscribeOptions

How to install

npm install tiny-rx-hub

Simple Pub/Sub example

example:

import { Broker } from "tiny-rx-hub";

// Creates a new broker instance
const broker = new Broker();
// Creates a new topic called users/
const topic = broker.channel("channel_1").topic<string>("users/")

// Subscribing to the topic
topic.subscribe((message: string) => {
    console.log(message)
})

// Publishing a message to the topic
topic.publish("wicklWackl")

TopicSets

If you want to subscribe to multiple topics, you could build and subscribe to a topicSet. In order to build a topicSet, you need to use either the single level wildcard (+) or the multi level wildcard (#)

example:

import { Broker } from "tiny-rx-hub";

// Creates a new broker instance
const broker = new Broker();
// Creates a new topic called users/configs
const userConfigsTopic = broker.channel("channel_1").topic<string>("users/configs")
// Creates a new topic called users/groups
const userGroupsTopic = broker.channel("channel_1").topic<string>("users/groups")
// Create a new topicSet with the single level wildcard +
const userTopicSet = broker.channel("channel_1").topics("users/+")

// Subscribing to the topic
userTopicSet.subscribe((message: any) => {
    console.log(message)
})

// Publishing a message to users/configs
userConfigsTopic.publish("Users:::Configs::: wicklWackl")
// Publishing a message to users/groups
userGroupsTopic.publish("Users:::Groups::: wicklWackl")

Using wildcards

Single level wildcard

example:

/**
 * Assuming you've got following topics:
 * users/groups
 * users/configs
 * users/configs/1
 * users/details/1
*/
const topicSet = broker.channel("channel_1").topics("users/+")
// The above topicSet would subscribe to the "users/groups" and "users/configs" topic, since the (+) only replaces a single level of the topic path
const topicSet = broker.channel("channel_1").topics("users/+/1")
// The above topicSet would subscribe to the "users/configs/1" and the "users/detaisl/1" topic

Multi level wildcard

example:

/**
 * Assuming you've got following topics:
 * users/groups
 * users/configs
 * users/details/1
 * users/details/2 
*/
const topicSet = broker.channel("channel_1").topics("users/#")
// The above topicSet would return all of the above stated topics.
// Please note, that the multi level wildcard could only be used at the very end of the topics path

Handle publishing and subscribing to a topic asynchronously

Publishing a message and subscribing are by default being executed synchronously. If you want to change this behavior, you could pass the { async: true } option, during the creation of a topic.

example:

import { Broker } from "tiny-rx-hub";

const broker = new Broker();

// Passing the Async: true option, will handle the publishing and subscribing of messages asynchronously
broker.channel("channel_1").createTopic("users/", {
    async: true,
});

Buffering

As a default behavior, subscribing to a topic, will emit all messages to the subscriber.

example:

import { Broker } from "tiny-rx-hub";

// Creates a new broker instance
const broker = new Broker();
// Creates a new topic called users/
const topic = broker.channel("channel_1").topic<string>("users/")

topic.publish("wicklWackl_1")
topic.publish("wicklWackl_2")
topic.publish("wicklWackl_3")

// Subscribing to the topic
topic.subscribe((message: string) => {
    console.log(message)
})

topic.publish("wicklWackl_4")

// Output after subscribing
// 1.) wicklWackl_1
// 2.) wicklWackl_2
// 3.) wicklWackl_3
// 4.) wicklWackl_4

If you just want to receive the future messages, you could pass the { fromStart: false } option to the subscribe method.

import { Broker } from "tiny-rx-hub";

// Creates a new broker instance
const broker = new Broker();
// Creates a new topic called users/
const topic = broker.channel("channel_1").topic<string>("users/")

topic.publish("wicklWackl_1")
topic.publish("wicklWackl_2")
topic.publish("wicklWackl_3")

// Subscribing to the topic
topic.subscribe((message: string) => {
    console.log(message)
}, {
    fromStart: false
})

topic.publish("wicklWackl_4")

// Output after subscribing
// 1.) wicklWackl_4

Sharing a topic within a group (sharedTopic)

In order to share a topic within a group, you need to pass a group to the subscribe method. Please note, that a message of a shared topic will only be processed by a single subscriber. This ensures, that if one of the subscriber will be destroyed or unsubscribes, future messages will be processed by the next available subscriber of this sharedTopic.

example:

import { Broker } from "tiny-rx-hub";

// Creates a new broker instance
const broker = new Broker();
// Creates a new topic called users/
const topic = broker.channel("channel_1").topic<string>("users/");

topic.publish("wicklWackl_1");
topic.publish("wicklWackl_2");

// First subscription of group_1
const firstSubscription = topic.subscribe(
    (message: string) => {
        console.log("from first subscriber:::", message);
    },
    {
        group: "group_1",
    }
);

// Second subscription of group_1
const secondSubscription = topic.subscribe(
    (message: string) => {
        console.log("from second subscriber:::", message);
    },
    {
        group: "group_1",
    }
);

// Unsubscribing the first subscription
firstSubscription.unsubscribe();
topic.publish("wicklWackl_3");
topic.publish("wicklWackl_4");

// Output:
// 1.) from first subscriber::: wicklWackl_1
// 2.) from first subscriber::: wicklWackl_2
// 3.) from second subscriber::: wicklWackl_3
// 4.) from second subscriber::: wicklWackl_4

Sealing the Broker or a Channel

In some use-cases, it's beneficial to prevent the creation of further channels or topics. For this use-case you could use the broker's or the channel's seal method.

example: Sealing the broker

import { Broker } from "tiny-rx-hub";

// Creates a new broker instance
const broker = new Broker();
// Creates a new channel called `channel_1`
broker.createChannel("channel_1"); // Will be created successfully
// Seal the broker, to prevent the creation of further channels.
broker.seal()
broker.createChannel("channel_2"); // Will throw an error.

example: Sealing a channel

import { Broker } from "tiny-rx-hub";

// Creates a new broker instance
const broker = new Broker();
// Creates a new channel called `channel_1`
broker.createChannel("channel_1");
// Create a new topic called `users`
broker.channel("channel_1").createTopic("users") // Will be created successfully
// Sealing the channel
broker.channel("channel_1").seal()
broker.channel("channel_1").createTopic("configs") // Will throw an error

Methods

Broker

|Name |Return |Parameters |Description | |---|---|---|---| |createChannel |void |channel: string |Create a new channel | |channel |IBrokerChannel |channel: string |Get an existing channel or create and return a new instance | |seal |void |- |Prevents further creation of channels | |listAllChannels |   string[] |- |Lists all existing channels as array of strings |

Channel

|Name |Return |Parameters |Description | |---|---|---|---| |createTopic |void |topic: string, options? Partial<IBrokerTopicOptions> |Create a new topic | |topic |IBrokerTopic |topic: string |Get an existing topic or create and return a new instance | |topics |IBrokerTopicSet |topicsPath: string, options?: Partial<IBrokerTopicOptions> |Create a new TopicSet | |seal |void |- |Prevents further creation of topics | |listAllTopics |string[] |- |List all existing topics as array of strings | |listAllTopicSets |string[] |- |List all existing topicSets as array of strings |

Topic

|Name |Return |Parameters |Description | |---|---|---|---| |subscribe |Subscription |observerFn: (message: T) => void, options?: Partial<IBrokerTopicSubscribeOptions> |Subscribe to this topic | |publish |void |message: T |Publish a message to this topic | |close |void |- |Closes this topic. Further messages will not be emitted to the subscribers of this topic. | |listAllGroups |string[] |- |List all existing groups as array of strings |

TopicSet

|Name |Return |Parameters |Description | |---|---|---|---| |subscribe |Subscription |observerFn: (message: any) => void, options?: Partial<IBrokerTopicSubscribeOptions> |Subscribe to this topicSet | |addTopic |void |topic: IBrokerTopic<any> |Adds a topic to this topicSet |close |void |- |Close this topicSet. Further messages will not be emitted to the subscribers of this topic. | |listAllTopics |string[] |- |List all existing topics as array of strings |

Options

TopicOptions

|Name |Default |Description | |---|---|---| |throwErrorIfClosed |false |If true, the topic will throw errors in the console, if a message was been emitted after the topic was been closed. | |async |false |If true, the publish and the subscribe methods will be handled asynchronously |

TopicSubscribeOptions

|Name |Default |Description | |---|---|---| |fromStart |true |If false, the subscriber will only receive messages after the subscription has been made. | |group? | |Group which the subscriber is part of. This option is used, to create a sharedTopic. |