Library API

grabr can be imported programmatically into any Node.js or Bun project.

Installation

npm install @linuxctrl/grabr

Import

import { Downloader, SpeedMeter, loadConfig, saveConfig } from "@linuxctrl/grabr";
import type { DownloadJob, DownloadOptions, JobStatus, ChunkInfo, GrabrConfig } from "@linuxctrl/grabr";

Downloader

The main class that orchestrates parallel chunked downloads. Extends EventEmitter.

Constructor

const downloader = new Downloader();
await downloader.start();

Methods

`start(): Promise<void>`

Initializes the downloader, loads interrupted jobs from the database, and starts the stats updater.

`stop(): void`

Stops all active downloads and clears the interval timer.

`addJob(url: string, options?: DownloadOptions): Promise<DownloadJob>`

Add a download job to the queue. Returns the created job.

const job = await downloader.addJob("https://example.com/file.zip", {
  outputDir: "./downloads",
  chunks: 4,
  filename: "myfile.zip",
});

`pauseJob(jobId: string): Promise<void>`

Pause a specific download job.

`resumeJob(jobId: string): Promise<void>`

Resume a paused or failed download job.

`removeJob(jobId: string): Promise<void>`

Remove a job from the queue and delete its resume state.

`pauseAll(): Promise<void>`

Pause all active and queued downloads.

`resumeAll(): Promise<void>`

Resume all paused and failed downloads.

Events

downloader.on("job:added", (job: DownloadJob) => {
  console.log("New job:", job.id);
});

downloader.on("job:progress", (data: { jobId: string; downloadedBytes: number; speed: number; eta: number }) => {
  console.log(`${data.jobId}: ${data.downloadedBytes} bytes`);
});

downloader.on("job:status", (data: { jobId: string; status: JobStatus; error?: string }) => {
  console.log(`${data.jobId}: ${data.status}`);
});

downloader.on("job:removed", (jobId: string) => {
  console.log(`Removed: ${jobId}`);
});

Types

DownloadJob

interface DownloadJob {
  id: string;
  url: string;
  filename: string;
  destination: string;
  totalBytes: number;
  downloadedBytes: number;
  chunks: ChunkInfo[];
  status: "queued" | "downloading" | "paused" | "completed" | "failed";
  speed: number;
  eta: number;
  createdAt: number;
  updatedAt: number;
  error?: string;
}

ChunkInfo

interface ChunkInfo {
  index: number;
  start: number;
  end: number;
  downloaded: number;
  status: "pending" | "downloading" | "done" | "failed";
}

DownloadOptions

interface DownloadOptions {
  outputDir?: string;
  filename?: string;
  chunks?: number;
}

GrabrConfig

interface GrabrConfig {
  outputDir: string;
  maxConcurrent: number;
  defaultChunks: number;
  serverPort: number;
  theme: string;
}

Config

import { loadConfig, saveConfig } from "@linuxctrl/grabr";

const config = loadConfig();
console.log(config.outputDir);

saveConfig({ defaultChunks: 8 });

Config is stored in ~/.grabr/config.json.

SpeedMeter

Utility class for EMA-smoothed speed calculation.

const meter = new SpeedMeter();
const speed = meter.update(1024);