UNPKG

4.4 kBMarkdownView Raw
1[![npm][npm]][npm-url]
2[![deps][deps]][deps-url]
3[![size][size]][size-url]
4
5# @subiz/ajax@1.0.29
6* *exception-free*
7* simple
8* tiny (2K Gzipped)
9* zero dependencies
10* *immutable*
11
12fetch api wrapper
13
14# Work in progress
150. docs
161. add timeout options
17
18## Usage
19
20### Simple
21```
22const ajax = require('@subiz/ajax')
23
24// try to making GET https://httpstat.us/200
25
26let res = await ajax.get("https://httpstat.us/200")
27console.log(req.body, res.code, res.error) // "200, OK" 200 undefined
28
29```
30
31### Derived from old object
32```
33var req = ajax.setBaseUrl("https://httpstat.us")
34res = await req.post("200")
35// POST https://httpstat.us/200
36
37```
38## References
39### Request object
40Request objects represences HTTP request.
41
42Request object are immutable, which mean, you cannot change its current state or data. Immutiblity makes object behavious more predictable, reducing bug.
43
44The object's state is initialize once when creating the object. You can create request object by either using Ajax object or making a derived object from old one.
45
46Available methods:
47#### `addQuery(key, value)`
48create a new derived object by appending new (key, value) pair into old request query
49
50#### `removeQuery(key)`
51create a new derived object by removing a (key, value) pair from old request query
52
53#### `setQuery(query)`
54create a new derived object by replacing old query with new one.
55
56examples:
57```js
58req = req.setQuery({a:"xin chao", b: 6})
59```
60
61#### `beforeHook(promise)`
62create a new derived object by registering (appending) a before hook
63
64#### `clearHooks`
65create a new derived object by removing all before hooks and after hooks
66
67#### `afterHook(promise)`
68create a new derived object by registering (appending) a hook
69
70#### `setBaseUrl(url)`
71create a new derived object by changing old request base url. New derived request with relative url will be append to this base url.
72
73#### `setHeader(header)`
74create a new derived object by merging old header with new header
75
76#### `setMeta(key, value)`
77attach hidden metadata to request, those key-value will not be sent to the server, designed to keep state in hooks
78
79examples:
80```js
81req = req.setHeader({"x-real-ip": "193.155.45.3"})
82```
83#### `get(url, data, cb)`
84#### `post(url, data, cb)`
85#### `put(url, data, cb)`
86#### `del(url, data, cb)`
87#### `head(url, data, cb)`
88#### `patch(url, data, cb)`
89#### `setBaseUrl`
90#### `setMethod`
91#### `contentTypeJson`
92#### `contentTypeForm`
93#### `setContentType`
94#### `setParser`
95#### `send`
96#### `setMeta`
97
98### Ajax object (singleton)
99Ajax object is lets you create request object. Available requests:
100+ `get(url)`: // create new GET request to address
101+ `post(url)`: // create new POST request to address
102+ `put(url)`: // create new PUT request to address
103+ `del(url)`: // create new DELETE request to address
104+ `head(url)`: // create new HEAD request to address
105+ `patch(url)`: // create new PATCH request to address
106
107### Before hook
108*before hooks* let you modify the request right before sending it.
109You register a *before hook* by calling `beforeHook`. beforeHook function return a promise and take in a reference to the request object as parameter.
110
111for examples: to add query `?a=5` and `?b=6` right before sending the request
112```js
113let req = ajax.setBaseUrl("https://google.com")
114
115req = req.beforeHook(async param => {
116 param.request = param.request.addQuery('a', 5)
117}).beforeHook(async param => {
118 param.request = param.request.addQuery('b', 6)
119})
120
121await req.get() // https://google.com?a=5&b=6
122```
123
124before hook is called one by one in registered order, which hook registered first will be called
125first.
126
127### With after hook
128```
129const apireq = ajax
130 .setBaseUrl("https://appv4.subiz.com/4.0/")
131 .afterHook(param => {
132 if (param.code !== 500) return
133 var retry = param.request.meta.retry || 0
134 if (retry === 3) return
135 var req = param.request.setMeta('retry', retry + 1) // increase number of attempt
136 // continue retry
137 return req.get().then(out => {
138 var [code, body, err] = out
139 param.code = code
140 param.body = body
141 param.err = err
142 })
143 })
144})
145
146let [code, body, err] = await apireq.get("me")
147
148```
149
150[npm]: https://img.shields.io/npm/v/@subiz/ajax.svg
151[npm-url]: https://npmjs.com/package/@subiz/ajax
152[deps]: https://david-dm.org/@subiz/ajax.svg
153[deps-url]: https://david-dm.org/@subiz/ajax
154[size]: https://packagephobia.now.sh/badge?p=@subiz/ajax
155[size-url]: https://packagephobia.now.sh/result?p=@subiz/ajax