events: add ability 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.

To address part of the issue, this adds a new optional
bitwise flag to the addListener/on/once methods that,
when set, causes the listener to be prepended.

Doc update and test case is included.

Fixes: nodejs#1817

Author: jasnell

doc/api/events.markdown

@@ -284,9 +284,9 @@ emitter.once('event', () => {
 });
 ```
 
-### emitter.addListener(eventName, listener)
+### emitter.addListener(eventName, listener[, flags])
 
-Alias for `emitter.on(eventName, listener)`.
+Alias for `emitter.on(eventName, listener[, flags])`.
 
 ### emitter.emit(eventName[, arg1][, arg2][, ...])
 
@@ -338,7 +338,12 @@ console.log(util.inspect(server.listeners('connection')));
   // Prints: [ [Function] ]
 ```
 
-### emitter.on(eventName, listener)
+### emitter.on(eventName, listener[, flags])
+
+* `eventName` {string|Symbol} The name of the event.
+* `listener` {Function} The callback function
+* `flags` {Bitwise field} Optional flags
+  * `EventEmitter.F_PREPEND` = `0x1`
 
 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
@@ -354,7 +359,26 @@ server.on('connection', (stream) => {
 
 Returns a reference to the `EventEmitter` so calls can be chained.
 
-### emitter.once(eventName, listener)
+By default, event listeners are invoked in the order they are added. The
+`EventEmitter.F_PREPEND` flag can be used to add the event listener to the
+beginning of the list of registered listeners.
+
+```js
+const myEE = new EventEmitter();
+myEE.on('foo', () => console.log('a'));
+myEE.on('foo', () => {console.log('b')}, EventEmitter.F_PREPEND);
+myEE.emit('foo');
+  // Prints:
+  //   b
+  //   a
+```
+
+### emitter.once(eventName, listener, flags)
+
+* `eventName` {string|Symbol} The name of the event.
+* `listener` {Function} The callback function
+* `flags` {Bitwise field} Optional flags
+  * `EventEmitter.F_PREPEND` = `0x1`
 
 Adds a **one time** `listener` function for the event named `eventName`. This
 listener is invoked only the next time `eventName` is triggered, after which
@@ -368,6 +392,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
+`EventEmitter.F_PREPEND` flag can be used to add the event listener to the
+beginning of the list of registered listeners.
+
+```js
+const myEE = new EventEmitter();
+myEE.once('foo', () => console.log('a'));
+myEE.once('foo', () => {console.log('b')}, EventEmitter.F_PREPEND);
+myEE.emit('foo');
+  // Prints:
+  //   b
+  //   a
+```
+
 ### emitter.removeAllListeners([eventName])
 
 Removes all listeners, or those of the specified `eventName`.

lib/_http_server.js

@@ -577,8 +577,8 @@ function unconsume(parser, socket) {
   }
 }
 
-function socketOnWrap(ev, fn) {
-  var res = net.Socket.prototype.on.call(this, ev, fn);
+function socketOnWrap(ev, fn, flags) {
+  var res = net.Socket.prototype.on.call(this, ev, fn, flags);
   if (!this.parser) {
     this.on = net.Socket.prototype.on;
     return res;

lib/_stream_readable.js

@@ -558,15 +558,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.
+  dest.on('error', onerror, EE.F_PREPEND);
 
   // Both close and finish should trigger unpipe, but only once.
   function onclose() {
@@ -669,8 +663,8 @@ Readable.prototype.unpipe = function(dest) {
 
 // set up data events if they are asked for
 // Ensure readable listeners eventually get something
-Readable.prototype.on = function(ev, fn) {
-  var res = Stream.prototype.on.call(this, ev, fn);
+Readable.prototype.on = function(ev, fn, flags) {
+  var res = Stream.prototype.on.call(this, ev, fn, flags);
 
   // If listening to data, and it has not explicitly been paused,
   // then call resume to start the flow of data on the next tick.

lib/events.js

@@ -7,6 +7,12 @@ function EventEmitter() {
 }
 module.exports = EventEmitter;
 
+Object.defineProperty(EventEmitter, 'F_PREPEND', {
+  configurable: false,
+  enumerable: true,
+  value: 0x1
+});
+
 // Backwards-compat with node 0.10.x
 EventEmitter.EventEmitter = EventEmitter;
 
@@ -201,11 +207,16 @@ EventEmitter.prototype.emit = function emit(type) {
   return true;
 };
 
-EventEmitter.prototype.addListener = function addListener(type, listener) {
+EventEmitter.prototype.addListener = function addListener(type,
+                                                          listener,
+                                                          flags) {
   var m;
   var events;
   var existing;
 
+  flags >>>= 0;
+  const prepend = (flags & EventEmitter.F_PREPEND) === EventEmitter.F_PREPEND;
+
   if (typeof listener !== 'function')
     throw new TypeError('"listener" argument must be a function');
 
@@ -234,10 +245,15 @@ EventEmitter.prototype.addListener = function addListener(type, listener) {
   } 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
@@ -257,7 +273,7 @@ EventEmitter.prototype.addListener = function addListener(type, listener) {
 
 EventEmitter.prototype.on = EventEmitter.prototype.addListener;
 
-EventEmitter.prototype.once = function once(type, listener) {
+EventEmitter.prototype.once = function once(type, listener, flags) {
   if (typeof listener !== 'function')
     throw new TypeError('"listener" argument must be a function');
 
@@ -273,7 +289,7 @@ EventEmitter.prototype.once = function once(type, listener) {
   }
 
   g.listener = listener;
-  this.on(type, g);
+  this.on(type, g, flags);
 
   return this;
 };

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

@@ -0,0 +1,21 @@
+'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.on('foo', () => {
+  assert.equal(m++, 1);
+}, EventEmitter.F_PREPEND);
+// This one comes first.
+myEE.once('foo', () => {
+  assert.equal(m++, 0);
+}, EventEmitter.F_PREPEND);
+myEE.emit('foo');