node-file-downloader

Simple file downloader module for Node.js

Installation

npm install @paradoxepoch/node-file-downloader

Usage

import fileDownload from '@paradoxepoch/node-file-downloader';
await fileDownload(url, filePath, options);

| Parameter | Type | Required | Description | | --------- | ------------------ | -------- | --------------------------------------------------------------- | | url | string | yes | The url of the file to download | | filePath | string or null | no | The local path to download the file to. Defaults to null. If falsy, downloads to a random filename in the system's temp directory | | options | string | no | The options object. Used to specify custom options to use for the download |

Examples

Simple download to local temp directory

The easiest way to use this module. Simply specify the url parameter and the file will be downloaded with a random name to your local temp directory on the system.

// Download to temp directory with random file name
const outputPath = await fileDownload('https://example.com/dummy.pdf');

// Log the path that the file was saved to
// eg: /tmp/tmp-21596-AnUG7d8LM75X-.pdf
// eg: C:\Users\User\AppData\Local\Temp
console.log(outputPath);

Simple download to specified path

Another easy way to use the module. Just specify the url and filePath parameters to download the file to a local path on the system.

// Download to specified path
const outputPath = await fileDownload('https://example.com/dummy.pdf', '/path/to/file.pdf');

// Log the path that the file was saved to
// /path/to/file.pdf
console.log(outputPath);

If the file extension is omitted from the filePath, the extension will automatically be appended to the output file based on the Content-Disposition header or extension in the download URL if present. This behaviour can be disabled by setting the appendMissingExtension option to false.

// Download to specified path (note the missing file extension in the filePath param)
const outputPath = await fileDownload('https://example.com/dummy.pdf', '/path/to/file');

// Log the path that the file was saved to
// /path/to/file.pdf
console.log(outputPath);

Download to local temp directory with custom options

Passing filePath as null (or any falsy value) will allow you to specify the options object while still downloading the file to the local temp directory with a random filename.

// Download to a specified directory with custom options
const filePath = await fileDownload('https://example.com/dummy.pdf', null, {
  successMsg: 'All good!',
  errorMsg: 'Something went wrong',
  httpMethod: 'post',
  showProgressBar: false
});

Options

| Property | Type | Default | Description | | ---------------------- | ----------------------- | ------------------------------ | --------------------------------------------------------------- | | startMsg | string | "Starting download..." | The message shown in the console when the download is starting. If falsy, no message is shown. | | downloadMsg | string | "Downloading, please wait..." | The message shown in the console when the file is downloading. If falsy, no message is shown. | | successMsg | string | "Download completed" | The message shown in the console when the download completes. If falsy, no message is shown. | | errorMsg | string | "Download failed" | The message shown in the console if the download fails. If falsy, no message is shown. | | appendMissingExtension | boolean | true | If true, appends file extension based on response headers or the URL if the save path does not include one. This option is ignored when filePath is falsy. | | httpMethod | string | "get" | The HTTP method to use for the download. Defaults to "get". | | appendHeaders | object | {} | An object containing custom headers to send with the request. | | showProgressBar | boolean | true | If true, displays a progress bar when the server includes a "Content-Length" header. | | throwOnFail | boolean | true | If true, throws an error if the download fails. If false, the error is only logged to the console as errorMsg and returns null. |