events: make #once unwrapping optional

De-semver-major-ify by only unwrapping the listeners when a flag
has been passed.

Author: addaleax

doc/api/events.md

@@ -305,9 +305,15 @@ set by [`emitter.setMaxListeners(n)`][] or defaults to
 
 Returns the number of listeners listening to the event named `eventName`.
 
-### emitter.listeners(eventName)
+### emitter.listeners(eventName[, unwrapOnceListeners])
+
+* `eventName` {string|Symbol} The name of the event.
+* `unwrapOnceListeners` {Boolean} Flag indicating whether to unwrap listeners
+  attached via `.once()`.
 
 Returns a copy of the array of listeners for the event named `eventName`.
+If `unwrapOnceListeners` is set to `true`, listeners that were attached
+using `.once()` are returned as they were originally passed to `.once()`.
 
 ```js
 server.on('connection', (stream) => {

lib/events.js

@@ -413,7 +413,7 @@ EventEmitter.prototype.removeAllListeners =
       return this;
     };
 
-EventEmitter.prototype.listeners = function listeners(type) {
+EventEmitter.prototype.listeners = function listeners(type, unwrap) {
   var evlistener;
   var ret;
   var events = this._events;
@@ -422,12 +422,19 @@ EventEmitter.prototype.listeners = function listeners(type) {
     ret = [];
   else {
     evlistener = events[type];
-    if (!evlistener)
+    if (!evlistener) {
       ret = [];
-    else if (typeof evlistener === 'function')
-      ret = [evlistener.listener || evlistener];
-    else
-      ret = unwrapListeners(evlistener);
+    } else if (typeof evlistener === 'function') {
+      if (unwrap)
+        ret = [evlistener.listener || evlistener];
+      else
+        ret = [evlistener];
+    } else {
+      if (unwrap)
+        ret = unwrapListeners(evlistener);
+      else
+        ret = arrayClone(evlistener, evlistener.length);
+    }
   }
 
   return ret;

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

@@ -40,12 +40,27 @@ function listener2() {}
 {
   const ee = new events.EventEmitter();
   ee.once('foo', listener);
-  assert.deepStrictEqual(ee.listeners('foo'), [listener]);
+  assert.deepStrictEqual(ee.listeners('foo').map((fn) => fn.listener || fn),
+                         [listener]);
+}
+
+{
+  const ee = new events.EventEmitter();
+  ee.once('foo', listener);
+  assert.deepStrictEqual(ee.listeners('foo', true), [listener]);
 }
 
 {
   const ee = new events.EventEmitter();
   ee.on('foo', listener);
   ee.once('foo', listener2);
-  assert.deepStrictEqual(ee.listeners('foo'), [listener, listener2]);
+  assert.deepStrictEqual(ee.listeners('foo').map((fn) => fn.listener || fn),
+                         [listener, listener2]);
+}
+
+{
+  const ee = new events.EventEmitter();
+  ee.on('foo', listener);
+  ee.once('foo', listener2);
+  assert.deepStrictEqual(ee.listeners('foo', true), [listener, listener2]);
 }