From fa9b5c35d282ac61c26888ab71b6cdcd1c24d7aa Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 26 Nov 2021 09:58:24 +0100 Subject: [PATCH] stream: deprecate thenable support 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: https://github.com/nodejs/node/issues/39535 Co-authored-by: Antoine du Hamel PR-URL: https://github.com/nodejs/node/pull/40860 Reviewed-By: Robert Nagy Reviewed-By: James M Snell --- doc/api/deprecations.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index c8526f55c3214a..e5e6b1c1521caf 100644 --- 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 + + + +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