From 8acfe5c2a4076d3e84247d512ffcf7025f27cdd3 Mon Sep 17 00:00:00 2001
From: Simon Knott <info@simonknott.de>
Date: Sat, 10 Apr 2021 10:57:51 +0200
Subject: [PATCH] typings: add JSDoc Types to lib/querystring
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/38185
Reviewed-By: Michaël Zasso <targos@protonmail.com>
---
 lib/internal/querystring.js |  6 +++
 lib/querystring.js          | 74 +++++++++++++++++++++++++++++++------
 2 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/lib/internal/querystring.js b/lib/internal/querystring.js
index f1390420558ed2..68f52c90c27237 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..5bcfa13a6a5b13 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 {string} 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 | symbol | undefined | null} 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<string, string | number | boolean
+ * | ReadonlyArray<string | number | boolean> | 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,17 @@ 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?: number;
+ *   decodeURIComponent?(v: string): string;
+ *   }} [options]
+ * @returns {Record<string, string | string[]>}
+ */
 function parse(qs, sep, eq, options) {
   const obj = ObjectCreate(null);
 
@@ -421,9 +468,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);