zlib: add typings for better dx

PR-URL: #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;
+}