Hertzy - Event bus channel

Hertzy provides additional messaging pattern for Node.js applications.

• Introduction
• Motivations
• Installation
• Usage
• Hertzy for browsers
• API documentation
• Code of conduct
• Team
• References and articles
• Acknowledgements
• License

Introduction

Node.js includes an event system which is an implementation of the Observer pattern that is the most common used event pattern in Node.js application and for good reasons: it's incredibly simple and useful.

Hertzy adds additional messaging related features called frequency that represent a communication bus through which different parts (modules) of the application can communicate with each other.

Motivations

Anyone who has used Node.js should be familiar with events. This module has the responsability to facilitate the communication between objects of your application.

Much of the Node.js core API modules are built around an idiomatic asynchronous event-driven architecture in which certains kinds of objects (called emitter) periodically emit named events that cause Function objects ("listeners") to be called.

Sometimes you need to promote loose coupling system by ensuring that instead of components (modules) referring to each other explicitly, their interaction is handled through a central point. This can help to decouple the systems and improve the module reusability.

In implementation terms Hertzy use the mediator pattern that is ideal for application level notifications such as the communication between different subsystems that are themselves complex.

The largest benefit of the mediator pattern is that it reduces the communication channels needed between objects or components in a system from many to many to just many to one.

Both pattern mediator and observer promote loose coupling, however, the mediator achieves this by having objects communicate strictly through it, while observer creates observable objects that publish events of interest of objects that are subscribed to them.

Installation

If you want to use hertzy you have to install it. There are two methods to do that:

In your package.json add the following item:

"hertzy": "version"

then digit:

npm install

Example:

"hertzy": "*" for the latest version
"hertzy": "0.0.1" for the version 0.0.1

OR

launch this command:

npm install hertzy --save

Usage

To start using hertzy you have to import it in you project. After that you need to obtain a frequency or create a new one. A frequency object is a channel where you can emit or listen for an event issued by other modules.

'use strict'

const Hertzy = require('hertzy')

// Obtain or create a new frequency, a channel where you can emit or listen for
// an event issued by other modules
const usr = Hertzy.tune('user')

// Listen for event 'user:add'
usr.on('user:add', function (data) {
    console.log('NEW USER ADDED WITH FOLLOWING DATA:')
    console.log(data)
})

// Emit event 'user:add'
usr.emit('user:add', {
    username: 'NickNaso',
    password: '********',
    email: '[email protected]'
})

Hertzy for browsers

To use Hertzy in the browser, please refer to this specific version.

API

VERSION

This is a String property that represents the version of hertzy

'use strict'

const Hertzy = require('hertzy')

// Get hertzy version and print it
console.log(Hertzy.VERSION)

WARNING

This is a Boolean property. Setting it to true will cause Node.js to print a warning if you add more then defaultMaxListeners listeners on a single event (for more informations about that take a look here event and max listeners number).

Otherwise setting it to false, which is also the default value for hertzy, the number of max listeners will be dynamically updated based on your usage.

'use strict'

const Hertzy = require('hertzy')

// Set hertzy warning value
// Get hertzy warning value and print it
console.log(Hertzy.WARNING = true)

tune (frequency)

The tune method returns a frequency that conceptually is a channel where you can emit or listen for an event and its data. The tune method checks if the parameter frequency is a valid String and creates or returns an instance of Frequency that you can use to intercept or dispatch the event using its methods.

'use strict'

const Hertzy = require('hertzy')

// Get frequency to use
const frequency = Hertzy.tune('user')

How to use Frequency

After you get the right frequency or the bus channel you want, you can start to emit and listen to the events with the methods exposed by Frequency object.

fq ()

The fq method returns the string representing the frequency's name

'use strict'

const Hertzy = require('hertzy')

// Get frequency to use
const frequency = Hertzy.tune('user')

console.log(frequency.fq())
// It prints the String 'user'

emit(evt, [, ...args])

The emit() method allows you to dispatch an event on a selected frequency. It takes as a required parameter evt. Others optional parameters will be passed to the listeners of the specified event. Remember, evt needs to be a valid String otherwise you will get an error.

'use strict'

const Hertzy = require('hertzy')

// Get frequency to use
const frequency = Hertzy.tune('user')

// Emit 'user:add' event on 'user' frequency
frequency.emit('user:add', {
    username: 'NickNaso',
    password: '********',
    email: '[email protected]'
})

on (evt, fn)

The on() method allows you to listen to an event on the selected frequency. It takes as input two parameters, evt and fn which represent the name of the event and the function handler you want to execute when the event happens. Remember, evt and fn need to be a valid String and Function respectively, otherwise you will get an error.

'use strict'

const Hertzy = require('hertzy')

// Get frequency to use
const frequency = Hertzy.tune('user')

// Listen 'user:add' event on 'user' frequency
frequency.on('user:add', function (data) {
    // DO SOMETHING ...
})

off (evt, fn)

The off() method allows you to remove listener on event on the selected frequency. It takes as input two parameters, evt and fn which represent the name of the event and the function handler you want to execute when the event happens. Remember, evt and fn need to be a valid String and Function respectively, otherwise you will get an error.

'use strict'

const Hertzy = require('hertzy')

// Get frequency to use
const frequency = Hertzy.tune('user')

const handler = function (data) {
    // DO SOMETHING ...
}

// Listen 'user:add' event on 'user' frequency
frequency.on('user:add', handler)

// Remove listener for 'user:add' event on 'user' frequency
frequency.off('user:add', handler)

Rererences and articles

Hertzy an event bus channel

The Team

Nicola Del Gobbo

https://github.com/NickNaso/

https://www.npmjs.com/~nicknaso

https://twitter.com/NickNaso

Mauro Doganieri

https://github.com/mauro-d

https://www.npmjs.com/~mauro-d

https://twitter.com/maurodoganieri

Pierluigi Iannarelli

https://github.com/pierluigiiannarelli

https://twitter.com/pierluigiiannar

Acknowledgements

Thank you to all people that encourage me every day.

Mantainers and creators of backbone.radio a module that has inspired my work on hertzy.

License

Licensed under Apache license V2