{"id":13472477,"url":"https://github.com/mroderick/PubSubJS","last_synced_at":"2025-03-26T17:30:45.948Z","repository":{"id":1092830,"uuid":"948047","full_name":"mroderick/PubSubJS","owner":"mroderick","description":"Dependency free publish/subscribe for JavaScript","archived":false,"fork":false,"pushed_at":"2024-05-22T16:18:21.000Z","size":6836,"stargazers_count":4775,"open_issues_count":30,"forks_count":458,"subscribers_count":95,"default_branch":"master","last_synced_at":"2024-10-11T13:33:37.591Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mroderick.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-09-29T10:28:50.000Z","updated_at":"2024-10-08T00:37:36.000Z","dependencies_parsed_at":"2024-09-20T16:14:47.399Z","dependency_job_id":"7f2d4e3a-3f3a-4dcc-b2d5-5ad3d1ed378f","html_url":"https://github.com/mroderick/PubSubJS","commit_stats":{"total_commits":266,"total_committers":39,"mean_commits":6.82051282051282,"dds":0.3458646616541353,"last_synced_commit":"3a53e3ec16f0071af1a3b5361a5970499ed15bb5"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroderick%2FPubSubJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroderick%2FPubSubJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroderick%2FPubSubJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mroderick%2FPubSubJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mroderick","download_url":"https://codeload.github.com/mroderick/PubSubJS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219851831,"owners_count":16556233,"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":[],"created_at":"2024-07-31T16:00:54.965Z","updated_at":"2024-10-30T03:30:19.161Z","avatar_url":"https://github.com/mroderick.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/mroderick/PubSubJS/master/branding/logo.png\"/ alt=\"PubSubJS\" title=\"PubSubJS\" width=\"200\" height=\"200\"\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://www.npmjs.com/package/pubsub-js\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/pubsub-js.svg?style=flat-square\" alt=\"NPM version\" title=\"Click to go to NPM\" /\u003e\u003c/a\u003e\u003c!--\n    --\u003e\u003ca href=\"https://github.com/mroderick/PubSubJS/blob/master/LICENSE.md\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/pubsub-js.svg?style=flat-square\" alt=\"MIT License\" title=\"License\" /\u003e\u003c/a\u003e\u003c!--\n    --\u003e\u003ca href=\"https://www.npmjs.com/package/pubsub-js\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/pubsub-js.svg?style=flat-square\" alt=\"NPM downloads/month\" title=\"Click to go to NPM\" /\u003e\u003c/a\u003e\u003c!--\n    --\u003e\u003ca href=\"https://coveralls.io/github/mroderick/PubSubJS\"\u003e\u003cimg src=\"https://img.shields.io/coveralls/github/mroderick/PubSubJS.svg?style=flat-square\" alt=\"Coverage Status\" title=\"View Coverage\"/\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nPubSubJS is a [topic-based](http://en.wikipedia.org/wiki/Publish–subscribe_pattern#Message_filtering) [publish/subscribe](http://en.wikipedia.org/wiki/Publish/subscribe) library written in JavaScript.\n\nPubSubJS has synchronisation decoupling, so topics are published asynchronously. This helps keep your program predictable as the originator of topics will not be blocked while consumers process them.\n\nFor the adventurous, PubSubJS also supports synchronous topic publication. This can give a speedup in some environments (browsers, not all), but can also lead to some very difficult to reason about programs, where one topic triggers publication of another topic in the same execution chain.\n\n#### Single process\n\nPubSubJS is designed to be used within a **single process**, and is not a good candidate for multi-process applications (like [Node.js – Cluster](http://nodejs.org/api/cluster.html) with many sub-processes). If your Node.js app is a single process app, you're good. If it is (or is going to be) a multi-process app, you're probably better off using [redis Pub/Sub](http://redis.io/topics/pubsub) or similar\n\n## Key features\n\n* Dependency free\n* synchronisation decoupling\n* ES3 compatible. PubSubJS should be able to run everywhere that can execute JavaScript. Browsers, servers, ebook readers, old phones, game consoles.\n* AMD / CommonJS module support\n* No modification of subscribers (jQuery custom events modify subscribers)\n* Easy to understand and use (thanks to synchronisation decoupling)\n* Small(ish), less than 1kb minified and gzipped\n\n## Getting PubSubJS\n\nThere are several ways of getting PubSubJS\n\n* Install via npm (`npm install pubsub-js`)\n* Use it directly from a CDN\n    - https://www.jsdelivr.com/package/npm/pubsub-js\n    - https://cdnjs.com/libraries/pubsub-js\n    - https://unpkg.com/pubsub-js\n* [Download a tagged version](https://github.com/mroderick/PubSubJS/tags) from GitHub\n\n**Note: the last version of this library available via bower is v1.5.4**\n\n## Examples\n\nFirst you have to import the module:\n\n```javascript\nimport PubSub from 'pubsub-js'\n\n// or when using CommonJS\nconst PubSub = require('pubsub-js');\n```\n\n### Basic example\n\n```javascript\n// create a function to subscribe to topics\nvar mySubscriber = function (msg, data) {\n    console.log( msg, data );\n};\n\n// add the function to the list of subscribers for a particular topic\n// we're keeping the returned token, in order to be able to unsubscribe\n// from the topic later on\nvar token = PubSub.subscribe('MY TOPIC', mySubscriber);\n\n// publish a topic asynchronously\nPubSub.publish('MY TOPIC', 'hello world!');\n\n// publish a topic synchronously, which is faster in some environments,\n// but will get confusing when one topic triggers new topics in the\n// same execution chain\n// USE WITH CAUTION, HERE BE DRAGONS!!!\nPubSub.publishSync('MY TOPIC', 'hello world!');\n```\n\n### Cancel specific subscription\n\n```javascript\n// create a function to receive the topic\nvar mySubscriber = function (msg, data) {\n    console.log(msg, data);\n};\n\n// add the function to the list of subscribers to a particular topic\n// we're keeping the returned token, in order to be able to unsubscribe\n// from the topic later on\nvar token = PubSub.subscribe('MY TOPIC', mySubscriber);\n\n// unsubscribe this subscriber from this topic\nPubSub.unsubscribe(token);\n```\n\n### Cancel all subscriptions for a function\n\n```javascript\n// create a function to receive the topic\nvar mySubscriber = function(msg, data) {\n    console.log(msg, data);\n};\n\n// unsubscribe mySubscriber from ALL topics\nPubSub.unsubscribe(mySubscriber);\n```\n\n### Clear all subscriptions for a topic\n\n```javascript\nPubSub.subscribe('a', myFunc1);\nPubSub.subscribe('a.b', myFunc2);\nPubSub.subscribe('a.b.c', myFunc3);\n\nPubSub.unsubscribe('a.b');\n// no further notifications for 'a.b' and 'a.b.c' topics\n// notifications for 'a' will still get published\n```\n\n### Clear all subscriptions\n\n```javascript\nPubSub.clearAllSubscriptions();\n// all subscriptions are removed\n```\n\n### Get Subscriptions\n\n```javascript\nPubSub.getSubscriptions('token');\n// subscriptions by token from all topics\n```\n\n### Count Subscriptions\n\n```javascript\nPubSub.countSubscriptions('token');\n// count by token from all topics\n```\n\n\n### Error Handling\n```javascript\n// isPublished is a boolean that represents if any subscribers was registered for this topic\nvar isPublished = PubSub.publish('a');\n\n// token will be false if something went wrong and subscriber was not registered\nvar token = PubSub.subscribe('MY TOPIC', mySubscriber); \n```\n\n### Hierarchical addressing\n\n```javascript\n// create a subscriber to receive all topics from a hierarchy of topics\nvar myToplevelSubscriber = function (msg, data) {\n    console.log('top level: ', msg, data);\n}\n\n// subscribe to all topics in the 'car' hierarchy\nPubSub.subscribe('car', myToplevelSubscriber);\n\n// create a subscriber to receive only leaf topic from hierarchy op topics\nvar mySpecificSubscriber = function (msg, data) {\n    console.log('specific: ', msg, data);\n}\n\n// subscribe only to 'car.drive' topics\nPubSub.subscribe('car.drive', mySpecificSubscriber);\n\n// Publish some topics\nPubSub.publish('car.purchase', {name: 'my new car'});\nPubSub.publish('car.drive', {speed: '14'});\nPubSub.publish('car.sell', {newOwner: 'someone else'});\n\n// In this scenario, myToplevelSubscriber will be called for all\n// topics, three times in total\n// But, mySpecificSubscriber will only be called once, as it only\n// subscribes to the 'car.drive' topic\n```\n\n\n\n\n## Tips\n\nUse \"constants\" for topics and not string literals. PubSubJS uses strings as topics, and will happily try to deliver your topics with ANY topic. So, save yourself from frustrating debugging by letting the JavaScript engine complain\nwhen you make typos.\n\n### Example of use of \"constants\"\n\n```javascript\n// 👎 Bad usage\nPubSub.subscribe('hello', function (msg, data) {\n\tconsole.log(data)\n});\n\nPubSub.publish('hello', 'world');\n\n// 👍 Better usage\nvar MY_TOPIC = 'hello';\nPubSub.subscribe(MY_TOPIC, function (msg, data) {\n\tconsole.log(data)\n});\n\nPubSub.publish(MY_TOPIC, 'world');\n```\n\n### Example of use of \"symbol constants\" with ES6/7 syntax\n\n```javascript\n// event-types.js\nexport const MY_TOPIC = Symbol('MY_TOPIC')\n\n// somefile.js\nimport { MY_TOPIC } from './event-types.js'\nPubSub.subscribe(MY_TOPIC, function (msg, data) {\n\tconsole.log(data)\n});\n\nPubSub.publish(MY_TOPIC, 'world');\n```\n\n### Immediate Exceptions for stack traces in developer tools\n\nAs of version 1.3.2, you can force immediate exceptions (instead of delayed exceptions), which has the benefit of maintaining the stack trace when viewed in dev tools.\n\nThis should be considered a development only option, as PubSubJS was designed to try to deliver your topics to all subscribers, even when some fail.\n\nSetting immediate exceptions in development is easy, just tell PubSubJS about it after it has been loaded.\n\n```javascript\nPubSub.immediateExceptions = true;\n```\n\n## Contributing to PubSubJS\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md)\n\n\n## More about Publish/Subscribe\n\n* [The Many Faces of Publish/Subscribe](http://www.cs.ru.nl/~pieter/oss/manyfaces.pdf) (PDF)\n* [Addy Osmani's mini book on Patterns](http://addyosmani.com/resources/essentialjsdesignpatterns/book/#observerpatternjavascript)\n* [Publish / Subscribe Systems, A summary of 'The Many Faces of Publish / Subscribe'](http://downloads.ohohlfeld.com/talks/hohlfeld_schroeder-publish_subscribe_systems-dsmware_eurecom2007.pdf)\n\n## Versioning\n\nPubSubJS uses [Semantic Versioning](http://semver.org/) for predictable versioning.\n\n## Changelog\n\nPlease see [https://github.com/mroderick/PubSubJS/releases](https://github.com/mroderick/PubSubJS/releases)\n\n## License\n\nMIT: http://mrgnrdrck.mit-license.org\n\n## Alternatives\n\nThese are a few alternative projects that also implement topic based publish subscribe in JavaScript.\n\n* http://www.joezimjs.com/projects/publish-subscribe-jquery-plugin/\n* http://amplifyjs.com/api/pubsub/\n* http://radio.uxder.com/ — oriented towards 'channels', free of dependencies\n* https://github.com/pmelander/Subtopic - supports vanilla, underscore, jQuery and is even available in NuGet\n","funding_links":[],"categories":["JavaScript","Resources","Utilities","Uncategorized"],"sub_categories":["Libraries","React Components","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmroderick%2FPubSubJS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmroderick%2FPubSubJS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmroderick%2FPubSubJS/lists"}