106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
# requests
|
|
|
|
[![Made by unshift][made-by]](http://unshift.io)[![Version npm][version]](http://browsenpm.org/package/requests)[![Build Status][build]](https://travis-ci.org/unshiftio/requests)[![Dependencies][david]](https://david-dm.org/unshiftio/requests)[![Coverage Status][cover]](https://coveralls.io/r/unshiftio/requests?branch=master)[![IRC channel][irc]](http://webchat.freenode.net/?channels=unshift)
|
|
|
|
[made-by]: https://img.shields.io/badge/made%20by-unshift-00ffcc.svg?style=flat-square
|
|
[version]: https://img.shields.io/npm/v/requests.svg?style=flat-square
|
|
[build]: https://img.shields.io/travis/unshiftio/requests/master.svg?style=flat-square
|
|
[david]: https://img.shields.io/david/unshiftio/requests.svg?style=flat-square
|
|
[cover]: https://img.shields.io/coveralls/unshiftio/requests/master.svg?style=flat-square
|
|
[irc]: https://img.shields.io/badge/IRC-irc.freenode.net%23unshift-00a8ff.svg?style=flat-square
|
|
|
|
Requests is a small library that implements fully and true streaming XHR for
|
|
browsers that support these methods. It uses a variety of proprietary
|
|
`responseType` properties to force a streaming connection, even for binary data.
|
|
For browsers that don't support this we will simply fallback to a regular but
|
|
**async** XHR 1/2 request or ActiveXObject in even older deprecated browsers.
|
|
|
|
- Internet Explorer >= 10: `ms-stream`
|
|
- FireFox >= 9: `moz-chunked`
|
|
- FireFox < 20: `multipart`
|
|
|
|
This module comes with build-in protection against ActiveX blocking that is
|
|
frequently used in firewalls & virus scanners.
|
|
|
|
## Installation
|
|
|
|
The module is released in the public npm registry and can be installed using:
|
|
|
|
```
|
|
npm install --save requests
|
|
```
|
|
|
|
## Usage
|
|
|
|
The API is a mix between the Fetch API, mixed with EventEmitter API for the
|
|
event handling.
|
|
|
|
```js
|
|
'use strict';
|
|
|
|
var requests = require('requests');
|
|
```
|
|
|
|
Now that we've included the library we can start making requests. The exported
|
|
method accepts 2 arguments:
|
|
|
|
- **url** Required URL that you want to have requested.
|
|
- **options** Optional object with additional configuration options:
|
|
- **streaming** Should we use streaming API's to fetch the data, defaults to
|
|
`false`.
|
|
- **method** The HTTP method that should be used to get the contents, defaults
|
|
to `GET`.
|
|
- **mode** The request mode, defaults to `cors`
|
|
- **headers** Object with header name/value that we need to send to the server.
|
|
- **timeout** The timeout in ms before we should abort the request.
|
|
- **manual** Manually `open` the request, defaults to `false`.
|
|
|
|
```js
|
|
requests('https://google.com/foo/bar', { streaming })
|
|
.on('data', function (chunk) {
|
|
console.log(chunk)
|
|
})
|
|
.on('end', function (err) {
|
|
if (err) return console.log('connection closed due to errors', err);
|
|
|
|
console.log('end');
|
|
});
|
|
```
|
|
|
|
## Events
|
|
|
|
In the example above you can see the that we're listing to various of events.
|
|
The following events are emitted:
|
|
|
|
- `data` A new chunk of data has been received. It can be a small chunk but also
|
|
the full response depending on the environment it's loaded in.
|
|
- `destroy` The request instance has been fully destroyed.
|
|
- `error` An error occurred while requesting the given URL.
|
|
- `end` Done with requesting the URL. An error argument can be supplied if the
|
|
connection was closed due to an error.
|
|
- `before` Emitted before we send the actual request.
|
|
- `send` Emitted after we've succesfully started the sending of the data.
|
|
|
|
### requests#destroy
|
|
|
|
Destroy the running XHR request and release all the references that the
|
|
`requests` instance holds. It returns a boolean as indication of a successful
|
|
destruction.
|
|
|
|
```js
|
|
requests.destroy();
|
|
```
|
|
|
|
### Requests.requested
|
|
|
|
The total amount of requests that we've made in this library. It also serves as
|
|
unique id for each request that we store in `.active`.
|
|
|
|
### Requests.active
|
|
|
|
An object that contains all running and active requests. Namespaced under
|
|
`request.requested` id and the requests instance.
|
|
|
|
## License
|
|
|
|
MIT
|