Range Request Fetcher

A JavaScript library for reliably fetching large files using chunked range requests, automatic retries, and progress tracking. Specifically designed to handle common network errors like ERR_HTTP2_PROTOCOL_ERROR and ERR_SSL_PROTOCOL_ERROR that frequently occur when downloading large files over unstable connections.

Handling download problems

This library specifically handles common network errors that occur during large file downloads:

ERR_HTTP2_PROTOCOL_ERROR

This error typically occurs when:

The HTTP/2 connection is disrupted or closed unexpectedly
The server terminates the stream prematurely
Network instability causes protocol-level issues

How range-request-fetcher helps:

Automatically retries failed requests with exponential backoff
Resumes downloads from the last successful byte position

ERR_SSL_PROTOCOL_ERROR

This error happens when:

SSL/TLS handshake fails or is interrupted
Certificate validation issues occur
Secure connection is dropped during transfer

How range-request-fetcher helps:

Implements intelligent retry logic for SSL failures
Maintains connection state to resume from interruption points
Uses chunked requests to minimize data loss on connection drops

These features make the library particularly reliable for downloading large files over unstable connections or from servers with intermittent issues

Features

✅ Chunked fetching - Splits large files into chunks for improved reliability
✅ Automatic retries - Automatically retries failed chunks
✅ Progress tracking - Real-time callbacks for progress updates
✅ Pause/Resume/Abort - Full download control with pause, resume, and abort functionality
✅ Authentication support - Compatible with Bearer tokens and custom headers
✅ Modern API - Uses File System Access API for saving files
✅ Error handling - Robust handling of network and protocol errors

Installation

npm install range-request-fetcher

Basic Usage

import { rangeRequestFetcher } from 'range-request-fetcher';

// Basic fetch (Promise-based)
const download = rangeRequestFetcher({
  url: 'https://example.com/large-file.zip',
  fileName: 'my-download.zip'
});

await download.promise;
console.log('Download completed!');

Download Control Examples

Simple Progress Tracking

const download = rangeRequestFetcher({
  url: 'https://example.com/large-file.zip',
  fileName: 'my-download.zip',
  onProgress: (percent) => console.log(`Progress: ${percent}%`),
  onStatus: (status) => console.log(`Status: ${status}`)
});

await download.promise;

Pause and Resume

const download = rangeRequestFetcher({
  url: 'https://example.com/large-file.zip',
  fileName: 'my-download.zip',
  onProgress: (percent) => {
    console.log(`Progress: ${percent}%`);

    // Auto-pause at 50%
    if (percent === 50) {
      download.pause();
      console.log('Download paused at 50%');

      // Resume after 5 seconds
      setTimeout(() => {
        download.resume();
        console.log('Download resumed');
      }, 5000);
    }
  }
});

await download.promise;

Manual Control with UI

const download = rangeRequestFetcher({
  url: 'https://example.com/ubuntu-22.04.3-desktop-amd64.iso',
  fileName: 'ubuntu-22.04.3-desktop-amd64.iso',
  onProgress: (percent) => {
    document.getElementById('progress').style.width = `${percent}%`;
    document.getElementById('percent').textContent = `${percent}%`;
  },
  onStatus: (status) => {
    document.getElementById('status').textContent = status;
  }
});

// UI Controls
document.getElementById('pauseBtn').onclick = () => {
  download.pause();
  document.getElementById('pauseBtn').disabled = true;
  document.getElementById('resumeBtn').disabled = false;
};

document.getElementById('resumeBtn').onclick = () => {
  download.resume();
  document.getElementById('pauseBtn').disabled = false;
  document.getElementById('resumeBtn').disabled = true;
};

document.getElementById('abortBtn').onclick = () => {
  download.abort();
  console.log('Download cancelled');
};

// Check download state
setInterval(() => {
  console.log(`Paused: ${download.isPaused()}, Aborted: ${download.isAborted()}, Progress: ${download.getProgress()}%`);
}, 1000);

try {
  await download.promise;
  console.log('Download completed!');
} catch (error) {
  if (download.isAborted()) {
    console.log('Download was cancelled by user');
  } else {
    console.error('Download failed:', error.message);
  }
}

With Authentication

const download = rangeRequestFetcher({
  url: 'https://api.example.com/secure-file.zip',
  fileName: 'secure-file.zip',
  token: 'your-bearer-token',
  headers: {
    'X-API-Key': 'your-api-key'
  },
  onProgress: (percent) => console.log(`Progress: ${percent}%`)
});

// You can still control authenticated downloads
setTimeout(() => download.pause(), 5000);
setTimeout(() => download.resume(), 10000);

await download.promise;

API Reference