Skip to content

Commit

Permalink
typings: add JSDoc Types to lib/querystring
Browse files Browse the repository at this point in the history
PR-URL: #38185
Reviewed-By: Michaël Zasso <targos@protonmail.com>
  • Loading branch information
Skn0tt authored and targos committed Apr 18, 2021
1 parent 14aed60 commit 8acfe5c
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 11 deletions.
6 changes: 6 additions & 0 deletions lib/internal/querystring.js
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
74 changes: 63 additions & 11 deletions lib/querystring.js
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand All @@ -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')
Expand All @@ -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;
Expand All @@ -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) : '');
Expand All @@ -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 || '=';
Expand Down Expand Up @@ -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)];
Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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);
Expand Down

0 comments on commit 8acfe5c

Please sign in to comment.