| 1 |
# node-miniget |
| 2 |
|
| 3 |
A small http(s) GET library with redirects, retries, reconnects, concatenating or streaming, and no dependencies. This keeps filesize small for potential browser use. |
| 4 |
|
| 5 |
 |
| 6 |
[](https://codecov.io/gh/fent/node-miniget) |
| 7 |
|
| 8 |
|
| 9 |
# Usage |
| 10 |
|
| 11 |
Concatenates a response |
| 12 |
|
| 13 |
```js |
| 14 |
const miniget = require('miniget'); |
| 15 |
|
| 16 |
miniget('http://mywebsite.com', (err, res, body) => { |
| 17 |
console.log('webpage contents: ', body); |
| 18 |
}); |
| 19 |
|
| 20 |
// with await |
| 21 |
let body = await miniget('http://yourwebsite.com').text(); |
| 22 |
``` |
| 23 |
|
| 24 |
Request can be streamed right away |
| 25 |
|
| 26 |
```js |
| 27 |
miniget('http://api.mywebsite.com/v1/messages.json') |
| 28 |
.pipe(someWritableStream()); |
| 29 |
``` |
| 30 |
|
| 31 |
|
| 32 |
# API |
| 33 |
|
| 34 |
### miniget(url, [options]) |
| 35 |
|
| 36 |
Makes a GET request. `url` can be a string or a `URL` object. `options` can have any properties from the [`http.request()` function](https://nodejs.org/api/http.html#http_http_request_options_callback), in addition to |
| 37 |
|
| 38 |
* `maxRedirects` - Default is `10`. |
| 39 |
* `maxRetries` - Number of times to retry the request if there is a 500 or connection error. Default is `2`. |
| 40 |
* `maxReconnects` - During a big download, if there is a disconnect, miniget can try to reconnect and continue the download where it left off. Default is `0`. |
| 41 |
* `backoff` - An object with `inc` and `max` used to calculate how long to wait to retry a request. Default is `{ inc: 100, max: 10000 }`. |
| 42 |
* `highWaterMark` - Amount of data to buffer when in stream mode. |
| 43 |
* `transform` - Use this to add additional features. Called with the object that `http.get()` or `https.get()` would be called with. Must return a transformed object. |
| 44 |
* `acceptEncoding` - An object with encoding name as the key, and the value as a function that returns a decoding stream. |
| 45 |
```js |
| 46 |
acceptEncoding: { gzip: () => require('zlip').createGunzip(stream) } |
| 47 |
``` |
| 48 |
Given encodings will be added to the `Accept-Encoding` header, and the response will be decoded if the server responds with encoded content. |
| 49 |
|
| 50 |
Defaults are held in `miniget.defaultOptions` and can be adjusted globally. |
| 51 |
|
| 52 |
Miniget returns a readable stream, errors will then be emitted on the stream. Returned stream has additional methods added, and can emit the following events. |
| 53 |
|
| 54 |
### Stream#destroy([error]) |
| 55 |
|
| 56 |
Destroys the request. |
| 57 |
|
| 58 |
### Stream#destroyed |
| 59 |
|
| 60 |
Set to `true` after `Stream#destroy()` has been called. |
| 61 |
|
| 62 |
### Stream#text() |
| 63 |
|
| 64 |
Returns a promise that resolves to the concatenated contents of the response. |
| 65 |
|
| 66 |
```js |
| 67 |
let body = await miniget('http://yourwebsite.com').text(); |
| 68 |
``` |
| 69 |
|
| 70 |
#### Event: redirect |
| 71 |
* `string` - URL redirected to. |
| 72 |
|
| 73 |
Emitted when the request was redirected with a redirection status code. |
| 74 |
|
| 75 |
#### Event: retry |
| 76 |
* `number` - Number of retry. |
| 77 |
* `Error` - Request or status code error. |
| 78 |
|
| 79 |
Emitted when the request fails, or the response has a status code >= 500. |
| 80 |
|
| 81 |
#### Event: reconnect |
| 82 |
* `number` - Number of reconnect. |
| 83 |
* `Error` - Request or response error. |
| 84 |
|
| 85 |
Emitted when the request or response fails after download has started. |
| 86 |
|
| 87 |
#### Event: request |
| 88 |
* [`http.ClientRequest`](https://nodejs.org/api/http.html#http_class_http_clientrequest) - Request. |
| 89 |
|
| 90 |
Emitted when a video request is made, including after any redirects, retries, and reconnects. |
| 91 |
|
| 92 |
#### Event: response |
| 93 |
* [`http.ServerResponse`](https://nodejs.org/api/http.html#http_class_http_serverresponse) - Response. |
| 94 |
|
| 95 |
Emitted when a video response has been found and has started downloading, including after any successful reconnects. |
| 96 |
|
| 97 |
#### Forwarded events |
| 98 |
|
| 99 |
Any events emitted from the [request](https://nodejs.org/api/http.html#http_class_http_clientrequest) or [response](https://nodejs.org/api/http.html#http_class_http_serverresponse) objects will be forwarded to the miniget stream. |
| 100 |
|
| 101 |
# Install |
| 102 |
|
| 103 |
npm install miniget |
| 104 |
|
| 105 |
|
| 106 |
# Tests |
| 107 |
Tests are written with [mocha](https://mochajs.org) |
| 108 |
|
| 109 |
```bash |
| 110 |
npm test |
| 111 |
``` |