Debian Codegraph @

miniget/README.md

raw
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 ![Depfu](https://img.shields.io/depfu/fent/node-miniget)
6 [![codecov](https://codecov.io/gh/fent/node-miniget/branch/master/graph/badge.svg)](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 ```