diff --git a/README.md b/README.md index 6810f1f..f6e694a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # PubSub -Javascript implementation of the [Publish–Subscribe pattern](http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern). +Javascript implementation of the [Publish/Subscribe](http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) pattern. [![Build Status](https://travis-ci.org/georapbox/PubSub.svg?branch=master)](https://travis-ci.org/georapbox/PubSub) [![npm version](https://badge.fury.io/js/PubSub.svg)](http://badge.fury.io/js/PubSub) @@ -54,9 +54,11 @@ For API updates and breaking changes, check the [CHANGELOG](https://github.com/g ### new PubSub() Creates a PubSub instance. +### Methods + -### pubSub.subscribe(topic, callback, [once]) ⇒ number +### .subscribe(topic, callback, [once]) ⇒ number Subscribe to events of interest with a specific topic name and a callback function, to be executed when the topic/event is observed. @@ -81,7 +83,7 @@ var onUserAdd = pubsub.subscribe('user_add', function (data, topic) { ``` -### pubSub.subscribeOnce(topic, callback) ⇒ number +### .subscribeOnce(topic, callback) ⇒ number Subscribe to events of interest setting a flag indicating the event will be published only one time. @@ -103,8 +105,10 @@ var onUserAdd = pubsub.subscribeOnce('user_add', function (data, topic) { ``` -### pubSub.publish(topic, [data]) ⇒ boolean -Publishes a topic, passing the data to its subscribers. +### .publish(topic, [data]) ⇒ boolean +Publishes a topic **asynchronously**, passing the data to its subscribers. +Asynchronous publication helps in that the originator of the topic will not be blocked while consumers process them. +For synchronous topic publication check `publishSync`. **Kind**: instance method of [PubSub](#PubSub) **Returns**: boolean - Returns `true` if topic exists and event is published; otheriwse `false` @@ -125,8 +129,8 @@ pubsub.publish('user_add', { ``` -### pubSub.publishSync(topic, [data]) ⇒ boolean -Publishes a topic synchronously, passing the data to its subscribers. +### .publishSync(topic, [data]) ⇒ boolean +Publishes a topic **synchronously**, passing the data to its subscribers. **Kind**: instance method of [PubSub](#PubSub) **Returns**: boolean - Returns `true` if topic exists and event is published; otheriwse `false` @@ -147,7 +151,7 @@ pubsub.publishSync('user_add', { ``` -### pubSub.unsubscribe(topic) ⇒ boolean \| string +### .unsubscribe(topic) ⇒ boolean \| string Unsubscribes from a specific topic, based on the topic name, or based on a tokenized reference to the subscription. @@ -169,7 +173,7 @@ pubsub.unsubscribe(onUserAdd); ``` -### pubSub.unsubscribeAll() ⇒ [PubSub](#PubSub) +### .unsubscribeAll() ⇒ [PubSub](#PubSub) Clears all subscriptions whatsoever. **Kind**: instance method of [PubSub](#PubSub) @@ -184,7 +188,7 @@ pubsub.unsubscribeAll(); ``` -### pubSub.hasSubscribers([topic]) ⇒ boolean +### .hasSubscribers([topic]) ⇒ boolean Checks if there are subscribers for a specific topic. If `topic` is not provided, checks if there is at least one subscriber. @@ -208,7 +212,7 @@ pubsub.hasSubscribers('message'); ``` -### pubSub.subscribers() ⇒ object +### .subscribers() ⇒ object Gets all the subscribers as a set of key value pairs that represent the topic's name and the event listener(s) bound. @@ -228,7 +232,7 @@ pubsub.subscribers(); ``` -### pubSub.subscribersByTopic(topic) ⇒ array +### .subscribersByTopic(topic) ⇒ array Gets subscribers for a specific topic. **Kind**: instance method of [PubSub](#PubSub) @@ -258,7 +262,7 @@ pubsub.subscribersByTopic('some_message_not_existing'); ``` -### pubSub.alias(aliasMap) ⇒ [PubSub](#PubSub) +### .alias(aliasMap) ⇒ [PubSub](#PubSub) Creates aliases for public methods. **Kind**: instance method of [PubSub](#PubSub) @@ -281,7 +285,7 @@ var pubsub = new PubSub().alias({ }); ``` -## Minify +## Minify source code ```sh $ npm run build @@ -296,6 +300,11 @@ To run the tests: $ npm test ``` +## More about Publish/Subscribe pattern + +- [The Observer Pattern - Addy Osmani](https://addyosmani.com/resources/essentialjsdesignpatterns/book/#observerpatternjavascript) +- [Publish–Subscribe pattern - Wikipedia](http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) + ## License [The MIT License (MIT)](https://georapbox.mit-license.org/@2014)