🌟 node-downloader-manager

📥 DownloadManager

node-downloader-manager is a lightweight and efficient file download manager for Node.js applications. It allows you to download files either sequentially or using a queue-based approach, providing features like retry mechanisms, concurrency control, stream, and custom file naming.

📚 Table of Contents

• 🌟 node-downloader-manager
• 📥 DownloadManager
  • 📚 Table of Contents
  • ✨ Features
  • 📦 Installation
    • npm
    • yarn
    • pnpm
    • bun
  • 🚀 Usage
    • Examples
      • More Examples
      • Queue Download
      • Stream Download
      • Simple Download
      • Pause, Resume, and Cancel Download
      • Thread Download (Beta)
  • 📖 API Reference
    • DownloadManager Options
    • Methods
    • Events
  • 🤔 Why Use DownloadManager?
  • 🤝 Contributing
  • 📝 License

✨ Features

• Supports both simple and queue-based download methods.
• Handles multiple concurrent downloads with customizable concurrency limits.
• Supports pausing, resuming, and canceling downloads.
• Provides detailed progress and error reporting.
• Allows custom file naming and pre/post-download hooks.
• Supports streaming downloads for large files.

📦 Installation

You can install node-downloader-manager using your favorite package manager:

npm

npm install node-downloader-manager

yarn

yarn add node-downloader-manager

pnpm

pnpm add node-downloader-manager

bun

bun add node-downloader-manager

🚀 Usage

Here's how you can use node-downloader-manager in your project:

Examples

More Examples

https://github.com/nextyfine-dev/node-downloader-manager/tree/master/src/examples

Queue Download

import { DownloadManager } from "node-downloader-manager";
// const { DownloadManager } = require("node-downloader-manager"); for cjs

const urls = [
  "https://i.imgur.com/StLyH09.jpeg",
  "https://i.imgur.com/vFopwVJ.png",
  "https://i.imgur.com/NaCQQ8c.jpeg",
  "https://i.imgur.com/GXeeLNx.jpeg",
  "https://i.imgur.com/ElhcT9n.jpeg",
  "https://i.imgur.com/sNNWmtU.png",
  "https://i.imgur.com/Upa7Em5.jpeg",
  "https://i.imgur.com/CTHsEaK.png",
];

// Initialize the DownloadManager with console logging enabled
const downloadManager = new DownloadManager({ consoleLog: true }); // By default method is 'queue'

// Start the download
downloadManager.download(urls);

Stream Download

import { DownloadManager } from "node-downloader-manager";

const url =
  "https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64";
const createFileName = () => "code.deb";

const downloadManager = new DownloadManager({
  stream: true,
  overWriteFile: true,
  getFileName: createFileName,
});

downloadManager.on("start", (data) => {
  console.log(`Download started: ${data?.url}`);
});

downloadManager.download(url);

Simple Download

import { DownloadManager } from "node-downloader-manager";

const urls = [
  "https://i.imgur.com/StLyH09.jpeg",
  "https://i.imgur.com/vFopwVJ.png",
];

const downloadManager = new DownloadManager({
  consoleLog: true,
  overWriteFile: true,
  method: "simple",
});

downloadManager.download(urls);

Pause, Resume, and Cancel Download

import { DownloadManager } from "node-downloader-manager";

const url =
  "https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64";
const createFileName = () => "code.deb";

const downloadManager = new DownloadManager({
  stream: true,
  overWriteFile: true,
  getFileName: createFileName,
});

downloadManager.on("start", (data) => {
  console.log(`Download started: ${data?.url}`);
});

setTimeout(() => {
  downloadManager.pauseDownload();
}, 5000);

setTimeout(() => {
  downloadManager.resumeDownload();
}, 8000);

setTimeout(() => {
  downloadManager.cancelDownload();
}, 10000);

downloadManager.download(url);

Thread Download (Beta)

import { DownloadManager } from "node-downloader-manager";

const urls = [
  "https://i.imgur.com/StLyH09.jpeg",
  "https://i.imgur.com/vFopwVJ.png",
  "https://i.imgur.com/NaCQQ8c.jpeg",
  "https://i.imgur.com/GXeeLNx.jpeg",
  "https://i.imgur.com/ElhcT9n.jpeg",
];

const downloadManager = new DownloadManager({
  consoleLog: true,
  method: "thread",
  maxWorkers: 5,
});

downloadManager.download(urls);

📖 API Reference

DownloadManager Options

• method: "simple" | "queue" - The download method to use.
• concurrencyLimit: number - Maximum number of concurrent downloads.
• retries: number - Maximum number of retries for failed downloads.
• consoleLog: boolean - Enable or disable console logging.
• downloadFolder: string - Folder to save downloaded files.
• getFileName: (url: string) => string - Function to generate file names.
• onBeforeDownload: (url: string, fileName: string) => Promise<void> - Hook before download starts.
• onAfterDownload: (url: string, fileName: string) => Promise<void> - Hook after download completes.
• overWriteFile: boolean - Overwrite existing files.
• requestOptions: RequestInit - Options for the fetch request.
• stream: boolean - Enable streaming downloads.
• backOff: boolean - Enable exponential backoff for retries.
• timeout: number - Timeout for download requests.

Methods

• download(urls: string | string[]): Start downloading the specified URLs.
• pauseDownload(url?: string): Pause the download for a specific URL or the current download.
• resumeDownload(url?: string): Resume the download for a specific URL or the current download.
• cancelDownload(url?: string): Cancel the download for a specific URL or the current download.
• pauseAll(): Pause all active downloads.
• resumeAll(): Resume all paused downloads.
• cancelAll(): Cancel all active downloads.

Events

• start: Emitted when a download starts.
• progress: Emitted periodically with download progress.
• complete: Emitted when a download completes.
• error: Emitted when a download fails.
• cancel: Emitted when a download is canceled.
• paused: Emitted when a download is paused.
• resumed: Emitted when a download is resumed.
• exists: Emitted if the file already exists.
• finished: Emitted when all downloads are finished.

🤔 Why Use DownloadManager?

node-downloader-manager is designed to simplify the process of downloading files in Node.js applications. It provides a robust and flexible API for handling downloads, with support for advanced features like streaming, concurrency control, and event-driven progress reporting. Whether you're building a CLI tool, a server-side application, or a desktop app, DownloadManager can help you manage downloads efficiently and effectively.

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

📝 License

This project is licensed under the MIT License. See the LICENSE file for more details.