@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)> ⏏

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