1 | # @36node/query-normalizr
|
2 |
|
3 | [![version][0]][1] [![downloads][2]][3]
|
4 |
|
5 | query-normalizr 的作用: 将 url 中的 query 规则化成方便 sdk 和 service 层调用的数据格式。
|
6 |
|
7 | ## Install
|
8 |
|
9 | ```bash
|
10 | yarn add @36node/query-normalizr
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | ```js
|
16 | import { queryNormalizr } from "@36node/query-normalizr";
|
17 |
|
18 | // koa app
|
19 | app.use(normalizr(queryNormalizr));
|
20 | ```
|
21 |
|
22 | ## API
|
23 |
|
24 | ### middleware
|
25 |
|
26 | ```js
|
27 | normalizr(options);
|
28 |
|
29 | // return koa middleware
|
30 | ```
|
31 |
|
32 | ### normalize
|
33 |
|
34 | ```js
|
35 | import { normalize } from "@36node/query-normalizr";
|
36 | import qs from "query-string";
|
37 |
|
38 | const queryStr =
|
39 | " _expand=department&_group=type&_limit=10&_offset=0&_populate=user&_select=name&_select=age&_sort=updatedAt&_sort=-createdAt&age_gt=10&age_lt=20&level_gte=10&level_lte=20&plate_like=沪A&plate_like=沪B&tag_ne=pretty&title_like=hello&type=test1&type=test2";
|
40 |
|
41 | normalize(qs.parse(queryStr));
|
42 |
|
43 | /*
|
44 | return {
|
45 | limit: 10,
|
46 | offset: 0,
|
47 | sort: ["updatedAt", "-createdAt"],
|
48 | populate: "user",
|
49 | select: ["name", "age"],
|
50 | group: "type",
|
51 | filter: {
|
52 | age: {
|
53 | $gt: "10",
|
54 | $lt: "20",
|
55 | },
|
56 | level: {
|
57 | $gte: "10",
|
58 | $lte: "20",
|
59 | },
|
60 | plate: {
|
61 | $regex: [/沪A/i, /沪B/i],
|
62 | },
|
63 | tag: {
|
64 | $ne: "pretty",
|
65 | },
|
66 | title: {
|
67 | $regex: /hello/i,
|
68 | },
|
69 | type: ["test1", "test2"]
|
70 | },
|
71 | _expand: "department",
|
72 | };
|
73 | */
|
74 | ```
|
75 |
|
76 | ### denormalize
|
77 |
|
78 | ```js
|
79 | import { denormalize } from "@36node/query-normalizr";
|
80 | import qs from "query-string";
|
81 |
|
82 | const queryObj = {
|
83 | limit: 10,
|
84 | offset: 0,
|
85 | sort: ["updatedAt", "-createdAt"],
|
86 | populate: "user",
|
87 | select: ["name", "age"],
|
88 | group: "type",
|
89 | filter: {
|
90 | age: {
|
91 | $gt: "10",
|
92 | $lt: "20",
|
93 | },
|
94 | level: {
|
95 | $gte: "10",
|
96 | $lte: "20",
|
97 | },
|
98 | plate: {
|
99 | $regex: [/沪A/i, /沪B/i],
|
100 | },
|
101 | tag: {
|
102 | $ne: "pretty",
|
103 | },
|
104 | title: {
|
105 | $regex: /hello/i,
|
106 | },
|
107 | type: ["test1", "test2"],
|
108 | },
|
109 | _expand: "department",
|
110 | };
|
111 |
|
112 | qs.stringfy(denormalize(queryObj));
|
113 |
|
114 | // return " _expand=department&_group=type&_limit=10&_offset=0&_populate=user&_select=name&_select=age&_sort=updatedAt&_sort=-createdAt&age_gt=10&age_lt=20&assignees=%2A&followers=none&level_gte=10&level_lte=20&plate_like=%E6%B2%AAA&plate_like=%E6%B2%AAB&q=hello&tag_ne=pretty&title_like=hello&type=test1&type=test2"
|
115 | ```
|
116 |
|
117 | ## What is query normalizr
|
118 |
|
119 | ![image](https://user-images.githubusercontent.com/4343458/53739979-0c2d6f00-3ece-11e9-9c32-9516ecea9c25.png)
|
120 |
|
121 | ### Query in route (QIR)
|
122 |
|
123 | #### Array
|
124 |
|
125 | we use standard url query format to pass array data.
|
126 |
|
127 | ```curl
|
128 | a=1&a=2
|
129 | ```
|
130 |
|
131 | #### Filter
|
132 |
|
133 | Use `.` to access deep properties
|
134 |
|
135 | ```curl
|
136 | GET /posts?title=json-server&author=typicode
|
137 | GET /posts?id=1&id=2
|
138 | GET /comments?author.name=typicode
|
139 | ```
|
140 |
|
141 | ### Paginate
|
142 |
|
143 | Use `_offset` and optionally `_limit` to paginate returned data. (an `X-Total-Count` header is included in the response)
|
144 |
|
145 | ```curl
|
146 | GET /posts?_offset=10
|
147 | GET /posts?_offset=7&_limit=20
|
148 | ```
|
149 |
|
150 | node 10 items are return by default
|
151 |
|
152 | #### Sort
|
153 |
|
154 | Add `_sort`
|
155 |
|
156 | ```curl
|
157 | # asc
|
158 | GET /posts?_sort=views
|
159 |
|
160 | # desc
|
161 | GET /posts/1/comments?_sort=-votes
|
162 | ```
|
163 |
|
164 | For multiple fields, use the following format:
|
165 |
|
166 | ```curl
|
167 | GET /posts/1/comments?_sort=-votes&_sort=likes
|
168 | ```
|
169 |
|
170 | \_prefixing a path with `-` will flag that sort is descending order.
|
171 | When a path does not have the `-` prefix, it is ascending order.
|
172 |
|
173 | #### Operators
|
174 |
|
175 | Add `_gt`, `_lt`, `_gte` or `_lte` for getting a range
|
176 |
|
177 | ```curl
|
178 | GET /posts?views_gte=10&views_lte=20
|
179 | ```
|
180 |
|
181 | Add `_ne` to exclude a value
|
182 |
|
183 | ```curl
|
184 | GET /posts?id_ne=1
|
185 | ```
|
186 |
|
187 | Add `_like` to filter (RegExp supported)
|
188 |
|
189 | `_like` support array
|
190 |
|
191 | ```curl
|
192 | GET /posts?title_like=server
|
193 | ```
|
194 |
|
195 | #### Select
|
196 |
|
197 | Specifies which document fields to include or exclude
|
198 |
|
199 | ```curl
|
200 | GET /posts?_select=title&_select=body
|
201 | GET /posts?_select=-comments&_select=-views
|
202 | ```
|
203 |
|
204 | _prefixing a path with `-` will flag that path as excluded.
|
205 | When a path does not have the `-` prefix, it is included_
|
206 | A projection must be either inclusive or exclusive.
|
207 | In other words, you must either list the fields to include (which excludes all others),
|
208 | or list the fields to exclude (which implies all other fields are included).
|
209 |
|
210 | ### Query in service (QIS)
|
211 |
|
212 | ```js
|
213 | {
|
214 | limit: 10,
|
215 | offset: 10,
|
216 | sort: "-createdBy", // if array should be: ["-createdBy", "views"]
|
217 | select: ["views", "body"], // if single should be: "views"
|
218 | populate: "author",
|
219 | filter: {
|
220 | age: {
|
221 | $lt: 10, // age_lt
|
222 | $gt: 5, // age_gt
|
223 | },
|
224 | tag: {
|
225 | $ne: "pretty", // tag_ne
|
226 | },
|
227 | name: "sherry",
|
228 | title: {
|
229 | $regex: /^hello .* world$/i, // like
|
230 | },
|
231 | }
|
232 | }
|
233 | ```
|
234 |
|
235 | ## Contributing
|
236 |
|
237 | 1. Fork it!
|
238 | 2. Create your feature branch: `git checkout -b my-new-feature`
|
239 | 3. Commit your changes: `git commit -am 'Add some feature'`
|
240 | 4. Push to the branch: `git push origin my-new-feature`
|
241 | 5. Submit a pull request :D
|
242 |
|
243 | ## Author
|
244 |
|
245 | **query-normalizr** © [36node](https://github.com/36node), Released under the [MIT](./LICENSE) License.
|
246 |
|
247 | Authored and maintained by 36node with help from contributors ([list](https://github.com/36node/query-normalizr/contributors)).
|
248 |
|
249 | > [github.com/zzswang](https://github.com/zzswang) · GitHub [@36node](https://github.com/36node) · Twitter [@y](https://twitter.com/y)
|
250 |
|
251 | [0]: https://img.shields.io/npm/v/@36node/query-normalizr.svg?style=flat
|
252 | [1]: https://npmjs.com/package/@36node/query-normalizr
|
253 | [2]: https://img.shields.io/npm/dm/@36node/query-normalizr.svg?style=flat
|
254 | [3]: https://npmjs.com/package/@36node/query-normalizr
|