fetch-byte-ranges

HTTP byte-range fetcher.

Issues concurrent partial GETs and returns a ReadableStream<Uint8Array> per requested range — no output destination assumed, works anywhere fetch does.

import { fetchByteRanges, collectStream } from '@treewyrm/fetch-byte-ranges'

const { ranges, totalSize } = await fetchByteRanges(url, [
  { start: 0,         end: 1_048_575 }, // first 1 MB
  { start: 2_097_152, end: 3_145_727 }, // third 1 MB
])

// Collect into memory
const buffer = await collectStream(ranges[0].stream)

// Or pipe to a file (Node.js)
import { createWriteStream } from 'node:fs'
import { Writable } from 'node:stream'

ranges[0].stream.pipeTo(Writable.toWeb(createWriteStream('chunkA.bin')))
ranges[1].stream.pipeTo(Writable.toWeb(createWriteStream('chunkB.bin')))

// Or return directly as a Response body (edge/browser)
return new Response(ranges[0].stream)

Ranges fed into fetchByteRanges are returned as-is in ranges property of return value.

How it works

Every call begins with a preflight HEAD to establish the contract:

Preflight result	Behaviour
No Content-Length	Throws MissingContentLengthError
Any range out of bounds	Throws RangeOutOfBoundsError
Accept-Ranges: bytes	Ranged path — concurrent partial GETs
Anything else	Full-body path — single GET, ranges sliced locally

On the ranged path nearby ranges are merged into fewer requests (up to maxRequests), their response bodies are tee'd and sliced back into one stream per original range. On the full-body path the single response stream is tee'd and sliced the same way.

API

fetchByteRanges(url, ranges, options?)

const { ranges, totalSize } = await fetchByteRanges(url, [
  { start: 0, end: 999 },
])

Options:

Option	Type	Default	Description
concurrency	number	6	Max simultaneous range GETs
maxRequests	number	8	Max requests after merging nearby ranges
headers	HeadersInit	—	Extra headers on every request
signal	AbortSignal	—	Cancellation signal
fetch	typeof fetch	globalThis.fetch	Custom fetch implementation

Result:

Field	Type	Description
ranges	RangeResult[]	One entry per input range, in the same order
totalSize	number	File size from preflight Content-Length

Each RangeResult:

Field	Type	Description
range	ByteRange	The requested range
stream	ReadableStream<Uint8Array>	Response bytes — consume exactly once
byteLength	number	end - start + 1
contentRange	string | null	Content-Range header; null on full-body path

condenseRanges(ranges, maxRanges?)

Merges overlapping and adjacent ranges, then merges the closest pairs until at most maxRanges remain. fetchByteRages always runs this function internally.

collectStream(stream)

Convenience helper — drains a ReadableStream<Uint8Array> into a Uint8Array.

splitIntoRanges(totalBytes, count)

Split a file into count evenly-sized ByteRanges covering [0, totalBytes-1]. Useful for parallel whole-file downloads:

const { totalSize } = await fetchByteRanges(url, [{ start: 0, end: 0 }])
const chunks = splitIntoRanges(totalSize, 8)
const { ranges } = await fetchByteRanges(url, chunks, { concurrency: 8 })

Errors

Class	When
MissingContentLengthError	Preflight HEAD has no Content-Length
RangeOutOfBoundsError	A range's end ≥ totalSize
RangeNotSatisfiableError	Server returns 416
UnexpectedRangeResponseError	Server returns anything other than 206 on the ranged path
FullBodyTooShortError	Full-body response closes before covering all requested ranges

Byte range semantics

Ranges are inclusive on both ends, matching HTTP's Range header:

{ start: 0, end: 9 }   // bytes 0–9 inclusive, 10 bytes total
                       // → Range: bytes=0-9

Byte range is a generic type in fetchByteRanges.

Requirements

• Node.js ≥ 18, Deno, Bun, or any modern browser
• No runtime dependencies