stream: deprecate thenable support

aduh95 · targos · commit fa9b5c35d282 · 2021-11-26T15:36:37.000+01:00
Deprecate support for returning thenables in stream implementation methods. This is causing more confusion and issues than it's worth, and never was documented. Refs: #39535 Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com> PR-URL: #40860 Reviewed-By: Robert Nagy <ronagy@icloud.com> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -3017,6 +3017,34 @@ should have the same effect. The receiving end should also check the
 [`readable.readableEnded`][] value on [`http.IncomingMessage`][] to get whether
 it was an aborted or graceful destroy.
 
+### DEP0157: Thenable support in streams
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/40860
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+An undocumented feature of Node.js streams was to support thenables in
+implementation methods. This is now deprecated, use callbacks instead and avoid
+use of async function for streams implementation methods.
+
+This feature caused users to encounter unexpected problems where the user
+implements the function in callback style but uses e.g. an async method which
+would cause an error since mixing promise and callback semantics is not valid.
+
+```js
+const w = new Writable({
+  async final(callback) {
+    await someOp();
+    callback();
+  }
+});
+```
+
 [Legacy URL API]: url.md#legacy-url-api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
