typings: add JSDoc Types to lib/querystring

PR-URL: #38185 Reviewed-By: Michaël Zasso <[email protected]>
nodejs · May 1, 2021 · 599434a · 599434a
1 parent 0544410
commit 599434a
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 11 deletions.
diff --git a/lib/internal/querystring.js b/lib/internal/querystring.js
@@ -30,6 +30,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
@@ -72,7 +72,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;
@@ -115,7 +120,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);
@@ -141,8 +150,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')
@@ -154,6 +168,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;
@@ -166,7 +184,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) : '');
@@ -182,12 +204,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 || '=';
@@ -232,6 +265,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 [str.charCodeAt(0)];
@@ -263,7 +300,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);
 
@@ -417,9 +464,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);