From dd248a662eaaf52f2f937254d594989a39c183a8 Mon Sep 17 00:00:00 2001 From: Simon Knott Date: Sat, 10 Apr 2021 10:57:51 +0200 Subject: [PATCH 1/8] lib/querystring: Add JSDoc Types --- lib/internal/querystring.js | 6 ++++ lib/querystring.js | 71 +++++++++++++++++++++++++++++++------ 2 files changed, 66 insertions(+), 11 deletions(-) diff --git a/lib/internal/querystring.js b/lib/internal/querystring.js index f1390420558ed2..23a8cadfd7aa4b 100644 --- a/lib/internal/querystring.js +++ b/lib/internal/querystring.js @@ -36,6 +36,12 @@ const isHexTable = new Int8Array([ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // ... 256 ]); +/** + * @param {string} str + * @param {Int8Array} noEscapeTable + * @param {string[]} hexTable + * @returns {string} + */ function encodeStr(str, noEscapeTable, hexTable) { const len = str.length; if (len === 0) diff --git a/lib/querystring.js b/lib/querystring.js index a6e780d6e9c71d..d80b641ed0937a 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -76,7 +76,12 @@ const unhexTable = new Int8Array([ -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // ... 255 ]); -// A safe fast alternative to decodeURIComponent +/** + * A safe fast alternative to decodeURIComponent + * @param {any} s + * @param {boolean} decodeSpaces + * @returns {string} + */ function unescapeBuffer(s, decodeSpaces) { const out = Buffer.allocUnsafe(s.length); let index = 0; @@ -119,7 +124,11 @@ function unescapeBuffer(s, decodeSpaces) { return hasHex ? out.slice(0, outIndex) : out; } - +/** + * @param {string} s + * @param {boolean} decodeSpaces + * @returns {string} + */ function qsUnescape(s, decodeSpaces) { try { return decodeURIComponent(s); @@ -145,8 +154,13 @@ const noEscape = new Int8Array([ 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 96 - 111 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 0, // 112 - 127 ]); -// QueryString.escape() replaces encodeURIComponent() -// https://www.ecma-international.org/ecma-262/5.1/#sec-15.1.3.4 + +/** + * QueryString.escape() replaces encodeURIComponent() + * @see https://www.ecma-international.org/ecma-262/5.1/#sec-15.1.3.4 + * @param {any} str + * @returns {string} + */ function qsEscape(str) { if (typeof str !== 'string') { if (typeof str === 'object') @@ -158,6 +172,10 @@ function qsEscape(str) { return encodeStr(str, noEscape, hexTable); } +/** + * @param {string | number | BigInt | boolean} v + * @returns {string} + */ function stringifyPrimitive(v) { if (typeof v === 'string') return v; @@ -170,7 +188,11 @@ function stringifyPrimitive(v) { return ''; } - +/** + * @param {string | number | BigInt | boolean} v + * @param {(v: string) => string} encode + * @returns + */ function encodeStringified(v, encode) { if (typeof v === 'string') return (v.length ? encode(v) : ''); @@ -186,12 +208,23 @@ function encodeStringified(v, encode) { return ''; } - +/** + * @param {string | number | boolean | null} v + * @param {(v: string) => string} encode + * @returns {string} + */ function encodeStringifiedCustom(v, encode) { return encode(stringifyPrimitive(v)); } - +/** + * + * @param {Record | ReadonlyArray | ReadonlyArray | null>} obj + * @param {string} [sep] + * @param {string} [eq] + * @param {{ encodeURIComponent?: (v: string) => string }} [options] + * @returns {string} + */ function stringify(obj, sep, eq, options) { sep = sep || '&'; eq = eq || '='; @@ -236,6 +269,10 @@ function stringify(obj, sep, eq, options) { return ''; } +/** + * @param {string} str + * @returns {number[]} + */ function charCodes(str) { if (str.length === 0) return []; if (str.length === 1) return [StringPrototypeCharCodeAt(str, 0)]; @@ -267,7 +304,14 @@ function addKeyVal(obj, key, value, keyEncoded, valEncoded, decode) { } } -// Parse a key/val string. +/** + * Parse a key/val string. + * @param {string} qs + * @param {string} [sep] + * @param {string} [eq] + * @param {{ maxKeys?: 1000; decodeURIComponent?(v: string): string; }} [options] + * @returns {Record} + */ function parse(qs, sep, eq, options) { const obj = ObjectCreate(null); @@ -421,9 +465,14 @@ function parse(qs, sep, eq, options) { } -// v8 does not optimize functions with try-catch blocks, so we isolate them here -// to minimize the damage (Note: no longer true as of V8 5.4 -- but still will -// not be inlined). +/** + * v8 does not optimize functions with try-catch blocks, so we isolate them here + * to minimize the damage (Note: no longer true as of V8 5.4 -- but still will + * not be inlined). + * @param {string} s + * @param {(v: string) => string} decoder + * @returns {string} + */ function decodeStr(s, decoder) { try { return decoder(s); From 52c342bd42605185ae77bec08684f22afd8a4c1a Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Sat, 10 Apr 2021 05:51:36 -0500 Subject: [PATCH 2/8] linter --- lib/internal/querystring.js | 6 +++--- lib/querystring.js | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/lib/internal/querystring.js b/lib/internal/querystring.js index 23a8cadfd7aa4b..68f52c90c27237 100644 --- a/lib/internal/querystring.js +++ b/lib/internal/querystring.js @@ -37,9 +37,9 @@ const isHexTable = new Int8Array([ ]); /** - * @param {string} str - * @param {Int8Array} noEscapeTable - * @param {string[]} hexTable + * @param {string} str + * @param {Int8Array} noEscapeTable + * @param {string[]} hexTable * @returns {string} */ function encodeStr(str, noEscapeTable, hexTable) { diff --git a/lib/querystring.js b/lib/querystring.js index d80b641ed0937a..7660eaecc50f8f 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -78,8 +78,8 @@ const unhexTable = new Int8Array([ ]); /** * A safe fast alternative to decodeURIComponent - * @param {any} s - * @param {boolean} decodeSpaces + * @param {any} s + * @param {boolean} decodeSpaces * @returns {string} */ function unescapeBuffer(s, decodeSpaces) { @@ -125,8 +125,8 @@ function unescapeBuffer(s, decodeSpaces) { } /** - * @param {string} s - * @param {boolean} decodeSpaces + * @param {string} s + * @param {boolean} decodeSpaces * @returns {string} */ function qsUnescape(s, decodeSpaces) { @@ -158,7 +158,7 @@ const noEscape = new Int8Array([ /** * QueryString.escape() replaces encodeURIComponent() * @see https://www.ecma-international.org/ecma-262/5.1/#sec-15.1.3.4 - * @param {any} str + * @param {any} str * @returns {string} */ function qsEscape(str) { @@ -173,7 +173,7 @@ function qsEscape(str) { } /** - * @param {string | number | BigInt | boolean} v + * @param {string | number | BigInt | boolean} v * @returns {string} */ function stringifyPrimitive(v) { @@ -189,7 +189,7 @@ function stringifyPrimitive(v) { } /** - * @param {string | number | BigInt | boolean} v + * @param {string | number | BigInt | boolean} v * @param {(v: string) => string} encode * @returns */ From 514ed2ad567a10316d72c83adfa36ba3a5a168c3 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Sat, 10 Apr 2021 20:12:13 -0500 Subject: [PATCH 3/8] linter Co-authored-by: Voltrex <62040526+VoltrexMaster@users.noreply.github.com> --- lib/querystring.js | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/lib/querystring.js b/lib/querystring.js index 7660eaecc50f8f..70962d892fbd14 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -190,8 +190,8 @@ function stringifyPrimitive(v) { /** * @param {string | number | BigInt | boolean} v - * @param {(v: string) => string} encode - * @returns + * @param {(v: string) => string} encode + * @returns */ function encodeStringified(v, encode) { if (typeof v === 'string') @@ -209,8 +209,8 @@ function encodeStringified(v, encode) { } /** - * @param {string | number | boolean | null} v - * @param {(v: string) => string} encode + * @param {string | number | boolean | null} v + * @param {(v: string) => string} encode * @returns {string} */ function encodeStringifiedCustom(v, encode) { @@ -218,11 +218,11 @@ function encodeStringifiedCustom(v, encode) { } /** - * - * @param {Record | ReadonlyArray | ReadonlyArray | null>} obj + * @param {Record | null>} obj * @param {string} [sep] - * @param {string} [eq] - * @param {{ encodeURIComponent?: (v: string) => string }} [options] + * @param {string} [eq] + * @param {{ encodeURIComponent?: (v: string) => string }} [options] * @returns {string} */ function stringify(obj, sep, eq, options) { @@ -270,7 +270,7 @@ function stringify(obj, sep, eq, options) { } /** - * @param {string} str + * @param {string} str * @returns {number[]} */ function charCodes(str) { From 4b4742a3f0a353b326f06691682cbaa9f3e60416 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Sat, 10 Apr 2021 20:13:13 -0500 Subject: [PATCH 4/8] use bigint primitive form not object wrapped form Co-authored-by: Voltrex <62040526+VoltrexMaster@users.noreply.github.com> --- lib/querystring.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/querystring.js b/lib/querystring.js index 70962d892fbd14..bde9a05795042d 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -173,7 +173,7 @@ function qsEscape(str) { } /** - * @param {string | number | BigInt | boolean} v + * @param {string | number | bigint | boolean} v * @returns {string} */ function stringifyPrimitive(v) { @@ -189,7 +189,7 @@ function stringifyPrimitive(v) { } /** - * @param {string | number | BigInt | boolean} v + * @param {string | number | bigint | boolean} v * @param {(v: string) => string} encode * @returns */ From c5d49fb55b05f31e43e89e51f448b088a3129672 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Sat, 10 Apr 2021 20:29:08 -0500 Subject: [PATCH 5/8] nits Co-authored-by: Voltrex <62040526+VoltrexMaster@users.noreply.github.com> --- lib/querystring.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/querystring.js b/lib/querystring.js index bde9a05795042d..2c13effaa3aa54 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -173,7 +173,7 @@ function qsEscape(str) { } /** - * @param {string | number | bigint | boolean} v + * @param {string | number | bigint | boolean | symbol | undefined | null} v * @returns {string} */ function stringifyPrimitive(v) { @@ -306,9 +306,9 @@ function addKeyVal(obj, key, value, keyEncoded, valEncoded, decode) { /** * Parse a key/val string. - * @param {string} qs - * @param {string} [sep] - * @param {string} [eq] + * @param {string} qs + * @param {string} sep + * @param {string} eq * @param {{ maxKeys?: 1000; decodeURIComponent?(v: string): string; }} [options] * @returns {Record} */ From d63d5f3be54d89869fd4b9701e16662283fffd2d Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Sat, 10 Apr 2021 20:51:26 -0500 Subject: [PATCH 6/8] lint Co-authored-by: Voltrex <62040526+VoltrexMaster@users.noreply.github.com> --- lib/querystring.js | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/lib/querystring.js b/lib/querystring.js index 2c13effaa3aa54..a726180b3ce84d 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -309,7 +309,10 @@ function addKeyVal(obj, key, value, keyEncoded, valEncoded, decode) { * @param {string} qs * @param {string} sep * @param {string} eq - * @param {{ maxKeys?: 1000; decodeURIComponent?(v: string): string; }} [options] + * @param {{ + * maxKeys?: number; + * decodeURIComponent?(v: string): string; + * }} [options] * @returns {Record} */ function parse(qs, sep, eq, options) { @@ -469,8 +472,8 @@ function parse(qs, sep, eq, options) { * v8 does not optimize functions with try-catch blocks, so we isolate them here * to minimize the damage (Note: no longer true as of V8 5.4 -- but still will * not be inlined). - * @param {string} s - * @param {(v: string) => string} decoder + * @param {string} s + * @param {(v: string) => string} decoder * @returns {string} */ function decodeStr(s, decoder) { From c5bbc9a1d6398eb8d52a6e1b3100c7bad2c85886 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Tue, 13 Apr 2021 08:38:15 -0500 Subject: [PATCH 7/8] style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michaël Zasso --- lib/querystring.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/querystring.js b/lib/querystring.js index a726180b3ce84d..8256c9cd7a7189 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -469,7 +469,7 @@ function parse(qs, sep, eq, options) { /** - * v8 does not optimize functions with try-catch blocks, so we isolate them here + * V8 does not optimize functions with try-catch blocks, so we isolate them here * to minimize the damage (Note: no longer true as of V8 5.4 -- but still will * not be inlined). * @param {string} s From a7bd3e497fd993b82983f6808aaa5c456e4669e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C3=ABl=20Zasso?= Date: Thu, 15 Apr 2021 16:52:07 +0200 Subject: [PATCH 8/8] Update lib/querystring.js Co-authored-by: Bradley Farias --- lib/querystring.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/querystring.js b/lib/querystring.js index 8256c9cd7a7189..5bcfa13a6a5b13 100644 --- a/lib/querystring.js +++ b/lib/querystring.js @@ -78,7 +78,7 @@ const unhexTable = new Int8Array([ ]); /** * A safe fast alternative to decodeURIComponent - * @param {any} s + * @param {string} s * @param {boolean} decodeSpaces * @returns {string} */