docs(node/querystring): Add docs #1531
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,7 +2,114 @@ | |
| import { Buffer } from "./buffer.ts"; | ||
| import { ERR_INVALID_URI } from "./_errors.ts"; | ||
|
|
||
| /******************** querystring.decode() ********************/ | ||
|
|
||
| /** | ||
| * Alias of querystring.parse() | ||
| * @deprecated | ||
|
||
| */ | ||
| export const decode = parse; | ||
|
|
||
| /******************** querystring.encode() ********************/ | ||
|
|
||
| /** | ||
| * Alias of querystring.stringify() | ||
| * @deprecated | ||
| */ | ||
| export const encode = stringify; | ||
|
|
||
| /******************** querystring.escape(str) ********************/ | ||
|
|
||
| const hexTable = new Array(256); | ||
| for (let i = 0; i < 256; ++i) { | ||
| hexTable[i] = "%" + ((i < 16 ? "0" : "") + i.toString(16)).toUpperCase(); | ||
| } | ||
|
|
||
| function encodeStr( | ||
| str: string, | ||
| noEscapeTable: Int8Array, | ||
| hexTable: string[], | ||
| ): string { | ||
| const len = str.length; | ||
| if (len === 0) return ""; | ||
|
|
||
| let out = ""; | ||
| let lastPos = 0; | ||
|
|
||
| for (let i = 0; i < len; i++) { | ||
| let c = str.charCodeAt(i); | ||
| // ASCII | ||
| if (c < 0x80) { | ||
| if (noEscapeTable[c] === 1) continue; | ||
| if (lastPos < i) out += str.slice(lastPos, i); | ||
| lastPos = i + 1; | ||
| out += hexTable[c]; | ||
| continue; | ||
| } | ||
|
|
||
| if (lastPos < i) out += str.slice(lastPos, i); | ||
|
|
||
| // Multi-byte characters ... | ||
| if (c < 0x800) { | ||
| lastPos = i + 1; | ||
| out += hexTable[0xc0 | (c >> 6)] + hexTable[0x80 | (c & 0x3f)]; | ||
| continue; | ||
| } | ||
| if (c < 0xd800 || c >= 0xe000) { | ||
| lastPos = i + 1; | ||
| out += hexTable[0xe0 | (c >> 12)] + hexTable[0x80 | ((c >> 6) & 0x3f)] + | ||
| hexTable[0x80 | (c & 0x3f)]; | ||
| continue; | ||
| } | ||
| // Surrogate pair | ||
| ++i; | ||
|
|
||
| // This branch should never happen because all URLSearchParams entries | ||
| // should already be converted to USVString. But, included for | ||
| // completion's sake anyway. | ||
| if (i >= len) throw new ERR_INVALID_URI(); | ||
|
|
||
| const c2 = str.charCodeAt(i) & 0x3ff; | ||
|
|
||
| lastPos = i + 1; | ||
| c = 0x10000 + (((c & 0x3ff) << 10) | c2); | ||
| out += hexTable[0xf0 | (c >> 18)] + | ||
| hexTable[0x80 | ((c >> 12) & 0x3f)] + | ||
| hexTable[0x80 | ((c >> 6) & 0x3f)] + | ||
| hexTable[0x80 | (c & 0x3f)]; | ||
| } | ||
| if (lastPos === 0) return str; | ||
| if (lastPos < len) return out + str.slice(lastPos); | ||
| return out; | ||
| } | ||
|
|
||
| /** | ||
| * replaces encodeURIComponent() | ||
| * @see https://www.ecma-international.org/ecma-262/5.1/#sec-15.1.3.4 | ||
| */ | ||
| function qsEscape(str: unknown): string { | ||
| if (typeof str !== "string") { | ||
| if (typeof str === "object") { | ||
| str = String(str); | ||
| } else { | ||
| str += ""; | ||
| } | ||
| } | ||
| return encodeStr(str as string, noEscape, hexTable); | ||
| } | ||
|
|
||
| /** | ||
| * Performs URL percent-encoding on the given `str` in a manner that is optimized for the specific requirements of URL query strings. | ||
| * Used by `querystring.stringify()` and is generally not expected to be used directly. | ||
| * It is exported primarily to allow application code to provide a replacement percent-encoding implementation if necessary by assigning `querystring.escape` to an alternative function. | ||
| * @deprecated | ||
| * @see Tested in `test-querystring-escape.js` | ||
| */ | ||
| export const escape = qsEscape; | ||
|
|
||
| /******************** querystring.parse(str[, sep[, eq[, options]]]) ********************/ | ||
|
|
||
| interface ParsedUrlQuery { | ||
| [key: string]: string | string[] | undefined; | ||
| } | ||
|
|
||
|
|
@@ -13,10 +120,25 @@ interface ParseOptions { | |
| maxKeys?: number; | ||
| } | ||
|
|
||
| // deno-fmt-ignore | ||
| const isHexTable = new Int8Array([ | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0 - 15 | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 16 - 31 | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 32 - 47 | ||
| 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, // 48 - 63 | ||
| 0, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 64 - 79 | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 80 - 95 | ||
| 0, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 96 - 111 | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 112 - 127 | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 128 ... | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, | ||
| 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // ... 256 | ||
| ]); | ||
|
|
||
| function charCodes(str: string): number[] { | ||
| const ret = new Array(str.length); | ||
|
|
@@ -56,32 +178,16 @@ function addKeyVal( | |
| } | ||
| } | ||
|
|
||
| /** | ||
| * Parses a URL query string into a collection of key and value pairs. | ||
| * @param str The URL query string to parse | ||
| * @param sep The substring used to delimit key and value pairs in the query string. Default: '&'. | ||
| * @param eq The substring used to delimit keys and values in the query string. Default: '='. | ||
| * @param options The parse options | ||
| * @param options.decodeURIComponent The function to use when decoding percent-encoded characters in the query string. Default: `querystring.unescape()`. | ||
| * @param options.maxKeys Specifies the maximum number of keys to parse. Specify `0` to remove key counting limitations. Default: `1000`. | ||
| * @deprecated | ||
| * @see Tested in test-querystring.js | ||
| */ | ||
| export function parse( | ||
| str: string, | ||
|
|
@@ -247,6 +353,8 @@ export function parse( | |
| return obj; | ||
| } | ||
|
|
||
| /******************** querystring.stringify(obj[, sep[, eq[, options]]]) ********************/ | ||
|
|
||
| interface StringifyOptions { | ||
| /** The function to use when converting URL-unsafe characters to percent-encoding in the query string. */ | ||
| encodeURIComponent: (string: string) => string; | ||
|
|
@@ -272,79 +380,6 @@ const noEscape = new Int8Array([ | |
| 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 0, // 112 - 127 | ||
| ]); | ||
|
|
||
| // deno-lint-ignore no-explicit-any | ||
| function stringifyPrimitive(v: any): string { | ||
| if (typeof v === "string") { | ||
|
|
@@ -395,6 +430,9 @@ function encodeStringified(v: any, encode: (string: string) => string): string { | |
| * @param sep The substring used to delimit key and value pairs in the query string. Default: '&'. | ||
| * @param eq The substring used to delimit keys and values in the query string. Default: '='. | ||
| * @param options The stringify options | ||
| * @param options.encodeURIComponent The function to use when converting URL-unsafe characters to percent-encoding in the query string. Default: `querystring.escape()`. | ||
| * @deprecated | ||
| * @see Tested in `test-querystring.js` | ||
| */ | ||
| export function stringify( | ||
| // deno-lint-ignore no-explicit-any | ||
|
|
@@ -444,6 +482,8 @@ export function stringify( | |
| return ""; | ||
| } | ||
|
|
||
| /******************** querystring.unescape(str) ********************/ | ||
|
|
||
| // deno-fmt-ignore | ||
| const unhexTable = new Int8Array([ | ||
| -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // 0 - 15 | ||
|
|
@@ -464,14 +504,6 @@ const unhexTable = new Int8Array([ | |
| -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, // ... 255 | ||
| ]); | ||
|
|
||
| /** | ||
| * A safe fast alternative to decodeURIComponent | ||
| */ | ||
|
|
@@ -517,17 +549,26 @@ export function unescapeBuffer(s: string, decodeSpaces = false): Buffer { | |
| return hasHex ? out.slice(0, outIndex) : out; | ||
| } | ||
|
|
||
| function qsUnescape(s: string): string { | ||
| try { | ||
| return decodeURIComponent(s); | ||
| } catch { | ||
| return unescapeBuffer(s).toString(); | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * Performs decoding of URL percent-encoded characters on the given `str`. | ||
| * Used by `querystring.parse()` and is generally not expected to be used directly. | ||
| * It is exported primarily to allow application code to provide a replacement decoding implementation if necessary by assigning `querystring.unescape` to an alternative function. | ||
| * @deprecated | ||
| * @see Tested in `test-querystring-escape.js` | ||
| */ | ||
| export const unescape = qsUnescape; | ||
|
|
||
| export default { | ||
| parse, | ||
| stringify, | ||
| decode, | ||
| encode, | ||
| unescape, | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -17,19 +17,6 @@ Deno.test({ | |
| }, | ||
| }); | ||
|
|
||
| Deno.test({ | ||
| name: "parse", | ||
| fn() { | ||
|
|
@@ -41,16 +28,3 @@ Deno.test({ | |
| }); | ||
| }, | ||
| }); | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm afraid this kind of comments are just confusing to other contributors because we don't have rule to group functions & variable by the position in the source code
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I reffered https://github.com/denoland/deno_std/blob/905408229b64a4b8b1b3886135fb7f1dae13417d/testing/fast_check_example.ts but this is just example so I deleted. 7d04d5f