@versatiles/container 1.5.1 → 2.0.1

package/README.md

@@ -2,7 +2,7 @@
 [![NPM downloads](https://img.shields.io/npm/dt/%40versatiles%2Fcontainer)](https://www.npmjs.com/package/@versatiles/container)
 [![Code coverage](https://codecov.io/gh/versatiles-org/node-versatiles-container/branch/main/graph/badge.svg?token=IDHAI13M0K)](https://codecov.io/gh/versatiles-org/node-versatiles-container)
 [![CI status](https://img.shields.io/github/actions/workflow/status/versatiles-org/node-versatiles-container/ci.yml)](https://github.com/versatiles-org/node-versatiles-container/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![License](https://img.shields.io/badge/license-Unlicense-green)](LICENSE)
 
 A client library for [VersaTiles containers](https://github.com/versatiles-org/versatiles-spec).
 
@@ -10,6 +10,8 @@ A client library for [VersaTiles containers](https://github.com/versatiles-org/v
 
 `npm i @versatiles/container`
 
+Requires Node.js 22.15 or newer, since Zstandard decompression uses the built-in `node:zlib` zstd support.
+
 # Usage Examples
 
 ## Basic: read a tile and write to disk
@@ -23,7 +25,7 @@ const header = await container.getHeader();
 const tile = await container.getTileUncompressed(z, x, y);
 fs.writeFileSync("tile." + header.tileFormat, tile);
 
-// don't forget to close file-backed containers
+// release the file descriptor (or pooled HTTP connections) when done
 await container.close();
 ```
 
@@ -51,6 +53,20 @@ if (metadata) {
 await container.close();
 ```
 
+## Options
+
+Both options are optional:
+
+```ts
+const container = new Container("https://example.org/planet.versatiles", {
+  tms: true, // read y=0 as the southernmost row (TMS ordering); default false
+  timeout: 30000, // idle timeout in ms for HTTP(S) sources; default 10000
+});
+```
+
+`timeout` applies while waiting for response headers and between body chunks, so a slow but
+progressing download is not aborted. It has no effect on local files or on a custom reader.
+
 ## Handle missing tiles
 
 Coordinates must lie within the zoom level's grid (`0 <= x, y < 2 ** z`), otherwise `getTile` throws a `RangeError`. For a valid coordinate that simply has no data, the container returns `null`:

package/dist/index.d.ts

@@ -12,9 +12,8 @@
  *   from the module's `interfaces.js` file to ensure type safety and consistency.
  *
  * Exported Constants:
- * - `FORMATS`: Supported formats organized by version for different tile data, including image formats (e.g., PNG, JPG)
- *   and vector formats (e.g., PBF).
- * - `COMPRESSIONS`: Available compression types, including 'raw' (no compression), 'gzip', and 'br' (Brotli).
+ * - `FORMATS`: Supported tile formats, including image formats (e.g., PNG, JPG) and vector formats (e.g., PBF).
+ * - `COMPRESSIONS`: Available compression types, including 'raw' (no compression), 'gzip', 'br' (Brotli) and 'zstd' (Zstandard).
  * - `MIMETYPES`: Maps supported tile formats to their respective MIME types for handling and delivery.
  *
  * Exported Types:
@@ -46,8 +45,10 @@ export declare class Container {
      *
      * @param source - The data source for the tiles. This can be a URL starting with `http://` or `https://`,
      * a path to a local file, or a custom `Reader` function that reads data chunks based on offset and length.
-     * @param options - Optional settings that configure tile handling.
+     * @param options - Optional settings that configure tile handling. See {@link OpenOptions}; `timeout`
+     * only applies when `source` is an HTTP(S) URL.
      * @throws Will throw an error if the provided source is neither a string nor a Reader function.
+     * @throws Will throw an error if `source` is a path to a file that cannot be opened.
      */
     constructor(source: Reader | string, options?: OpenOptions);
     /**
@@ -55,14 +56,21 @@ export declare class Container {
      *
      * @returns A promise that resolves with the header object.
      * @throws Will throw an error if the container does not start with expected magic bytes indicating a valid format.
+     * @throws Will throw an error if the container is a `versatiles_v01` file. That format is obsolete and
+     *   no longer readable by this library; convert such containers to v02 first.
+     * @throws Will throw an error if `tile_format` or `precompression` holds a value this library does not support.
+     *   Such a container is rejected rather than read with a substituted default, as required by the
+     *   [container spec](https://github.com/versatiles-org/versatiles-spec/blob/main/v02/readme.md#2-general-guidelines).
      */
     getHeader(): Promise<Header>;
     /**
      * Asynchronously retrieves the metadata associated with the `.versatiles` container.
-     * Metadata typically includes information about `vector_layers` for vector tiles.
-     * If the container does not include metadata, this method returns `null`.
+     * Metadata is stored as a string, usually TileJSON, and typically includes information
+     * about `vector_layers` for vector tiles.
+     * If the container does not include metadata, this method returns `undefined`.
      *
-     * @returns A promise that resolves with an object representing the metadata.
+     * @returns A promise that resolves with the metadata string, or `undefined` if the
+     *   container holds no metadata.
      */
     getMetadata(): Promise<string | undefined>;
     /**
@@ -107,11 +115,11 @@ export declare class Container {
      */
     protected getTileIndex(block: Block): Promise<TileIndex>;
     /**
-     * Releases any resources held by the underlying reader, such as an open file
-     * descriptor when reading from a local file. Readers that hold no resources
-     * (e.g. the HTTP reader or a custom `Reader` function without a `close`
-     * method) are unaffected. After calling `close`, no further methods should
-     * be called on this container.
+     * Releases any resources held by the underlying reader: the open file descriptor
+     * when reading from a local file, or the pooled keep-alive sockets when reading
+     * over HTTP(S). A custom `Reader` function without a `close` method is left
+     * untouched. After calling `close`, no further methods should be called on this
+     * container.
      *
      * @returns A promise that resolves once the reader has been closed.
      */

package/dist/index.js

@@ -12,9 +12,8 @@
  *   from the module's `interfaces.js` file to ensure type safety and consistency.
  *
  * Exported Constants:
- * - `FORMATS`: Supported formats organized by version for different tile data, including image formats (e.g., PNG, JPG)
- *   and vector formats (e.g., PBF).
- * - `COMPRESSIONS`: Available compression types, including 'raw' (no compression), 'gzip', and 'br' (Brotli).
+ * - `FORMATS`: Supported tile formats, including image formats (e.g., PNG, JPG) and vector formats (e.g., PBF).
+ * - `COMPRESSIONS`: Available compression types, including 'raw' (no compression), 'gzip', 'br' (Brotli) and 'zstd' (Zstandard).
  * - `MIMETYPES`: Maps supported tile formats to their respective MIME types for handling and delivery.
  *
  * Exported Types:
@@ -36,48 +35,45 @@
 import HttpReader from './lib/reader_http.js';
 import FileReader from './lib/reader_file.js';
 import { decompress } from './lib/decompress.js';
-const FORMATS = {
-    v01: ['png', 'jpg', 'webp', 'pbf'],
-    v02: [
-        'bin',
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        'png',
-        'jpg',
-        'webp',
-        'avif',
-        'svg',
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        'pbf',
-        'geojson',
-        'topojson',
-        'json',
-    ],
-};
-const COMPRESSIONS = ['raw', 'gzip', 'br'];
+const FORMATS = [
+    'bin',
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    'png',
+    'jpg',
+    'webp',
+    'avif',
+    'svg',
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    null,
+    'pbf',
+    'geojson',
+    'topojson',
+    'json',
+];
+const COMPRESSIONS = ['raw', 'gzip', 'br', 'zstd'];
 const MIMETYPES = {
     avif: 'image/avif',
     bin: 'application/octet-stream',
@@ -107,15 +103,17 @@ export class Container {
      *
      * @param source - The data source for the tiles. This can be a URL starting with `http://` or `https://`,
      * a path to a local file, or a custom `Reader` function that reads data chunks based on offset and length.
-     * @param options - Optional settings that configure tile handling.
+     * @param options - Optional settings that configure tile handling. See {@link OpenOptions}; `timeout`
+     * only applies when `source` is an HTTP(S) URL.
      * @throws Will throw an error if the provided source is neither a string nor a Reader function.
+     * @throws Will throw an error if `source` is a path to a file that cannot be opened.
      */
     constructor(source, options) {
         if (options)
             Object.assign(this.#options, options);
         if (typeof source === 'string') {
             if (source.startsWith('https://') || source.startsWith('http://')) {
-                this.#reader = HttpReader(source);
+                this.#reader = HttpReader(source, this.#options.timeout);
             }
             else {
                 this.#reader = FileReader(source);
@@ -133,6 +131,11 @@ export class Container {
      *
      * @returns A promise that resolves with the header object.
      * @throws Will throw an error if the container does not start with expected magic bytes indicating a valid format.
+     * @throws Will throw an error if the container is a `versatiles_v01` file. That format is obsolete and
+     *   no longer readable by this library; convert such containers to v02 first.
+     * @throws Will throw an error if `tile_format` or `precompression` holds a value this library does not support.
+     *   Such a container is rejected rather than read with a substituted default, as required by the
+     *   [container spec](https://github.com/versatiles-org/versatiles-spec/blob/main/v02/readme.md#2-general-guidelines).
      */
     async getHeader() {
         // deliver if known
@@ -140,41 +143,38 @@ export class Container {
             return this.#header;
         const data = await this.read(0, 66);
         // check magic bytes
-        if (!/^versatiles_v0[12]$/.test(data.toString('utf8', 0, 14))) {
+        const magic = data.toString('utf8', 0, 14);
+        if (magic === 'versatiles_v01') {
+            throw new Error('versatiles_v01 containers are no longer supported. Convert it to v02 with: versatiles convert <input> <output>');
+        }
+        if (magic !== 'versatiles_v02') {
             throw new Error('Invalid Container');
         }
-        const magic = data.toString('utf8', 0, 14);
         const version = data.toString('utf8', 11, 14);
-        const tileFormat = FORMATS[version][data.readUInt8(14)] ?? 'bin';
+        const tileFormatValue = data.readUInt8(14);
+        const tileFormat = FORMATS[tileFormatValue] ?? null;
+        if (tileFormat === null) {
+            throw new Error(`Unsupported tile_format value ${tileFormatValue} in ${version} container header`);
+        }
         const tileMime = MIMETYPES[tileFormat];
-        const tileCompression = COMPRESSIONS[data.readUInt8(15)] ?? 'raw';
+        const compressionValue = data.readUInt8(15);
+        const tileCompression = COMPRESSIONS[compressionValue];
+        if (tileCompression === undefined) {
+            throw new Error(`Unsupported precompression value ${compressionValue} in ${version} container header`);
+        }
         const zoomMin = data.readUInt8(16);
         const zoomMax = data.readUInt8(17);
-        let bbox;
         const metaOffset = Number(data.readBigUInt64BE(34));
         const metaLength = Number(data.readBigUInt64BE(42));
         const blockIndexOffset = Number(data.readBigUInt64BE(50));
         const blockIndexLength = Number(data.readBigUInt64BE(58));
-        switch (version) {
-            case 'v01':
-                bbox = [
-                    data.readFloatBE(18),
-                    data.readFloatBE(22),
-                    data.readFloatBE(26),
-                    data.readFloatBE(30),
-                ];
-                break;
-            case 'v02':
-                bbox = [
-                    data.readInt32BE(18) / 1e7,
-                    data.readInt32BE(22) / 1e7,
-                    data.readInt32BE(26) / 1e7,
-                    data.readInt32BE(30) / 1e7,
-                ];
-                break;
-            default:
-                throw new Error('Invalid Container');
-        }
+        // bbox coordinates are stored as int32, scaled by 1e7
+        const bbox = [
+            data.readInt32BE(18) / 1e7,
+            data.readInt32BE(22) / 1e7,
+            data.readInt32BE(26) / 1e7,
+            data.readInt32BE(30) / 1e7,
+        ];
         this.#header = {
             magic,
             version,
@@ -193,10 +193,12 @@ export class Container {
     }
     /**
      * Asynchronously retrieves the metadata associated with the `.versatiles` container.
-     * Metadata typically includes information about `vector_layers` for vector tiles.
-     * If the container does not include metadata, this method returns `null`.
+     * Metadata is stored as a string, usually TileJSON, and typically includes information
+     * about `vector_layers` for vector tiles.
+     * If the container does not include metadata, this method returns `undefined`.
      *
-     * @returns A promise that resolves with an object representing the metadata.
+     * @returns A promise that resolves with the metadata string, or `undefined` if the
+     *   container holds no metadata.
      */
     async getMetadata() {
         if (this.#metadata !== undefined)
@@ -263,8 +265,8 @@ export class Container {
         const j = (ty - block.rowMin) * (block.colMax - block.colMin + 1) + (tx - block.colMin);
         // get tile index
         const tileIndex = await this.getTileIndex(block);
-        const offset = tileIndex.offsets[j];
-        const length = tileIndex.lengths[j];
+        const offset = tileIndex.offsets[j] ?? 0;
+        const length = tileIndex.lengths[j] ?? 0;
         if (length === 0)
             return null;
         return this.read(offset, length);
@@ -303,26 +305,13 @@ export class Container {
         data = await decompress(data, 'br');
         // read index from buffer
         const blocks = [];
-        switch (header.version) {
-            case 'v01':
-                // check block index length
-                if (data.length % 29 !== 0)
-                    throw new Error('invalid block index');
-                for (let i = 0; i < data.length; i += 29) {
-                    const slice = data.subarray(i, i + 29);
-                    addBlock(slice, 0n, slice.readBigUInt64BE(13), slice.readBigUInt64BE(21));
-                }
-                break;
-            case 'v02':
-                // check block index length
-                if (data.length % 33 !== 0)
-                    throw new Error('invalid block index');
-                for (let i = 0; i < data.length; i += 33) {
-                    const slice = data.subarray(i, i + 33);
-                    addBlock(slice, slice.readBigUInt64BE(13), slice.readBigUInt64BE(13) + slice.readBigUInt64BE(21), // block_offset + tile_blobs_length
-                    slice.readUInt32BE(29));
-                }
-                break;
+        // check block index length
+        if (data.length % 33 !== 0)
+            throw new Error('invalid block index');
+        for (let i = 0; i < data.length; i += 33) {
+            const slice = data.subarray(i, i + 33);
+            addBlock(slice, slice.readBigUInt64BE(13), slice.readBigUInt64BE(13) + slice.readBigUInt64BE(21), // block_offset + tile_blobs_length
+            slice.readUInt32BE(29));
         }
         // build map
         this.#blockIndex = new Map(blocks.map((b) => [`${b.level},${b.column},${b.row}`, b]));
@@ -338,7 +327,7 @@ export class Container {
                 rowMax: buffer.readUInt8(12),
                 blockOffset: Number(blockOffset),
                 tileIndexOffset: Number(tileIndexOffset),
-                tileIndexLength: Number(tileIndexLength),
+                tileIndexLength,
                 tileCount: 0,
             };
             block.tileCount = (block.colMax - block.colMin + 1) * (block.rowMax - block.rowMin + 1);
@@ -379,11 +368,11 @@ export class Container {
         return block.tileIndex;
     }
     /**
-     * Releases any resources held by the underlying reader, such as an open file
-     * descriptor when reading from a local file. Readers that hold no resources
-     * (e.g. the HTTP reader or a custom `Reader` function without a `close`
-     * method) are unaffected. After calling `close`, no further methods should
-     * be called on this container.
+     * Releases any resources held by the underlying reader: the open file descriptor
+     * when reading from a local file, or the pooled keep-alive sockets when reading
+     * over HTTP(S). A custom `Reader` function without a `close` method is left
+     * untouched. After calling `close`, no further methods should be called on this
+     * container.
      *
      * @returns A promise that resolves once the reader has been closed.
      */

package/dist/lib/decompress.d.ts

@@ -1,13 +1,14 @@
 import type { Compression } from './interfaces.js';
 /**
- * Decompresses a buffer using the specified compression algorithm. Currently supports 'br' for Brotli and 'gzip' for GZIP.
- * If the specified algorithm is not supported, the function resolves the promise with the original buffer.
+ * Decompresses a buffer using the specified compression algorithm. Currently supports 'br' for Brotli, 'gzip' for GZIP
+ * and 'zstd' for Zstandard. For 'raw' the buffer is passed through unchanged. Any other value is rejected rather than passed through, so that
+ * data the library cannot decompress is never handed back mislabelled as uncompressed.
  *
  * @param {Buffer} buffer - The buffer to be decompressed.
- * @param {Compression} compression - The compression algorithm to use. Supported values are 'br' for Brotli and 'gzip' for GZIP.
- * @returns {Promise<Buffer>} A promise that, when resolved, provides the decompressed buffer. If the compression type is not recognized,
- * the promise will resolve with the original buffer. If decompression fails, the promise will be rejected with an error message.
- * @throws {Error} Throws an error if the decompression process encounters an error. The error includes the buffer's length and
- * the compression algorithm that was attempted.
+ * @param {Compression} compression - The compression algorithm to use. Supported values are 'br' for Brotli, 'gzip' for GZIP, 'zstd' for Zstandard and 'raw' for uncompressed data.
+ * @returns {Promise<Buffer>} A promise that, when resolved, provides the decompressed buffer. If decompression fails,
+ * the promise will be rejected with an error message.
+ * @throws {Error} Throws an error if the compression algorithm is unsupported, or if the decompression process encounters
+ * an error. The error includes the buffer's length and the compression algorithm that was attempted.
  */
 export declare function decompress(buffer: Buffer, compression: Compression): Promise<Buffer>;

package/dist/lib/decompress.js

@@ -1,14 +1,15 @@
 import zlib from 'zlib';
 /**
- * Decompresses a buffer using the specified compression algorithm. Currently supports 'br' for Brotli and 'gzip' for GZIP.
- * If the specified algorithm is not supported, the function resolves the promise with the original buffer.
+ * Decompresses a buffer using the specified compression algorithm. Currently supports 'br' for Brotli, 'gzip' for GZIP
+ * and 'zstd' for Zstandard. For 'raw' the buffer is passed through unchanged. Any other value is rejected rather than passed through, so that
+ * data the library cannot decompress is never handed back mislabelled as uncompressed.
  *
  * @param {Buffer} buffer - The buffer to be decompressed.
- * @param {Compression} compression - The compression algorithm to use. Supported values are 'br' for Brotli and 'gzip' for GZIP.
- * @returns {Promise<Buffer>} A promise that, when resolved, provides the decompressed buffer. If the compression type is not recognized,
- * the promise will resolve with the original buffer. If decompression fails, the promise will be rejected with an error message.
- * @throws {Error} Throws an error if the decompression process encounters an error. The error includes the buffer's length and
- * the compression algorithm that was attempted.
+ * @param {Compression} compression - The compression algorithm to use. Supported values are 'br' for Brotli, 'gzip' for GZIP, 'zstd' for Zstandard and 'raw' for uncompressed data.
+ * @returns {Promise<Buffer>} A promise that, when resolved, provides the decompressed buffer. If decompression fails,
+ * the promise will be rejected with an error message.
+ * @throws {Error} Throws an error if the compression algorithm is unsupported, or if the decompression process encounters
+ * an error. The error includes the buffer's length and the compression algorithm that was attempted.
  */
 export async function decompress(buffer, compression) {
     return new Promise((resolve, reject) => {
@@ -19,9 +20,15 @@ export async function decompress(buffer, compression) {
             case 'gzip':
                 zlib.gunzip(buffer, handle);
                 break;
-            default:
+            case 'zstd':
+                zlib.zstdDecompress(buffer, handle);
+                break;
+            case 'raw':
                 resolve(buffer);
                 break;
+            default:
+                reject(new Error(`Can not decompress buffer (length=${buffer.length}): unsupported compression "${String(compression)}"`));
+                break;
         }
         /**
          * Handles the result of the decompression operation. If decompression is successful, the promise is resolved

package/dist/lib/interfaces.d.ts

@@ -1,20 +1,12 @@
 /**
  * Supported compression.
- * `null` signifies that the data is uncompressed.
+ * `'raw'` signifies that the data is uncompressed.
  */
-export type Compression = 'br' | 'gzip' | 'raw';
+export type Compression = 'br' | 'gzip' | 'raw' | 'zstd';
 /**
  * Supported tile formats.
  */
 export type Format = 'avif' | 'bin' | 'geojson' | 'jpg' | 'json' | 'pbf' | 'png' | 'svg' | 'topojson' | 'webp';
-/**
- * Type definition for a function that decompresses data.
- *
- * @param {Buffer} data - The compressed data.
- * @param {Compression} compression - The type of compression used.
- * @returns {Promise<Buffer>} - The decompressed data.
- */
-export type Decompressor = (data: Buffer, compression: Compression) => Promise<Buffer>;
 /**
  * Type definition for reading content from a VersaTiles container.
  *
@@ -120,8 +112,15 @@ export interface TileIndex {
 }
 /**
  * Interface for defining the options available for reading a container.
- * @property {boolean} tms - If set to true, uses the [TMS (Tile Map Service) tile ordering](https://wiki.openstreetmap.org/wiki/TMS) where y=0 is the southernmost point.
+ *
+ * All properties are optional; omitted ones fall back to the documented default.
+ *
+ * @property {boolean} tms - If set to true, uses the [TMS (Tile Map Service) tile ordering](https://wiki.openstreetmap.org/wiki/TMS) where y=0 is the southernmost point. Defaults to `false`.
+ * @property {number} timeout - Idle timeout in milliseconds for HTTP(S) sources, applied both while
+ *   waiting for the response headers and between body chunks. Has no effect on local files or on a
+ *   custom {@link Reader}, which manages its own timeouts. Defaults to 10000.
  */
 export interface OpenOptions {
-    tms: boolean;
+    tms?: boolean;
+    timeout?: number;
 }

package/dist/lib/reader_file.d.ts

@@ -11,9 +11,8 @@ import type { Reader } from './interfaces.js';
  * @returns {Reader} A reader function that when called, returns a promise. This promise resolves with a
  *                   Buffer containing the read bytes from the file. The function reads `length` bytes of data
  *                   from the file starting at `position`. If an error occurs during the read operation,
- *                   the promise is rejected with the error. If `position` is beyond the end of the file,
- *                   the promise resolves to an empty buffer. If the read operation attempts to read beyond
- *                   the end of the file, the promise resolves with a buffer that contains only the bytes
- *                   that could be read.
+ *                   the promise is rejected with the error. Reads are bounds-checked against the file size
+ *                   captured when the reader was created: a range that ends beyond the end of the file is
+ *                   rejected with a `RangeError` rather than returning a short buffer.
  */
 export default function getFileReader(filename: string): Reader;

package/dist/lib/reader_file.js

@@ -11,10 +11,9 @@ import fs from 'node:fs';
  * @returns {Reader} A reader function that when called, returns a promise. This promise resolves with a
  *                   Buffer containing the read bytes from the file. The function reads `length` bytes of data
  *                   from the file starting at `position`. If an error occurs during the read operation,
- *                   the promise is rejected with the error. If `position` is beyond the end of the file,
- *                   the promise resolves to an empty buffer. If the read operation attempts to read beyond
- *                   the end of the file, the promise resolves with a buffer that contains only the bytes
- *                   that could be read.
+ *                   the promise is rejected with the error. Reads are bounds-checked against the file size
+ *                   captured when the reader was created: a range that ends beyond the end of the file is
+ *                   rejected with a `RangeError` rather than returning a short buffer.
  */
 export default function getFileReader(filename) {
     const fd = fs.openSync(filename, 'r');
@@ -26,16 +25,15 @@ export default function getFileReader(filename) {
      * that are not being concurrently modified, as it relies on consistent file state to
      * function correctly.
      *
-     * @param {number} position - The starting position in the file to read from. If this position
-     *                            is beyond the end of the file, the function will resolve to an
-     *                            empty buffer.
+     * @param {number} position - The starting position in the file to read from. Must be non-negative.
      * @param {number} length   - The number of bytes to read from the file starting at `position`.
-     *                            If `length` extends beyond the end of the file, the returned buffer
-     *                            will only include the bytes that could be read up to the end of the file.
+     *                            Must be non-negative.
      * @returns {Promise<Buffer>} A promise that resolves with the buffer containing the read bytes. If
-     *                            an error occurs during the read, such as if the position is invalid or
-     *                            the file descriptor becomes invalid due to the file being closed, the
-     *                            promise will be rejected with an error.
+     *                            an error occurs during the read, such as the file descriptor becoming
+     *                            invalid due to the file being closed, the promise will be rejected with
+     *                            an error.
+     * @throws {RangeError} If `position` or `length` is negative, or if `position + length` exceeds the
+     *                      size of the file.
      */
     const read = async function read(position, length) {
         if (position < 0) {

package/dist/lib/reader_http.d.ts

@@ -4,6 +4,10 @@ import type { Reader } from './interfaces.js';
  * to read data chunks in an HTTP GET request. This is particularly useful for
  * operations such as streaming or handling large data in segments.
  *
+ * The returned reader keeps HTTP connections alive between reads, which matters because
+ * reading a container issues many small range requests. Call its `close` method when done
+ * to release those pooled sockets.
+ *
  * @param url - The URL from which data will be read.
  * @param timeout - Idle timeout in milliseconds applied both while waiting for the
  *   response headers and between body chunks. Defaults to {@link DEFAULT_TIMEOUT}.

package/dist/lib/reader_http.js

@@ -5,14 +5,18 @@ const DEFAULT_TIMEOUT = 10000;
  * A collection mapping protocol names to their respective `ClientInfo`.
  */
 const clients = {
-    https: { client: https, agent: new https.Agent({ keepAlive: true }) },
-    http: { client: http, agent: new http.Agent({ keepAlive: true }) },
+    https: { client: https, createAgent: () => new https.Agent({ keepAlive: true }) },
+    http: { client: http, createAgent: () => new http.Agent({ keepAlive: true }) },
 };
 /**
  * Creates a function capable of reading data from a specified URL, which can be used
  * to read data chunks in an HTTP GET request. This is particularly useful for
  * operations such as streaming or handling large data in segments.
  *
+ * The returned reader keeps HTTP connections alive between reads, which matters because
+ * reading a container issues many small range requests. Call its `close` method when done
+ * to release those pooled sockets.
+ *
  * @param url - The URL from which data will be read.
  * @param timeout - Idle timeout in milliseconds applied both while waiting for the
  *   response headers and between body chunks. Defaults to {@link DEFAULT_TIMEOUT}.
@@ -20,9 +24,12 @@ const clients = {
  */
 export default function getHTTPReader(url, timeout = DEFAULT_TIMEOUT) {
     const protocol = new URL(url).protocol.slice(0, -1);
-    if (!(protocol in clients)) {
+    const clientInfo = clients[protocol];
+    if (clientInfo == null) {
         throw new Error(`Unsupported protocol: ${protocol}`);
     }
+    const { client, createAgent } = clientInfo;
+    const agent = createAgent();
     /**
      * Asynchronously reads a data chunk from the provided URL based on the specified range.
      *
@@ -32,7 +39,7 @@ export default function getHTTPReader(url, timeout = DEFAULT_TIMEOUT) {
      *          If the request fails or the server responds with a non-successful status code,
      *          the promise is rejected with an error.
      */
-    return async function read(position, length) {
+    const read = async function read(position, length) {
         if (position < 0) {
             throw new RangeError(`Invalid read position: ${position}. The read position must be a non-negative integer.`);
         }
@@ -40,7 +47,7 @@ export default function getHTTPReader(url, timeout = DEFAULT_TIMEOUT) {
             throw new RangeError(`Invalid read length: ${length}. The read length must be a non-negative integer.`);
         }
         const headers = {
-            'user-agent': 'Mozilla/5.0 (compatible; versatiles; +https://www.npmjs.com/package/versatiles)',
+            'user-agent': 'Mozilla/5.0 (compatible; versatiles; +https://www.npmjs.com/package/@versatiles/container)',
             range: `bytes=${position}-${position + length - 1}`,
         };
         /**
@@ -52,10 +59,10 @@ export default function getHTTPReader(url, timeout = DEFAULT_TIMEOUT) {
                 req.destroy();
                 reject(new Error('Request timed out'));
             }, timeout);
-            const req = clients[protocol].client
+            const req = client
                 .request(url, {
                 method: 'GET',
-                agent: clients[protocol].agent,
+                agent,
                 headers,
                 timeout,
             })
@@ -89,12 +96,17 @@ export default function getHTTPReader(url, timeout = DEFAULT_TIMEOUT) {
         const parts = /^bytes (\d+)-(\d+)\/(\d+)/i.exec(contentRange);
         if (parts == null)
             fail(new Error('"content-range" in response header is malformed'));
-        if (position !== parseInt(parts[1], 10))
-            fail(new Error(`requested position (${position}) and returned offset (${parts[1]}) must be equal`));
-        if (position + length > parseInt(parts[3], 10)) {
-            fail(new RangeError(`Read range out of bounds: The requested range ends at position ${position + length}, which exceeds the file's limit of ${parts[3]} bytes.`));
+        // The pattern matches digits only, so these are finite numbers whenever it
+        // matched; Number() of a missing group would be NaN, which fails the same checks.
+        const returnedOffset = Number(parts[1]);
+        const returnedLast = Number(parts[2]);
+        const totalSize = Number(parts[3]);
+        if (position !== returnedOffset)
+            fail(new Error(`requested position (${position}) and returned offset (${returnedOffset}) must be equal`));
+        if (position + length > totalSize) {
+            fail(new RangeError(`Read range out of bounds: The requested range ends at position ${position + length}, which exceeds the file's limit of ${totalSize} bytes.`));
         }
-        const returnedLength = parseInt(parts[2], 10) + 1 - position;
+        const returnedLength = returnedLast + 1 - position;
         if (length !== returnedLength) {
             fail(new Error(`Returned length (${returnedLength}) is not requested length (${length}).`));
         }
@@ -130,4 +142,13 @@ export default function getHTTPReader(url, timeout = DEFAULT_TIMEOUT) {
         });
         return body;
     };
+    /**
+     * Destroys this reader's connection agent, closing any sockets it is holding
+     * open for keep-alive. After this resolves, the reader must not be called again.
+     */
+    read.close = function close() {
+        agent.destroy();
+        return Promise.resolve();
+    };
+    return read;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/container",
-  "version": "1.5.1",
+  "version": "2.0.1",
   "description": "A client library for reading VersaTiles containers",
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && npm run doc-graph",
@@ -28,11 +28,19 @@
   "homepage": "https://github.com/versatiles-org/node-versatiles-container",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "type": "module",
+  "sideEffects": false,
   "author": "yetzt <node@yetzt.me>, Michael Kreil <versatiles@michael-kreil.de>",
   "license": "Unlicense",
   "engines": {
-    "node": ">= 18"
+    "node": ">= 22.15"
   },
   "keywords": [
     "cloudtiles",
@@ -54,18 +62,18 @@
   ],
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^26.2.0",
-    "@typescript-eslint/eslint-plugin": "^8.67.0",
-    "@typescript-eslint/parser": "^8.67.0",
-    "@versatiles/release-tool": "^2.9.0",
-    "@vitest/coverage-v8": "^4.1.11",
-    "eslint": "^10.8.1",
+    "@types/node": "^26.6.4",
+    "@typescript-eslint/eslint-plugin": "^8.71.0",
+    "@typescript-eslint/parser": "^8.71.0",
+    "@versatiles/release-tool": "^2.19.1",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
-    "prettier": "^3.9.6",
-    "tsx": "^4.23.12",
+    "prettier": "^3.9.9",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.67.0",
-    "vitest": "^4.1.11"
+    "typescript-eslint": "^8.71.0",
+    "vitest": "^5.0.3"
   },
   "allowScripts": {
     "esbuild": true,