@devteks/downloader v0.0.4

@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

Properties

Events

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

Test

$ npm test

License

Read License for more licensing information.

Contributing

Read here for more information.

TODO

• Better code testing