{"id":17190638,"url":"https://github.com/nicknaso/hertzy","last_synced_at":"2025-04-13T19:31:32.063Z","repository":{"id":57263008,"uuid":"113477373","full_name":"NickNaso/hertzy","owner":"NickNaso","description":"Event bus channel","archived":false,"fork":false,"pushed_at":"2020-12-02T15:43:06.000Z","size":7106,"stargazers_count":49,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-22T05:32:46.628Z","etag":null,"topics":["eventbus","events","javascript","mediator","mediator-pattern","nodejs"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NickNaso.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-07T17:02:01.000Z","updated_at":"2023-08-21T16:14:50.000Z","dependencies_parsed_at":"2022-09-01T04:27:27.768Z","dependency_job_id":null,"html_url":"https://github.com/NickNaso/hertzy","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickNaso%2Fhertzy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickNaso%2Fhertzy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickNaso%2Fhertzy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickNaso%2Fhertzy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NickNaso","download_url":"https://codeload.github.com/NickNaso/hertzy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248767898,"owners_count":21158555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eventbus","events","javascript","mediator","mediator-pattern","nodejs"],"created_at":"2024-10-15T01:23:27.748Z","updated_at":"2025-04-13T19:31:29.900Z","avatar_url":"https://github.com/NickNaso.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/NickNaso/hertzy/master/hertzy.png\"/\u003e\n\u003c/p\u003e\n\n# Hertzy - Event bus channel\n\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Build Status](https://travis-ci.org/NickNaso/hertzy.svg?branch=master)](https://travis-ci.org/NickNaso/hertzy)\n[![Build status](https://ci.appveyor.com/api/projects/status/twdommvefkpw70dp/branch/master?svg=true)](https://ci.appveyor.com/project/NickNaso/hertzy/branch/master)\n[![NPM version](https://img.shields.io/npm/v/hertzy.svg?style=flat)](https://www.npmjs.com/package/hertzy)\n[![NPM downloads](https://img.shields.io/npm/dm/hertzy.svg?style=flat)](https://www.npmjs.com/package/hertzy)\n\n\u003c/div\u003e\n\n## Hertzy provides additional messaging pattern for Node.js applications.\n\n* [Introduction](#introduction)\n* [Motivations](#motivations)\n* [Installation](#install)\n* [Usage](#usage)\n* [Hertzy for browsers](#hertzy_for_browsers)\n* [API documentation](#api)\n* [Code of conduct](CODE_OF_CONDUCT.md)\n* [Team](#team)\n* [References and articles](#references_and_articles)\n* [Acknowledgements](#acknowledgements)\n* [License](#license)\n\n\u003ca name=\"introduction\"\u003e\u003c/a\u003e\n\n## Introduction\n\nNode.js includes an **[event system](https://nodejs.org/dist/latest/docs/api/events.html)**\nwhich is an implementation of the **Observer** pattern that is the most common\nused **event** pattern in Node.js application and for good reasons: it's\nincredibly simple and useful.\n\n**Hertzy** adds additional messaging related features called **frequency** that\nrepresent a communication bus through which different parts (modules) of the\napplication can communicate with each other.\n\n\u003ca name=\"motivations\"\u003e\u003c/a\u003e\n\n## Motivations\n\nAnyone who has used Node.js should be familiar with **[events](https://nodejs.org/dist/latest/docs/api/events.html)**.\nThis module has the responsability to facilitate the communication between\n**objects** of your application.\n\n\u003e Much of the Node.js core API modules are built around an idiomatic asynchronous\n\u003e event-driven architecture in which certains kinds of objects (called **emitter**)\n\u003e periodically emit named events that cause Function objects (\"listeners\") to be called.\n\nSometimes you need to promote loose coupling system by ensuring that instead of\ncomponents (modules) referring to each other explicitly, their interaction is\nhandled through a central point. This can help to decouple the systems and\nimprove the module reusability.\n\nIn implementation terms Hertzy use the **mediator pattern** that is ideal for\napplication level notifications such as the communication between different\nsubsystems that are themselves complex.\n\nThe largest benefit of the mediator pattern is that it reduces the communication\nchannels needed between objects or components in a system from **many to many**\nto just **many to one**.\n\nBoth pattern **mediator** and **observer** promote loose coupling, however, the\nmediator achieves this by having objects communicate strictly through it, while\nobserver creates observable objects that publish events of interest of objects\nthat are subscribed to them.\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n\n## Installation\n\nIf you want to use **hertzy** you have to install it. There are two methods to\ndo that:\n\nIn your package.json add the following item:\n\n```json\n\"hertzy\": \"version\"\n```\n\nthen digit:\n\n```console\nnpm install\n```\n\n**Example**:\n\n```json\n\"hertzy\": \"*\" for the latest version\n\"hertzy\": \"0.0.1\" for the version 0.0.1\n```\n\n**OR**\n\nlaunch this command:\n\n```console\nnpm install hertzy --save\n```\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\n## Usage\n\nTo start using **hertzy** you have to import it in you project. After that you\nneed to obtain a frequency or create a new one. A **frequency** object is a\nchannel where you can emit or listen for an event issued by other modules.\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Obtain or create a new frequency, a channel where you can emit or listen for\n// an event issued by other modules\nconst usr = Hertzy.tune('user')\n\n// Listen for event 'user:add'\nusr.on('user:add', function (data) {\n    console.log('NEW USER ADDED WITH FOLLOWING DATA:')\n    console.log(data)\n})\n\n// Emit event 'user:add'\nusr.emit('user:add', {\n    username: 'NickNaso',\n    password: '********',\n    email: 'nicoladelgobbo@gmail.com'\n})\n```\n\n\u003ca name=\"hertzy_for_browsers\"\u003e\u003c/a\u003e\n\n## Hertzy for browsers\n\nTo use Hertzy in the browser, please refer to this specific [version](https://github.com/NickNaso/hertzy/tree/browser).\n\n\u003ca name=\"api\"\u003e\u003c/a\u003e\n\n## API\n\n### VERSION\n\nThis is a String property that represents the version of **hertzy**\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Get hertzy version and print it\nconsole.log(Hertzy.VERSION)\n```\n\n### WARNING\n\nThis is a Boolean property. Setting it to ```true``` will cause Node.js to print\na warning if you add more then **defaultMaxListeners** listeners on a single\nevent (for more informations about that take a look here **[event and max listeners number](https://nodejs.org/dist/latest/docs/api/events.html#events_eventemitter_defaultmaxlisteners)**).\n\nOtherwise setting it to ```false```, which is also the **default** value for\nhertzy, the number of max listeners will be dynamically updated based on your\nusage.\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Set hertzy warning value\n// Get hertzy warning value and print it\nconsole.log(Hertzy.WARNING = true)\n```\n\n### tune (frequency)\n\nThe **tune** method returns a frequency that conceptually is a channel where you\ncan emit or listen for an event and its data. The **tune** method checks if the\nparameter **frequency** is a valid String and creates or returns an instance of\n**Frequency** that you can use to intercept or dispatch the event using its\nmethods.\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Get frequency to use\nconst frequency = Hertzy.tune('user')\n```\n\n#### How to use **Frequency**\n\nAfter you get the right **frequency** or the bus channel you want, you can start\nto emit and listen to the events with the methods exposed by **Frequency**\nobject.\n\n#### fq ()\n\nThe **fq** method returns the string representing the frequency's name\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Get frequency to use\nconst frequency = Hertzy.tune('user')\n\nconsole.log(frequency.fq())\n// It prints the String 'user'\n```\n\n#### emit(evt, [, ...args])\n\nThe **emit()** method allows you to dispatch an event on a selected\n**frequency**.\nIt takes as a required parameter **evt**. Others optional parameters will be\npassed to the listeners of the specified event.\nRemember, **evt** needs to be a valid String otherwise you will get an error.\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Get frequency to use\nconst frequency = Hertzy.tune('user')\n\n// Emit 'user:add' event on 'user' frequency\nfrequency.emit('user:add', {\n    username: 'NickNaso',\n    password: '********',\n    email: 'nicoladelgobbo@gmail.com'\n})\n```\n\n#### on (evt, fn)\n\nThe **on()** method allows you to listen to an event on the selected\n**frequency**.\nIt takes as input two parameters, **evt** and **fn** which represent the name of\nthe event and the function handler you want to execute when the event happens.\nRemember, **evt** and **fn** need to be a valid String and Function\nrespectively, otherwise you will get an error.\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Get frequency to use\nconst frequency = Hertzy.tune('user')\n\n// Listen 'user:add' event on 'user' frequency\nfrequency.on('user:add', function (data) {\n    // DO SOMETHING ...\n})\n```\n\n#### off (evt, fn)\n\nThe **off()** method allows you to remove listener on event on the selected\n**frequency**.\nIt takes as input two parameters, **evt** and **fn** which represent the name of\nthe event and the function handler you want to execute when the event happens.\nRemember, **evt** and **fn** need to be a valid String and Function\nrespectively, otherwise you will get an error.\n\n```js\n'use strict'\n\nconst Hertzy = require('hertzy')\n\n// Get frequency to use\nconst frequency = Hertzy.tune('user')\n\nconst handler = function (data) {\n    // DO SOMETHING ...\n}\n\n// Listen 'user:add' event on 'user' frequency\nfrequency.on('user:add', handler)\n\n// Remove listener for 'user:add' event on 'user' frequency\nfrequency.off('user:add', handler)\n```\n\n\u003ca name=\"references_and_articles\"\u003e\u003c/a\u003e\n\n## Rererences and articles\n\n**[Hertzy an event bus channel](https://blog.cloudboost.io/hertzy-an-event-bus-channel-469e033671be)**\n\n\u003ca name=\"team\"\u003e\u003c/a\u003e\n\n## The Team\n\n### Nicola Del Gobbo\n\n\u003chttps://github.com/NickNaso/\u003e\n\n\u003chttps://www.npmjs.com/~nicknaso\u003e\n\n\u003chttps://twitter.com/NickNaso\u003e\n\n### Mauro Doganieri\n\n\u003chttps://github.com/mauro-d\u003e\n\n\u003chttps://www.npmjs.com/~mauro-d\u003e\n\n\u003chttps://twitter.com/maurodoganieri\u003e\n\n### Pierluigi Iannarelli\n\n\u003chttps://github.com/pierluigiiannarelli\u003e\n\n\u003chttps://twitter.com/pierluigiiannar\u003e\n\n\u003ca name=\"acknowledgements\"\u003e\u003c/a\u003e\n\n## Acknowledgements\n\nThank you to all people that encourage me every day.\n\nMantainers and creators of **[backbone.radio](https://github.com/marionettejs/backbone.radio)**\na module that has inspired my work on **hertzy**.\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n\n## License\n\nLicensed under [Apache license V2](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicknaso%2Fhertzy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicknaso%2Fhertzy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicknaso%2Fhertzy/lists"}