2015-01-26 01:02:34 -08:00
node-fetch
==========
[![npm version][npm-image]][npm-url]
[![build status][travis-image]][travis-url]
2015-01-27 09:00:53 -08:00
[![coverage status][coveralls-image]][coveralls-url]
2015-01-26 01:02:34 -08:00
2015-02-06 03:15:37 -08:00
A light-weight module that brings `window.fetch` to node.js & io.js
2015-01-26 01:02:34 -08:00
# Motivation
2015-01-26 09:46:32 -08:00
I really like the notion of Matt Andrews' [isomorphic-fetch ](https://github.com/matthew-andrews/isomorphic-fetch ): it bridges the API gap between client-side and server-side http requests, so developers have less to worry about.
2015-01-26 01:02:34 -08:00
2015-01-26 09:46:32 -08:00
Instead of implementing `XMLHttpRequest` in node to run browser-specific [fetch polyfill ](https://github.com/github/fetch ), why not go from node's `http` to `fetch` API directly? Node has native stream support, browserify build targets (browsers) don't, so underneath they are going to be vastly different anyway.
2015-01-26 05:28:23 -08:00
2015-02-06 03:15:37 -08:00
Hence `node-fetch` , minimal code for a `window.fetch` compatible API on node.js/io.js runtime.
2015-01-26 01:02:34 -08:00
# Features
2015-01-26 05:28:23 -08:00
- Stay consistent with `window.fetch` API.
- Make conscious trade-off when following [whatwg fetch spec ](https://fetch.spec.whatwg.org/ ) and [stream spec ](https://streams.spec.whatwg.org/ ) implementation details, document known difference.
- Use native promise, but allow substituting it with [insert your favorite promise library].
2015-01-27 10:02:27 -08:00
- Use native stream for body, on both request and response.
- Decode content encoding (gzip/deflate) properly, and convert string output (such as `res.text()` and `res.json()` ) to utf-8 automatically.
- Useful extensions such as timeout, redirect limit, response size limit.
2015-01-26 05:28:23 -08:00
2015-01-27 05:11:26 -08:00
# Difference from client-side fetch
2015-01-26 05:28:23 -08:00
2015-05-03 03:07:20 -07:00
- See [Known Differences ](https://github.com/bitinn/node-fetch/blob/master/LIMITS.md ) for details.
2015-01-27 05:11:26 -08:00
- If you happen to use a missing feature that `window.fetch` offers, feel free to open an issue.
- Pull requests are welcomed too!
2015-01-26 01:02:34 -08:00
# Install
`npm install node-fetch --save`
# Usage
2015-01-27 09:20:54 -08:00
```javascript
var fetch = require('node-fetch');
2015-03-19 08:38:27 -07:00
// If you are not on node v0.12, set a Promise library first, eg.
2015-01-27 20:17:12 -08:00
// fetch.Promise = require('bluebird');
2015-01-27 09:20:54 -08:00
// plain text or html
fetch('https://github.com/')
.then(function(res) {
return res.text();
}).then(function(body) {
console.log(body);
});
// json
fetch('https://api.github.com/users/github')
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
// meta
fetch('https://github.com/')
.then(function(res) {
2015-01-27 20:17:12 -08:00
console.log(res.ok);
2015-01-27 09:20:54 -08:00
console.log(res.status);
console.log(res.statusText);
console.log(res.headers.raw());
console.log(res.headers.get('content-type'));
});
// post
2015-01-27 09:34:43 -08:00
fetch('http://httpbin.org/post', { method: 'POST', body: 'a=1' })
2015-01-27 09:20:54 -08:00
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
2015-01-27 09:34:43 -08:00
// post with stream from resumer
2015-01-27 09:20:54 -08:00
var resumer = require('resumer');
2015-01-27 09:34:43 -08:00
var stream = resumer().queue('a=1').end();
fetch('http://httpbin.org/post', { method: 'POST', body: stream })
2015-01-27 09:20:54 -08:00
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
2015-07-22 00:40:52 -07:00
// post with form-data (detect multipart)
2015-01-27 09:20:54 -08:00
var FormData = require('form-data');
var form = new FormData();
form.append('a', 1);
2015-07-21 19:05:06 -07:00
fetch('http://httpbin.org/post', { method: 'POST', body: form })
2015-01-27 09:20:54 -08:00
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
2015-01-27 09:34:43 -08:00
2015-07-22 00:40:52 -07:00
// post with form-data (custom headers)
var FormData = require('form-data');
var form = new FormData();
form.append('a', 1);
fetch('http://httpbin.org/post', { method: 'POST', body: form, headers: form.getHeaders() })
.then(function(res) {
return res.json();
}).then(function(json) {
console.log(json);
});
2015-01-27 09:34:43 -08:00
// node 0.11+, yield with co
var co = require('co');
co(function *() {
2015-01-28 01:46:15 -08:00
var res = yield fetch('https://api.github.com/users/github');
var json = yield res.json();
2015-01-27 09:34:43 -08:00
console.log(res);
});
2015-01-27 09:20:54 -08:00
```
See [test cases ](https://github.com/bitinn/node-fetch/blob/master/test/test.js ) for more examples.
2015-01-26 01:02:34 -08:00
2015-01-27 10:02:27 -08:00
# API
## fetch(url, options)
Returns a `Promise`
### Url
Should be an absolute url, eg `http://example.com/`
### Options
default values are shown, note that only `method` , `headers` and `body` are allowed in `window.fetch` , others are node.js extensions.
```
{
method: 'GET'
, headers: {} // request header, format {a:1} or {b:[1,2,3]}
2015-03-19 09:22:23 -07:00
, follow: 20 // maximum redirect count, 0 to not follow redirect
2015-04-16 22:31:58 -07:00
, timeout: 0 // req/res timeout in ms, 0 to disable, timeout reset on redirect
2015-01-27 10:02:27 -08:00
, compress: true // support gzip/deflate content encoding, false to disable
, size: 0 // maximum response body size in bytes, 0 to disable
, body: empty // request body, can be a string or readable stream
, agent: null // custom http.Agent instance
}
```
2015-01-26 05:28:23 -08:00
# License
2015-01-26 01:02:34 -08:00
2015-01-26 05:28:23 -08:00
MIT
2015-01-26 01:02:34 -08:00
2015-01-26 05:28:23 -08:00
# Acknowledgement
2015-01-26 09:46:32 -08:00
Thanks to [github/fetch ](https://github.com/github/fetch ) for providing a solid implementation reference.
2015-01-26 01:02:34 -08:00
[npm-image]: https://img.shields.io/npm/v/node-fetch.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/node-fetch
[travis-image]: https://img.shields.io/travis/bitinn/node-fetch.svg?style=flat-square
[travis-url]: https://travis-ci.org/bitinn/node-fetch
2015-01-27 09:00:53 -08:00
[coveralls-image]: https://img.shields.io/coveralls/bitinn/node-fetch.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/bitinn/node-fetch