Publish synchronously and public method hasSubscribers

.eslintrc.json

@@ -242,7 +242,7 @@
     "max-len": [1, 100, 2, {"ignoreComments": true, "ignoreTrailingComments": true, "ignoreUrls": true, "ignoreStrings": true, "ignoreTemplateLiterals": true}],
 
     // enforce a maximum number of parameters in function definitions
-    "max-params": [1, 3],
+    "max-params": [1, 5],
 
     // require constructor function names to begin with a capital letter
     "new-cap": 1,

.gitignore

@@ -1,4 +1,6 @@
 /node_modules
 /demo
 /tests/*.html
+/temp
 .idea
+npm-debug.log

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v2.1.0
+- Add support for publishing events synchronously using `publishSync` method.
+- Add public method `hasSubscribers` to check if there are subscribers for a specific topic.
+
 ## v2.0.3
 - Add support for Travis CI.
 - Lint source code using ESLint.

README.md

@@ -8,75 +8,184 @@ Javascript implementation of the [Publish–Subscribe pattern](http://en.wikiped
 [![Dependencies](https://david-dm.org/georapbox/PubSub.svg?theme=shields.io)](https://david-dm.org/georapbox/PubSub)
 [![devDependency Status](https://david-dm.org/georapbox/PubSub/dev-status.svg)](https://david-dm.org/georapbox/PubSub#info=devDependencies)
 
-## Installation
+## Install
 
-### Git installation
+### Git
 ```sh
 $ git clone https://github.com/georapbox/PubSub.git
 ```
 
-### npm installation
+### npm
 ```sh
 $ npm install PubSub
 ```
 
-### Bower installation
+### Bower
 ```sh
 $ bower install georapbox.pubsub.js
 ```
 
-## Using PubSub
+## API
 
+* [PubSub](#PubSub)
+    * [new PubSub()](#new_PubSub_new)
+    * [.subscribe(topic, callback, [once])](#PubSub+subscribe) ⇒ <code>number</code>
+    * [.subscribeOnce(topic, callback)](#PubSub+subscribeOnce) ⇒ <code>number</code>
+    * [.publish(topic, [data])](#PubSub+publish) ⇒ <code>boolean</code>
+    * [.publishSync(topic, [data])](#PubSub+publishSync) ⇒ <code>boolean</code>
+    * [.unsubscribe(topic)](#PubSub+unsubscribe) ⇒ <code>boolean</code> &#124; <code>string</code>
+    * [.hasSubscribers(topic)](#PubSub+hasSubscribers) ⇒ <code>Boolean</code>
+
+<a name="new_PubSub_new"></a>
+
+### new PubSub()
+Creates a PubSub instance.
+
+<a name="PubSub+subscribe"></a>
+
+### pubSub.subscribe(topic, callback, [once]) ⇒ <code>number</code>
+Subscribe to events of interest with a specific topic name and a
+callback function, to be executed when the topic/event is observed.
+
+**Kind**: instance method of <code>[PubSub](#PubSub)</code>  
+**Returns**: <code>number</code> - The topic's token  
+**this**: <code>{PubSub}</code>  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| topic | <code>string</code> |  | The topic's name |
+| callback | <code>function</code> |  | Callback function to execute on event, taking two arguments:        - {*} data The data passed when publishing an event        - {object} The topic's info (name & token) |
+| [once] | <code>boolean</code> | <code>false</code> | Checks if event will be triggered only one time |
+
+**Example**  
 ```js
-// Initialize PubSub
-var ps = new PubSub();
+var pubsub = new PubSub();
+
+var onUserAdd = pubsub.subscribe('user_add', function (data, topic) {
+  console.log('User added');
+  console.log('user data:', data);
+});
 ```
+<a name="PubSub+subscribeOnce"></a>
+
+### pubSub.subscribeOnce(topic, callback) ⇒ <code>number</code>
+Subscribe to events of interest setting a flag
+indicating the event will be published only one time.
+
+**Kind**: instance method of <code>[PubSub](#PubSub)</code>  
+**Returns**: <code>number</code> - The topic's token  
+**this**: <code>{PubSub}</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| topic | <code>string</code> | The topic's name |
+| callback | <code>function</code> | Callback function to execute on event, taking two arguments:        - {*} data The data passed when publishing an event        - {object} The topic's info (name & token) |
 
-### Subscribing events
-The "listener" is the function to be executed when an event is emitted.
+**Example**  
 ```js
-function listener(data, topic) {
-  console.log('An event is published.');
-  console.log(topic);
-  console.log(data);
-}
+var onUserAdd = pubsub.subscribeOnce('user_add', function (data, topic) {
+  console.log('User added');
+  console.log('user data:', data);
+});
+```
+<a name="PubSub+publish"></a>
+
+### pubSub.publish(topic, [data]) ⇒ <code>boolean</code>
+Publishes a topic, passing the data to its subscribers.
 
-// Subscribe to event
-var sub = ps.subscribe('event-name', listener);
+**Kind**: instance method of <code>[PubSub](#PubSub)</code>  
+**Returns**: <code>boolean</code> - Returns `true` if topic exists and event is published; otheriwse `false`  
+**this**: <code>{PubSub}</code>  
 
-// Subscribe to event and execute only one time
-var subOnce = ps.subscribeOnce('event-name', listener)
+| Param | Type | Description |
+| --- | --- | --- |
+| topic | <code>string</code> | The topic's name |
+| [data] | <code>\*</code> | The data to be passed to its subscribers |
+
+**Example**  
+```js
+pubsub.publish('user_add', {
+  firstName: 'John',
+  lastName: 'Doe',
+  email: '[email protected]'
+});
 ```
+<a name="PubSub+publishSync"></a>
+
+### pubSub.publishSync(topic, [data]) ⇒ <code>boolean</code>
+Publishes a topic synchronously, passing the data to its subscribers.
 
-### Publishing events
-The `publish` method takes two arguments:
+**Kind**: instance method of <code>[PubSub](#PubSub)</code>  
+**Returns**: <code>boolean</code> - Returns `true` if topic exists and event is published; otheriwse `false`  
+**this**: <code>{PubSub}</code>  
 
-- The first one is the name of the event.
-- The second one (optional) is the data we may want to pass along as. We can pass data along using an array or an object as shown below.
+| Param | Type | Description |
+| --- | --- | --- |
+| topic | <code>string</code> | The topic's name |
+| [data] | <code>\*</code> | The data to be passed to its subscribers |
+
+**Example**  
 ```js
-ps.publish('event-name', {
-  prop1: value1,
-  prop2: value2
+pubsub.publishSync('user_add', {
+  firstName: 'John',
+  lastName: 'Doe',
+  email: '[email protected]'
 });
 ```
+<a name="PubSub+unsubscribe"></a>
+
+### pubSub.unsubscribe(topic) ⇒ <code>boolean</code> &#124; <code>string</code>
+Unsubscribes from a specific topic, based on the topic name,
+or based on a tokenized reference to the subscription.
 
-### Unsubscribing events
-There are two ways to unsubscribe an event:
+**Kind**: instance method of <code>[PubSub](#PubSub)</code>  
+**Returns**: <code>boolean</code> &#124; <code>string</code> - Returns `false` if `topic` does not match a subscribed event; otherwise the topic's name  
+**this**: <code>{PubSub}</code>  
 
-- Unsubscribe from a specific topic based on a tokenized reference to the subscription.
+| Param | Type | Description |
+| --- | --- | --- |
+| topic | <code>string</code> &#124; <code>object</code> | Topic's name or subscription referenece |
+
+**Example**  
 ```js
-ps.unsubscribe(sub);
+// Unsubscribe using the topic's name.
+pubsub.unsubscribe('user_add');
+
+// Unsubscribe using a tokenized reference to the subscription.
+pubsub.unsubscribe(onUserAdd);
 ```
-- Unsubscribe from a specific topic based on topic name. This way we can unsubscribe all events with the same name.
+<a name="PubSub+hasSubscribers"></a>
+
+### pubSub.hasSubscribers(topic) ⇒ <code>Boolean</code>
+Checks if there are subscribers for a specific topic.
+
+**Kind**: instance method of <code>[PubSub](#PubSub)</code>  
+**Returns**: <code>Boolean</code> - Returns `true` if topic has subscribers; otherwise `false`  
+**this**: <code>{PubSub}</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| topic | <code>String</code> | The topic's name to check |
+
+**Example**  
 ```js
-ps.unsubscribe('event-name');
+var pubsub = new PubSub();
+pubsub.on('message', function (data) {
+  console.log(data);
+});
+
+pubsub.hasSubscribers('message');
+// -> true
 ```
 
-## Methods aliases
+
+### Methods aliases
 - `on` - `subscribe`
 - `once` - `subscribeOnce`
 - `trigger` - `publish`
+- `triggerSync` - `publishSync`
 - `off` - `unsubscribe`
+- `has` - `hasSubscribers`
 
 ## Minify
 

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "georapbox.pubsub.js",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "homepage": "https://github.com/georapbox/PubSub",
   "authors": [
     "George Raptis <[email protected]>"

package.json

@@ -1,12 +1,13 @@
 {
   "name": "PubSub",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Javascript implementation of the Publish/Subscribe pattern.",
   "main": "src/pubsub.js",
   "scripts": {
     "build": "grunt build",
     "test": "karma start",
     "lint": "eslint src/**",
+    "jsdoc2md": "jsdoc2md \"src/pubsub.js\" > \"temp/api_readme.md\"",
     "ci": "npm run lint; npm test;"
   },
   "repository": {
@@ -30,13 +31,14 @@
   },
   "homepage": "https://github.com/georapbox/PubSub#readme",
   "devDependencies": {
-    "eslint": "~3.12.2",
+    "eslint": "~3.13.1",
     "grunt": "~1.0.1",
     "grunt-cli": "~1.2.0",
     "grunt-contrib-uglify": "~2.0.0",
     "grunt-remove-logging": "~0.2.0",
     "jasmine-core": "~2.5.2",
-    "karma": "~1.3.0",
+    "jsdoc-to-markdown": "~2.0.1",
+    "karma": "~1.4.0",
     "karma-chrome-launcher": "~2.0.0",
     "karma-cli": "~1.0.0",
     "karma-firefox-launcher": "~1.0.0",