New 'proxyEvents' function

Gruntfile.js

@@ -27,7 +27,8 @@ module.exports = function (grunt) {
                         'usage-emit-async': 'EnhancedEventEmitter+emitAsync',
                         'usage-on-async': 'EnhancedEventEmitter+onAsync',
                         'usage-on-any': 'EnhancedEventEmitter+onAny',
-                        'usage-filter': 'EnhancedEventEmitter+addFilter'
+                        'usage-filter': 'EnhancedEventEmitter+addFilter',
+                        'usage-proxyEvents': 'EnhancedEventEmitter+proxyEvents'
                     },
                     modifySignature: function (line) {
                         return line.split('### \'EnhancedEventEmitter.').join('### \'emitter.').split('emitter.addFilter(').join('emitter.filter(').split('emitAsync(event, [params]').join('emitAsync(event, [...params]');

README.md

@@ -17,6 +17,7 @@
   * [onAsync](#usage-on-async)
   * [onAny](#usage-on-any)
   * [filter](#usage-filter)
+  * [proxyEvents](#usage-proxyEvents)
 * [Installation](#installation)
 * [API Documentation](docs/api.md)
 * [Contributing](.github/CONTRIBUTING.md)
@@ -295,6 +296,27 @@ removeGlobalArg2Filter();
 ```
 <!-- markdownlint-enable MD009 MD031 MD036 -->
 
+<a name="usage-proxyEvents"></a>
+<!-- markdownlint-disable MD009 MD031 MD036 -->
+### 'emitter.proxyEvents(emitters, events) ⇒ function'
+Will setup an event proxy so if any of the requested event/s are fired from the provided emitter/s, they will be triggered by this emitter.
+
+**Example**  
+```js
+var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
+var emitter = new EnhancedEventEmitter();
+
+//proxy the 'data' and 'end' events from all sockets
+var stop = emitter.proxyEvents(sockets, ['data', 'end']);
+
+//listen to events via emitter
+emitter.on('data', onData);
+
+//stop events proxy
+stop();
+```
+<!-- markdownlint-enable MD009 MD031 MD036 -->
+
 <a name="installation"></a>
 ## Installation
 In order to use this library, just run the following npm install command:
@@ -314,6 +336,7 @@ See [contributing guide](.github/CONTRIBUTING.md)
 
 | Date        | Version | Description |
 | ----------- | ------- | ----------- |
+| 2017-01-07  | v1.0.25 | New 'proxyEvents' function |
 | 2017-01-06  | v1.0.24 | New extended 'on' function |
 | 2016-12-31  | v1.0.23 | Maintenance |
 | 2016-11-11  | v1.0.15 | 'emitAsync' callback is now optional |

docs/CHANGELOG.md

@@ -1,5 +1,6 @@
 | Date        | Version | Description |
 | ----------- | ------- | ----------- |
+| 2017-01-07  | v1.0.25 | New 'proxyEvents' function |
 | 2017-01-06  | v1.0.24 | New extended 'on' function |
 | 2016-12-31  | v1.0.23 | Maintenance |
 | 2016-11-11  | v1.0.15 | 'emitAsync' callback is now optional |

docs/api.md

@@ -58,6 +58,7 @@
     * [#addEventFilter(event, filter)](#EnhancedEventEmitter+addEventFilter) ⇒ <code>function</code>
     * [#addGlobalFilter(filter)](#EnhancedEventEmitter+addGlobalFilter) ⇒ <code>function</code>
     * [#filter([event], filter)](#EnhancedEventEmitter+filter) ⇒ <code>function</code>
+    * [#proxyEvents(emitters, events)](#EnhancedEventEmitter+proxyEvents) ⇒ <code>function</code>
 
 <a name="new_EnhancedEventEmitter_new"></a>
 
@@ -473,6 +474,33 @@ See 'addFilter' documentation.
 | [event] | <code>String</code> | The event name. If not provided, the filter is relevant for all events. |
 | filter | <code>[FilterCallback](#FilterCallback)</code> | The filter function |
 
+<a name="EnhancedEventEmitter+proxyEvents"></a>
+
+### EnhancedEventEmitter#proxyEvents(emitters, events) ⇒ <code>function</code>
+Will setup an event proxy so if any of the requested event/s are fired from the provided emitter/s, they will be triggered by this emitter.
+
+**Returns**: <code>function</code> - Once invoked, will stop proxying of events  
+**Access:** public  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| emitters | <code>Array.&lt;Object&gt;</code> &#124; <code>Object</code> | An event emitter or array of event emitters to proxy the events from |
+| events | <code>Array.&lt;String&gt;</code> &#124; <code>String</code> | A single event name or an array of event names to proxy from the provided emitter/s |
+
+**Example**  
+```js
+var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
+var emitter = new EnhancedEventEmitter();
+
+//proxy the 'data' and 'end' events from all sockets
+var stop = emitter.proxyEvents(sockets, ['data', 'end']);
+
+//listen to events via emitter
+emitter.on('data', onData);
+
+//stop events proxy
+stop();
+```
 <a name="EventEmitterEnhancer"></a>
 
 ## EventEmitterEnhancer

lib/enhanced-event-emitter.js

@@ -781,6 +781,89 @@ EnhancedEventEmitter.prototype.addGlobalFilter = function (filter) {
  */
 EnhancedEventEmitter.prototype.filter = EnhancedEventEmitter.prototype.addFilter; //shorter function name
 
+/**
+ * Will setup an event proxy so if any of the requested event/s are fired from the provided emitter/s, they will be triggered by this emitter.
+ *
+ * @function
+ * @memberof! EnhancedEventEmitter
+ * @public
+ * @param {Object[]|Object} emitters - An event emitter or array of event emitters to proxy the events from
+ * @param {String[]|String} events - A single event name or an array of event names to proxy from the provided emitter/s
+ * @returns {function} Once invoked, will stop proxying of events
+ * @example
+ * ```js
+ * var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
+ * var emitter = new EnhancedEventEmitter();
+ *
+ * //proxy the 'data' and 'end' events from all sockets
+ * var stop = emitter.proxyEvents(sockets, ['data', 'end']);
+ *
+ * //listen to events via emitter
+ * emitter.on('data', onData);
+ *
+ * //stop events proxy
+ * stop();
+ * ```
+ */
+EnhancedEventEmitter.prototype.proxyEvents = function (emitters, events) {
+    if (!emitters) {
+        throw new Error('Event Emitter/s not provided.');
+    }
+
+    if (!events) {
+        throw new Error('Event/s not provided.');
+    }
+
+    var self = this;
+
+    if (!Array.isArray(emitters)) {
+        emitters = [emitters];
+    }
+
+    if (typeof events === 'string') {
+        events = [events];
+    }
+
+    var releaseFuncs = [];
+    events.forEach(function createProxy(event) {
+        emitters.forEach(function onClientEvent(emitter) {
+            var onEvent = function onEvent() {
+                //get event arguments
+                var argumentsArray = Array.prototype.slice.call(arguments, 0);
+
+                //add event name to list
+                argumentsArray.unshift(event);
+
+                //emit event
+                self.emit.apply(self, argumentsArray);
+            };
+
+            emitter.on(event, onEvent);
+
+            releaseFuncs.push(function stop() {
+                emitter.removeListener(event, onEvent);
+            });
+        });
+    });
+
+    var stopped = false;
+
+    return function stopProxy() {
+        if (!stopped) {
+            /*istanbul ignore else*/
+            if (releaseFuncs) {
+                releaseFuncs.forEach(function invokeStop(release) {
+                    release();
+                });
+
+                releaseFuncs = null;
+            }
+
+            stopped = true;
+        }
+    };
+};
+
 /**
  * Returns true if to allow to emit the event based on the currently setup filters.
  *

package.json

@@ -1,6 +1,6 @@
 {
   "name": "event-emitter-enhancer",
-  "version": "1.0.24",
+  "version": "1.0.25",
   "description": "Enhances the Node.js EventEmitter with extra capabilities.",
   "author": {
     "name": "Sagie Gur-Ari",

project/config/README-template.md

@@ -17,6 +17,7 @@
   * [onAsync](#usage-on-async)
   * [onAny](#usage-on-any)
   * [filter](#usage-filter)
+  * [proxyEvents](#usage-proxyEvents)
 * [Installation](#installation)
 * [API Documentation](docs/api.md)
 * [Contributing](.github/CONTRIBUTING.md)
@@ -76,6 +77,8 @@ EventEmitterEnhancer.modifyInstance(emitter);   //modify the specific instance a
 
 <a name="usage-filter"></a>
 
+<a name="usage-proxyEvents"></a>
+
 <a name="installation"></a>
 ## Installation
 In order to use this library, just run the following npm install command: