From 93e6b3f74dab6ccc68b3117cbae1009ce91a4859 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 9 Sep 2019 13:33:51 +0200
Subject: [PATCH 1/7] events: add/removeListener should call on/off

Previously these used alias which caused surprising behaviour
when trying to override add/removeListener, e.g. Readable.

This resolves this by making add/remove actually call the
corresponding function through the prototype chain.
---
 doc/api/events.md                     | 61 ++++++++++++++-------------
 lib/events.js                         |  8 +++-
 test/parallel/test-events-override.js | 17 ++++++++
 3 files changed, 55 insertions(+), 31 deletions(-)
 create mode 100644 test/parallel/test-events-override.js

diff --git a/doc/api/events.md b/doc/api/events.md
index 021c6b05989dad..07f05aa5ed7c4f 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -290,8 +290,35 @@ added: v0.1.26
 -->
 * `eventName` {string|symbol}
 * `listener` {Function}
+* Returns: {EventEmitter}
+
+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`
+and `listener` will result in the `listener` being added, and called, multiple
+times.
+
+```js
+server.addListener('connection', (stream) => {
+  console.log('someone connected!');
+});
+```
+
+Returns a reference to the `EventEmitter`, so that calls can be chained.
 
-Alias for `emitter.on(eventName, listener)`.
+By default, event listeners are invoked in the order they are added. The
+`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.addListener('foo', () => console.log('a'));
+myEE.prependListener('foo', () => console.log('b'));
+myEE.emit('foo');
+// Prints:
+//   b
+//   a
+```
 
 ### emitter.emit(eventName[, ...args])
 <!-- YAML
@@ -415,7 +442,8 @@ added: v10.0.0
 * `listener` {Function}
 * Returns: {EventEmitter}
 
-Alias for [`emitter.removeListener()`][].
+Calls [`emitter.removeListener()`][]. When overriding, override
+[`emitter.removeListener()`][].
 
 ### emitter.on(eventName, listener)
 <!-- YAML
@@ -426,33 +454,8 @@ added: v0.1.101
 * `listener` {Function} The callback function
 * Returns: {EventEmitter}
 
-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`
-and `listener` will result in the `listener` being added, and called, multiple
-times.
-
-```js
-server.on('connection', (stream) => {
-  console.log('someone connected!');
-});
-```
-
-Returns a reference to the `EventEmitter`, so that calls can be chained.
-
-By default, event listeners are invoked in the order they are added. The
-`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.prependListener('foo', () => console.log('b'));
-myEE.emit('foo');
-// Prints:
-//   b
-//   a
-```
+Calls [`emitter.addListener()`][]. When overriding, override
+[`emitter.addListener()`][].
 
 ### emitter.once(eventName, listener)
 <!-- YAML
diff --git a/lib/events.js b/lib/events.js
index ebde85c6ddf990..e5a563f60a09af 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -283,7 +283,9 @@ EventEmitter.prototype.addListener = function addListener(type, listener) {
   return _addListener(this, type, listener, false);
 };
 
-EventEmitter.prototype.on = EventEmitter.prototype.addListener;
+EventEmitter.prototype.on = function (type, listener) {
+  this.addListener(type, listener);
+}
 
 EventEmitter.prototype.prependListener =
     function prependListener(type, listener) {
@@ -378,7 +380,9 @@ EventEmitter.prototype.removeListener =
       return this;
     };
 
-EventEmitter.prototype.off = EventEmitter.prototype.removeListener;
+EventEmitter.prototype.off = function (type, listener) {
+  this.removeListener(type, listener);
+}
 
 EventEmitter.prototype.removeAllListeners =
     function removeAllListeners(type) {
diff --git a/test/parallel/test-events-override.js b/test/parallel/test-events-override.js
new file mode 100644
index 00000000000000..fca84b6fc9ec8e
--- /dev/null
+++ b/test/parallel/test-events-override.js
@@ -0,0 +1,17 @@
+'use strict';
+
+const common = require('../common');
+const { once, EventEmitter: EE } = require('events');
+const { strictEqual, deepStrictEqual } = require('assert');
+
+{
+  const e = new EE();
+  e.addListener = common.mustCall();
+  e.on('test', () => {});
+}
+
+{
+  const e = new EE();
+  e.removeListener = common.mustCall();
+  e.off('test', () => {});
+}

From cae69fd9c2ced70e0940b7b46a3b13f80f8baf5e Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 9 Sep 2019 14:31:12 +0200
Subject: [PATCH 2/7] fixup: linting

---
 lib/events.js                         | 8 ++++----
 test/parallel/test-events-override.js | 3 +--
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/lib/events.js b/lib/events.js
index e5a563f60a09af..7d107270aa6fe2 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -283,9 +283,9 @@ EventEmitter.prototype.addListener = function addListener(type, listener) {
   return _addListener(this, type, listener, false);
 };
 
-EventEmitter.prototype.on = function (type, listener) {
+EventEmitter.prototype.on = function(type, listener) {
   this.addListener(type, listener);
-}
+};
 
 EventEmitter.prototype.prependListener =
     function prependListener(type, listener) {
@@ -380,9 +380,9 @@ EventEmitter.prototype.removeListener =
       return this;
     };
 
-EventEmitter.prototype.off = function (type, listener) {
+EventEmitter.prototype.off = function(type, listener) {
   this.removeListener(type, listener);
-}
+};
 
 EventEmitter.prototype.removeAllListeners =
     function removeAllListeners(type) {
diff --git a/test/parallel/test-events-override.js b/test/parallel/test-events-override.js
index fca84b6fc9ec8e..7f692698c7ef30 100644
--- a/test/parallel/test-events-override.js
+++ b/test/parallel/test-events-override.js
@@ -1,8 +1,7 @@
 'use strict';
 
 const common = require('../common');
-const { once, EventEmitter: EE } = require('events');
-const { strictEqual, deepStrictEqual } = require('assert');
+const { EventEmitter: EE } = require('events');
 
 {
   const e = new EE();

From a41b352ee05761e40ca0962dcefe30783f050f14 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 9 Sep 2019 14:32:52 +0200
Subject: [PATCH 3/7] fixup: docs

---
 doc/api/events.md | 62 +++++++++++++++++++++++------------------------
 lib/events.js     |  6 ++---
 2 files changed, 34 insertions(+), 34 deletions(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index 07f05aa5ed7c4f..f51509d0a48146 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -292,33 +292,8 @@ added: v0.1.26
 * `listener` {Function}
 * Returns: {EventEmitter}
 
-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`
-and `listener` will result in the `listener` being added, and called, multiple
-times.
-
-```js
-server.addListener('connection', (stream) => {
-  console.log('someone connected!');
-});
-```
-
-Returns a reference to the `EventEmitter`, so that calls can be chained.
-
-By default, event listeners are invoked in the order they are added. The
-`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.addListener('foo', () => console.log('a'));
-myEE.prependListener('foo', () => console.log('b'));
-myEE.emit('foo');
-// Prints:
-//   b
-//   a
-```
+This function is implemented by calling [`emitter.on()`][].
+When overriding, override [`emitter.on()`][].
 
 ### emitter.emit(eventName[, ...args])
 <!-- YAML
@@ -442,8 +417,8 @@ added: v10.0.0
 * `listener` {Function}
 * Returns: {EventEmitter}
 
-Calls [`emitter.removeListener()`][]. When overriding, override
-[`emitter.removeListener()`][].
+This function is implemented by calling [`emitter.removeListener()`][].
+When overriding, override [`emitter.removeListener()`][].
 
 ### emitter.on(eventName, listener)
 <!-- YAML
@@ -454,8 +429,33 @@ added: v0.1.101
 * `listener` {Function} The callback function
 * Returns: {EventEmitter}
 
-Calls [`emitter.addListener()`][]. When overriding, override
-[`emitter.addListener()`][].
+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`
+and `listener` will result in the `listener` being added, and called, multiple
+times.
+
+```js
+server.on('connection', (stream) => {
+  console.log('someone connected!');
+});
+```
+
+Returns a reference to the `EventEmitter`, so that calls can be chained.
+
+By default, event listeners are invoked in the order they are added. The
+`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.prependListener('foo', () => console.log('b'));
+myEE.emit('foo');
+// Prints:
+//   b
+//   a
+```
 
 ### emitter.once(eventName, listener)
 <!-- YAML
diff --git a/lib/events.js b/lib/events.js
index 7d107270aa6fe2..a7bda2564f4ef7 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -280,11 +280,11 @@ function _addListener(target, type, listener, prepend) {
 }
 
 EventEmitter.prototype.addListener = function addListener(type, listener) {
-  return _addListener(this, type, listener, false);
+  return this.on(type, listener);
 };
 
 EventEmitter.prototype.on = function(type, listener) {
-  this.addListener(type, listener);
+  return _addListener(this, type, listener, false);
 };
 
 EventEmitter.prototype.prependListener =
@@ -381,7 +381,7 @@ EventEmitter.prototype.removeListener =
     };
 
 EventEmitter.prototype.off = function(type, listener) {
-  this.removeListener(type, listener);
+  return this.removeListener(type, listener);
 };
 
 EventEmitter.prototype.removeAllListeners =

From ef8ec597d5e9927e1798b267f997ba7b478b4015 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 9 Sep 2019 21:48:51 +0200
Subject: [PATCH 4/7] fixup: make off/on primary

---
 doc/api/events.md       | 164 ++++++++++++++++++++--------------------
 lib/_http_server.js     |   2 -
 lib/_stream_readable.js |   5 +-
 lib/events.js           |   8 +-
 4 files changed, 88 insertions(+), 91 deletions(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index f51509d0a48146..7f1dfeab227a92 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -417,8 +417,86 @@ added: v10.0.0
 * `listener` {Function}
 * Returns: {EventEmitter}
 
-This function is implemented by calling [`emitter.removeListener()`][].
-When overriding, override [`emitter.removeListener()`][].
+Removes the specified `listener` from the listener array for the event named
+`eventName`.
+
+```js
+const callback = (stream) => {
+  console.log('someone connected!');
+};
+server.on('connection', callback);
+// ...
+server.off('connection', callback);
+```
+
+`off()` will remove, at most, one instance of a listener from the
+listener array. If any single listener has been added multiple times to the
+listener array for the specified `eventName`, then `off()` must be
+called multiple times to remove each instance.
+
+Once an event has been emitted, all listeners attached to it at the
+time of emitting will be called in order. This implies that any
+`off()` or `removeAllListeners()` calls *after* emitting and
+*before* the last listener finishes execution will not remove them from
+`emit()` in progress. Subsequent events will behave as expected.
+
+```js
+const myEmitter = new MyEmitter();
+
+const callbackA = () => {
+  console.log('A');
+  myEmitter.off('event', callbackB);
+};
+
+const callbackB = () => {
+  console.log('B');
+};
+
+myEmitter.on('event', callbackA);
+
+myEmitter.on('event', callbackB);
+
+// callbackA removes listener callbackB but it will still be called.
+// Internal listener array at time of emit [callbackA, callbackB]
+myEmitter.emit('event');
+// Prints:
+//   A
+//   B
+
+// callbackB is now removed.
+// Internal listener array [callbackA]
+myEmitter.emit('event');
+// Prints:
+//   A
+```
+
+Because listeners are managed using an internal array, calling this will
+change the position indices of any listener registered *after* the listener
+being removed. This will not impact the order in which listeners are called,
+but it means that any copies of the listener array as returned by
+the `emitter.listeners()` method will need to be recreated.
+
+When a single function has been added as a handler multiple times for a single
+event (as in the example below), `off()` will remove the most
+recently added instance. In the example the `once('ping')`
+listener is removed:
+
+```js
+const ee = new EventEmitter();
+
+function pong() {
+  console.log('pong');
+}
+
+ee.on('ping', pong);
+ee.once('ping', pong);
+ee.off('ping', pong);
+
+ee.emit('ping');
+ee.emit('ping');
+```
+
+Returns a reference to the `EventEmitter`, so that calls can be chained.
 
 ### emitter.on(eventName, listener)
 <!-- YAML
@@ -558,86 +636,8 @@ added: v0.1.26
 * `listener` {Function}
 * Returns: {EventEmitter}
 
-Removes the specified `listener` from the listener array for the event named
-`eventName`.
-
-```js
-const callback = (stream) => {
-  console.log('someone connected!');
-};
-server.on('connection', callback);
-// ...
-server.removeListener('connection', callback);
-```
-
-`removeListener()` will remove, at most, one instance of a listener from the
-listener array. If any single listener has been added multiple times to the
-listener array for the specified `eventName`, then `removeListener()` must be
-called multiple times to remove each instance.
-
-Once an event has been emitted, all listeners attached to it at the
-time of emitting will be called in order. This implies that any
-`removeListener()` or `removeAllListeners()` calls *after* emitting and
-*before* the last listener finishes execution will not remove them from
-`emit()` in progress. Subsequent events will behave as expected.
-
-```js
-const myEmitter = new MyEmitter();
-
-const callbackA = () => {
-  console.log('A');
-  myEmitter.removeListener('event', callbackB);
-};
-
-const callbackB = () => {
-  console.log('B');
-};
-
-myEmitter.on('event', callbackA);
-
-myEmitter.on('event', callbackB);
-
-// callbackA removes listener callbackB but it will still be called.
-// Internal listener array at time of emit [callbackA, callbackB]
-myEmitter.emit('event');
-// Prints:
-//   A
-//   B
-
-// callbackB is now removed.
-// Internal listener array [callbackA]
-myEmitter.emit('event');
-// Prints:
-//   A
-```
-
-Because listeners are managed using an internal array, calling this will
-change the position indices of any listener registered *after* the listener
-being removed. This will not impact the order in which listeners are called,
-but it means that any copies of the listener array as returned by
-the `emitter.listeners()` method will need to be recreated.
-
-When a single function has been added as a handler multiple times for a single
-event (as in the example below), `removeListener()` will remove the most
-recently added instance. In the example the `once('ping')`
-listener is removed:
-
-```js
-const ee = new EventEmitter();
-
-function pong() {
-  console.log('pong');
-}
-
-ee.on('ping', pong);
-ee.once('ping', pong);
-ee.removeListener('ping', pong);
-
-ee.emit('ping');
-ee.emit('ping');
-```
-
-Returns a reference to the `EventEmitter`, so that calls can be chained.
+This function is implemented by calling [`emitter.off()`][].
+When overriding, override [`emitter.off()`][].
 
 ### emitter.setMaxListeners(n)
 <!-- YAML
diff --git a/lib/_http_server.js b/lib/_http_server.js
index 6dc29c855e414c..61b7067e71f7b7 100644
--- a/lib/_http_server.js
+++ b/lib/_http_server.js
@@ -421,7 +421,6 @@ function connectionListenerInternal(server, socket) {
 
   // Overrides to unconsume on `data`, `readable` listeners
   socket.on = generateSocketListenerWrapper('on');
-  socket.addListener = generateSocketListenerWrapper('addListener');
   socket.prependListener = generateSocketListenerWrapper('prependListener');
 
   // We only consume the socket if it has never been consumed before.
@@ -792,7 +791,6 @@ function generateSocketListenerWrapper(originalFnName) {
     const res = net.Socket.prototype[originalFnName].call(this, ev, fn);
     if (!this.parser) {
       this.on = net.Socket.prototype.on;
-      this.addListener = net.Socket.prototype.addListener;
       this.prependListener = net.Socket.prototype.prependListener;
       return res;
     }
diff --git a/lib/_stream_readable.js b/lib/_stream_readable.js
index cfa36731e3d661..27afa774e4de0e 100644
--- a/lib/_stream_readable.js
+++ b/lib/_stream_readable.js
@@ -897,10 +897,9 @@ Readable.prototype.on = function(ev, fn) {
 
   return res;
 };
-Readable.prototype.addListener = Readable.prototype.on;
 
-Readable.prototype.removeListener = function(ev, fn) {
-  const res = Stream.prototype.removeListener.call(this, ev, fn);
+Readable.prototype.off = function(ev, fn) {
+  const res = Stream.prototype.off.call(this, ev, fn);
 
   if (ev === 'readable') {
     // We need to check if there is someone still listening to
diff --git a/lib/events.js b/lib/events.js
index a7bda2564f4ef7..6b37baa08e388c 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -326,8 +326,8 @@ EventEmitter.prototype.prependOnceListener =
     };
 
 // Emits a 'removeListener' event if and only if the listener was removed.
-EventEmitter.prototype.removeListener =
-    function removeListener(type, listener) {
+EventEmitter.prototype.off =
+    function off(type, listener) {
       let originalListener;
 
       checkListener(listener);
@@ -380,8 +380,8 @@ EventEmitter.prototype.removeListener =
       return this;
     };
 
-EventEmitter.prototype.off = function(type, listener) {
-  return this.removeListener(type, listener);
+EventEmitter.prototype.removeListener = function(type, listener) {
+  return this.off(type, listener);
 };
 
 EventEmitter.prototype.removeAllListeners =

From 6fb1004287ce280e8ee20e486739f2ffe3435374 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 9 Sep 2019 23:10:29 +0200
Subject: [PATCH 5/7] fixup: linting & test

---
 doc/api/events.md                                 | 3 ++-
 lib/events.js                                     | 4 ++--
 test/parallel/test-event-emitter-add-listeners.js | 3 ---
 test/parallel/test-event-emitter-method-names.js  | 5 ++---
 test/parallel/test-events-override.js             | 8 ++++----
 5 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index 7f1dfeab227a92..01cb885886698e 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -734,7 +734,8 @@ run();
 [`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
 [`domain`]: domain.html
 [`emitter.listenerCount()`]: #events_emitter_listenercount_eventname
-[`emitter.removeListener()`]: #events_emitter_removelistener_eventname_listener
+[`emitter.on()`]: #events_emitter_on_eventname_listener
+[`emitter.off()`]: #events_emitter_off_eventname_listener
 [`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n
 [`fs.ReadStream`]: fs.html#fs_class_fs_readstream
 [`net.Server`]: net.html#net_class_net_server
diff --git a/lib/events.js b/lib/events.js
index 6b37baa08e388c..ef3e4649799917 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -283,7 +283,7 @@ EventEmitter.prototype.addListener = function addListener(type, listener) {
   return this.on(type, listener);
 };
 
-EventEmitter.prototype.on = function(type, listener) {
+EventEmitter.prototype.on = function on(type, listener) {
   return _addListener(this, type, listener, false);
 };
 
@@ -380,7 +380,7 @@ EventEmitter.prototype.off =
       return this;
     };
 
-EventEmitter.prototype.removeListener = function(type, listener) {
+EventEmitter.prototype.removeListener = function removeListener(type, listener) {
   return this.off(type, listener);
 };
 
diff --git a/test/parallel/test-event-emitter-add-listeners.js b/test/parallel/test-event-emitter-add-listeners.js
index 7812de670ff5fb..58a3e48251eaf0 100644
--- a/test/parallel/test-event-emitter-add-listeners.js
+++ b/test/parallel/test-event-emitter-add-listeners.js
@@ -29,9 +29,6 @@ const EventEmitter = require('events');
   const events_new_listener_emitted = [];
   const listeners_new_listener_emitted = [];
 
-  // Sanity check
-  assert.strictEqual(ee.addListener, ee.on);
-
   ee.on('newListener', function(event, listener) {
     // Don't track newListener listeners.
     if (event === 'newListener')
diff --git a/test/parallel/test-event-emitter-method-names.js b/test/parallel/test-event-emitter-method-names.js
index 684024d0276261..35913b25839b17 100644
--- a/test/parallel/test-event-emitter-method-names.js
+++ b/test/parallel/test-event-emitter-method-names.js
@@ -26,10 +26,9 @@ const events = require('events');
 
 const E = events.EventEmitter.prototype;
 assert.strictEqual(E.constructor.name, 'EventEmitter');
-assert.strictEqual(E.on, E.addListener);  // Same method.
-assert.strictEqual(E.off, E.removeListener);  // Same method.
+
 Object.getOwnPropertyNames(E).forEach(function(name) {
-  if (name === 'constructor' || name === 'on' || name === 'off') return;
+  if (name === 'constructor') return;
   if (typeof E[name] !== 'function') return;
   assert.strictEqual(E[name].name, name);
 });
diff --git a/test/parallel/test-events-override.js b/test/parallel/test-events-override.js
index 7f692698c7ef30..377ed54f6ae5c9 100644
--- a/test/parallel/test-events-override.js
+++ b/test/parallel/test-events-override.js
@@ -5,12 +5,12 @@ const { EventEmitter: EE } = require('events');
 
 {
   const e = new EE();
-  e.addListener = common.mustCall();
-  e.on('test', () => {});
+  e.on = common.mustCall();
+  e.addListener('test', () => {});
 }
 
 {
   const e = new EE();
-  e.removeListener = common.mustCall();
-  e.off('test', () => {});
+  e.off = common.mustCall();
+  e.removeListener('test', () => {});
 }

From 1dabd38a26acf1986afee9da0a8a03267aa3313e Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Mon, 9 Sep 2019 23:46:42 +0200
Subject: [PATCH 6/7] fixup: linting

---
 lib/events.js | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/lib/events.js b/lib/events.js
index ef3e4649799917..621c352af4afaa 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -380,9 +380,10 @@ EventEmitter.prototype.off =
       return this;
     };
 
-EventEmitter.prototype.removeListener = function removeListener(type, listener) {
-  return this.off(type, listener);
-};
+EventEmitter.prototype.removeListener =
+    function removeListener(type, listener) {
+      return this.off(type, listener);
+    };
 
 EventEmitter.prototype.removeAllListeners =
     function removeAllListeners(type) {

From 7f4519018c1a5ed5a8ee825cdb8c0cb1f07e9c93 Mon Sep 17 00:00:00 2001
From: Robert Nagy <ronagy@icloud.com>
Date: Tue, 10 Sep 2019 17:43:25 +0200
Subject: [PATCH 7/7] fixup: on/removeListener

---
 doc/api/events.md                     | 167 +++++++++++++-------------
 lib/_stream_readable.js               |   4 +-
 lib/events.js                         |  10 +-
 test/parallel/test-events-override.js |   4 +-
 4 files changed, 92 insertions(+), 93 deletions(-)

diff --git a/doc/api/events.md b/doc/api/events.md
index 01cb885886698e..f51509d0a48146 100644
--- a/doc/api/events.md
+++ b/doc/api/events.md
@@ -417,86 +417,8 @@ added: v10.0.0
 * `listener` {Function}
 * Returns: {EventEmitter}
 
-Removes the specified `listener` from the listener array for the event named
-`eventName`.
-
-```js
-const callback = (stream) => {
-  console.log('someone connected!');
-};
-server.on('connection', callback);
-// ...
-server.off('connection', callback);
-```
-
-`off()` will remove, at most, one instance of a listener from the
-listener array. If any single listener has been added multiple times to the
-listener array for the specified `eventName`, then `off()` must be
-called multiple times to remove each instance.
-
-Once an event has been emitted, all listeners attached to it at the
-time of emitting will be called in order. This implies that any
-`off()` or `removeAllListeners()` calls *after* emitting and
-*before* the last listener finishes execution will not remove them from
-`emit()` in progress. Subsequent events will behave as expected.
-
-```js
-const myEmitter = new MyEmitter();
-
-const callbackA = () => {
-  console.log('A');
-  myEmitter.off('event', callbackB);
-};
-
-const callbackB = () => {
-  console.log('B');
-};
-
-myEmitter.on('event', callbackA);
-
-myEmitter.on('event', callbackB);
-
-// callbackA removes listener callbackB but it will still be called.
-// Internal listener array at time of emit [callbackA, callbackB]
-myEmitter.emit('event');
-// Prints:
-//   A
-//   B
-
-// callbackB is now removed.
-// Internal listener array [callbackA]
-myEmitter.emit('event');
-// Prints:
-//   A
-```
-
-Because listeners are managed using an internal array, calling this will
-change the position indices of any listener registered *after* the listener
-being removed. This will not impact the order in which listeners are called,
-but it means that any copies of the listener array as returned by
-the `emitter.listeners()` method will need to be recreated.
-
-When a single function has been added as a handler multiple times for a single
-event (as in the example below), `off()` will remove the most
-recently added instance. In the example the `once('ping')`
-listener is removed:
-
-```js
-const ee = new EventEmitter();
-
-function pong() {
-  console.log('pong');
-}
-
-ee.on('ping', pong);
-ee.once('ping', pong);
-ee.off('ping', pong);
-
-ee.emit('ping');
-ee.emit('ping');
-```
-
-Returns a reference to the `EventEmitter`, so that calls can be chained.
+This function is implemented by calling [`emitter.removeListener()`][].
+When overriding, override [`emitter.removeListener()`][].
 
 ### emitter.on(eventName, listener)
 <!-- YAML
@@ -636,8 +558,86 @@ added: v0.1.26
 * `listener` {Function}
 * Returns: {EventEmitter}
 
-This function is implemented by calling [`emitter.off()`][].
-When overriding, override [`emitter.off()`][].
+Removes the specified `listener` from the listener array for the event named
+`eventName`.
+
+```js
+const callback = (stream) => {
+  console.log('someone connected!');
+};
+server.on('connection', callback);
+// ...
+server.removeListener('connection', callback);
+```
+
+`removeListener()` will remove, at most, one instance of a listener from the
+listener array. If any single listener has been added multiple times to the
+listener array for the specified `eventName`, then `removeListener()` must be
+called multiple times to remove each instance.
+
+Once an event has been emitted, all listeners attached to it at the
+time of emitting will be called in order. This implies that any
+`removeListener()` or `removeAllListeners()` calls *after* emitting and
+*before* the last listener finishes execution will not remove them from
+`emit()` in progress. Subsequent events will behave as expected.
+
+```js
+const myEmitter = new MyEmitter();
+
+const callbackA = () => {
+  console.log('A');
+  myEmitter.removeListener('event', callbackB);
+};
+
+const callbackB = () => {
+  console.log('B');
+};
+
+myEmitter.on('event', callbackA);
+
+myEmitter.on('event', callbackB);
+
+// callbackA removes listener callbackB but it will still be called.
+// Internal listener array at time of emit [callbackA, callbackB]
+myEmitter.emit('event');
+// Prints:
+//   A
+//   B
+
+// callbackB is now removed.
+// Internal listener array [callbackA]
+myEmitter.emit('event');
+// Prints:
+//   A
+```
+
+Because listeners are managed using an internal array, calling this will
+change the position indices of any listener registered *after* the listener
+being removed. This will not impact the order in which listeners are called,
+but it means that any copies of the listener array as returned by
+the `emitter.listeners()` method will need to be recreated.
+
+When a single function has been added as a handler multiple times for a single
+event (as in the example below), `removeListener()` will remove the most
+recently added instance. In the example the `once('ping')`
+listener is removed:
+
+```js
+const ee = new EventEmitter();
+
+function pong() {
+  console.log('pong');
+}
+
+ee.on('ping', pong);
+ee.once('ping', pong);
+ee.removeListener('ping', pong);
+
+ee.emit('ping');
+ee.emit('ping');
+```
+
+Returns a reference to the `EventEmitter`, so that calls can be chained.
 
 ### emitter.setMaxListeners(n)
 <!-- YAML
@@ -734,8 +734,7 @@ run();
 [`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners
 [`domain`]: domain.html
 [`emitter.listenerCount()`]: #events_emitter_listenercount_eventname
-[`emitter.on()`]: #events_emitter_on_eventname_listener
-[`emitter.off()`]: #events_emitter_off_eventname_listener
+[`emitter.removeListener()`]: #events_emitter_removelistener_eventname_listener
 [`emitter.setMaxListeners(n)`]: #events_emitter_setmaxlisteners_n
 [`fs.ReadStream`]: fs.html#fs_class_fs_readstream
 [`net.Server`]: net.html#net_class_net_server
diff --git a/lib/_stream_readable.js b/lib/_stream_readable.js
index 27afa774e4de0e..a430a52ae29115 100644
--- a/lib/_stream_readable.js
+++ b/lib/_stream_readable.js
@@ -898,8 +898,8 @@ Readable.prototype.on = function(ev, fn) {
   return res;
 };
 
-Readable.prototype.off = function(ev, fn) {
-  const res = Stream.prototype.off.call(this, ev, fn);
+Readable.prototype.removeListener = function(ev, fn) {
+  const res = Stream.prototype.removeListener.call(this, ev, fn);
 
   if (ev === 'readable') {
     // We need to check if there is someone still listening to
diff --git a/lib/events.js b/lib/events.js
index 621c352af4afaa..ab4e10a006a9ee 100644
--- a/lib/events.js
+++ b/lib/events.js
@@ -326,8 +326,8 @@ EventEmitter.prototype.prependOnceListener =
     };
 
 // Emits a 'removeListener' event if and only if the listener was removed.
-EventEmitter.prototype.off =
-    function off(type, listener) {
+EventEmitter.prototype.removeListener =
+    function removeListener(type, listener) {
       let originalListener;
 
       checkListener(listener);
@@ -380,9 +380,9 @@ EventEmitter.prototype.off =
       return this;
     };
 
-EventEmitter.prototype.removeListener =
-    function removeListener(type, listener) {
-      return this.off(type, listener);
+EventEmitter.prototype.off =
+    function off(type, listener) {
+      return this.removeListener(type, listener);
     };
 
 EventEmitter.prototype.removeAllListeners =
diff --git a/test/parallel/test-events-override.js b/test/parallel/test-events-override.js
index 377ed54f6ae5c9..4192fde715c15a 100644
--- a/test/parallel/test-events-override.js
+++ b/test/parallel/test-events-override.js
@@ -11,6 +11,6 @@ const { EventEmitter: EE } = require('events');
 
 {
   const e = new EE();
-  e.off = common.mustCall();
-  e.removeListener('test', () => {});
+  e.removeListener = common.mustCall();
+  e.off('test', () => {});
 }