zlib: add typings for better dx

PR-URL: nodejs#54699
Reviewed-By: LiviaMedeiros <livia@cirno.name>
Reviewed-By: James M Snell <jasnell@gmail.com>

lib/zlib.js

@@ -294,9 +294,12 @@ ObjectDefineProperty(ZlibBase.prototype, 'bytesRead', {
      'This feature will be removed in the future.', 'DEP0108'),
 });
 
+/**
+ * @this ZlibBase
+ * @returns {void}
+ */
 ZlibBase.prototype.reset = function() {
-  if (!this._handle)
-    assert(false, 'zlib binding closed');
+  assert(this._handle, 'zlib binding closed');
   return this._handle.reset();
 };
 
@@ -358,6 +361,10 @@ ZlibBase.prototype.flush = function(kind, callback) {
   }
 };
 
+/**
+ * @this import('stream').Transform
+ * @param {(err?: Error) => any} [callback]
+ */
 ZlibBase.prototype.close = function(callback) {
   if (callback) finished(this, callback);
   this.destroy();
@@ -398,7 +405,7 @@ function processChunkSync(self, chunk, flushFlag) {
   let availOutAfter;
   let availInAfter;
 
-  let buffers = null;
+  const buffers = [];
   let nread = 0;
   let inputRead = 0;
   const state = self._writeState;
@@ -435,10 +442,7 @@ function processChunkSync(self, chunk, flushFlag) {
     if (have > 0) {
       const out = buffer.slice(offset, offset + have);
       offset += have;
-      if (!buffers)
-        buffers = [out];
-      else
-        ArrayPrototypePush(buffers, out);
+      ArrayPrototypePush(buffers, out);
       nread += out.byteLength;
 
       if (nread > self._maxOutputLength) {
@@ -589,12 +593,13 @@ function processCallback() {
   this.cb();
 }
 
+/**
+ * @param {ZlibBase} engine
+ * @private
+ */
 function _close(engine) {
-  // Caller may invoke .close after a zlib error (which will null _handle).
-  if (!engine._handle)
-    return;
-
-  engine._handle.close();
+  // Caller may invoke .close after a zlib error (which will null _handle)
+  engine._handle?.close();
   engine._handle = null;
 }
 

typings/globals.d.ts

@@ -18,6 +18,7 @@ import { UtilBinding } from './internalBinding/util';
 import { WASIBinding } from './internalBinding/wasi';
 import { WorkerBinding } from './internalBinding/worker';
 import { ModulesBinding } from './internalBinding/modules';
+import { ZlibBinding } from './internalBinding/zlib';
 
 interface InternalBindingMap {
   async_wrap: AsyncWrapBinding;
@@ -40,6 +41,7 @@ interface InternalBindingMap {
   util: UtilBinding;
   wasi: WASIBinding;
   worker: WorkerBinding;
+  zlib: ZlibBinding;
 }
 
 type InternalBindingKeys = keyof InternalBindingMap;

typings/internalBinding/zlib.d.ts

@@ -0,0 +1,40 @@
+import { TypedArray } from '../globals';
+
+declare namespace InternalZlibBinding {
+  class ZlibBase {
+    // These attributes are not used by the C++ binding, but declared on JS side.
+    buffer?: TypedArray;
+    cb?: VoidFunction;
+    availOutBefore?: number;
+    availInBefore?: number;
+    inOff?: number;
+    flushFlag?: number;
+
+    reset(): void;
+    close(): void;
+    params(level: number, strategy: number): void;
+    write(flushFlag: number, input: TypedArray, inputOff: number, inputLen: number, out: TypedArray, outOff: number, outLen: number): void;
+    writeSync(flushFlag: number, input: TypedArray, inputOff: number, inputLen: number, out: TypedArray, outOff: number, outLen: number): void;
+  }
+
+  class Zlib extends ZlibBase{
+    constructor(mode: number)
+    init(windowBits: number, level: number, memLevel: number, strategy: number, writeState: Uint32Array, callback: VoidFunction, dictionary: Uint32Array): number;
+  }
+
+  class BrotliDecoder extends ZlibBase {
+    constructor(mode: number);
+    init(initParamsArray: Uint32Array, writeState: Uint32Array, callback: VoidFunction): boolean;
+  }
+
+  class BrotliEncoder extends ZlibBase {
+    constructor(mode: number);
+    init(initParamsArray: Uint32Array, writeState: Uint32Array, callback: VoidFunction): boolean;
+  }
+}
+
+export interface ZlibBinding {
+  BrotliDecoder: typeof InternalZlibBinding.BrotliDecoder;
+  BrotliEncoder: typeof InternalZlibBinding.BrotliEncoder;
+  Zlib: typeof InternalZlibBinding.Zlib;
+}