Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DownloaderHelper
✓ import { DownloaderHelper } from 'node-downloader-helper';
✗ const DownloaderHelper = require('node-downloader-helper').DownloaderHelper;
The primary class for managing downloads. While CommonJS `require` is supported, ESM `import` is recommended in modern Node.js projects, especially with TypeScript.
DownloaderHelper (CommonJS)
✓ const { DownloaderHelper } = require('node-downloader-helper');
CommonJS syntax shown in older examples. Ensure this is used if your project is not ESM-enabled or configured for TypeScript.
DownloadOptions (Type)
✓ import type { DownloadOptions } from 'node-downloader-helper';
✗ import { DownloadOptions } from 'node-downloader-helper';
When importing types in TypeScript, it's best practice to use `import type` to explicitly indicate a type-only import, which gets stripped during compilation.
This quickstart demonstrates how to initialize `DownloaderHelper`, configure basic options like retries and a custom filename, and set up event listeners for monitoring download progress, completion, and errors. It also ensures the download directory exists before starting.
import { DownloaderHelper } from 'node-downloader-helper';
import path from 'path';
import fs from 'fs';
const downloadUrl = 'https://proof.ovh.net/files/1Gb.dat'; // Example URL for a large file
const destinationFolder = path.join(__dirname, 'downloads');
// Ensure the destination folder exists
if (!fs.existsSync(destinationFolder)) {
fs.mkdirSync(destinationFolder, { recursive: true });
}
const dl = new DownloaderHelper(downloadUrl, destinationFolder, {
fileName: 'test-file.dat',
retry: { maxRetries: 3, delay: 1000 }, // Retry 3 times with 1-second delay
resumeOnIncomplete: true,
maxRedirects: 5
});
dl.on('start', () => console.log(`Starting download for ${downloadUrl} to ${destinationFolder}`));
dl.on('progress', (stats) => {
const progress = stats.progress.toFixed(2);
const speed = (stats.speed / 1024 / 1024).toFixed(2); // MB/s
console.log(`Progress: ${progress}% - Speed: ${speed} MB/s - Downloaded: ${(stats.downloaded / 1024 / 1024).toFixed(2)} MB`);
});
dl.on('end', () => console.log('Download Completed successfully!'));
dl.on('error', (err) => console.error('Download Failed:', err.message));
dl.on('timeout', () => console.error('Download Timed out!'));
dl.on('skip', (info) => console.log(`Download skipped: ${info.message}`));
dl.start().catch(err => {
console.error('Failed to initiate download:', err.message);
});
Debug
Known issues
gotchaIt is highly recommended to use both `.on('error')` and `.start().catch` for comprehensive error handling. If `on('error')` is not defined, an `unhandled error event` will be thrown by EventEmitter, potentially crashing your application.fixAlways define an `.on('error')` listener on the `DownloaderHelper` instance and wrap the `.start()` call in a `.catch()` block. affects: >=2.0.0
breakingVersions prior to `2.1.8` had a critical bug where the file stream was not properly closed after a download retry, leading to memory leaks and potential file corruption.fixUpgrade to `node-downloader-helper@2.1.8` or newer to resolve this memory leak. If upgrading is not possible, ensure robust error handling and manual stream management.
affects: <2.1.8
gotchaUsing `resumeOnIncomplete: true` in conjunction with piping the download stream (e.g., for compression or encryption) can lead to corrupted files if the pipe modifies the content, as the resume mechanism assumes the raw file content.fixIf piping modifies the file, set `resumeOnIncomplete: false`. Consider external mechanisms for managing partial files or re-downloading the entire file on interruption.
affects: >=2.0.0
gotchaDownloads could fail to resume correctly if the server responds with HTTP status 200 instead of 206 for a partial content request, or if there's a redirect from HTTP to HTTPS that isn't handled properly by older versions.fixUpgrade to `node-downloader-helper@2.1.5` or newer. This version includes fixes for resume behavior when encountering HTTP 200 instead of 206 and improved handling of HTTP to HTTPS redirects during resume.
affects: <2.1.2 || <2.1.5
gotchaFor Node.js 19 and newer, `keep alive` is disabled by default in `node-downloader-helper` (since v2.1.5). This might impact performance for multiple sequential downloads from the same host by preventing connection reuse.fixIf `keep alive` is desired for performance in Node.js 19+, explicitly enable it via `httpRequestOptions: { agent: new http.Agent({ keepAlive: true }) }` within the DownloaderHelper options. affects: >=2.1.5 (Node.js >=19)
Errors
Common errors & fixes
Error: Unhandled error event.
The 'error' event was emitted by DownloaderHelper, but no listener was registered for it, causing the EventEmitter to throw an unhandled error.
fixAdd an event listener for the 'error' event: `dl.on('error', (err) => console.error('Download failed:', err));` Error: Too many redirects
The download URL experienced more HTTP redirects than the `maxRedirects` option allowed, or an infinite redirect loop occurred.
fixIncrease the `maxRedirects` option in the DownloaderHelper constructor (e.g., `{ maxRedirects: 20 }`) or verify the URL for redirect loops. Error: Cannot write to file stream after it has been closed or destroyed.
This error can occur in older versions (pre-2.1.8) due to a bug where the internal file stream was not properly closed or recreated during retries, leading to attempts to write to a closed stream.
fixUpgrade to `node-downloader-helper@2.1.8` or newer to get the fix for stream management during retries.
Download stuck or reports 0 bytes downloaded after a resume attempt.
This can happen in older versions if the server responds with HTTP 200 (OK) instead of 206 (Partial Content) to a resume request, or if a redirect during resume (e.g., http to https) was not correctly handled.
fixUpgrade to `node-downloader-helper@2.1.5` or newer, which includes fixes for these specific resume scenarios.
Audit
Dependencies
No dependency data recorded yet.