@mappedin/mvf-fetch 3.0.0-beta.15

package/dist/zip/entry.js

@@ -0,0 +1,178 @@
+import { inflateSync } from 'fflate';
+import { readUint16LE, readUint32LE } from './bytes.js';
+import { LOCAL_FILE_HEADER_SIGNATURE } from './index.js';
+import { fetchByteRange } from './range.js';
+import { RangeBufferCache, coalesceRanges, fetchCoalescedRanges } from './ranges.js';
+export const LOCAL_EXTRA_FIELD_PAD = 1024;
+/**
+ * Computes the initial byte range to fetch for a zip entry local header and payload.
+ */
+export function computeEntryEstimatedRange(entryPath, meta, totalSize) {
+    const headerStart = meta.relativeOffsetOfLocalHeader;
+    const nameByteLength = new TextEncoder().encode(entryPath).length;
+    const estimatedEnd = Math.min(headerStart + 30 + nameByteLength + LOCAL_EXTRA_FIELD_PAD + meta.compressedSize - 1, totalSize - 1);
+    return {
+        start: headerStart,
+        endInclusive: estimatedEnd,
+    };
+}
+/**
+ * Extracts compressed entry bytes from a fetched buffer covering the entry header region.
+ */
+export function extractCompressedBytes(buffer, bufferAbsoluteStart, entryPath, meta) {
+    if (meta.compressedSize === 0) {
+        return { compressed: new Uint8Array(0) };
+    }
+    const headerStart = meta.relativeOffsetOfLocalHeader;
+    const offsetInBuffer = headerStart - bufferAbsoluteStart;
+    if (offsetInBuffer < 0 || offsetInBuffer + 30 > buffer.length) {
+        throw new Error(`Local file header truncated: ${entryPath}`);
+    }
+    if (readUint32LE(buffer, offsetInBuffer) !== LOCAL_FILE_HEADER_SIGNATURE) {
+        throw new Error(`Invalid local file header: ${entryPath}`);
+    }
+    const fileNameLength = readUint16LE(buffer, offsetInBuffer + 26);
+    const extraFieldLength = readUint16LE(buffer, offsetInBuffer + 28);
+    const dataOffsetInBuffer = offsetInBuffer + 30 + fileNameLength + extraFieldLength;
+    if (dataOffsetInBuffer + meta.compressedSize <= buffer.length) {
+        return {
+            compressed: buffer.subarray(dataOffsetInBuffer, dataOffsetInBuffer + meta.compressedSize),
+        };
+    }
+    const absoluteDataStart = headerStart + 30 + fileNameLength + extraFieldLength;
+    const absoluteDataEnd = absoluteDataStart + meta.compressedSize - 1;
+    const alreadyHave = buffer.length > dataOffsetInBuffer ? buffer.subarray(dataOffsetInBuffer) : new Uint8Array(0);
+    return {
+        compressed: alreadyHave,
+        remainingRange: {
+            start: absoluteDataStart + alreadyHave.length,
+            endInclusive: absoluteDataEnd,
+        },
+    };
+}
+function mergeBytes(prefix, suffix) {
+    if (prefix.length === 0) {
+        return suffix;
+    }
+    if (suffix.length === 0) {
+        return prefix;
+    }
+    const merged = new Uint8Array(prefix.length + suffix.length);
+    merged.set(prefix, 0);
+    merged.set(suffix, prefix.length);
+    return merged;
+}
+/**
+ * Reads the compressed bytes for a single zip entry via HTTP Range.
+ */
+export async function readZipEntryBytes(url, entryPath, index, fetchFn = fetch) {
+    const meta = index.entries[entryPath];
+    if (meta == null) {
+        throw new Error(`Zip entry not found: ${entryPath}`);
+    }
+    const primaryRange = computeEntryEstimatedRange(entryPath, meta, index.totalSize);
+    const buffer = await fetchByteRange(url, primaryRange.start, primaryRange.endInclusive, fetchFn);
+    const extracted = extractCompressedBytes(buffer, primaryRange.start, entryPath, meta);
+    if (extracted.remainingRange == null) {
+        return extracted.compressed;
+    }
+    const remaining = await fetchByteRange(url, extracted.remainingRange.start, extracted.remainingRange.endInclusive, fetchFn);
+    return mergeBytes(extracted.compressed, remaining);
+}
+/**
+ * Decompresses a zip entry payload.
+ */
+export function decompressEntry(compressed, meta) {
+    if (meta.compressionMethod === 0) {
+        return compressed;
+    }
+    if (meta.compressionMethod === 8) {
+        return inflateSync(compressed, { out: new Uint8Array(meta.uncompressedSize) });
+    }
+    throw new Error(`Unsupported compression method: ${meta.compressionMethod}`);
+}
+async function readZipEntriesWithCoalescedRanges(url, plans, fetchFn, concurrency, maxGapBytes) {
+    const results = new Map();
+    if (plans.length === 0) {
+        return results;
+    }
+    const cache = new RangeBufferCache();
+    await fetchCoalescedRanges(url, plans.map((plan) => plan.primaryRange), fetchFn, concurrency, cache, maxGapBytes);
+    const pendingRemaining = [];
+    for (const plan of plans) {
+        const buffer = cache.slice(plan.primaryRange.start, plan.primaryRange.endInclusive);
+        const extracted = extractCompressedBytes(buffer, plan.primaryRange.start, plan.entryPath, plan.meta);
+        if (extracted.remainingRange == null) {
+            results.set(plan.entryPath, decompressEntry(extracted.compressed, plan.meta));
+            continue;
+        }
+        pendingRemaining.push({
+            entryPath: plan.entryPath,
+            meta: plan.meta,
+            prefix: extracted.compressed,
+            range: extracted.remainingRange,
+        });
+    }
+    if (pendingRemaining.length > 0) {
+        await fetchCoalescedRanges(url, pendingRemaining.map((entry) => entry.range), fetchFn, concurrency, cache, maxGapBytes);
+        for (const entry of pendingRemaining) {
+            const suffix = cache.slice(entry.range.start, entry.range.endInclusive);
+            results.set(entry.entryPath, decompressEntry(mergeBytes(entry.prefix, suffix), entry.meta));
+        }
+    }
+    return results;
+}
+/**
+ * Reads and decompresses multiple zip entries, coalescing adjacent HTTP Range requests.
+ */
+export async function readZipEntries(url, entryPaths, index, options = {}) {
+    const { allowMissing = false, concurrency = 32, fetchFn = fetch, maxGapBytes = 0 } = options;
+    const plans = [];
+    for (const entryPath of entryPaths) {
+        const meta = index.entries[entryPath];
+        if (meta == null) {
+            if (allowMissing) {
+                continue;
+            }
+            throw new Error(`Zip entry not found: ${entryPath}`);
+        }
+        plans.push({
+            entryPath,
+            meta,
+            primaryRange: computeEntryEstimatedRange(entryPath, meta, index.totalSize),
+        });
+    }
+    if (plans.length === 0) {
+        return new Map();
+    }
+    if (plans.length === 1) {
+        const plan = plans[0];
+        const compressed = await readZipEntryBytes(url, plan.entryPath, index, fetchFn);
+        return new Map([[plan.entryPath, decompressEntry(compressed, plan.meta)]]);
+    }
+    return readZipEntriesWithCoalescedRanges(url, plans, fetchFn, concurrency, maxGapBytes);
+}
+/**
+ * Returns the coalesced HTTP Range count for a batch of entry paths.
+ * Useful for testing and diagnostics.
+ */
+export function countCoalescedRangesForEntries(entryPaths, index, maxGapBytes = 0) {
+    const ranges = [];
+    for (const entryPath of entryPaths) {
+        const meta = index.entries[entryPath];
+        if (meta != null) {
+            ranges.push(computeEntryEstimatedRange(entryPath, meta, index.totalSize));
+        }
+    }
+    return {
+        rawRanges: ranges.length,
+        coalescedRanges: coalesceRanges(ranges, maxGapBytes).length,
+    };
+}
+/**
+ * Decodes zip entry bytes as UTF-8 JSON.
+ */
+export function decodeZipEntryJson(raw) {
+    return JSON.parse(new TextDecoder().decode(raw));
+}
+//# sourceMappingURL=entry.js.map

package/dist/zip/index.d.ts

@@ -0,0 +1,44 @@
+import { type FetchFn } from './range.js';
+export declare const EOCD_SIGNATURE = 101010256;
+export declare const EOCD_MIN_SIZE = 22;
+export declare const EOCD_MAX_COMMENT = 65535;
+export declare const CENTRAL_DIRECTORY_SIGNATURE = 33639248;
+export declare const LOCAL_FILE_HEADER_SIGNATURE = 67324752;
+export declare const ZIP64_EXTRA_FIELD_ID = 1;
+export interface ZipEntryMeta {
+    relativeOffsetOfLocalHeader: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    compressionMethod: number;
+}
+export interface ZipIndex {
+    totalSize: number;
+    entries: Record<string, ZipEntryMeta>;
+}
+export interface ZipEndOfCentralDirectory {
+    entryCount: number;
+    centralDirectorySize: number;
+    centralDirectoryOffset: number;
+}
+/**
+ * Size of the speculative first tail read.
+ *
+ * The EOCD record may legally sit up to {@link EOCD_MAX_COMMENT} bytes from the end, but
+ * only when the archive carries a large comment, which published MVF archives do not.
+ * Reading that maximum up front would be a large fraction of a small archive — 64 KiB
+ * against a 165 KiB bundle — so speculate small, big enough that a typical central
+ * directory arrives in the same response, and widen only when the record is not in there.
+ */
+export declare const DEFAULT_TAIL_READ_LENGTH = 4096;
+export declare function getZipTailReadLength(fileSize: number): number;
+export declare function parseEndOfCentralDirectory(tail: Uint8Array): ZipEndOfCentralDirectory;
+export declare function parseCentralDirectory(centralDirectory: Uint8Array, entryCount: number): Map<string, ZipEntryMeta>;
+/**
+ * Opens a remote zip index by reading the EOCD and central directory via HTTP Range.
+ *
+ * Costs a single round trip for a typical archive: the suffix range that reads the tail
+ * also reports the total size, and the central directory is normally inside those same
+ * bytes.
+ */
+export declare function openRemoteZipIndex(url: string, fetchFn?: FetchFn): Promise<ZipIndex>;
+//# sourceMappingURL=index.d.ts.map

package/dist/zip/index.js

@@ -0,0 +1,140 @@
+import { readUint16LE, readUint32LE } from './bytes.js';
+import { fetchByteRange, fetchZipTail } from './range.js';
+export const EOCD_SIGNATURE = 0x06054b50;
+export const EOCD_MIN_SIZE = 22;
+export const EOCD_MAX_COMMENT = 65535;
+export const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50;
+export const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
+export const ZIP64_EXTRA_FIELD_ID = 0x0001;
+/**
+ * Size of the speculative first tail read.
+ *
+ * The EOCD record may legally sit up to {@link EOCD_MAX_COMMENT} bytes from the end, but
+ * only when the archive carries a large comment, which published MVF archives do not.
+ * Reading that maximum up front would be a large fraction of a small archive — 64 KiB
+ * against a 165 KiB bundle — so speculate small, big enough that a typical central
+ * directory arrives in the same response, and widen only when the record is not in there.
+ */
+export const DEFAULT_TAIL_READ_LENGTH = 4096;
+export function getZipTailReadLength(fileSize) {
+    return Math.min(fileSize, EOCD_MIN_SIZE + EOCD_MAX_COMMENT);
+}
+/**
+ * Scans backwards for the EOCD record, which is the last thing in a zip.
+ * @returns The record, or null when it is not inside the given bytes
+ */
+function findEndOfCentralDirectory(tail) {
+    for (let commentLength = 0; commentLength <= EOCD_MAX_COMMENT; commentLength++) {
+        const eocdStart = tail.length - EOCD_MIN_SIZE - commentLength;
+        if (eocdStart < 0) {
+            return null;
+        }
+        if (readUint32LE(tail, eocdStart) !== EOCD_SIGNATURE) {
+            continue;
+        }
+        return {
+            entryCount: readUint16LE(tail, eocdStart + 10),
+            centralDirectorySize: readUint32LE(tail, eocdStart + 12),
+            centralDirectoryOffset: readUint32LE(tail, eocdStart + 16),
+        };
+    }
+    return null;
+}
+export function parseEndOfCentralDirectory(tail) {
+    const eocd = findEndOfCentralDirectory(tail);
+    if (eocd == null) {
+        throw new Error('End of Central Directory record not found in zip tail.');
+    }
+    return eocd;
+}
+function assertClassicZipSizes(...values) {
+    for (const value of values) {
+        if (value === 0xffffffff) {
+            throw new Error('Zip64 archives are not supported.');
+        }
+    }
+}
+export function parseCentralDirectory(centralDirectory, entryCount) {
+    const entries = new Map();
+    let offset = 0;
+    const decoder = new TextDecoder();
+    for (let i = 0; i < entryCount; i++) {
+        if (offset + 46 > centralDirectory.length) {
+            throw new Error('Central directory is truncated.');
+        }
+        if (readUint32LE(centralDirectory, offset) !== CENTRAL_DIRECTORY_SIGNATURE) {
+            throw new Error(`Invalid central directory signature at ${offset}`);
+        }
+        const compressionMethod = readUint16LE(centralDirectory, offset + 10);
+        const compressedSize = readUint32LE(centralDirectory, offset + 20);
+        const uncompressedSize = readUint32LE(centralDirectory, offset + 24);
+        const fileNameLength = readUint16LE(centralDirectory, offset + 28);
+        const extraFieldLength = readUint16LE(centralDirectory, offset + 30);
+        const fileCommentLength = readUint16LE(centralDirectory, offset + 32);
+        const relativeOffsetOfLocalHeader = readUint32LE(centralDirectory, offset + 42);
+        assertClassicZipSizes(compressedSize, uncompressedSize, relativeOffsetOfLocalHeader);
+        const nameStart = offset + 46;
+        const nameEnd = nameStart + fileNameLength;
+        const fileName = decoder.decode(centralDirectory.subarray(nameStart, nameEnd));
+        const extraStart = nameEnd;
+        const extraEnd = extraStart + extraFieldLength;
+        for (let extraOffset = extraStart; extraOffset + 4 <= extraEnd;) {
+            const headerId = readUint16LE(centralDirectory, extraOffset);
+            const dataSize = readUint16LE(centralDirectory, extraOffset + 2);
+            if (headerId === ZIP64_EXTRA_FIELD_ID) {
+                throw new Error('Zip64 archives are not supported.');
+            }
+            extraOffset += 4 + dataSize;
+        }
+        if (!fileName.endsWith('/')) {
+            entries.set(fileName, {
+                relativeOffsetOfLocalHeader,
+                compressedSize,
+                uncompressedSize,
+                compressionMethod,
+            });
+        }
+        offset = nameEnd + extraFieldLength + fileCommentLength;
+    }
+    return entries;
+}
+/**
+ * The central directory usually sits inside the tail that was already fetched, so only
+ * go back to the network when it does not.
+ */
+async function readCentralDirectory(url, tail, eocd, fetchFn) {
+    const start = eocd.centralDirectoryOffset;
+    const endInclusive = start + eocd.centralDirectorySize - 1;
+    if (start >= tail.start && endInclusive < tail.start + tail.bytes.length) {
+        return tail.bytes.subarray(start - tail.start, endInclusive - tail.start + 1);
+    }
+    return fetchByteRange(url, start, endInclusive, fetchFn);
+}
+/**
+ * Opens a remote zip index by reading the EOCD and central directory via HTTP Range.
+ *
+ * Costs a single round trip for a typical archive: the suffix range that reads the tail
+ * also reports the total size, and the central directory is normally inside those same
+ * bytes.
+ */
+export async function openRemoteZipIndex(url, fetchFn = fetch) {
+    let tail = await fetchZipTail(url, DEFAULT_TAIL_READ_LENGTH, fetchFn);
+    let eocd = findEndOfCentralDirectory(tail.bytes);
+    // The speculative read missed the record, so widen to the largest legal window.
+    const maxTailLength = getZipTailReadLength(tail.totalSize);
+    if (eocd == null && tail.bytes.length < maxTailLength) {
+        tail = await fetchZipTail(url, maxTailLength, fetchFn);
+        eocd = findEndOfCentralDirectory(tail.bytes);
+    }
+    if (eocd == null) {
+        throw new Error('End of Central Directory record not found in zip tail.');
+    }
+    assertClassicZipSizes(eocd.centralDirectorySize, eocd.centralDirectoryOffset);
+    const centralDirectory = await readCentralDirectory(url, tail, eocd, fetchFn);
+    const entryMap = parseCentralDirectory(centralDirectory, eocd.entryCount);
+    return {
+        totalSize: tail.totalSize,
+        entries: Object.fromEntries(entryMap),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/zip/range.d.ts

@@ -0,0 +1,40 @@
+export declare class HttpRangeError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export type FetchFn = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Fetches an inclusive byte range from a URL using HTTP Range requests.
+ */
+export declare function fetchByteRange(url: string, start: number, endInclusive: number, fetchFn?: FetchFn): Promise<Uint8Array>;
+/**
+ * The trailing bytes of a remote file, positioned within it.
+ */
+export interface ZipTail {
+    bytes: Uint8Array;
+    /** Absolute offset of `bytes[0]` within the file. */
+    start: number;
+    totalSize: number;
+}
+/**
+ * Parses a `Content-Range: bytes <start>-<end>/<total>` header.
+ */
+export declare function parseContentRange(header: string | null): {
+    start: number;
+    totalSize: number;
+} | null;
+/**
+ * Reads the last `tailLength` bytes of a remote file, along with its total size.
+ *
+ * Uses a suffix range (`bytes=-N`), so `Content-Range` reports the total size and no
+ * separate `HEAD` round trip is needed to learn it.
+ */
+export declare function fetchZipTail(url: string, tailLength: number, fetchFn?: FetchFn): Promise<ZipTail>;
+/**
+ * Reads the total size of a remote resource from its Content-Length header.
+ *
+ * Prefer {@link fetchZipTail} when the tail bytes are wanted too: it returns the size
+ * from `Content-Range` and saves a round trip.
+ */
+export declare function getTotalSize(url: string, fetchFn?: FetchFn): Promise<number>;
+//# sourceMappingURL=range.d.ts.map

package/dist/zip/range.js

@@ -0,0 +1,99 @@
+export class HttpRangeError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpRangeError';
+    }
+}
+/**
+ * Fetches an inclusive byte range from a URL using HTTP Range requests.
+ */
+export async function fetchByteRange(url, start, endInclusive, fetchFn = fetch) {
+    const response = await fetchFn(url, {
+        headers: { Range: `bytes=${start}-${endInclusive}` },
+        redirect: 'follow',
+    });
+    if (!response.ok && response.status !== 206) {
+        throw new HttpRangeError(`Range request failed: ${response.status}`, response.status);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    // Anything other than 206 means the server ignored Range and sent the whole entity.
+    // Returning that as-is would leave the caller slicing at the wrong offsets, so cut
+    // the requested window out of it here.
+    if (response.status !== 206) {
+        return bytes.subarray(start, endInclusive + 1);
+    }
+    return bytes;
+}
+/**
+ * Parses a `Content-Range: bytes <start>-<end>/<total>` header.
+ */
+export function parseContentRange(header) {
+    if (header == null) {
+        return null;
+    }
+    const match = /bytes\s+(\d+)-(\d+)\/(\d+)/.exec(header);
+    if (match == null) {
+        return null;
+    }
+    return {
+        start: Number.parseInt(match[1] ?? '', 10),
+        totalSize: Number.parseInt(match[3] ?? '', 10),
+    };
+}
+/**
+ * Reads the last `tailLength` bytes of a remote file, along with its total size.
+ *
+ * Uses a suffix range (`bytes=-N`), so `Content-Range` reports the total size and no
+ * separate `HEAD` round trip is needed to learn it.
+ */
+export async function fetchZipTail(url, tailLength, fetchFn = fetch) {
+    const response = await fetchFn(url, {
+        headers: { Range: `bytes=-${tailLength}` },
+        redirect: 'follow',
+    });
+    if (!response.ok && response.status !== 206) {
+        throw new HttpRangeError(`Tail range request failed: ${response.status}`, response.status);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    // The server ignored Range and sent the whole entity, which still contains the tail.
+    if (response.status !== 206) {
+        return { bytes, start: 0, totalSize: bytes.length };
+    }
+    const contentRange = parseContentRange(response.headers.get('content-range'));
+    if (contentRange == null) {
+        throw new Error(`Unusable Content-Range header: ${response.headers.get('content-range')}`);
+    }
+    const { start, totalSize } = contentRange;
+    const expectedStart = Math.max(0, totalSize - Math.min(tailLength, totalSize));
+    // Some static file servers misread `bytes=-N` as `bytes=0-N` while still answering
+    // 206 with a plausible Content-Range. Absolute ranges are unambiguous, so retry.
+    if (start !== expectedStart) {
+        const absolute = await fetchByteRange(url, expectedStart, totalSize - 1, fetchFn);
+        return { bytes: absolute, start: expectedStart, totalSize };
+    }
+    return { bytes, start, totalSize };
+}
+/**
+ * Reads the total size of a remote resource from its Content-Length header.
+ *
+ * Prefer {@link fetchZipTail} when the tail bytes are wanted too: it returns the size
+ * from `Content-Range` and saves a round trip.
+ */
+export async function getTotalSize(url, fetchFn = fetch) {
+    const response = await fetchFn(url, { method: 'HEAD', redirect: 'follow' });
+    if (!response.ok) {
+        throw new HttpRangeError(`HEAD request failed: ${response.status}`, response.status);
+    }
+    const contentLength = response.headers.get('content-length');
+    if (contentLength == null) {
+        throw new Error('Missing Content-Length header');
+    }
+    const totalSize = Number.parseInt(contentLength, 10);
+    if (!Number.isFinite(totalSize) || totalSize <= 0) {
+        throw new Error('Invalid Content-Length header');
+    }
+    return totalSize;
+}
+//# sourceMappingURL=range.js.map

package/dist/zip/ranges.d.ts

@@ -0,0 +1,33 @@
+import { type FetchFn } from './range.js';
+/**
+ * An inclusive byte range within a remote file.
+ */
+export interface ByteRange {
+    start: number;
+    endInclusive: number;
+}
+/**
+ * Merges overlapping or adjacent byte ranges to minimize HTTP requests.
+ *
+ * @param ranges - The ranges to merge
+ * @param maxGapBytes - Also merge ranges separated by at most this many unwanted bytes.
+ * Entries a consumer wants are rarely laid out contiguously, so tolerating a small gap
+ * trades a few wasted bytes for noticeably fewer round trips. Merging without a bound
+ * would pull the whole archive, so this is deliberately a ceiling rather than a flag.
+ * @default 0
+ */
+export declare function coalesceRanges(ranges: ByteRange[], maxGapBytes?: number): ByteRange[];
+/**
+ * In-memory cache of fetched byte ranges keyed by absolute file offset.
+ */
+export declare class RangeBufferCache {
+    #private;
+    add(start: number, buffer: Uint8Array): void;
+    slice(start: number, endInclusive: number): Uint8Array;
+    get size(): number;
+}
+/**
+ * Fetches byte ranges after coalescing overlaps and adjacency.
+ */
+export declare function fetchCoalescedRanges(url: string, ranges: ByteRange[], fetchFn: FetchFn, concurrency: number, cache: RangeBufferCache, maxGapBytes?: number): Promise<void>;
+//# sourceMappingURL=ranges.d.ts.map

package/dist/zip/ranges.js

@@ -0,0 +1,84 @@
+import { fetchByteRange } from './range.js';
+/**
+ * Runs async tasks with a bounded concurrency limit.
+ */
+async function mapWithConcurrency(items, concurrency, fn) {
+    if (items.length === 0) {
+        return [];
+    }
+    const limit = Math.max(1, concurrency);
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (nextIndex < items.length) {
+            const current = nextIndex++;
+            const item = items[current];
+            if (item === undefined) {
+                continue;
+            }
+            results[current] = await fn(item);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Merges overlapping or adjacent byte ranges to minimize HTTP requests.
+ *
+ * @param ranges - The ranges to merge
+ * @param maxGapBytes - Also merge ranges separated by at most this many unwanted bytes.
+ * Entries a consumer wants are rarely laid out contiguously, so tolerating a small gap
+ * trades a few wasted bytes for noticeably fewer round trips. Merging without a bound
+ * would pull the whole archive, so this is deliberately a ceiling rather than a flag.
+ * @default 0
+ */
+export function coalesceRanges(ranges, maxGapBytes = 0) {
+    if (ranges.length === 0) {
+        return [];
+    }
+    const sorted = [...ranges].sort((a, b) => a.start - b.start || a.endInclusive - b.endInclusive);
+    const merged = [{ ...sorted[0] }];
+    for (let i = 1; i < sorted.length; i++) {
+        const current = sorted[i];
+        const last = merged[merged.length - 1];
+        if (current.start <= last.endInclusive + 1 + maxGapBytes) {
+            last.endInclusive = Math.max(last.endInclusive, current.endInclusive);
+            continue;
+        }
+        merged.push({ ...current });
+    }
+    return merged;
+}
+/**
+ * In-memory cache of fetched byte ranges keyed by absolute file offset.
+ */
+export class RangeBufferCache {
+    #segments = [];
+    add(start, buffer) {
+        this.#segments.push({ start, buffer });
+    }
+    slice(start, endInclusive) {
+        for (const segment of this.#segments) {
+            const segmentEnd = segment.start + segment.buffer.length - 1;
+            if (start >= segment.start && endInclusive <= segmentEnd) {
+                const offset = start - segment.start;
+                return segment.buffer.subarray(offset, offset + (endInclusive - start + 1));
+            }
+        }
+        throw new Error(`Byte range ${start}-${endInclusive} is not available in the cache.`);
+    }
+    get size() {
+        return this.#segments.length;
+    }
+}
+/**
+ * Fetches byte ranges after coalescing overlaps and adjacency.
+ */
+export async function fetchCoalescedRanges(url, ranges, fetchFn, concurrency, cache, maxGapBytes = 0) {
+    const coalesced = coalesceRanges(ranges, maxGapBytes);
+    await mapWithConcurrency(coalesced, concurrency, async (range) => {
+        const buffer = await fetchByteRange(url, range.start, range.endInclusive, fetchFn);
+        cache.add(range.start, buffer);
+    });
+}
+//# sourceMappingURL=ranges.js.map