@versatiles/container 1.4.2 → 1.5.1

package/README.md

@@ -10,9 +10,11 @@ A client library for [VersaTiles containers](https://github.com/versatiles-org/v
 
 `npm i @versatiles/container`
 
-# Usage Example
+# Usage Examples
 
-```js
+## Basic: read a tile and write to disk
+
+```ts
 import { Container } from "@versatiles/container";
 import fs from "fs";
 
@@ -20,6 +22,63 @@ const container = new Container("https://example.org/planet.versatiles");
 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
+await container.close();
+```
+
+## Inspect tile metadata
+
+VersaTiles containers can carry JSON metadata describing vector tile layers:
+
+```ts
+import { Container } from "@versatiles/container";
+
+const container = new Container("/path/to/layers.versatiles");
+
+const header = await container.getHeader();
+console.log("Format:", header.tileFormat);  // e.g. "pbf"
+console.log("Compression:", header.tileCompression);
+console.log("Zoom range:", header.zoomMin, "→", header.zoomMax);
+console.log("Bounding box:", header.bbox);
+
+const metadata = await container.getMetadata();
+if (metadata) {
+  const parsed = JSON.parse(metadata);
+  console.log("Vector layers:", parsed.vector_layers?.length);
+}
+
+await container.close();
+```
+
+## 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`:
+
+```ts
+const tile = await container.getTileUncompressed(12, 100, 4000);
+if (!tile) {
+  console.log("Tile does not exist in this container");
+}
+```
+
+## Custom reader (e.g. S3, in-memory)
+
+For custom storage backends, implement the `Reader` interface:
+
+```ts
+import type { Reader } from "@versatiles/container";
+import { Container } from "@versatiles/container";
+
+const myReader: Reader = async (offset, length) => {
+  // e.g. fetch from an S3 bucket or read from a typed array
+  const buffer = Buffer.alloc(length);
+  // … fill buffer with data starting at offset …
+  return buffer;
+};
+
+const container = new Container(myReader);
+const header = await container.getHeader();
 ```
 
 # API

package/dist/index.d.ts

@@ -96,7 +96,7 @@ export declare class Container {
      * @returns A promise that resolves with the block index map.
      * @protected
      */
-    getBlockIndex(): Promise<Map<string, Block>>;
+    protected getBlockIndex(): Promise<Map<string, Block>>;
     /**
      * Asynchronously retrieves the tile index for a specified block. This is an internal method used to
      * maintain a lookup for every tile within a block.
@@ -105,7 +105,17 @@ export declare class Container {
      * @returns A promise that resolves with the tile index.
      * @protected
      */
-    getTileIndex(block: Block): Promise<TileIndex>;
+    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.
+     *
+     * @returns A promise that resolves once the reader has been closed.
+     */
+    close(): Promise<void>;
     /**
      * A protected method to read a chunk of data from the source based on the specified offset and length.
      *

package/dist/index.js

@@ -37,25 +37,6 @@ import HttpReader from './lib/reader_http.js';
 import FileReader from './lib/reader_file.js';
 import { decompress } from './lib/decompress.js';
 const FORMATS = {
-    c01: [
-        'png',
-        'jpg',
-        'webp',
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        null,
-        'pbf',
-    ],
     v01: ['png', 'jpg', 'webp', 'pbf'],
     v02: [
         'bin',
@@ -243,17 +224,31 @@ export class Container {
      * @returns A promise that resolves with the tile data as a Buffer, or null if the tile cannot be found.
      */
     async getTile(z, x, y) {
+        // validate coordinates: must be non-negative integers within the zoom level
+        if (!Number.isInteger(z) || !Number.isInteger(x) || !Number.isInteger(y)) {
+            throw new RangeError(`Tile coordinates must be integers, got z=${z}, x=${x}, y=${y}`);
+        }
+        // zoom is capped at 30: a tile coordinate at higher zoom would exceed 2^30
+        // and no longer be an exact integer under the arithmetic below
+        if (z < 0 || z > 30) {
+            throw new RangeError(`Zoom level must be between 0 and 30, got z=${z}`);
+        }
+        // x and y must lie inside the 2^z × 2^z tile grid for this zoom level
+        const size = 2 ** z;
+        if (x < 0 || x >= size || y < 0 || y >= size) {
+            throw new RangeError(`Tile coordinates out of range for zoom ${z}: x and y must be in [0, ${size}), got x=${x}, y=${y}`);
+        }
         // when y index is inverted
         if (this.#options.tms)
-            y = Math.pow(2, z) - y - 1;
+            y = size - y - 1;
         // ensure block index is loaded
         const blockIndex = await this.getBlockIndex();
-        // block xy
-        const bx = x >> 8;
-        const by = y >> 8;
+        // block xy (avoid bitwise ops: they coerce to int32 and break above zoom 30)
+        const bx = Math.floor(x / 256);
+        const by = Math.floor(y / 256);
         // tile xy (within block)
-        const tx = x & 0xff;
-        const ty = y & 0xff;
+        const tx = x % 256;
+        const ty = y % 256;
         // check if block containing tile is within bounds
         const blockKey = `${z},${bx},${by}`;
         const block = blockIndex.get(blockKey);
@@ -309,7 +304,6 @@ export class Container {
         // read index from buffer
         const blocks = [];
         switch (header.version) {
-            case 'c01':
             case 'v01':
                 // check block index length
                 if (data.length % 29 !== 0)
@@ -364,15 +358,38 @@ export class Container {
             return block.tileIndex;
         let buffer = await this.read(block.tileIndexOffset, block.tileIndexLength);
         buffer = await decompress(buffer, 'br');
+        // each tile entry is 12 bytes (8-byte offset + 4-byte length); guard against
+        // a truncated/corrupt index before indexing into the buffer below
+        if (buffer.length < block.tileCount * 12) {
+            throw new Error('invalid tile index');
+        }
         const offsets = new Float64Array(block.tileCount);
         const lengths = new Float64Array(block.tileCount);
         for (let i = 0; i < block.tileCount; i++) {
-            offsets[i] = Number(buffer.readBigUInt64BE(12 * i)) + block.blockOffset;
+            const offset = Number(buffer.readBigUInt64BE(12 * i)) + block.blockOffset;
+            // offsets are addressed as `number`; beyond 2^53 they can no longer be
+            // represented exactly, so surface it instead of reading corrupt data
+            if (!Number.isSafeInteger(offset)) {
+                throw new Error('invalid tile index: tile offset exceeds safe integer range (2^53)');
+            }
+            offsets[i] = offset;
             lengths[i] = buffer.readUInt32BE(12 * i + 8);
         }
         block.tileIndex = { offsets, lengths };
         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.
+     *
+     * @returns A promise that resolves once the reader has been closed.
+     */
+    async close() {
+        await this.#reader.close?.();
+    }
     /**
      * A protected method to read a chunk of data from the source based on the specified offset and length.
      *

package/dist/lib/interfaces.d.ts

@@ -20,6 +20,9 @@ export type Decompressor = (data: Buffer, compression: Compression) => Promise<B
  *
  * This is useful for implementing new container readers, e.g. reading over other network protocols.
  *
+ * A reader may optionally expose a `close` method to release any underlying
+ * resources (e.g. a file descriptor). {@link Container.close} calls it if present.
+ *
  * @param {number} position - The byte offset at which to start reading.
  * @param {number} length - The number of bytes to read.
  * @returns {Promise<Buffer>} A promise that resolves with the data read as a Buffer.
@@ -27,7 +30,15 @@ export type Decompressor = (data: Buffer, compression: Compression) => Promise<B
  * @throws {RangeError} If the sum of `position` and `length` exceeds the size of the content (filesize).
  * @throws {Error} If there is any filesystem or network error such as the content not being accessible or readable.
  */
-export type Reader = (position: number, length: number) => Promise<Buffer>;
+export interface Reader {
+    (position: number, length: number): Promise<Buffer>;
+    /**
+     * Releases any underlying resources held by the reader (e.g. an open file
+     * descriptor). Optional; readers that hold no resources may omit it.
+     * After `close` resolves, the reader must not be called again.
+     */
+    close?: () => Promise<void>;
+}
 /**
  * Interface for the metadata header of a `*.Versatiles` container.
  *
@@ -92,6 +103,14 @@ export interface Block {
 /**
  * Interface for the index structure used for tiles within a block.
  *
+ * Byte offsets are stored as `Float64Array`, which represents integers exactly
+ * up to `Number.MAX_SAFE_INTEGER` (2^53 − 1, ~9 PB). This is not a limitation of
+ * this type specifically: the {@link Reader} contract addresses data by `number`
+ * position, and both `fs.read` and HTTP byte-range requests are likewise
+ * `Number`-based, so 2^53 is the effective addressing limit of the whole reader
+ * pipeline. Storing offsets as `BigInt` here would therefore not extend the
+ * reachable range.
+ *
  * @property {Float64Array} offsets - Array indicating the start byte positions of tiles within the block.
  * @property {Float64Array} lengths - Array specifying the byte lengths of the tiles. A length of 0 means the tile is not stored.
  */

package/dist/lib/reader_file.js

@@ -37,7 +37,7 @@ export default function getFileReader(filename) {
      *                            the file descriptor becomes invalid due to the file being closed, the
      *                            promise will be 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.`);
         }
@@ -61,4 +61,14 @@ export default function getFileReader(filename) {
             });
         });
     };
+    /**
+     * Closes the underlying file descriptor. After this resolves, the reader
+     * must not be called again.
+     */
+    read.close = async function close() {
+        await new Promise((resolve, reject) => {
+            fs.close(fd, (err) => (err ? reject(err) : resolve()));
+        });
+    };
+    return read;
 }

package/dist/lib/reader_http.d.ts

@@ -5,6 +5,8 @@ import type { Reader } from './interfaces.js';
  * operations such as streaming or handling large data in segments.
  *
  * @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}.
  * @returns A `Reader` function that asynchronously reads a specified chunk of data from the URL.
  */
-export default function getHTTPReader(url: string): Reader;
+export default function getHTTPReader(url: string, timeout?: number): Reader;

package/dist/lib/reader_http.js

@@ -14,9 +14,11 @@ const clients = {
  * operations such as streaming or handling large data in segments.
  *
  * @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}.
  * @returns A `Reader` function that asynchronously reads a specified chunk of data from the URL.
  */
-export default function getHTTPReader(url) {
+export default function getHTTPReader(url, timeout = DEFAULT_TIMEOUT) {
     const protocol = new URL(url).protocol.slice(0, -1);
     if (!(protocol in clients)) {
         throw new Error(`Unsupported protocol: ${protocol}`);
@@ -49,13 +51,13 @@ export default function getHTTPReader(url) {
             const watchdog = setTimeout(() => {
                 req.destroy();
                 reject(new Error('Request timed out'));
-            }, DEFAULT_TIMEOUT);
+            }, timeout);
             const req = clients[protocol].client
                 .request(url, {
                 method: 'GET',
                 agent: clients[protocol].agent,
                 headers,
-                timeout: DEFAULT_TIMEOUT,
+                timeout,
             })
                 .on('response', (response) => {
                 clearTimeout(watchdog);
@@ -68,38 +70,61 @@ export default function getHTTPReader(url) {
             })
                 .end();
         });
-        if (message.statusCode == null || Math.floor(message.statusCode / 100) !== 2) {
+        /**
+         * Destroys the response (draining the socket / freeing the keep-alive
+         * connection) and then throws the given error. Every validation failure
+         * below must go through this so an unread response body never leaks a
+         * connection back to the keep-alive agent's pool.
+         */
+        function fail(error) {
             message.destroy();
-            throw new Error(`Server responded with status code: ${message.statusCode} `);
+            throw error;
+        }
+        if (message.statusCode == null || Math.floor(message.statusCode / 100) !== 2) {
+            fail(new Error(`Server responded with status code: ${message.statusCode} `));
         }
         const contentRange = message.headers['content-range'];
         if (contentRange == null)
-            throw Error('The response header does not contain "content-range"');
+            fail(new Error('The response header does not contain "content-range"'));
         const parts = /^bytes (\d+)-(\d+)\/(\d+)/i.exec(contentRange);
         if (parts == null)
-            throw Error('"content-range" in response header is malformed');
+            fail(new Error('"content-range" in response header is malformed'));
         if (position !== parseInt(parts[1], 10))
-            throw Error(`requested position (${position}) and returned offset (${parts[1]}) must be equal`);
+            fail(new Error(`requested position (${position}) and returned offset (${parts[1]}) must be equal`));
         if (position + length > parseInt(parts[3], 10)) {
-            throw 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.`);
+            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.`));
         }
         const returnedLength = parseInt(parts[2], 10) + 1 - position;
         if (length !== returnedLength) {
-            throw new Error(`Returned length (${returnedLength}) is not requested length (${length}).`);
+            fail(new Error(`Returned length (${returnedLength}) is not requested length (${length}).`));
         }
         /**
          * Collects and concatenates response data chunks into a buffer.
+         *
+         * An idle watchdog guards the download: it aborts the request if no data
+         * chunk arrives within `timeout` ms. The timer is reset on every chunk,
+         * so a slow-but-progressing transfer is not killed, while a stalled socket is.
          * @type {Buffer}
          */
         const body = await new Promise((resolve, reject) => {
             const buffers = [];
+            const watchdog = setTimeout(onTimeout, timeout);
+            function onTimeout() {
+                message.destroy();
+                reject(new Error('Request timed out'));
+            }
             message
-                .on('data', (chunk) => buffers.push(chunk))
+                .on('data', (chunk) => {
+                watchdog.refresh();
+                buffers.push(chunk);
+            })
                 .on('error', (err) => {
+                clearTimeout(watchdog);
                 message.destroy();
                 reject(err);
             })
                 .once('end', () => {
+                clearTimeout(watchdog);
                 resolve(Buffer.concat(buffers));
             });
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/container",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "description": "A client library for reading VersaTiles containers",
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && npm run doc-graph",
@@ -54,18 +54,21 @@
   ],
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.8.0",
-    "@typescript-eslint/eslint-plugin": "^8.59.3",
-    "@typescript-eslint/parser": "^8.59.3",
-    "@versatiles/release-tool": "^2.8.0",
-    "@vitest/coverage-v8": "^4.1.6",
-    "eslint": "^10.4.0",
+    "@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",
     "eslint-config-prettier": "^10.1.8",
-    "prettier": "^3.8.3",
-    "ts-node": "^10.9.2",
-    "tsx": "^4.22.0",
+    "prettier": "^3.9.6",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.3",
-    "vitest": "^4.1.6"
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.11"
+  },
+  "allowScripts": {
+    "esbuild": true,
+    "fsevents": true
   }
 }