From 6cba1e60f60a66b66340e3fcdec12a64fc39ae63 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 18 Apr 2016 20:30:07 -0700 Subject: [PATCH] Rename to prependListener/prependOnceListener --- doc/api/events.markdown | 84 ++++++++++----------- lib/_stream_readable.js | 12 +-- lib/events.js | 20 ++--- test/parallel/test-event-emitter-prepend.js | 8 +- 4 files changed, 63 insertions(+), 61 deletions(-) diff --git a/doc/api/events.markdown b/doc/api/events.markdown index 9ea4df89c8052f..fd9c97f9974954 100644 --- a/doc/api/events.markdown +++ b/doc/api/events.markdown @@ -314,42 +314,6 @@ console.log(myErr.eventNames()); // Prints ['foo', 'bar', Symbol('symbol')] ``` -### emitter.firstOn(eventName, listener) - -* `eventName` {string|Symbol} The name of the event. -* `listener` {Function} The callback function - -Adds the `listener` function to the *beginning* of the listeners array for the -event named `eventName`. No checks are made to see if the `listener` has -already been added. Multiple calls passing the same combination of `eventName` -and `listener` will result in the `listener` being added, and called, multiple -times. - -```js -server.firstOn('connection', (stream) => { - console.log('someone connected!'); -}); -``` - -Returns a reference to the `EventEmitter` so calls can be chained. - -### emitter.firstOnce(eventName, listener) - -* `eventName` {string|Symbol} The name of the event. -* `listener` {Function} The callback function - -Adds a **one time** `listener` function for the event named `eventName` to the -beginning of the listeners array. This listener is invoked only the next time -`eventName` is triggered, after which it is removed. - -```js -server.firstOnce('connection', (stream) => { - console.log('Ah, we have our first user!'); -}); -``` - -Returns a reference to the `EventEmitter` so calls can be chained. - ### emitter.getMaxListeners() Returns the current max listener value for the `EventEmitter` which is either @@ -394,13 +358,13 @@ server.on('connection', (stream) => { Returns a reference to the `EventEmitter` so calls can be chained. By default, event listeners are invoked in the order they are added. The -`emitter.firstOn()` method can be used as an alternative to add the event -listener to the beginning of the listeners array. +`emitter.prependListener()` method can be used as an alternative to add the +event listener to the beginning of the listeners array. ```js const myEE = new EventEmitter(); myEE.on('foo', () => console.log('a')); -myEE.firstOn('foo', () => console.log('b')); +myEE.prependListener('foo', () => console.log('b')); myEE.emit('foo'); // Prints: // b @@ -425,19 +389,55 @@ server.once('connection', (stream) => { Returns a reference to the `EventEmitter` so calls can be chained. By default, event listeners are invoked in the order they are added. The -`emitter.firstOnce()` method can be used as an alternative to add the event -listener to the beginning of the listeners array. +`emitter.prependOnceListener()` method can be used as an alternative to add the +event listener to the beginning of the listeners array. ```js const myEE = new EventEmitter(); myEE.once('foo', () => console.log('a')); -myEE.firstOnce('foo', () => console.log('b')); +myEE.prependOnceListener('foo', () => console.log('b')); myEE.emit('foo'); // Prints: // b // a ``` +### emitter.prependListener(eventName, listener) + +* `eventName` {string|Symbol} The name of the event. +* `listener` {Function} The callback function + +Adds the `listener` function to the *beginning* of the listeners array for the +event named `eventName`. No checks are made to see if the `listener` has +already been added. Multiple calls passing the same combination of `eventName` +and `listener` will result in the `listener` being added, and called, multiple +times. + +```js +server.prependListener('connection', (stream) => { + console.log('someone connected!'); +}); +``` + +Returns a reference to the `EventEmitter` so calls can be chained. + +### emitter.prependOnceListener(eventName, listener) + +* `eventName` {string|Symbol} The name of the event. +* `listener` {Function} The callback function + +Adds a **one time** `listener` function for the event named `eventName` to the +beginning of the listeners array. This listener is invoked only the next time +`eventName` is triggered, after which it is removed. + +```js +server.prependOnceListener('connection', (stream) => { + console.log('Ah, we have our first user!'); +}); +``` + +Returns a reference to the `EventEmitter` so calls can be chained. + ### emitter.removeAllListeners([eventName]) Removes all listeners, or those of the specified `eventName`. diff --git a/lib/_stream_readable.js b/lib/_stream_readable.js index f3fbbce226e011..204fa7e95933fb 100644 --- a/lib/_stream_readable.js +++ b/lib/_stream_readable.js @@ -12,17 +12,17 @@ var StringDecoder; util.inherits(Readable, Stream); -const has_firston = typeof EE.prototype.firstOn === 'function'; +const has_firston = typeof EE.prototype.prependListener === 'function'; -function firstOn(emitter, event, fn) { +function prependListener(emitter, event, fn) { if (has_firston) - return emitter.firstOn(event, fn); + return emitter.prependListener(event, fn); // This is a brutally ugly hack to make sure that our error handler // is attached before any userland ones. NEVER DO THIS. This is here // only because this code needs to continue to work with older versions - // of Node.js that do not include the firstOn() method. The goal is to - // eventually remove this hack. + // of Node.js that do not include the prependListener() method. The goal + // is to eventually remove this hack. if (!emitter._events || !emitter._events[event]) emitter.on(event, fn); else if (Array.isArray(emitter._events[event])) @@ -579,7 +579,7 @@ Readable.prototype.pipe = function(dest, pipeOpts) { } // Make sure our error handler is attached before userland ones. - firstOn(dest, 'error', onerror); + prependListener(dest, 'error', onerror); // Both close and finish should trigger unpipe, but only once. function onclose() { diff --git a/lib/events.js b/lib/events.js index efe3d4e7108115..dd8aeaf66206ac 100644 --- a/lib/events.js +++ b/lib/events.js @@ -272,9 +272,10 @@ EventEmitter.prototype.addListener = function addListener(type, listener) { EventEmitter.prototype.on = EventEmitter.prototype.addListener; -EventEmitter.prototype.firstOn = function firstOn(type, listener) { - return _addListener(this, type, listener, true); -}; +EventEmitter.prototype.prependListener = + function prependListener(type, listener) { + return _addListener(this, type, listener, true); + }; function _onceWrap(target, type, listener) { var fired = false; @@ -296,12 +297,13 @@ EventEmitter.prototype.once = function once(type, listener) { return this; }; -EventEmitter.prototype.firstOnce = function firstOnce(type, listener) { - if (typeof listener !== 'function') - throw new TypeError('"listener" argument must be a function'); - this.firstOn(type, _onceWrap(this, type, listener)); - return this; -}; +EventEmitter.prototype.prependOnceListener = + function prependOnceListener(type, listener) { + if (typeof listener !== 'function') + throw new TypeError('"listener" argument must be a function'); + this.prependListener(type, _onceWrap(this, type, listener)); + return this; + }; // emits a 'removeListener' event iff the listener was removed EventEmitter.prototype.removeListener = diff --git a/test/parallel/test-event-emitter-prepend.js b/test/parallel/test-event-emitter-prepend.js index 125d263acc4f19..7772e42c95a55d 100644 --- a/test/parallel/test-event-emitter-prepend.js +++ b/test/parallel/test-event-emitter-prepend.js @@ -10,19 +10,19 @@ var m = 0; myEE.on('foo', common.mustCall(() => assert.equal(m, 2))); // This one comes second. -myEE.firstOn('foo', common.mustCall(() => assert.equal(m++, 1))); +myEE.prependListener('foo', common.mustCall(() => assert.equal(m++, 1))); // This one comes first. -myEE.firstOnce('foo', common.mustCall(() => assert.equal(m++, 0))); +myEE.prependOnceListener('foo', common.mustCall(() => assert.equal(m++, 0))); myEE.emit('foo'); -// Test fail-back if firstOn is undefined +// Test fail-back if prependListener is undefined const stream = require('stream'); const util = require('util'); -delete EventEmitter.prototype.firstOn; +delete EventEmitter.prototype.prependListener; function Writable() { this.writable = true;