stream: deprecate piping to emitters without prependListener

Author: karan-lrn

doc/api/deprecations.md

@@ -4548,6 +4548,22 @@ that have proven unresolveable. See [caveats of asynchronous customization hooks
 `module.registerHooks()` as soon as possible as `module.register()` will be
 removed in a future version of Node.js.
 
+### DEP0206: Piping to emitters without `prependListener`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62435
+    description: Runtime deprecation.
+-->
+
+Type: Runtime
+
+Piping to an EventEmitter that does not have a `prependListener` method is
+deprecated. The `prependListener` method has been available on EventEmitter
+since Node.js v6.0.0. The internal fallback code that manually manipulates
+the `_events` object will be removed in a future version.
+
 [DEP0142]: #dep0142-repl_builtinlibs
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3

lib/internal/streams/legacy.js

@@ -105,6 +105,8 @@ Stream.prototype.eventNames = function eventNames() {
   return names;
 };
 
+let emittedPrependListenerDeprecation = false;
+
 function prependListener(emitter, event, fn) {
   // Sadly this is not cacheable as some libraries bundle their own
   // event emitter implementation with them.
@@ -115,6 +117,15 @@ function prependListener(emitter, event, fn) {
   // 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 prependListener() method. The goal is to eventually remove this hack.
+  if (!emittedPrependListenerDeprecation) {
+    process.emitWarning(
+      'Piping to an EventEmitter without a prependListener method is deprecated. ' +
+      'The emitter should have a prependListener method.',
+      'DeprecationWarning',
+      'DEP0206',
+    );
+    emittedPrependListenerDeprecation = true;
+  }
   if (!emitter._events || !emitter._events[event])
     emitter.on(event, fn);
   else if (ArrayIsArray(emitter._events[event]))

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

@@ -37,6 +37,14 @@ function Readable() {
 Object.setPrototypeOf(Readable.prototype, stream.Stream.prototype);
 Object.setPrototypeOf(Readable, stream.Stream);
 
+// Expect deprecation warning when using fallback path
+common.expectWarning(
+  'DeprecationWarning',
+  'Piping to an EventEmitter without a prependListener method is deprecated. ' +
+  'The emitter should have a prependListener method.',
+  'DEP0206',
+);
+
 const w = new Writable();
 const r = new Readable();
 r.pipe(w);

test/parallel/test-stream-events-prepend.js

@@ -19,6 +19,14 @@ class Readable extends stream.Readable {
   }
 }
 
+// Expect deprecation warning when using fallback path
+common.expectWarning(
+  'DeprecationWarning',
+  'Piping to an EventEmitter without a prependListener method is deprecated. ' +
+  'The emitter should have a prependListener method.',
+  'DEP0206',
+);
+
 const w = new Writable();
 w.on('pipe', common.mustCall());