stream: deprecate thenable support

doc/api/deprecations.md

@@ -3019,6 +3019,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