From ef34910ee75734c5f8cc2b30460cabb9e39a10b3 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Sat, 17 Mar 2018 16:59:54 +0100 Subject: [PATCH 1/3] zlib: use `.bytesWritten` instead of `.bytesRead` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The introduction of `.bytesRead` to zlib streams was unfortunate, because other streams in Node.js core use the exact opposite naming of `.bytesRead` and `.bytesWritten`. While one could see how the original naming makes sense in a `Transform` stream context, we should try to work towards more consistent APIs in core for these things. This introduces `zlib.bytesWritten` and documentation-only deprecates `zlib.bytesRead`. (Luckily, the old property name hasn’t even been around for a whole year yet.) Refs: https://github.com/nodejs/node/issues/8874 Refs: https://github.com/nodejs/node/pull/13088 --- doc/api/deprecations.md | 11 +++++++++++ doc/api/zlib.md | 22 +++++++++++++++++++--- lib/zlib.js | 23 +++++++++++++++++++---- test/parallel/test-zlib-bytes-read.js | 16 +++++++++------- 4 files changed, 58 insertions(+), 14 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index bca2558336afd0..bd59de5afbda98 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -979,6 +979,16 @@ Type: Runtime This was an undocumented helper function not intended for use outside Node.js core and obsoleted by the removal of NPN (Next Protocol Negotiation) support. + +### DEP00XX: zlib.bytesRead + +Type: Documentation-only + +Deprecated alias for [`zlib.bytesWritten`][]. This original name was chosen +because it also made sense to interpret the value as the number of bytes +read by the engine, but is inconsistent with other streams in Node.js that +expose values under these names. + [`--pending-deprecation`]: cli.html#cli_pending_deprecation [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array @@ -1058,6 +1068,7 @@ core and obsoleted by the removal of NPN (Next Protocol Negotiation) support. [`util.types`]: util.html#util_util_types [`util`]: util.html [`worker.exitedAfterDisconnect`]: cluster.html#cluster_worker_exitedafterdisconnect +[`zlib.bytesWritten`]: zlib.html#zlib_zlib_byteswritten [alloc]: buffer.html#buffer_class_method_buffer_alloc_size_fill_encoding [alloc_unsafe_size]: buffer.html#buffer_class_method_buffer_allocunsafe_size [from_arraybuffer]: buffer.html#buffer_class_method_buffer_from_arraybuffer_byteoffset_length diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 41b7ed498706be..e0d09734189fa5 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -400,13 +400,28 @@ class of the compressor/decompressor classes. ### zlib.bytesRead + +> Stability: 0 - Deprecated: Use [`zlib.bytesWritten`][] instead. + +* {number} + +Deprecated alias for [`zlib.bytesWritten`][]. This original name was chosen +because it also made sense to interpret the value as the number of bytes +read by the engine, but is inconsistent with other streams in Node.js that +expose values under these names. + +### zlib.bytesWritten + * {number} -The `zlib.bytesRead` property specifies the number of bytes read by the engine -before the bytes are processed (compressed or decompressed, as appropriate for -the derived class). +The `zlib.bytesWritten` property specifies the number of bytes written to +the engine, before the bytes are processed (compressed or decompressed, +as appropriate for the derived class). ### zlib.close([callback])