events: add firstOn() and firstOnce() to prepend event listeners

A handful of modules (including readable-streams) make
inappropriate use of the internal _events property. One
such use is to prepend an event listener to the front
of the array of listeners.

This adds EE.prototype.firstOn() and EE.prototype.firstOnce()
methods to add handlers to the *front* of the listener array.

Doc update and test case is included.

Fixes: nodejs#1817

doc/api/events.markdown

@@ -314,6 +314,42 @@ 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
@@ -340,6 +376,9 @@ console.log(util.inspect(server.listeners('connection')));
 
 ### emitter.on(eventName, listener)
 
+* `eventName` {string|Symbol} The name of the event.
+* `listener` {Function} The callback function
+
 Adds the `listener` function to the end 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`
@@ -354,8 +393,25 @@ 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.
+
+```js
+const myEE = new EventEmitter();
+myEE.on('foo', () => console.log('a'));
+myEE.firstOn('foo', () => console.log('b'));
+myEE.emit('foo');
+  // Prints:
+  //   b
+  //   a
+```
+
 ### emitter.once(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`. This
 listener is invoked only the next time `eventName` is triggered, after which
 it is removed.
@@ -368,6 +424,20 @@ 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.
+
+```js
+const myEE = new EventEmitter();
+myEE.once('foo', () => console.log('a'));
+myEE.firstOnce('foo', () => console.log('b'));
+myEE.emit('foo');
+  // Prints:
+  //   b
+  //   a
+```
+
 ### emitter.removeAllListeners([eventName])
 
 Removes all listeners, or those of the specified `eventName`.

lib/_stream_readable.js

@@ -12,6 +12,25 @@ var StringDecoder;
 
 util.inherits(Readable, Stream);
 
+const has_firston = typeof EE.prototype.firstOn === 'function';
+
+function firstOn(emitter, event, fn) {
+  if (has_firston)
+    return emitter.firstOn(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.
+  if (!emitter._events || !emitter._events[event])
+    emitter.on(event, fn);
+  else if (Array.isArray(emitter._events[event]))
+    emitter._events[event].unshift(fn);
+  else
+    emitter._events[event] = [fn, emitter._events[event]];
+}
+
 function ReadableState(options, stream) {
   options = options || {};
 
@@ -558,15 +577,9 @@ Readable.prototype.pipe = function(dest, pipeOpts) {
     if (EE.listenerCount(dest, 'error') === 0)
       dest.emit('error', er);
   }
-  // This is a brutally ugly hack to make sure that our error handler
-  // is attached before any userland ones.  NEVER DO THIS.
-  if (!dest._events || !dest._events.error)
-    dest.on('error', onerror);
-  else if (Array.isArray(dest._events.error))
-    dest._events.error.unshift(onerror);
-  else
-    dest._events.error = [onerror, dest._events.error];
 
+  // Make sure our error handler is attached before userland ones.
+  firstOn(dest, 'error', onerror);
 
   // Both close and finish should trigger unpipe, but only once.
   function onclose() {

lib/events.js

@@ -207,48 +207,53 @@ EventEmitter.prototype.emit = function emit(type) {
   return true;
 };
 
-EventEmitter.prototype.addListener = function addListener(type, listener) {
+function _addListener(target, type, listener, prepend) {
   var m;
   var events;
   var existing;
 
   if (typeof listener !== 'function')
     throw new TypeError('"listener" argument must be a function');
 
-  events = this._events;
+  events = target._events;
   if (!events) {
-    events = this._events = new EventHandlers();
-    this._eventsCount = 0;
+    events = target._events = new EventHandlers();
+    target._eventsCount = 0;
   } else {
     // To avoid recursion in the case that type === "newListener"! Before
     // adding it to the listeners, first emit "newListener".
     if (events.newListener) {
-      this.emit('newListener', type,
-                listener.listener ? listener.listener : listener);
+      target.emit('newListener', type,
+                  listener.listener ? listener.listener : listener);
 
       // Re-assign `events` because a newListener handler could have caused the
       // this._events to be assigned to a new object
-      events = this._events;
+      events = target._events;
     }
     existing = events[type];
   }
 
   if (!existing) {
     // Optimize the case of one listener. Don't need the extra array object.
     existing = events[type] = listener;
-    ++this._eventsCount;
+    ++target._eventsCount;
   } else {
     if (typeof existing === 'function') {
       // Adding the second element, need to change to array.
-      existing = events[type] = [existing, listener];
+      existing = events[type] = prepend ? [listener, existing] :
+                                          [existing, listener];
     } else {
       // If we've already got an array, just append.
-      existing.push(listener);
+      if (prepend) {
+        existing.unshift(listener);
+      } else {
+        existing.push(listener);
+      }
     }
 
     // Check for listener leak
     if (!existing.warned) {
-      m = $getMaxListeners(this);
+      m = $getMaxListeners(target);
       if (m && m > 0 && existing.length > m) {
         existing.warned = true;
         process.emitWarning('Possible EventEmitter memory leak detected. ' +
@@ -258,29 +263,43 @@ EventEmitter.prototype.addListener = function addListener(type, listener) {
     }
   }
 
-  return this;
+  return target;
+}
+
+EventEmitter.prototype.addListener = function addListener(type, listener) {
+  return _addListener(this, type, listener, false);
 };
 
 EventEmitter.prototype.on = EventEmitter.prototype.addListener;
 
-EventEmitter.prototype.once = function once(type, listener) {
-  if (typeof listener !== 'function')
-    throw new TypeError('"listener" argument must be a function');
+EventEmitter.prototype.firstOn = function firstOn(type, listener) {
+  return _addListener(this, type, listener, true);
+};
 
+function _onceWrap(target, type, listener) {
   var fired = false;
-
   function g() {
-    this.removeListener(type, g);
-
+    target.removeListener(type, g);
     if (!fired) {
       fired = true;
-      listener.apply(this, arguments);
+      listener.apply(target, arguments);
     }
   }
-
   g.listener = listener;
-  this.on(type, g);
+  return g;
+}
+
+EventEmitter.prototype.once = function once(type, listener) {
+  if (typeof listener !== 'function')
+    throw new TypeError('"listener" argument must be a function');
+  this.on(type, _onceWrap(this, 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;
 };
 

test/parallel/test-event-emitter-prepend.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const common = require('../common');
+const EventEmitter = require('events');
+const assert = require('assert');
+
+const myEE = new EventEmitter();
+var m = 0;
+// This one comes last.
+myEE.on('foo', common.mustCall(() => assert.equal(m, 2)));
+
+// This one comes second.
+myEE.firstOn('foo', common.mustCall(() => assert.equal(m++, 1)));
+
+// This one comes first.
+myEE.firstOnce('foo', common.mustCall(() => assert.equal(m++, 0)));
+
+myEE.emit('foo');
+
+
+// Test fail-back if firstOn is undefined
+const stream = require('stream');
+const util = require('util');
+
+delete EventEmitter.prototype.firstOn;
+
+function Writable() {
+  this.writable = true;
+  stream.Stream.call(this);
+}
+util.inherits(Writable, stream.Stream);
+
+function Readable() {
+  this.readable = true;
+  stream.Stream.call(this);
+}
+util.inherits(Readable, stream.Stream);
+
+const w = new Writable();
+const r = new Readable();
+r.pipe(w);