1 | # querystring.js
|
2 |
|
3 | [![npm version](https://img.shields.io/npm/v/x-query-string.svg)](https://www.npmjs.com/package/x-query-string)
|
4 | [![Build Status](https://travis-ci.org/john-yuan/querystring.js.svg?branch=master)](https://travis-ci.org/john-yuan/querystring.js)
|
5 | [![install size](https://packagephobia.now.sh/badge?p=x-query-string)](https://packagephobia.now.sh/result?p=x-query-string)
|
6 | [![npm downloads](https://img.shields.io/npm/dm/x-query-string.svg)](http://npm-stat.com/charts.html?package=x-query-string)
|
7 |
|
8 | A query string encoder and decoder. It works like the `$.param(...)` function of jQuery and has the ability to decode the query string. Can be used in Node.js and browser side.
|
9 |
|
10 | Features:
|
11 |
|
12 | * Encode & Decode array (nested)
|
13 | * Encode & Decode object (nested)
|
14 |
|
15 | API:
|
16 |
|
17 | * [QS.encode(object, [keepArrayIndex])](#qsencodeobject-keeparrayindex)
|
18 | * [QS.decode(string)](#qsdecodestring)
|
19 |
|
20 | ## Install
|
21 |
|
22 | If you are using npm, just install `x-query-string` as a dependency.
|
23 |
|
24 | ```bash
|
25 | npm i x-query-string
|
26 | ```
|
27 |
|
28 | Otherwise, you can import the bundle file with `script` tag directly.
|
29 |
|
30 | ```html
|
31 | <script scr="path/to/querystring.min.js"></script>
|
32 | ```
|
33 |
|
34 | The bundle file also can be used as an AMD module, which means it can be loaded by [require.js](https://requirejs.org/).
|
35 |
|
36 | ## Example
|
37 |
|
38 | ```js
|
39 | var QS = require('x-query-string');
|
40 |
|
41 | // a=1&b=2
|
42 | QS.encode({ a: 1, b: 2 });
|
43 |
|
44 | // a%5B%5D=1&a%5B%5D=2&a%5B%5D=3 (a[]=1&a[]=2&a[]=3)
|
45 | QS.encode({ a: [1, 2, 3] });
|
46 |
|
47 | // a%5Bb%5D%5Bc%5D=3 (a[b][c]=3)
|
48 | QS.encode({ a: { b: { c: 3 } } });
|
49 | ```
|
50 |
|
51 | For npm users, if you just want to include only the `encode` or `decode` function, you can do this as the following example.
|
52 |
|
53 | ```js
|
54 | // include encode only
|
55 | var encode = require('x-query-string/encode');
|
56 | ```
|
57 |
|
58 | Or
|
59 |
|
60 | ```js
|
61 | // include decode only
|
62 | var decode = require('x-query-string/decode');
|
63 | ```
|
64 |
|
65 | This is helpful when you want to reduce the bundle size of your application when you just use `encode` or `decode`.
|
66 |
|
67 | ## API
|
68 |
|
69 | ### QS.encode(object, [keepArrayIndex])
|
70 |
|
71 | * `object` {Object} The data to be encoded to query string
|
72 | * `boolean` {keepArrayIndex} Whether to always keep array index in the query string. If the array to be encoded just has one dimension, the index can be omitted. The default value is `false`.
|
73 | * Returns: {string} Returns the URI component encoded query string
|
74 |
|
75 | Encode the data to query string.
|
76 |
|
77 | ```js
|
78 | var QS = require('x-query-string');
|
79 |
|
80 | // a%5B%5D=1&a%5B%5D=2 (a[]=1&a[]=2)
|
81 | QS.encode({ a: [1, 2] });
|
82 |
|
83 | // a%5B0%5D=1&a%5B1%5D=2 (a[0]=1&a[1]=2)
|
84 | QS.encode({ a: [1, 2] }, true);
|
85 | ```
|
86 |
|
87 | ### QS.decode(string)
|
88 |
|
89 | * `string` {string} The query string to be decoded
|
90 | * Returns {Object} Returns the decoded data
|
91 |
|
92 | Decode the query string to a data object. The values in the result data object is `string` or `null`. This method will **NOT** try to parse `number` or `boolean` values.
|
93 |
|
94 | ```js
|
95 | var QS = require('x-query-string');
|
96 |
|
97 | QS.decode('a[]=1&a[]=2&b=false&c[d]=1&e=&f');
|
98 | // or (The query string below is url-encoded)
|
99 | QS.decode('a%5B%5D=1&a%5B%5D=2&b=false&c%5Bd%5D=1&e=&f');
|
100 | ```
|
101 |
|
102 | result:
|
103 |
|
104 | ```js
|
105 | {
|
106 | "a": [
|
107 | "1",
|
108 | "2"
|
109 | ],
|
110 | "b": "false",
|
111 | "c": {
|
112 | "d": "1"
|
113 | },
|
114 | "e": "",
|
115 | "f": null
|
116 | }
|
117 | ```
|
118 |
|
119 | ## License
|
120 |
|
121 | [MIT](./LICENSE "MIT")
|