@versatiles/container 1.0.0 → 1.0.2

package/README.md

@@ -1,29 +1,5 @@
 A client library for [VersaTiles containers](https://github.com/versatiles-org/versatiles-spec).
 
-# Table of Content
-
-* [Install](#install)
-* [Usage Example](#usage-example)
-* [API](#api)
-  * [Class: VersaTiles](#class_versatiles)
-    * [constructor: new VersaTiles(source, options)](#constructor-new-versatilessource-options)
-    * [async getHeader()](#async-getheader)
-    * [async getMetadata()](#async-getmetadata)
-    * [async getTileFormat()](#async-gettileformat)
-    * [async getBlockIndex()](#async-getblockindex)
-    * [async getTileIndex(block)](#async-gettileindexblock)
-    * [async getTile(z, x, y)](#async-gettilez-x-y)
-    * [async getTileUncompressed(z, x, y)](#async-gettileuncompressedz-x-y)
-  * [Interface: Block](#interface_block)
-  * [Interface: Header](#interface_header)
-  * [Interface: Options](#interface_options)
-  * [Interface: TileIndex](#interface_tileindex)
-  * [Type: Compression](#type_compression)
-  * [Type: Format](#type_format)
-  * [Type: Reader](#type_reader)
-* [License](#license)
-* [Future work](#future-work)
-
 # Install
 
 `npm i versatiles`
@@ -42,199 +18,175 @@ fs.writeFileSync('tile.' + header.tile_format, tile);
 
 # API
 
-## Class: `VersaTiles`<a id="class_versatiles"></a>
+<!--- This chapter is generated automatically --->
+
+<details>
+
+<summary><h2>Class: <code>VersaTiles</code><a id="class_versatiles"></a></h2></summary>
 
 The `VersaTiles` class is a wrapper around a `.versatiles` container file. It provides methods\
-to access tile data, metadata, and other properties within the container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L27">\[src]</a></sup>
+to access tile data, metadata, and other properties within the container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/index.ts#L27">\[src]</a></sup>
+
+<details>
 
-### constructor: `new VersaTiles(source, options)`
+<summary><h3>Constructor: <code>new VersaTiles&#40;source, options&#41;</code></h3></summary>
 
-Constructs a new instance of the VersaTiles class. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L50">\[src]</a></sup>
+Constructs a new instance of the VersaTiles class. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/index.ts#L50">\[src]</a></sup>
 
 **Parameters:**
 
-* `source: string | `[`Reader`](#type_reader)\
+* <code>source: string | [Reader](#type_reader)</code>\
   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.
-* `options: `[`Options`](#interface_options) (optional)\
+* <code>options: [Options](#interface_options)</code> (optional)\
   Optional settings that configure tile handling.
 
-**Returns:** [`VersaTiles`](#class_versatiles)
-**Methods**
+**Returns:** <code>[VersaTiles](#class_versatiles)</code>
 
-### `async getHeader()`
+</details>
 
-Asynchronously retrieves the header information from the `.versatiles` container.\
-This method is primarily for internal use. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L75">\[src]</a></sup>
+<details>
 
-**Returns:** [`Header`](#interface_header)
-
-### `async getMetadata()`
-
-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`. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L133">\[src]</a></sup>
+<summary><h3>Method: <code>getHeader&#40;&#41;</code></h3></summary>
 
-**Returns:** `null | object`
+Asynchronously retrieves the header information from the `.versatiles` container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/index.ts#L74">\[src]</a></sup>
 
-### `async getTileFormat()`
+**Returns:** <code>Promise<[Header](#interface_header)></code>
 
-Asynchronously determines the tile format, such as "png" or "pbf", based on the header information. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L153">\[src]</a></sup>
+</details>
 
-**Returns:** [`Format`](#type_format)
+<details>
 
-### `async getBlockIndex()`
+<summary><h3>Method: <code>getMetadata&#40;&#41;</code></h3></summary>
 
-Asynchronously retrieves a mapping of tile block indices. The map's keys are formatted as "{z},{x},{y}".\
-This method is for internal use to manage tile lookup within the container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L165">\[src]</a></sup>
-
-**Returns:** `Map<string,`[`Block`](#interface_block)`>`
-
-### `async getTileIndex(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. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L244">\[src]</a></sup>
+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`. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/index.ts#L132">\[src]</a></sup>
 
-**Parameters:**
+**Returns:** <code>Promise\<null | object></code>
 
-* `block: `[`Block`](#interface_block)\
-  The block for which to retrieve the tile index.
+</details>
 
-**Returns:** [`TileIndex`](#interface_tileindex)
+<details>
 
-### `async getTile(z, x, y)`
+<summary><h3>Method: <code>getTile&#40;z, x, y&#41;</code></h3></summary>
 
 Asynchronously retrieves a specific tile's data as a Buffer. If the tile data is compressed as\
 defined in the container header, the returned Buffer will contain the compressed data.
 To obtain uncompressed data, use the `getTileUncompressed` method.
-If the specified tile does not exist, the method returns `null`. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L274">\[src]</a></sup>
+If the specified tile does not exist, the method returns `null`. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/index.ts#L158">\[src]</a></sup>
 
 **Parameters:**
 
-* `z: number`\
+* <code>z: number</code>\
   The zoom level of the tile.
-* `x: number`\
+* <code>x: number</code>\
   The x coordinate of the tile within its zoom level.
-* `y: number`\
+* <code>y: number</code>\
   The y coordinate of the tile within its zoom level.
 
-**Returns:** `null | Buffer`
+**Returns:** <code>Promise\<null | Buffer></code>
+
+</details>
 
-### `async getTileUncompressed(z, x, y)`
+<details>
+
+<summary><h3>Method: <code>getTileUncompressed&#40;z, x, y&#41;</code></h3></summary>
 
 Asynchronously retrieves a specific tile's uncompressed data as a Buffer. This method first\
 retrieves the compressed tile data using `getTile` and then decompresses it based on the
 compression setting in the container header.
-If the specified tile does not exist, the method returns `null`. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/index.ts#L322">\[src]</a></sup>
+If the specified tile does not exist, the method returns `null`. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/index.ts#L206">\[src]</a></sup>
 
 **Parameters:**
 
-* `z: number`\
+* <code>z: number</code>\
   The zoom level of the tile.
-* `x: number`\
+* <code>x: number</code>\
   The x coordinate of the tile within its zoom level.
-* `y: number`\
+* <code>y: number</code>\
   The y coordinate of the tile within its zoom level.
 
-**Returns:** `null | Buffer`
-
-## Interface: `Block`<a id="interface_block"></a>
-
-Interface for a block of tiles including necessary metadata.\
-For more details, refer to [spec v02](https://github.com/versatiles-org/versatiles-spec/blob/main/v02/readme.md#block_index). <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/interfaces.ts#L85">\[src]</a></sup>
-**Properties**
-
-* `level: number`\
-  The zoom level for this block.
-* `column: number`\
-  The column position of this block at the current zoom level.
-* `row: number`\
-  The row position of this block at the current zoom level.
-* `colMin: number`\
-  Minimum column index for tiles stored in this block (range: 0-255).
-* `rowMin: number`\
-  Minimum row index for tiles stored in this block (range: 0-255).
-* `colMax: number`\
-  Maximum column index for tiles stored in this block (range: 0-255).
-* `rowMax: number`\
-  Maximum row index for tiles stored in this block (range: 0-255).
-* `blockOffset: number`\
-  Byte position where this block starts in the file container.
-* `tileIndexOffset: number`\
-  Byte position where the tile index starts within the container.
-* `tileIndexLength: number`\
-  Length of the tile index in bytes.
-* `tileCount: number`\
-  The number of tiles contained in this block.
-* `tileIndex: `[`TileIndex`](#interface_tileindex) (optional)\
-  Optional tile index if it has been fetched.
-
-## Interface: `Header`<a id="interface_header"></a>
-
-Interface for the metadata header of a `*.Versatiles` container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/interfaces.ts#L52">\[src]</a></sup>
-**Properties**
-
-* `magic: string`\
+**Returns:** <code>Promise\<null | Buffer></code>
+
+</details>
+
+</details>
+
+<details>
+
+<summary><h2>Interface: <code>Header</code><a id="interface_header"></a></h2></summary>
+
+Interface for the metadata header of a `*.Versatiles` container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/interfaces.ts#L56">\[src]</a></sup>
+
+* <code>magic: string</code>\
   Identifier for the container format, usually "versatiles\_v02".
-* `version: string`\
+* <code>version: string</code>\
   Version of the container format, typically "v02".
-* `tileFormat: `[`Format`](#type_format)\
+* <code>tileFormat: [Format](#type_format)</code>\
   The format used for storing tiles.
-* `tileCompression: `[`Compression`](#type_compression)\
+* <code>tileCompression: [Compression](#type_compression)</code>\
   The type of compression applied to tiles.
-* `zoomMin: number`\
+* <code>zoomMin: number</code>\
   The minimum zoom level.
-* `zoomMax: number`\
+* <code>zoomMax: number</code>\
   The maximum zoom level.
-* `bbox: [number, number, number, number]`\
+* <code>bbox: \[number, number, number, number]</code>\
   Bounding box coordinates as \[lon\_min, lat\_min, lon\_max, lat\_max].
-* `metaOffset: number`\
+* <code>metaOffset: number</code>\
   The byte offset for metadata within the container.
-* `metaLength: number`\
+* <code>metaLength: number</code>\
   The byte size of the metadata. A value of 0 means no metadata.
-* `blockIndexOffset: number`\
+* <code>blockIndexOffset: number</code>\
   The byte offset for the block index within the container.
-* `blockIndexLength: number`\
+* <code>blockIndexLength: number</code>\
   The byte size of the block index. A value of 0 indicates no tiles in the container.
 
-## Interface: `Options`<a id="interface_options"></a>
+</details>
 
-Interface for defining the options available for reading a container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/interfaces.ts#L119">\[src]</a></sup>
-**Properties**
+<details>
 
-* `tms: boolean`\
-  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.
+<summary><h2>Interface: <code>Options</code><a id="interface_options"></a></h2></summary>
 
-## Interface: `TileIndex`<a id="interface_tileindex"></a>
+Interface for defining the options available for reading a container. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/interfaces.ts#L123">\[src]</a></sup>
 
-Interface for the index structure used for tiles within a block. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/interfaces.ts#L108">\[src]</a></sup>
-**Properties**
+* <code>tms: boolean</code>\
+  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.
+
+</details>
 
-* `offsets: Float64Array`\
-  Array indicating the start byte positions of tiles within the block.
-* `lengths: Float64Array`\
-  Array specifying the byte lengths of the tiles. A length of 0 means the tile is not stored.
+<details>
 
-## Type: `Compression`<a id="type_compression"></a>
+<summary><h2>Type: <code>Compression</code><a id="type_compression"></a></h2></summary>
 
 Supported compression.\
-`null` signifies that the data is uncompressed. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/interfaces.ts#L5">\[src]</a></sup>
+`null` signifies that the data is uncompressed. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/interfaces.ts#L5">\[src]</a></sup>
+
+**Type:** <code>"br" | "gzip" | null</code>
+
+</details>
+
+<details>
+
+<summary><h2>Type: <code>Format</code><a id="type_format"></a></h2></summary>
+
+Supported tile formats. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/interfaces.ts#L11">\[src]</a></sup>
 
-**Type:** `"br" | "gzip" | null`
+**Type:** <code>"avif" | "bin" | "geojson" | "jpeg" | "json" | "pbf" | "png" | "svg" | "topojson" | "webp" | null</code>
 
-## Type: `Format`<a id="type_format"></a>
+</details>
 
-Supported tile formats. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/interfaces.ts#L11">\[src]</a></sup>
+<details>
 
-**Type:** `"avif" | "bin" | "geojson" | "jpeg" | "json" | "pbf" | "png" | "svg" | "topojson" | "webp" | null`
+<summary><h2>Type: <code>Reader</code><a id="type_reader"></a></h2></summary>
 
-## Type: `Reader`<a id="type_reader"></a>
+Type definition for reading content from a VersaTiles container.
 
-Type definition for an asynchronous function to read a container's content.
+This is useful for implementing new container readers, e.g. reading over other network protocols. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/interfaces.ts#L37">\[src]</a></sup>
 
-This can be useful for accessing data stored in various storage mediums. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/575beea/container/src/interfaces.ts#L33">\[src]</a></sup>
+**Type:** <code>(position: number, length: number) => Promise<Buffer></code>
 
-**Type:** `(position: number, length: number) => Promise<Buffer>`
+</details>
 
 # License
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" resolution-mode="require"/>
-import type { Block, Format, Header, Options, Reader, TileIndex } from './interfaces.js';
-export type { Block, Compression, Format, Header, Options, Reader, TileIndex } from './interfaces.js';
+import type { Block, Header, OpenOptions, Reader, TileIndex } from './interfaces.js';
+export type { Compression, Format, Header, OpenOptions, Reader } from './interfaces.js';
 /**
  * The `VersaTiles` class is a wrapper around a `.versatiles` container file. It provides methods
  * to access tile data, metadata, and other properties within the container.
@@ -15,10 +15,9 @@ export declare class VersaTiles {
      * @param options - Optional settings that configure tile handling.
      * @throws Will throw an error if the provided source is neither a string nor a Reader function.
      */
-    constructor(source: Reader | string, options?: Options);
+    constructor(source: Reader | string, options?: OpenOptions);
     /**
      * Asynchronously retrieves the header information from the `.versatiles` container.
-     * This method is primarily for internal use.
      *
      * @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.
@@ -29,32 +28,9 @@ export declare class VersaTiles {
      * Metadata typically includes information about `vector_layers` for vector tiles.
      * If the container does not include metadata, this method returns `null`.
      *
-     * @returns A promise that resolves with an object representing the metadata, or null if no metadata is present.
+     * @returns A promise that resolves with an object representing the metadata.
      */
-    getMetadata(): Promise<object | null>;
-    /**
-     * Asynchronously determines the tile format, such as "png" or "pbf", based on the header information.
-     *
-     * @returns A promise that resolves with the tile format string, or null if the format is undefined.
-     */
-    getTileFormat(): Promise<Format | null>;
-    /**
-     * Asynchronously retrieves a mapping of tile block indices. The map's keys are formatted as "{z},{x},{y}".
-     * This method is for internal use to manage tile lookup within the container.
-     *
-     * @returns A promise that resolves with the block index map.
-     * @internal
-     */
-    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.
-     *
-     * @param block - The block for which to retrieve the tile index.
-     * @returns A promise that resolves with the tile index.
-     * @internal
-     */
-    getTileIndex(block: Block): Promise<TileIndex>;
+    getMetadata(): Promise<unknown>;
     /**
      * Asynchronously retrieves a specific tile's data as a Buffer. If the tile data is compressed as
      * defined in the container header, the returned Buffer will contain the compressed data.
@@ -79,4 +55,30 @@ export declare class VersaTiles {
      * @returns A promise that resolves with the uncompressed tile data as a Buffer, or null if the tile cannot be found.
      */
     getTileUncompressed(z: number, x: number, y: number): Promise<Buffer | null>;
+    /**
+     * Asynchronously retrieves a mapping of tile block indices. The map's keys are formatted as "{z},{x},{y}".
+     * This method is for internal use to manage tile lookup within the container.
+     *
+     * @returns A promise that resolves with the block index map.
+     * @protected
+     */
+    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.
+     *
+     * @param block - The block for which to retrieve the tile index.
+     * @returns A promise that resolves with the tile index.
+     * @protected
+     */
+    protected getTileIndex(block: Block): Promise<TileIndex>;
+    /**
+     * A protected method to read a chunk of data from the source based on the specified offset and length.
+     *
+     * @param offset - The offset from the start of the source data to begin reading.
+     * @param length - The number of bytes to read from the source.
+     * @returns A promise that resolves with the read data as a Buffer.
+     * @protected
+     */
+    protected read(offset: number, length: number): Promise<Buffer>;
 }

package/dist/index.js

@@ -53,7 +53,6 @@ export class VersaTiles {
     }
     /**
      * Asynchronously retrieves the header information from the `.versatiles` container.
-     * This method is primarily for internal use.
      *
      * @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.
@@ -62,7 +61,7 @@ export class VersaTiles {
         // deliver if known
         if (this.#header)
             return this.#header;
-        const data = await this.#read(0, 66);
+        const data = await this.read(0, 66);
         // check magic bytes
         if (!/^versatiles_v0[12]$/.test(data.toString('utf8', 0, 14))) {
             throw new Error('Invalid Container');
@@ -109,7 +108,7 @@ export class VersaTiles {
      * Metadata typically includes information about `vector_layers` for vector tiles.
      * If the container does not include metadata, this method returns `null`.
      *
-     * @returns A promise that resolves with an object representing the metadata, or null if no metadata is present.
+     * @returns A promise that resolves with an object representing the metadata.
      */
     async getMetadata() {
         if (this.#metadata !== undefined)
@@ -119,33 +118,86 @@ export class VersaTiles {
             this.#metadata = null;
         }
         else {
-            let buffer = await this.#read(header.metaOffset, header.metaLength);
+            let buffer = await this.read(header.metaOffset, header.metaLength);
             buffer = await this.#decompress(buffer, header.tileCompression);
             this.#metadata = JSON.parse(buffer.toString());
         }
         return this.#metadata;
     }
     /**
-     * Asynchronously determines the tile format, such as "png" or "pbf", based on the header information.
+     * Asynchronously retrieves a specific tile's data as a Buffer. If the tile data is compressed as
+     * defined in the container header, the returned Buffer will contain the compressed data.
+     * To obtain uncompressed data, use the `getTileUncompressed` method.
+     * If the specified tile does not exist, the method returns `null`.
+     *
+     * @param z - The zoom level of the tile.
+     * @param x - The x coordinate of the tile within its zoom level.
+     * @param y - The y coordinate of the tile within its zoom level.
+     * @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) {
+        // when y index is inverted
+        if (this.#options.tms)
+            y = Math.pow(2, z) - y - 1;
+        // ensure block index is loaded
+        const blockIndex = await this.getBlockIndex();
+        // block xy
+        const bx = x >> 8;
+        const by = y >> 8;
+        // tile xy (within block)
+        const tx = x & 0xFF;
+        const ty = y & 0xFF;
+        // check if block containing tile is within bounds
+        const blockKey = `${z},${bx},${by}`;
+        const block = blockIndex.get(blockKey);
+        if (!block)
+            return null;
+        // check if block contains tile
+        if (tx < block.colMin || tx > block.colMax)
+            return null;
+        if (ty < block.rowMin || ty > block.rowMax)
+            return null;
+        // calculate sequential tile number
+        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];
+        if (length === 0)
+            return null;
+        return this.read(offset, length);
+    }
+    /**
+     * Asynchronously retrieves a specific tile's uncompressed data as a Buffer. This method first
+     * retrieves the compressed tile data using `getTile` and then decompresses it based on the
+     * compression setting in the container header.
+     * If the specified tile does not exist, the method returns `null`.
      *
-     * @returns A promise that resolves with the tile format string, or null if the format is undefined.
+     * @param z - The zoom level of the tile.
+     * @param x - The x coordinate of the tile within its zoom level.
+     * @param y - The y coordinate of the tile within its zoom level.
+     * @returns A promise that resolves with the uncompressed tile data as a Buffer, or null if the tile cannot be found.
      */
-    async getTileFormat() {
-        return (await this.getHeader()).tileFormat;
+    async getTileUncompressed(z, x, y) {
+        const tile = await this.getTile(z, x, y);
+        if (!tile)
+            return null;
+        const header = await this.getHeader();
+        return this.#decompress(tile, header.tileCompression);
     }
     /**
      * Asynchronously retrieves a mapping of tile block indices. The map's keys are formatted as "{z},{x},{y}".
      * This method is for internal use to manage tile lookup within the container.
      *
      * @returns A promise that resolves with the block index map.
-     * @internal
+     * @protected
      */
     async getBlockIndex() {
         if (this.#blockIndex)
             return this.#blockIndex;
         const header = await this.getHeader();
         // read block_index buffer
-        let data = await this.#read(header.blockIndexOffset, header.blockIndexLength);
+        let data = await this.read(header.blockIndexOffset, header.blockIndexLength);
         data = await this.#decompress(data, 'br');
         // read index from buffer
         const blocks = [];
@@ -199,12 +251,12 @@ export class VersaTiles {
      *
      * @param block - The block for which to retrieve the tile index.
      * @returns A promise that resolves with the tile index.
-     * @internal
+     * @protected
      */
     async getTileIndex(block) {
         if (block.tileIndex)
             return block.tileIndex;
-        let buffer = await this.#read(block.tileIndexOffset, block.tileIndexLength);
+        let buffer = await this.read(block.tileIndexOffset, block.tileIndexLength);
         buffer = await this.#decompress(buffer, 'br');
         const offsets = new Float64Array(block.tileCount);
         const lengths = new Float64Array(block.tileCount);
@@ -216,75 +268,14 @@ export class VersaTiles {
         return block.tileIndex;
     }
     /**
-     * Asynchronously retrieves a specific tile's data as a Buffer. If the tile data is compressed as
-     * defined in the container header, the returned Buffer will contain the compressed data.
-     * To obtain uncompressed data, use the `getTileUncompressed` method.
-     * If the specified tile does not exist, the method returns `null`.
-     *
-     * @param z - The zoom level of the tile.
-     * @param x - The x coordinate of the tile within its zoom level.
-     * @param y - The y coordinate of the tile within its zoom level.
-     * @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) {
-        // when y index is inverted
-        if (this.#options.tms)
-            y = Math.pow(2, z) - y - 1;
-        // ensure block index is loaded
-        const blockIndex = await this.getBlockIndex();
-        // block xy
-        const bx = x >> 8;
-        const by = y >> 8;
-        // tile xy (within block)
-        const tx = x & 0xFF;
-        const ty = y & 0xFF;
-        // check if block containing tile is within bounds
-        const blockKey = `${z},${bx},${by}`;
-        const block = blockIndex.get(blockKey);
-        if (!block)
-            return null;
-        // check if block contains tile
-        if (tx < block.colMin || tx > block.colMax)
-            return null;
-        if (ty < block.rowMin || ty > block.rowMax)
-            return null;
-        // calculate sequential tile number
-        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];
-        if (length === 0)
-            return null;
-        return this.#read(offset, length);
-    }
-    /**
-     * Asynchronously retrieves a specific tile's uncompressed data as a Buffer. This method first
-     * retrieves the compressed tile data using `getTile` and then decompresses it based on the
-     * compression setting in the container header.
-     * If the specified tile does not exist, the method returns `null`.
-     *
-     * @param z - The zoom level of the tile.
-     * @param x - The x coordinate of the tile within its zoom level.
-     * @param y - The y coordinate of the tile within its zoom level.
-     * @returns A promise that resolves with the uncompressed tile data as a Buffer, or null if the tile cannot be found.
-     */
-    async getTileUncompressed(z, x, y) {
-        const tile = await this.getTile(z, x, y);
-        if (!tile)
-            return null;
-        const header = await this.getHeader();
-        return this.#decompress(tile, header.tileCompression);
-    }
-    /**
-     * A private method to read a chunk of data from the source based on the specified offset and length.
+     * A protected method to read a chunk of data from the source based on the specified offset and length.
      *
      * @param offset - The offset from the start of the source data to begin reading.
      * @param length - The number of bytes to read from the source.
      * @returns A promise that resolves with the read data as a Buffer.
-     * @private
+     * @protected
      */
-    async #read(offset, length) {
+    async read(offset, length) {
         if (length === 0)
             return Buffer.allocUnsafe(0);
         return this.#reader(offset, length);

package/dist/interfaces.d.ts

@@ -17,12 +17,16 @@ export type Format = 'avif' | 'bin' | 'geojson' | 'jpeg' | 'json' | 'pbf' | 'png
  */
 export type Decompressor = (data: Buffer, compression: Compression) => Promise<Buffer>;
 /**
- * Type definition for an asynchronous function to read a container's content.
+ * Type definition for reading content from a VersaTiles container.
+ *
+ * This is useful for implementing new container readers, e.g. reading over other network protocols.
  *
- * This can be useful for accessing data stored in various storage mediums.
  * @param {number} position - The byte offset at which to start reading.
  * @param {number} length - The number of bytes to read.
- * @returns {Promise<Buffer>} - The read data.
+ * @returns {Promise<Buffer>} A promise that resolves with the data read as a Buffer.
+ * @throws {RangeError} If `position` is less than 0 or if `length` is less than 0.
+ * @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>;
 /**
@@ -98,6 +102,6 @@ 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.
  */
-export interface Options {
+export interface OpenOptions {
     tms: boolean;
 }

package/dist/reader_file.js

@@ -1,4 +1,4 @@
-import fs from 'fs';
+import fs from 'node:fs';
 /**
  * Creates a file reader function for reading chunks of data from a file. This reader abstracts
  * the file reading process and provides a simple async interface to read data from the specified file.
@@ -18,6 +18,7 @@ import fs from 'fs';
  */
 export default function getFileReader(filename) {
     const fd = fs.openSync(filename, 'r');
+    const { size } = fs.statSync(filename);
     /**
      * Reads a chunk of data from the file at the specified position and length.
      * It creates a buffer of the specified `length`, seeks to the `position` in the file,
@@ -37,6 +38,15 @@ export default function getFileReader(filename) {
      *                            promise will be rejected with an error.
      */
     return async function read(position, length) {
+        if (position < 0) {
+            throw new RangeError(`Invalid read position: ${position}. The read position must be a non-negative integer.`);
+        }
+        if (length < 0) {
+            throw new RangeError(`Invalid read length: ${length}. The read length must be a non-negative integer.`);
+        }
+        if (position + length > size) {
+            throw new RangeError(`Read range out of bounds: The requested range ends at position ${position + length}, which exceeds the file's limit of ${size} bytes.`);
+        }
         return new Promise((resolve, reject) => {
             fs.read(fd, {
                 buffer: Buffer.alloc(length),

package/dist/reader_http.js

@@ -27,6 +27,12 @@ export default function getHTTPReader(url) {
      *          the promise is rejected with an error.
      */
     return async function read(position, length) {
+        if (position < 0) {
+            throw new RangeError(`Invalid read position: ${position}. The read position must be a non-negative integer.`);
+        }
+        if (length < 0) {
+            throw new RangeError(`Invalid read length: ${length}. The read length must be a non-negative integer.`);
+        }
         const headers = {
             // eslint-disable-next-line @typescript-eslint/naming-convention
             'user-agent': 'Mozilla/5.0 (compatible; versatiles; +https://www.npmjs.com/package/versatiles)',
@@ -61,9 +67,24 @@ export default function getHTTPReader(url) {
             })
                 .end();
         });
+        const contentRange = message.headers['content-range'];
+        if (contentRange == null)
+            throw 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');
+        if (position !== parseInt(parts[1], 10))
+            throw Error(`requestet 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.`);
+        }
+        const returnedLength = parseInt(parts[2], 10) + 1 - position;
+        if (length !== returnedLength) {
+            throw new Error(`Returned length (${returnedLength}) is not requested length (${length}).`);
+        }
         if ((message.statusCode == null) || Math.floor(message.statusCode / 100) !== 2) {
             message.destroy();
-            throw new Error(`Server responded with status code: ${message.statusCode}`);
+            throw new Error(`Server responded with status code: ${message.statusCode} `);
         }
         /**
          * Collects and concatenates response data chunks into a buffer.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@versatiles/container",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A client library for reading VersaTiles containers",
   "scripts": {
-    "check": "npm run lint && npm run build && npm run test",
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "doc": "npm run -w tsdoc2readme update_readme container/src/index.ts '# API'",
-    "lint": "eslint .",
-    "test": "jest"
+    "check": "npm run lint && npm run test && npm run build",
+    "doc": "npx vrt ts2md src/index.ts tsconfig.build.json | npx vrt insertmd README.md '# API' true",
+    "lint": "eslint . --color",
+    "prepublish": "npm run build && npm run doc",
+    "test": "cd ..; NODE_OPTIONS=--experimental-vm-modules jest --testPathPattern versatiles-container"
   },
   "files": [
     "dist/**/*.js",
@@ -46,7 +47,8 @@
   ],
   "devDependencies": {
     "@types/node": "^20.9.0",
-    "jest": "^29.7.0",
-    "typescript": "^5.2.2"
+    "tsx": "^4.1.0",
+    "typescript": "^5.2.2",
+    "@versatiles/release-tool": "^1.0.0"
   }
 }