What is qlobber?
The qlobber npm package is a fast and flexible topic-based publish/subscribe library for Node.js. It allows you to match topics to subscribers using a trie-based approach, which is efficient and scalable. This package is particularly useful for implementing message brokers, event emitters, and other pub/sub systems.
What are qlobber's main functionalities?
Basic Topic Matching
This feature allows you to add topics and match them against patterns. The code sample demonstrates how to add topics and retrieve matches for specific topics.
const Qlobber = require('qlobber').Qlobber;
let matcher = new Qlobber();
matcher.add('foo.*', 'it matches foo.bar');
matcher.add('foo.*', 'it also matches foo.baz');
matcher.add('foo.bar', 'it matches foo.bar exactly');
console.log(matcher.match('foo.bar')); // ['it matches foo.bar', 'it matches foo.bar exactly']
console.log(matcher.match('foo.baz')); // ['it also matches foo.baz']
Removing Topics
This feature allows you to remove specific topics from the matcher. The code sample demonstrates how to add and then remove a topic, showing the updated matches.
const Qlobber = require('qlobber').Qlobber;
let matcher = new Qlobber();
matcher.add('foo.*', 'it matches foo.bar');
matcher.add('foo.bar', 'it matches foo.bar exactly');
matcher.remove('foo.bar', 'it matches foo.bar exactly');
console.log(matcher.match('foo.bar')); // ['it matches foo.bar']
Wildcard Matching
This feature supports wildcard matching using '*' and '#' symbols. The code sample demonstrates how to use wildcards to match multiple topics.
const Qlobber = require('qlobber').Qlobber;
let matcher = new Qlobber();
matcher.add('foo.*', 'it matches foo.bar');
matcher.add('foo.#', 'it matches foo.bar and foo.baz');
console.log(matcher.match('foo.bar')); // ['it matches foo.bar', 'it matches foo.bar and foo.baz']
console.log(matcher.match('foo.baz.qux')); // ['it matches foo.bar and foo.baz']
Other packages similar to qlobber
mqtt
The mqtt package is a client library for the MQTT protocol, which is a lightweight messaging protocol for small sensors and mobile devices. It provides similar pub/sub functionality but is more focused on network communication and IoT applications. Unlike qlobber, mqtt is protocol-specific and includes features for connecting to MQTT brokers.
eventemitter2
The eventemitter2 package is an enhanced version of Node.js's EventEmitter class. It provides advanced features like wildcard event names, which are similar to qlobber's topic matching. However, eventemitter2 is more general-purpose and is used for event handling within applications rather than for message brokering.
postal
The postal package is a JavaScript library for pub/sub messaging. It offers similar topic-based subscription and publication features. Postal is more focused on in-app messaging and provides additional features like message channels and middleware, making it more versatile for complex applications compared to qlobber.
qlobber
Node.js globbing for amqp-like topics.
Example:
var Qlobber = require('qlobber').Qlobber;
var matcher = new Qlobber();
matcher.add('foo.*', 'it matched!');
assert.deepEqual(matcher.match('foo.bar'), ['it matched!']);
assert(matcher.test('foo.bar', 'it matched!'));
The API is described here.
qlobber is implemented using a trie, as described in the RabbitMQ blog posts here and here.
Installation
npm install qlobber
Another Example
A more advanced example using topics from the RabbitMQ topic tutorial:
var matcher = new Qlobber();
matcher.add('*.orange.*', 'Q1');
matcher.add('*.*.rabbit', 'Q2');
matcher.add('lazy.#', 'Q2');
assert.deepEqual(['quick.orange.rabbit',
'lazy.orange.elephant',
'quick.orange.fox',
'lazy.brown.fox',
'lazy.pink.rabbit',
'quick.brown.fox',
'orange',
'quick.orange.male.rabbit',
'lazy.orange.male.rabbit'].map(function (topic)
{
return matcher.match(topic).sort();
}),
[['Q1', 'Q2'],
['Q1', 'Q2'],
['Q1'],
['Q2'],
['Q2', 'Q2'],
[],
[],
[],
['Q2']]);
Licence
MIT
Tests
qlobber passes the RabbitMQ topic tests (I converted them from Erlang to Javascript).
To run the tests:
grunt test
Lint
grunt lint
Code Coverage
grunt coverage
Instanbul results are available here.
Coveralls page is here.
Benchmarks
grunt bench
qlobber is also benchmarked in ascoltatori.
API
Source: lib/qlobber.js
Qlobber([options])
Creates a new qlobber.
Parameters:
{Object} [options]
Configures the qlobber. Use the following properties:
-
{String} separator
The character to use for separating words in topics. Defaults to '.'. MQTT uses '/' as the separator, for example.
-
{String} wildcard_one
The character to use for matching exactly one word in a topic. Defaults to '*'. MQTT uses '+', for example.
-
{String} wildcard_some
The character to use for matching zero or more words in a topic. Defaults to '#'. MQTT uses '#' too.
-
{Boolean} cache_adds
Whether to cache topics when adding topic matchers. This will make adding multiple matchers for the same topic faster at the cost of extra memory usage. Defaults to false
.
Go: TOC
Qlobber.prototype.add(topic, val)
Add a topic matcher to the qlobber.
Note you can match more than one value against a topic by calling add
multiple times with the same topic and different values.
Parameters:
{String} topic
The topic to match against.{Any} val
The value to return if the topic is matched. undefined
is not supported.
Return:
{Qlobber}
The qlobber (for chaining).
Go: TOC | Qlobber.prototype
Qlobber.prototype.remove(topic, [val])
Remove a topic matcher from the qlobber.
Parameters:
{String} topic
The topic that's being matched against.{Any} [val]
The value that's being matched. If you don't specify val
then all matchers for topic
are removed.
Return:
{Qlobber}
The qlobber (for chaining).
Go: TOC | Qlobber.prototype
Qlobber.prototype.match(topic)
Match a topic.
Parameters:
{String} topic
The topic to match against.
Return:
{Array}
List of values that matched the topic. This may contain duplicates.
Go: TOC | Qlobber.prototype
Qlobber.prototype.test(topic, [val])
Test whether a topic match contains a value. Faster than calling match
and searching the result for the value. Values are tested using test_values
.
Parameters:
{String} topic
The topic to match against.{Any} [val]
The value being tested for.
Return:
{Boolean}
Whether matching against topic
contains val
.
Go: TOC | Qlobber.prototype
Qlobber.prototype.test_values(vals, val)
Test whether values found in a match contain a value passed to test
. You can override this to provide a custom implementation. Defaults to using indexOf
.
Parameters:
{Array} vals
The values found while matching.{Any} val
The value being tested for.
Return:
{Boolean}
Whether vals
contains val
.
Go: TOC | Qlobber.prototype
Qlobber.prototype.clear()
Reset the qlobber.
Removes all topic matchers from the qlobber.
Return:
{Qlobber}
The qlobber (for chaining).
Go: TOC | Qlobber.prototype
QlobberDedup([options])
Creates a new de-duplicating qlobber.
Inherits from Qlobber.
Parameters:
{Object} [options]
Same options as Qlobber.
Go: TOC
QlobberDedup.prototype.test_values(vals, val)
Test whether values found in a match contain a value passed to test
. You can override this to provide a custom implementation. Defaults to using has
.
Parameters:
{Set} vals
The values found while matching (ES6 Set).{Any} val
The value being tested for.
Return:
{Boolean}
Whether vals
contains val
.
Go: TOC | QlobberDedup.prototype
QlobberDedup.prototype.match(topic)
Match a topic.
Parameters:
{String} topic
The topic to match against.
Return:
{Set}
ES6 Set of values that matched the topic.
Go: TOC | QlobberDedup.prototype
—generated by apidox—