1 | <p align="center" style="text-align: center"><img src="https://raw.githubusercontent.com/ethanent/phin/master/media/phin-textIncluded.png" width="250" alt="phin logo"/></p>
|
2 |
|
3 | ---
|
4 |
|
5 | > The ultra-lightweight Node.js HTTP client
|
6 |
|
7 | [Full documentation](https://ethanent.github.io/phin/) | [GitHub](https://github.com/ethanent/phin) | [NPM](https://www.npmjs.com/package/phin)
|
8 |
|
9 |
|
10 | ## Simple Usage
|
11 |
|
12 | ```javascript
|
13 | const p = require('phin')
|
14 |
|
15 | const res = await p('https://ethanent.me')
|
16 |
|
17 | console.log(res.body)
|
18 | ```
|
19 |
|
20 | Note that the above should be in an async context! phin also provides an unpromisified version of the library.
|
21 |
|
22 |
|
23 | ## Install
|
24 |
|
25 | ```
|
26 | npm install phin
|
27 | ```
|
28 |
|
29 |
|
30 | ## Why phin?
|
31 |
|
32 | phin is **trusted** by some really important projects. The hundreds of contributors at [Less](https://github.com/less/less.js), for example, depend on phin as part of their development process.
|
33 |
|
34 | Also, phin is super **lightweight**. Like **99.8% smaller than request** lightweight. To compare to other libraries, see [phin vs. the Competition](https://github.com/ethanent/phin/blob/master/README.md#phin-vs-the-competition).
|
35 |
|
36 | <img src="https://pbs.twimg.com/media/DSPF9TaUQAA0tIe.jpg:large" alt="phin became 33% lighter with release 2.7.0!"/>
|
37 |
|
38 |
|
39 | ## Quick Demos
|
40 |
|
41 | Simple POST:
|
42 |
|
43 | ```js
|
44 | await p({
|
45 | url: 'https://ethanent.me',
|
46 | method: 'POST',
|
47 | data: {
|
48 | hey: 'hi'
|
49 | }
|
50 | })
|
51 | ```
|
52 |
|
53 | ### Unpromisified Usage
|
54 |
|
55 | ```js
|
56 | const p = require('phin').unpromisified
|
57 |
|
58 | p('https://ethanent.me', (err, res) => {
|
59 | if (!err) console.log(res.body)
|
60 | })
|
61 | ```
|
62 |
|
63 | Simple parsing of JSON:
|
64 |
|
65 | ```js
|
66 | // (In async function in this case.)
|
67 |
|
68 | const res = await p({
|
69 | 'url': 'https://ethanent.me/name',
|
70 | 'parse': 'json'
|
71 | })
|
72 |
|
73 | console.log(res.body.first)
|
74 | ```
|
75 |
|
76 | ### Default Options
|
77 |
|
78 | ```js
|
79 | const ppostjson = p.defaults({
|
80 | 'method': 'POST',
|
81 | 'parse': 'json',
|
82 | 'timeout': 2000
|
83 | })
|
84 |
|
85 | // In async function...
|
86 |
|
87 | const res = await ppostjson('https://ethanent.me/somejson')
|
88 | // ^ An options object could also be used here to set other options.
|
89 |
|
90 | // Do things with res.body?
|
91 | ```
|
92 |
|
93 | ### Custom Core HTTP Options
|
94 |
|
95 | phin allows you to set [core HTTP options](https://nodejs.org/api/http.html#http_http_request_url_options_callback).
|
96 |
|
97 | ```js
|
98 | await p({
|
99 | 'url': 'https://ethanent.me/name',
|
100 | 'core': {
|
101 | 'agent': myAgent // Assuming you'd already created myAgent earlier.
|
102 | }
|
103 | })
|
104 | ```
|
105 |
|
106 |
|
107 | ## Full Documentation
|
108 |
|
109 | There's a lot more which can be done with the phin library.
|
110 |
|
111 | See [the phin documentation](https://ethanent.github.io/phin/).
|
112 |
|
113 |
|
114 | ## phin vs. the Competition
|
115 |
|
116 | phin is a very lightweight library, yet it contains all of the common HTTP client features included in competing libraries!
|
117 |
|
118 | Here's a size comparison table:
|
119 |
|
120 | Package | Size
|
121 | --- | ---
|
122 | request | [![request package size](https://packagephobia.now.sh/badge?p=request)](https://packagephobia.now.sh/result?p=request)
|
123 | superagent | [![superagent package size](https://packagephobia.now.sh/badge?p=superagent)](https://packagephobia.now.sh/result?p=superagent)
|
124 | isomorphic-fetch | [![isomorphic-fetch package size](https://packagephobia.now.sh/badge?p=isomorphic-fetch)](https://packagephobia.now.sh/result?p=isomorphic-fetch)
|
125 | axios | [![axios package size](https://packagephobia.now.sh/badge?p=axios)](https://packagephobia.now.sh/result?p=axios)
|
126 | got | [![got package size](https://packagephobia.now.sh/badge?p=got)](https://packagephobia.now.sh/result?p=got)
|
127 | r2 | [![r2 package size](https://packagephobia.now.sh/badge?p=r2)](https://packagephobia.now.sh/result?p=r2)
|
128 | node-fetch | [![node-fetch package size](https://packagephobia.now.sh/badge?p=node-fetch)](https://packagephobia.now.sh/result?p=node-fetch)
|
129 | snekfetch | [![snekfetch package size](https://packagephobia.now.sh/badge?p=snekfetch)](https://packagephobia.now.sh/result?p=snekfetch)
|
130 | phin | [![phin package size](https://packagephobia.now.sh/badge?p=phin)](https://packagephobia.now.sh/result?p=phin) |
\ | No newline at end of file |