3.0.2 • Published 3 years ago

@particle/fetch-file v3.0.2

Weekly downloads
56
License
UNLICENSED
Repository
-
Last release
3 years ago

@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


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

ParamTypeDefaultDescription
urlstringThe URL for the file you'd like to download
destinationstringPath where downloaded bits will be saved
optionsobject
options.signalobjectAbortSignal object as defined in https://dom.spec.whatwg.org/#interface-AbortSignal (optional)
options.headersobjectRequest headers as key-value map object (optional)
options.maxRetriesnumber3How many times to retry before giving up (optional)
options.onProgressonProgressFunction to call with progess info (optional)
options.intervalnumber100How often to report progress in milliseconds (optional)
options.algorithmstring"sha256"Algorith to use when verifying checksum - supports whatever node's crypto.createHash() method does (optional)
stateInternalState

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

NameTypeDescription
filenamestringFilename of downloaded file
hashstringChecksum for downloaded file

module.exports~Progress : Object

Progress data passed to onProgress callback

Kind: inner typedef of module.exports
Properties

NameTypeDescription
lengthnumbersize in bytes of your file
transferrednumberbytes processed
remainingnumberbytes remaining to be processed
percentagenumberpercentage of bytes transferred (0-100)

module.exports~onProgress : function

Kind: inner typedef of module.exports

ParamTypeDescription
progressProgressprogress info for file

NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in tests

3.0.2

3 years ago

3.0.1

3 years ago

3.0.0

3 years ago

2.0.6

3 years ago

2.0.5

3 years ago

2.0.3

4 years ago

2.0.4

4 years ago

2.0.2

4 years ago

2.0.1

5 years ago

2.0.0

5 years ago

1.0.6

5 years ago

1.0.5

5 years ago

1.0.4

5 years ago

1.0.3

5 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago