3.0.2 • Public • Published


Download a file, report progress, retry when appropriate, and verify integrity of downloaded bits.


npm install @particle/fetch-file --save
const fetchFile = require('@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

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


// 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

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

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




Package Sidebar


npm i @particle/fetch-file

Weekly Downloads






Unpacked Size

14.6 kB

Total Files


Last publish


  • jackson-particle
  • mike.grundy.npm
  • mohitparticle
  • eugene_particle
  • kmok23
  • karlag
  • cole-abbeduto-particle
  • pedrosordo
  • guohui
  • sbrust
  • particlebot
  • no1089
  • carlos.hdez
  • keeramis5
  • monkbroc
  • suda
  • mstan
  • sergeuz
  • debbie23
  • avtolstoy
  • mlauer
  • wraithan
  • azenk
  • bwalach
  • parteberseth
  • rickkas7
  • mrlambchop_particle
  • hugo.montero
  • mphsi