1 | export interface ParseOptions {
|
2 | |
3 |
|
4 |
|
5 |
|
6 |
|
7 | readonly decode?: boolean;
|
8 |
|
9 | |
10 |
|
11 |
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
|
24 |
|
25 |
|
26 |
|
27 |
|
28 |
|
29 |
|
30 |
|
31 |
|
32 |
|
33 |
|
34 |
|
35 |
|
36 |
|
37 |
|
38 |
|
39 |
|
40 |
|
41 |
|
42 |
|
43 |
|
44 |
|
45 |
|
46 |
|
47 |
|
48 |
|
49 |
|
50 |
|
51 |
|
52 |
|
53 |
|
54 |
|
55 |
|
56 |
|
57 |
|
58 |
|
59 |
|
60 |
|
61 |
|
62 |
|
63 |
|
64 |
|
65 |
|
66 |
|
67 |
|
68 |
|
69 |
|
70 |
|
71 |
|
72 |
|
73 |
|
74 |
|
75 |
|
76 |
|
77 |
|
78 |
|
79 |
|
80 |
|
81 |
|
82 |
|
83 |
|
84 |
|
85 |
|
86 |
|
87 |
|
88 |
|
89 |
|
90 | readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none';
|
91 |
|
92 | |
93 |
|
94 |
|
95 |
|
96 |
|
97 | readonly arrayFormatSeparator?: string;
|
98 |
|
99 | |
100 |
|
101 |
|
102 |
|
103 |
|
104 |
|
105 |
|
106 |
|
107 |
|
108 |
|
109 |
|
110 |
|
111 |
|
112 |
|
113 |
|
114 |
|
115 |
|
116 |
|
117 |
|
118 |
|
119 |
|
120 |
|
121 |
|
122 |
|
123 |
|
124 |
|
125 |
|
126 | readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;
|
127 |
|
128 | /**
|
129 | Parse the value as a number type instead of string type if it's a number.
|
130 |
|
131 | @default false
|
132 |
|
133 | @example
|
134 | ```
|
135 | import queryString = require('query-string');
|
136 |
|
137 | queryString.parse('foo=1', {parseNumbers: true});
|
138 | //=> {foo: 1}
|
139 | ```
|
140 | */
|
141 | readonly parseNumbers?: boolean;
|
142 |
|
143 | /**
|
144 | Parse the value as a boolean type instead of string type if it's a boolean.
|
145 |
|
146 | @default false
|
147 |
|
148 | @example
|
149 | ```
|
150 | import queryString = require('query-string');
|
151 |
|
152 | queryString.parse('foo=true', {parseBooleans: true});
|
153 |
|
154 | ```
|
155 | */
|
156 | readonly parseBooleans?: boolean;
|
157 |
|
158 | /**
|
159 | Parse the fragment identifier from the URL and add it to result object.
|
160 |
|
161 | @default false
|
162 |
|
163 | @example
|
164 | ```
|
165 | import queryString = require('query-string');
|
166 |
|
167 | queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
|
168 |
|
169 | ```
|
170 | */
|
171 | readonly parseFragmentIdentifier?: boolean;
|
172 | }
|
173 |
|
174 | export interface ParsedQuery<T = string> {
|
175 | [key: string]: T | T[] | null;
|
176 | }
|
177 |
|
178 | /**
|
179 | Parse a query string into an object. Leading `?` or `#` are ignored, so you can pass `location.search` or `location.hash` directly.
|
180 |
|
181 | The returned object is created with [`Object.create(null)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create) and thus does not have a `prototype`.
|
182 |
|
183 | @param query - The query string to parse.
|
184 | */
|
185 | export function parse(query: string, options: {parseBooleans: true, parseNumbers: true} & ParseOptions): ParsedQuery<string | boolean | number>;
|
186 | export function parse(query: string, options: {parseBooleans: true} & ParseOptions): ParsedQuery<string | boolean>;
|
187 | export function parse(query: string, options: {parseNumbers: true} & ParseOptions): ParsedQuery<string | number>;
|
188 | export function parse(query: string, options?: ParseOptions): ParsedQuery;
|
189 |
|
190 | export interface ParsedUrl {
|
191 | readonly url: string;
|
192 | readonly query: ParsedQuery;
|
193 |
|
194 | /**
|
195 | The fragment identifier of the URL.
|
196 |
|
197 | Present when the `parseFragmentIdentifier` option is `true`.
|
198 | */
|
199 | readonly fragmentIdentifier?: string;
|
200 | }
|
201 |
|
202 | /**
|
203 | Extract the URL and the query string as an object.
|
204 |
|
205 | If the `parseFragmentIdentifier` option is `true`, the object will also contain a `fragmentIdentifier` property.
|
206 |
|
207 | @param url - The URL to parse.
|
208 |
|
209 | @example
|
210 | ```
|
211 | import queryString = require('query-string');
|
212 |
|
213 | queryString.parseUrl('https://foo.bar?foo=bar');
|
214 |
|
215 |
|
216 | queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
|
217 |
|
218 | ```
|
219 | */
|
220 | export function parseUrl(url: string, options?: ParseOptions): ParsedUrl;
|
221 |
|
222 | export interface StringifyOptions {
|
223 | /**
|
224 | Strictly encode URI components with [`strict-uri-encode`](https://github.com/kevva/strict-uri-encode). It uses [`encodeURIComponent`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to `false`. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option.
|
225 |
|
226 | @default true
|
227 | */
|
228 | readonly strict?: boolean;
|
229 |
|
230 | /**
|
231 | [URL encode](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) the keys and values.
|
232 |
|
233 | @default true
|
234 | */
|
235 | readonly encode?: boolean;
|
236 |
|
237 | /**
|
238 | @default 'none'
|
239 |
|
240 | - `bracket`: Serialize arrays using bracket representation:
|
241 |
|
242 | ```
|
243 | import queryString = require('query-string');
|
244 |
|
245 | queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
|
246 |
|
247 | ```
|
248 |
|
249 | - `index`: Serialize arrays using index representation:
|
250 |
|
251 | ```
|
252 | import queryString = require('query-string');
|
253 |
|
254 | queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
|
255 |
|
256 | ```
|
257 |
|
258 | - `comma`: Serialize arrays by separating elements with comma:
|
259 |
|
260 | ```
|
261 | import queryString = require('query-string');
|
262 |
|
263 | queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
|
264 |
|
265 |
|
266 | queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'});
|
267 |
|
268 |
|
269 |
|
270 | ```
|
271 |
|
272 | - `separator`: Serialize arrays by separating elements with character:
|
273 |
|
274 | ```
|
275 | import queryString = require('query-string');
|
276 |
|
277 | queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'});
|
278 |
|
279 | ```
|
280 |
|
281 | - `bracket-separator`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character:
|
282 |
|
283 | ```
|
284 | import queryString = require('query-string');
|
285 |
|
286 | queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
|
287 |
|
288 |
|
289 | queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
|
290 |
|
291 |
|
292 | queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
|
293 |
|
294 |
|
295 | queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
|
296 |
|
297 |
|
298 | queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
|
299 |
|
300 |
|
301 | queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true});
|
302 |
|
303 |
|
304 | queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
|
305 |
|
306 | ```
|
307 |
|
308 | - `colon-list-separator`: Serialize arrays with parameter names that are explicitly marked with `:list`:
|
309 |
|
310 | ```js
|
311 | import queryString = require('query-string');
|
312 |
|
313 | queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'});
|
314 |
|
315 | ```
|
316 |
|
317 | - `none`: Serialize arrays by using duplicate keys:
|
318 |
|
319 | ```
|
320 | import queryString = require('query-string');
|
321 |
|
322 | queryString.stringify({foo: [1, 2, 3]});
|
323 |
|
324 | ```
|
325 | */
|
326 | readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'bracket-separator' | 'colon-list-separator' | 'none';
|
327 |
|
328 | /**
|
329 | The character used to separate array elements when using `{arrayFormat: 'separator'}`.
|
330 |
|
331 | @default ,
|
332 | */
|
333 | readonly arrayFormatSeparator?: string;
|
334 |
|
335 | /**
|
336 | Supports both `Function` as a custom sorting function or `false` to disable sorting.
|
337 |
|
338 | If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order.
|
339 |
|
340 | @default true
|
341 |
|
342 | @example
|
343 | ```
|
344 | import queryString = require('query-string');
|
345 |
|
346 | const order = ['c', 'a', 'b'];
|
347 |
|
348 | queryString.stringify({a: 1, b: 2, c: 3}, {
|
349 | sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight)
|
350 | });
|
351 |
|
352 | ```
|
353 |
|
354 | @example
|
355 | ```
|
356 | import queryString = require('query-string');
|
357 |
|
358 | queryString.stringify({b: 1, c: 2, a: 3}, {sort: false});
|
359 |
|
360 | ```
|
361 | */
|
362 | readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;
|
363 |
|
364 | /**
|
365 | Skip keys with `null` as the value.
|
366 |
|
367 | Note that keys with `undefined` as the value are always skipped.
|
368 |
|
369 | @default false
|
370 |
|
371 | @example
|
372 | ```
|
373 | import queryString = require('query-string');
|
374 |
|
375 | queryString.stringify({a: 1, b: undefined, c: null, d: 4}, {
|
376 | skipNull: true
|
377 | });
|
378 |
|
379 |
|
380 | queryString.stringify({a: undefined, b: null}, {
|
381 | skipNull: true
|
382 | });
|
383 |
|
384 | ```
|
385 | */
|
386 | readonly skipNull?: boolean;
|
387 |
|
388 | /**
|
389 | Skip keys with an empty string as the value.
|
390 |
|
391 | @default false
|
392 |
|
393 | @example
|
394 | ```
|
395 | import queryString = require('query-string');
|
396 |
|
397 | queryString.stringify({a: 1, b: '', c: '', d: 4}, {
|
398 | skipEmptyString: true
|
399 | });
|
400 |
|
401 | ```
|
402 |
|
403 | @example
|
404 | ```
|
405 | import queryString = require('query-string');
|
406 |
|
407 | queryString.stringify({a: '', b: ''}, {
|
408 | skipEmptyString: true
|
409 | });
|
410 |
|
411 | ```
|
412 | */
|
413 | readonly skipEmptyString?: boolean;
|
414 | }
|
415 |
|
416 | export type Stringifiable = string | boolean | number | null | undefined;
|
417 |
|
418 | export type StringifiableRecord = Record<
|
419 | string,
|
420 | Stringifiable | readonly Stringifiable[]
|
421 | >;
|
422 |
|
423 | /**
|
424 | Stringify an object into a query string and sort the keys.
|
425 | */
|
426 | export function stringify(
|
427 | // TODO: Use the below instead when the following TS issues are fixed:
|
428 | // - https://github.com/microsoft/TypeScript/issues/15300
|
429 | // - https://github.com/microsoft/TypeScript/issues/42021
|
430 | // Context: https://github.com/sindresorhus/query-string/issues/298
|
431 | // object: StringifiableRecord,
|
432 | object: Record<string, any>,
|
433 | options?: StringifyOptions
|
434 | ): string;
|
435 |
|
436 | /**
|
437 | Extract a query string from a URL that can be passed into `.parse()`.
|
438 |
|
439 | Note: This behaviour can be changed with the `skipNull` option.
|
440 | */
|
441 | export function extract(url: string): string;
|
442 |
|
443 | export interface UrlObject {
|
444 | readonly url: string;
|
445 |
|
446 | /**
|
447 | Overrides queries in the `url` property.
|
448 | */
|
449 | readonly query?: StringifiableRecord;
|
450 |
|
451 | /**
|
452 | Overrides the fragment identifier in the `url` property.
|
453 | */
|
454 | readonly fragmentIdentifier?: string;
|
455 | }
|
456 |
|
457 | /**
|
458 | Stringify an object into a URL with a query string and sorting the keys. The inverse of [`.parseUrl()`](https://github.com/sindresorhus/query-string#parseurlstring-options)
|
459 |
|
460 | Query items in the `query` property overrides queries in the `url` property.
|
461 |
|
462 | The `fragmentIdentifier` property overrides the fragment identifier in the `url` property.
|
463 |
|
464 | @example
|
465 | ```
|
466 | queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}});
|
467 |
|
468 |
|
469 | queryString.stringifyUrl({url: 'https://foo.bar?foo=baz', query: {foo: 'bar'}});
|
470 |
|
471 |
|
472 | queryString.stringifyUrl({
|
473 | url: 'https://foo.bar',
|
474 | query: {
|
475 | top: 'foo'
|
476 | },
|
477 | fragmentIdentifier: 'bar'
|
478 | });
|
479 |
|
480 | ```
|
481 | */
|
482 | export function stringifyUrl(
|
483 | object: UrlObject,
|
484 | options?: StringifyOptions
|
485 | ): string;
|
486 |
|
487 | /**
|
488 | Pick query parameters from a URL.
|
489 |
|
490 | @param url - The URL containing the query parameters to pick.
|
491 | @param keys - The names of the query parameters to keep. All other query parameters will be removed from the URL.
|
492 | @param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`.
|
493 |
|
494 | @returns The URL with the picked query parameters.
|
495 |
|
496 | @example
|
497 | ```
|
498 | queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']);
|
499 |
|
500 |
|
501 | queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
|
502 |
|
503 | ```
|
504 | */
|
505 | export function pick(
|
506 | url: string,
|
507 | keys: readonly string[],
|
508 | options?: ParseOptions & StringifyOptions
|
509 | ): string
|
510 | export function pick(
|
511 | url: string,
|
512 | filter: (key: string, value: string | boolean | number) => boolean,
|
513 | options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions
|
514 | ): string
|
515 | export function pick(
|
516 | url: string,
|
517 | filter: (key: string, value: string | boolean) => boolean,
|
518 | options?: {parseBooleans: true} & ParseOptions & StringifyOptions
|
519 | ): string
|
520 | export function pick(
|
521 | url: string,
|
522 | filter: (key: string, value: string | number) => boolean,
|
523 | options?: {parseNumbers: true} & ParseOptions & StringifyOptions
|
524 | ): string
|
525 |
|
526 | /**
|
527 | Exclude query parameters from a URL. Like `.pick()` but reversed.
|
528 |
|
529 | @param url - The URL containing the query parameters to exclude.
|
530 | @param keys - The names of the query parameters to remove. All other query parameters will remain in the URL.
|
531 | @param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`.
|
532 |
|
533 | @returns The URL without the excluded the query parameters.
|
534 |
|
535 | @example
|
536 | ```
|
537 | queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']);
|
538 |
|
539 |
|
540 | queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
|
541 |
|
542 | ```
|
543 | */
|
544 | export function exclude(
|
545 | url: string,
|
546 | keys: readonly string[],
|
547 | options?: ParseOptions & StringifyOptions
|
548 | ): string
|
549 | export function exclude(
|
550 | url: string,
|
551 | filter: (key: string, value: string | boolean | number) => boolean,
|
552 | options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions
|
553 | ): string
|
554 | export function exclude(
|
555 | url: string,
|
556 | filter: (key: string, value: string | boolean) => boolean,
|
557 | options?: {parseBooleans: true} & ParseOptions & StringifyOptions
|
558 | ): string
|
559 | export function exclude(
|
560 | url: string,
|
561 | filter: (key: string, value: string | number) => boolean,
|
562 | options?: {parseNumbers: true} & ParseOptions & StringifyOptions
|
563 | ): string
|
564 |
|
\ | No newline at end of file |