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




    npm i @particle/fetch-file

    DownloadsWeekly Downloads






    Unpacked Size

    14.6 kB

    Total Files


    Last publish


    • amaury.particle
    • cole-abbeduto-particle
    • pedrosordo
    • rowan.hamilton
    • guohui
    • sbrust
    • busticated
    • particlebot
    • no1089
    • carlos.hdez
    • keeramis5
    • monkbroc
    • suda
    • mstan
    • sergeuz
    • debbie23
    • avtolstoy
    • mlauer
    • wraithan
    • toolboxbot
    • azenk
    • shewy
    • bwalach
    • parteberseth
    • rickkas7
    • mrlambchop_particle
    • hugo.montero
    • toddparticle
    • mphsi