3.0.2 • Published 3 years ago
@particle/fetch-file v3.0.2
@particle/fetch-file
Download a file, report progress, retry when appropriate, and verify integrity of downloaded bits.
Installation
npm install @particle/fetch-file --save
const fetchFile = require('@particle/fetch-file');
API
@particle/fetch-file
- @particle/fetch-file
- module.exports(url, destination, [options], state) ⇒ Promise.<(DowloadedFile|Error)> ⏏
- ~DowloadedFile : Object
- ~Progress : Object
- ~onProgress : function
- module.exports(url, destination, [options], state) ⇒ Promise.<(DowloadedFile|Error)> ⏏
module.exports(url, destination, options, state) ⇒ Promise.<(DowloadedFile|Error)> ⏏
Tries really, really, really hard to download a file, verifying integrity of the downloaded bits and optionally reporting progress along the way. Also supports cancellation.
Kind: Exported function
Returns: Promise.<(DowloadedFile|Error)> - A promise for the downloaded file or
an error
Param | Type | Default | Description |
---|---|---|---|
url | string | The URL for the file you'd like to download | |
destination | string | Path where downloaded bits will be saved | |
options | object | ||
options.signal | object | AbortSignal object as defined in https://dom.spec.whatwg.org/#interface-AbortSignal (optional) | |
options.headers | object | Request headers as key-value map object (optional) | |
options.maxRetries | number | 3 | How many times to retry before giving up (optional) |
options.onProgress | onProgress | Function to call with progess info (optional) | |
options.interval | number | 100 | How often to report progress in milliseconds (optional) |
options.algorithm | string | "sha256" | Algorith to use when verifying checksum - supports whatever node's crypto.createHash() method does (optional) |
state | InternalState |
Example
// download a file
const result = await fetchFile(url, tmpFile.path);
// download a file and report progress
const onProgress = (progress) => console.log(progress);
const result = await fetchFile(url, tmpFile.path, { onProgress, interval: 250 });
// download a file but don't retry if the first attempt fails
const result = await fetchFile(url, tmpFile.path, { maxRetries: 0 });
// cancel downloading a file
const { AbortController } = fetchFile;
const controller = new AbortController();
try {
setTimeout(() => controller.abort(), 50);
await fetchFile(url, tmpFile.path, { signal });
} catch (error){
error.type; // 'aborted'
error.name; // 'AbortError'
error.message; // 'The user aborted a request.'
}
module.exports~DowloadedFile : Object
Info about the downloaded file
Kind: inner typedef of module.exports
Properties
Name | Type | Description |
---|---|---|
filename | string | Filename of downloaded file |
hash | string | Checksum for downloaded file |
module.exports~Progress : Object
Progress data passed to onProgress
callback
Kind: inner typedef of module.exports
Properties
Name | Type | Description |
---|---|---|
length | number | size in bytes of your file |
transferred | number | bytes processed |
remaining | number | bytes remaining to be processed |
percentage | number | percentage of bytes transferred (0-100) |
module.exports~onProgress : function
Kind: inner typedef of module.exports
Param | Type | Description |
---|---|---|
progress | Progress | progress info for file |
NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in tests