From cd2230b9890d2ebccddcd9d1372e0a3f7bb89f54 Mon Sep 17 00:00:00 2001 From: Qingyu Deng Date: Tue, 13 Apr 2021 23:32:57 +0800 Subject: [PATCH 1/4] typings: add typing for internal/string_decoder --- lib/string_decoder.js | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/lib/string_decoder.js b/lib/string_decoder.js index 2891e0a1d1a43a..ec3493c134bc32 100644 --- a/lib/string_decoder.js +++ b/lib/string_decoder.js @@ -51,6 +51,11 @@ const kNativeDecoder = Symbol('kNativeDecoder'); // Do not cache `Buffer.isEncoding` when checking encoding names as some // modules monkey-patch it to support additional encodings +/** + * + * @param {string} enc + * @returns {"utf8" | "utf16le" | "hex" | "ascii" | "base64" | "latin1" | "base64url"} + */ function normalizeEncoding(enc) { const nenc = internalUtil.normalizeEncoding(enc); if (nenc === undefined) { @@ -68,12 +73,21 @@ for (let i = 0; i < encodings.length; ++i) // StringDecoder provides an interface for efficiently splitting a series of // buffers into a series of JS strings without breaking apart multi-byte // characters. +/** + * + * @param {string} encoding + */ function StringDecoder(encoding) { this.encoding = normalizeEncoding(encoding); this[kNativeDecoder] = Buffer.alloc(kSize); this[kNativeDecoder][kEncodingField] = encodingsMap[this.encoding]; } +/** + * + * @param {string | Buffer | TypedArray | DataView} buf + * @returns {string} + */ StringDecoder.prototype.write = function write(buf) { if (typeof buf === 'string') return buf; @@ -84,6 +98,11 @@ StringDecoder.prototype.write = function write(buf) { return decode(this[kNativeDecoder], buf); }; +/** + * + * @param {string | Buffer | TypedArray | DataView} buf + * @returns {string} + */ StringDecoder.prototype.end = function end(buf) { let ret = ''; if (buf !== undefined) @@ -94,6 +113,12 @@ StringDecoder.prototype.end = function end(buf) { }; /* Everything below this line is undocumented legacy stuff. */ +/** + * + * @param {string | Buffer | TypedArray | DataView} buf + * @param {number} offset + * @returns {string} + */ StringDecoder.prototype.text = function text(buf, offset) { this[kNativeDecoder][kMissingBytes] = 0; this[kNativeDecoder][kBufferedBytes] = 0; From b9ccd90946a947eca0a6fceb320d1b21969b137b Mon Sep 17 00:00:00 2001 From: Qingyu Deng Date: Wed, 14 Apr 2021 20:54:19 +0800 Subject: [PATCH 2/4] fixup: typings: add typing for internal/string_decoder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michaël Zasso --- lib/string_decoder.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/string_decoder.js b/lib/string_decoder.js index ec3493c134bc32..35c928842c132d 100644 --- a/lib/string_decoder.js +++ b/lib/string_decoder.js @@ -54,7 +54,8 @@ const kNativeDecoder = Symbol('kNativeDecoder'); /** * * @param {string} enc - * @returns {"utf8" | "utf16le" | "hex" | "ascii" | "base64" | "latin1" | "base64url"} + * @returns {"utf8" | "utf16le" | "hex" | "ascii" + * | "base64" | "latin1" | "base64url"} */ function normalizeEncoding(enc) { const nenc = internalUtil.normalizeEncoding(enc); From 4aee5ee4eecaf54c626b520c56b397ff26183e73 Mon Sep 17 00:00:00 2001 From: Qingyu Deng Date: Tue, 20 Apr 2021 22:48:55 +0800 Subject: [PATCH 3/4] fixup: add function description Co-authored-by: marsonya --- lib/string_decoder.js | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/lib/string_decoder.js b/lib/string_decoder.js index 35c928842c132d..b3a56cccebd662 100644 --- a/lib/string_decoder.js +++ b/lib/string_decoder.js @@ -52,10 +52,12 @@ const kNativeDecoder = Symbol('kNativeDecoder'); // Do not cache `Buffer.isEncoding` when checking encoding names as some // modules monkey-patch it to support additional encodings /** + * Normalize encoding notation * * @param {string} enc * @returns {"utf8" | "utf16le" | "hex" | "ascii" * | "base64" | "latin1" | "base64url"} + * @throws {TypeError} Throws an error when encoding is invalid */ function normalizeEncoding(enc) { const nenc = internalUtil.normalizeEncoding(enc); @@ -71,10 +73,10 @@ const encodingsMap = {}; for (let i = 0; i < encodings.length; ++i) encodingsMap[encodings[i]] = i; -// StringDecoder provides an interface for efficiently splitting a series of -// buffers into a series of JS strings without breaking apart multi-byte -// characters. /** + * StringDecoder provides an interface for efficiently splitting a series of + * buffers into a series of JS strings without breaking apart multi-byte + * characters. * * @param {string} encoding */ @@ -85,9 +87,12 @@ function StringDecoder(encoding) { } /** + * Returns a decoded string, omitting any incomplete multi-bytes + * characters at the end of the Buffer, or TypedArray, or DataView * * @param {string | Buffer | TypedArray | DataView} buf * @returns {string} + * @throws {TypeError} Throws when buf is not in one of supported types */ StringDecoder.prototype.write = function write(buf) { if (typeof buf === 'string') @@ -100,6 +105,9 @@ StringDecoder.prototype.write = function write(buf) { }; /** + * Returns any remaining input stored in the internal buffer as a string. + * After end() is called, the stringDecoder object can be reused for new + * input. * * @param {string | Buffer | TypedArray | DataView} buf * @returns {string} From 1d2dc412d67a2905e217eee72cd0143b4b32c37b Mon Sep 17 00:00:00 2001 From: Qingyu Deng Date: Wed, 21 Apr 2021 23:11:12 +0800 Subject: [PATCH 4/4] fixup: mark optional parameters Co-authored-by: Akhil Marsonya --- lib/string_decoder.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/string_decoder.js b/lib/string_decoder.js index b3a56cccebd662..7447bb3f4699b1 100644 --- a/lib/string_decoder.js +++ b/lib/string_decoder.js @@ -78,7 +78,7 @@ for (let i = 0; i < encodings.length; ++i) * buffers into a series of JS strings without breaking apart multi-byte * characters. * - * @param {string} encoding + * @param {string} [encoding=utf-8] */ function StringDecoder(encoding) { this.encoding = normalizeEncoding(encoding); @@ -109,7 +109,7 @@ StringDecoder.prototype.write = function write(buf) { * After end() is called, the stringDecoder object can be reused for new * input. * - * @param {string | Buffer | TypedArray | DataView} buf + * @param {string | Buffer | TypedArray | DataView} [buf] * @returns {string} */ StringDecoder.prototype.end = function end(buf) {