@devteks/downloader

Simple node.js file downloader

Features:

• Zero dependecies
• Pause / Resume
• Retry on fail
• Supports http / https
• Supports http redirects
• Supports pipes
• Custom native http request options
• Progress stats

Install

$ npm i @devteks/downloader

Usage

const { Downloader } = require('@devteks/downloader');
const downloader = new Downloader('https://proof.ovh.net/files/10Mb.dat', __dirname);
downloader.on('end', () => console.log('Download Completed'))
downloader.start();

CLI

This can be used as standalone CLI downloader

$ npm i -g @devteks/downloader

Usage: $ download [dir] url

dir: destination folder to download the file to (optional).

url: remote url to download.

$ download "./files" "https://proof.ovh.net/files/10Mb.dat"

Options

constructor(url, destination, options)

{
    //  Request body, can be any, string, object, etc.
    body: null,
    // Request Method Verb
    method: 'GET',
    // Custom HTTP Header ex: Authorization, User-Agent
    headers: {},
    // Custom filename when saved
    fileName: string | cb(fileName, filePath, contentType)|{name, ext},
    // { maxRetries: number, delay: number in ms } or false to disable (default)
    retry: false,
    // If the server does not return the "accept-ranges" header, can be force if it does support it
    forceResume: false,
    // remove the file when is stopped (default:true)
    removeOnStop: true,
    // remove the file when fail (default:true)
    removeOnFail: true,
    // interval time of the 'progress.throttled' event will be emitted
    progressThrottle: 1000,
    // Behavior when local file already exists
    override: boolean | { skip, skipSmaller },
    // Override the http request options  
    httpRequestOptions: {},
    // Override the https request options, ex: to add SSL Certs
    httpsRequestOptions: {},
}

for body you can provide any parameter accepted by http.request write function req.write(body) https://nodejs.org/api/http.html, when using this, you might need to add the content-length and content-type header in addition with the http method POST or PUT

Example:

const data = JSON.stringify({ todo: 'Buy the milk' });
const dl = new Downloader('http://server/api/data.json', __dirname, { 
  method: 'POST',
  body: data,
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
});

for fileName you can provide 3 types of parameter

• string: will use the full string as the filename including extension
• callback(fileName, filePath, contentType): must return a string, only sync function are supported ex: (fileName) => 'PREFIX_' + fileName;, contentType will be provided if available
• object: this object must contain a name attribute and an optional ext attribute, the ext attribute can be an string without dot(.) or a boolean where true use the name as full file name (same as just giving a string to the fileName parameter) or false (default) will only replace the name and keep the original extension, for example if the original name is somefile.dat and the option is {name: 'newname'} the output will be somename.dat

for override you can provide 2 types of parameter

• boolean: true to override existing local file, false to append '(number)' to new file name
• object: object with properties skip (boolean): whether to skip download if file exists, and skipSmaller (boolean): whether to skip download if file exists but is smaller. Both default to false, for the equivalent of override: true.

for httpRequestOptions the available options are detailed in here https://nodejs.org/api/http.html#http_http_request_options_callback

for httpsRequestOptions the available options are detailed in here https://nodejs.org/api/https.html#https_https_request_options_callback

Methods

| Name | Description | |------|-------------| | start | Starts the downloading. | | pause | Pauses the downloading. | | resume | Resumes the downloading if supported, if not it will start from the beginning. | | stop | Stops the downloading and remove the file. | | pipe | Attaches a stream. | | unpipe | Detaches previously attached stream. | | unpipeAll | Detaches all piped streams. | | updateOptions | Updates the options, can be use on pause/resume events. | | getTotalSize | Gets the total file size from the server. |

Properties

| Name | Description | |-----------------|-------------------------------------------------------------------------------| | get requestUrl | Gets the request url. | | get stats | Gets stats from the current download, these are the same stats sent via progress event. | | get downloadPath | Gets the full path where the file will be downloaded, available after the start phase. | | get isResumable | Gets if the download can be resumable, available after the start phase. |

Events

| Name | Description | |-------------------|------------------------------------------------------------------------------------| | start | Emites when the start() method is called. | | skip | Emites when the download is skipped because the file already exists cb(skipInfo). | | download | Emites when the download starts cb(downloadInfo). | | progress | Emites every time gets data from the server cb(stats). | | progressThrottled | The same as progress but emits every 1 second while is downloading cb(stats). | | retry | Emites when the download fails and retry is enabled cb(retryInfo). | | end | Emites when the downloading has finished cb(downloadEndInfo). | | error | Emites when there is any error cb(error). | | timeout | Emites when the underlying socket times out from inactivity. | | pause | Emites when the .pause method is called. | | resume | Emites when the .resume method is called cb(isResume). | | stop | Emites when the .stop method is called. | | renamed | Emites when '(number)' is appended to the end of file, this requires override:false opt, cb(renameInfo). | | stateChanged | Emites when the state changes cd(state). |

event skip skipInfo object

{
  totalSize:, // total file size got from the server.
  fileName:, // original file name
  filePath:, // original path name
  downloadedSize:, // the downloaded amount
}

event download downloadInfo object

{
  totalSize:, // total file size got from the server.
  fileName:, // assigned name
  filePath:, // download path
  isResumed:, // if the download is a resume,
  downloadedSize:, // the downloaded amount (only if is resumed otherwise always 0).
}

event progress or progressThrottled stats object

{
  name:, // file name
  total:, // total size that needs to be downloaded in bytes.
  downloaded:, // downloaded size in bytes
  progress:, // progress porcentage 0-100%, (will be set as 0 if total is null)
  speed: // download speed in bytes
}

event end downloadEndInfo object

{
  fileName:, 
  filePath:,
  totalSize:, // total file size got from the server.
  incomplete:, // true if the download endend but still incomplete
  onDiskSize, // total size of file on the disk
  downloadedSize:, // the total size downloaded
}

event renamed renameInfo object

{
  path:, // modified path name
  fileName:, // modified file name
  prevPath:, // original path name
  prevFileName:, // original file name
}

event error error object

{
  message:, // Error message
  status:, // Http status response if available
  body:, // Http body response if available
}

States

| Name | Value | |---------------|-------| | IDLE | 'IDLE' | | SKIPPED | 'SKIPPED' | | STARTED | 'STARTED' | | DOWNLOADING | 'DOWNLOADING' | | PAUSED | 'PAUSED' | | RESUMED | 'RESUMED' | | STOPPED | 'STOPPED' | | FINISHED | 'FINISHED' | | FAILED | 'FAILED' | | RETRY | 'RETRY' |

Test

$ npm test

License

Read License for more licensing information.

Contributing

Read here for more information.

TODO

• Better code testing