@versatiles/container 1.0.2 → 1.2.0

package/README.md

@@ -1,13 +1,16 @@
+[![Code Coverage](https://codecov.io/gh/versatiles-org/node-versatiles/branch/main/graph/badge.svg?token=IDHAI13M0K)](https://codecov.io/gh/versatiles-org/node-versatiles)
+[![GitHub Workflow 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)
+
 A client library for [VersaTiles containers](https://github.com/versatiles-org/versatiles-spec).
 
 # Install
 
-`npm i versatiles`
+`npm i @versatiles/container"`
 
 # Usage Example
 
 ```js
-import VersaTiles from 'versatiles';
+import VersaTiles from '@versatiles/container"';
 import fs from 'fs';
 
 const container = new VersaTiles('https://example.org/planet.versatiles');
@@ -20,61 +23,45 @@ fs.writeFileSync('tile.' + header.tile_format, tile);
 
 <!--- This chapter is generated automatically --->
 
-<details>
+## Classes
 
-<summary><h2>Class: <code>VersaTiles</code><a id="class_versatiles"></a></h2></summary>
+### Class: `Container`<a id="class_container"></a>
 
 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/8921e07/versatiles-container/src/index.ts#L27">\[src]</a></sup>
-
-<details>
+to access tile data, metadata, and other properties within the container. <sup><a href="https://github.com/versatiles-org/node-versatiles-container/blob/67a9864/src/index.ts#L38">\[src]</a></sup>
 
-<summary><h3>Constructor: <code>new VersaTiles&#40;source, options&#41;</code></h3></summary>
+#### Constructor: `new Container(source, options)`
 
-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>
+Constructs a new instance of the VersaTiles class. <sup><a href="https://github.com/versatiles-org/node-versatiles-container/blob/67a9864/src/index.ts#L59">\[src]</a></sup>
 
 **Parameters:**
 
 * <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.
-* <code>options: [Options](#interface_options)</code> (optional)\
+* <code>options: [OpenOptions](#interface_openoptions)</code> (optional)\
   Optional settings that configure tile handling.
 
-**Returns:** <code>[VersaTiles](#class_versatiles)</code>
-
-</details>
-
-<details>
+#### Method: `getHeader()`
 
-<summary><h3>Method: <code>getHeader&#40;&#41;</code></h3></summary>
-
-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>
+Asynchronously retrieves the header information from the `.versatiles` container. <sup><a href="https://github.com/versatiles-org/node-versatiles-container/blob/67a9864/src/index.ts#L81">\[src]</a></sup>
 
 **Returns:** <code>Promise<[Header](#interface_header)></code>
 
-</details>
-
-<details>
-
-<summary><h3>Method: <code>getMetadata&#40;&#41;</code></h3></summary>
+#### Method: `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/8921e07/versatiles-container/src/index.ts#L132">\[src]</a></sup>
-
-**Returns:** <code>Promise\<null | object></code>
+If the container does not include metadata, this method returns `null`. <sup><a href="https://github.com/versatiles-org/node-versatiles-container/blob/67a9864/src/index.ts#L128">\[src]</a></sup>
 
-</details>
+**Returns:** <code>Promise\<undefined | string></code>
 
-<details>
-
-<summary><h3>Method: <code>getTile&#40;z, x, y&#41;</code></h3></summary>
+#### Method: `getTile(z, x, y)`
 
 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/8921e07/versatiles-container/src/index.ts#L158">\[src]</a></sup>
+If the specified tile does not exist, the method returns `null`. <sup><a href="https://github.com/versatiles-org/node-versatiles-container/blob/67a9864/src/index.ts#L155">\[src]</a></sup>
 
 **Parameters:**
 
@@ -87,16 +74,12 @@ If the specified tile does not exist, the method returns `null`. <sup><a href="h
 
 **Returns:** <code>Promise\<null | Buffer></code>
 
-</details>
-
-<details>
-
-<summary><h3>Method: <code>getTileUncompressed&#40;z, x, y&#41;</code></h3></summary>
+#### Method: `getTileUncompressed(z, x, y)`
 
 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/8921e07/versatiles-container/src/index.ts#L206">\[src]</a></sup>
+If the specified tile does not exist, the method returns `null`. <sup><a href="https://github.com/versatiles-org/node-versatiles-container/blob/67a9864/src/index.ts#L203">\[src]</a></sup>
 
 **Parameters:**
 
@@ -109,84 +92,48 @@ If the specified tile does not exist, the method returns `null`. <sup><a href="h
 
 **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".
-* <code>version: string</code>\
-  Version of the container format, typically "v02".
-* <code>tileFormat: [Format](#type_format)</code>\
-  The format used for storing tiles.
-* <code>tileCompression: [Compression](#type_compression)</code>\
-  The type of compression applied to tiles.
-* <code>zoomMin: number</code>\
-  The minimum zoom level.
-* <code>zoomMax: number</code>\
-  The maximum zoom level.
-* <code>bbox: \[number, number, number, number]</code>\
-  Bounding box coordinates as \[lon\_min, lat\_min, lon\_max, lat\_max].
-* <code>metaOffset: number</code>\
-  The byte offset for metadata within the container.
-* <code>metaLength: number</code>\
-  The byte size of the metadata. A value of 0 means no metadata.
-* <code>blockIndexOffset: number</code>\
-  The byte offset for the block index within the container.
-* <code>blockIndexLength: number</code>\
-  The byte size of the block index. A value of 0 indicates no tiles in the container.
-
-</details>
-
-<details>
-
-<summary><h2>Interface: <code>Options</code><a id="interface_options"></a></h2></summary>
-
-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>
-
-* <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>
-
-<details>
-
-<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/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>
+## Interfaces
+
+### Interface: `Header`<a id="interface_header"></a>
+
+```typescript
+interface {
+  bbox: [number, number, number, number];
+  blockIndexLength: number;
+  blockIndexOffset: number;
+  magic: string;
+  metaLength: number;
+  metaOffset: number;
+  tileCompression: [Compression](#type_compression);
+  tileFormat: [Format](#type_format);
+  tileMime: string;
+  version: string;
+  zoomMax: number;
+  zoomMin: number;
+}
+```
 
-Supported tile formats. <sup><a href="https://github.com/versatiles-org/node-versatiles/blob/8921e07/versatiles-container/src/interfaces.ts#L11">\[src]</a></sup>
+### Interface: `OpenOptions`<a id="interface_openoptions"></a>
 
-**Type:** <code>"avif" | "bin" | "geojson" | "jpeg" | "json" | "pbf" | "png" | "svg" | "topojson" | "webp" | null</code>
+```typescript
+interface {
+  tms: boolean;
+}
+```
 
-</details>
+## Type Aliases
 
-<details>
+### Type: `Compression`<a id="type_compression"></a>
 
-<summary><h2>Type: <code>Reader</code><a id="type_reader"></a></h2></summary>
+**Type:** <code>"br" | "gzip" | "raw"</code>
 
-Type definition for reading content from a VersaTiles container.
+### Type: `Format`<a id="type_format"></a>
 
-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>
+**Type:** <code>"avif" | "bin" | "geojson" | "jpg" | "json" | "pbf" | "png" | "svg" | "topojson" | "webp"</code>
 
-**Type:** <code>(position: number, length: number) => Promise<Buffer></code>
+### Type: `Reader`<a id="type_reader"></a>
 
-</details>
+**Type:** <code>(position: number, length: number) => Promise\<Buffer></code>
 
 # License
 

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-/// <reference types="node" resolution-mode="require"/>
-import type { Block, Header, OpenOptions, Reader, TileIndex } from './interfaces.js';
-export type { Compression, Format, Header, OpenOptions, Reader } from './interfaces.js';
+/// <reference types="node" />
+import type { Block, Header, OpenOptions, Reader, TileIndex } from './lib/interfaces';
+export type { Compression, Format, Header, OpenOptions, Reader } from './lib/interfaces';
 /**
  * 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.
  */
-export declare class VersaTiles {
+export declare class Container {
     #private;
     /**
      * Constructs a new instance of the VersaTiles class.
@@ -30,7 +30,7 @@ export declare class VersaTiles {
      *
      * @returns A promise that resolves with an object representing the metadata.
      */
-    getMetadata(): Promise<unknown>;
+    getMetadata(): Promise<string | undefined>;
     /**
      * 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.

package/dist/index.js

@@ -1,26 +1,37 @@
-import HttpReader from './reader_http.js';
-import FileReader from './reader_file.js';
-import { decompress } from './decompress.js';
+import HttpReader from './lib/reader_http';
+import FileReader from './lib/reader_file';
+import { decompress } from './lib/decompress';
 const FORMATS = {
-    'c01': ['png', 'jpeg', 'webp', null, null, null, null, null, null, null, null, null, null, null, null, null, 'pbf'],
-    'v01': ['png', 'jpeg', 'webp', 'pbf'],
+    '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', null, null, null, null, null, null, null, null, null, null, null, null, null, null, null,
-        'png', 'jpeg', 'webp', 'avif', 'svg', 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 = [null, 'gzip', 'br'];
+const COMPRESSIONS = ['raw', 'gzip', 'br'];
+const MIMETYPES = {
+    'avif': 'image/avif',
+    'bin': 'application/octet-stream',
+    'geojson': 'application/geo+json; charset=utf-8',
+    'jpg': 'image/jpeg',
+    'json': 'application/json; charset=utf-8',
+    'pbf': 'application/x-protobuf',
+    'png': 'image/png',
+    'svg': 'image/svg+xml; charset=utf-8',
+    'topojson': 'application/topo+json; charset=utf-8',
+    'webp': 'image/webp',
+};
 /**
  * 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.
  */
-export class VersaTiles {
+export class Container {
     #options = {
         tms: false,
     };
     #reader;
-    #decompress;
     #header;
     #metadata;
     #blockIndex;
@@ -49,7 +60,6 @@ export class VersaTiles {
         else {
             throw new Error('source must be a string or a Reader');
         }
-        this.#decompress = decompress;
     }
     /**
      * Asynchronously retrieves the header information from the `.versatiles` container.
@@ -66,41 +76,29 @@ export class VersaTiles {
         if (!/^versatiles_v0[12]$/.test(data.toString('utf8', 0, 14))) {
             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 tileMime = MIMETYPES[tileFormat];
+        const tileCompression = COMPRESSIONS[data.readUInt8(15)] ?? 'raw';
+        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':
-                this.#header = {
-                    magic: data.toString('utf8', 0, 14),
-                    version: version,
-                    tileFormat: FORMATS[version][data.readUInt8(14)] ?? 'bin',
-                    tileCompression: COMPRESSIONS[data.readUInt8(15)] ?? null,
-                    zoomMin: data.readUInt8(16),
-                    zoomMax: data.readUInt8(17),
-                    bbox: [data.readFloatBE(18), data.readFloatBE(22), data.readFloatBE(26), data.readFloatBE(30)],
-                    metaOffset: Number(data.readBigUInt64BE(34)),
-                    metaLength: Number(data.readBigUInt64BE(42)),
-                    blockIndexOffset: Number(data.readBigUInt64BE(50)),
-                    blockIndexLength: Number(data.readBigUInt64BE(58)),
-                };
+                bbox = [data.readFloatBE(18), data.readFloatBE(22), data.readFloatBE(26), data.readFloatBE(30)];
                 break;
             case 'v02':
-                this.#header = {
-                    magic: data.toString('utf8', 0, 14),
-                    version: version,
-                    tileFormat: FORMATS[version][data.readUInt8(14)] ?? 'bin',
-                    tileCompression: COMPRESSIONS[data.readUInt8(15)] ?? null,
-                    zoomMin: data.readUInt8(16),
-                    zoomMax: data.readUInt8(17),
-                    bbox: [data.readInt32BE(18) / 1e7, data.readInt32BE(22) / 1e7, data.readInt32BE(26) / 1e7, data.readInt32BE(30) / 1e7],
-                    metaOffset: Number(data.readBigUInt64BE(34)),
-                    metaLength: Number(data.readBigUInt64BE(42)),
-                    blockIndexOffset: Number(data.readBigUInt64BE(50)),
-                    blockIndexLength: Number(data.readBigUInt64BE(58)),
-                };
+                bbox = [data.readInt32BE(18) / 1e7, data.readInt32BE(22) / 1e7, data.readInt32BE(26) / 1e7, data.readInt32BE(30) / 1e7];
                 break;
             default:
                 throw new Error('Invalid Container');
         }
+        this.#header = { magic, version, tileFormat, tileMime, tileCompression, zoomMin, zoomMax, bbox, metaOffset, metaLength, blockIndexOffset, blockIndexLength };
         return this.#header;
     }
     /**
@@ -115,12 +113,12 @@ export class VersaTiles {
             return this.#metadata;
         const header = await this.getHeader();
         if (header.metaLength === 0) {
-            this.#metadata = null;
+            this.#metadata = undefined;
         }
         else {
             let buffer = await this.read(header.metaOffset, header.metaLength);
-            buffer = await this.#decompress(buffer, header.tileCompression);
-            this.#metadata = JSON.parse(buffer.toString());
+            buffer = await decompress(buffer, header.tileCompression);
+            this.#metadata = buffer.toString();
         }
         return this.#metadata;
     }
@@ -183,7 +181,7 @@ export class VersaTiles {
         if (!tile)
             return null;
         const header = await this.getHeader();
-        return this.#decompress(tile, header.tileCompression);
+        return decompress(tile, header.tileCompression);
     }
     /**
      * Asynchronously retrieves a mapping of tile block indices. The map's keys are formatted as "{z},{x},{y}".
@@ -198,7 +196,7 @@ export class VersaTiles {
         const header = await this.getHeader();
         // read block_index buffer
         let data = await this.read(header.blockIndexOffset, header.blockIndexLength);
-        data = await this.#decompress(data, 'br');
+        data = await decompress(data, 'br');
         // read index from buffer
         const blocks = [];
         switch (header.version) {
@@ -257,7 +255,7 @@ export class VersaTiles {
         if (block.tileIndex)
             return block.tileIndex;
         let buffer = await this.read(block.tileIndexOffset, block.tileIndexLength);
-        buffer = await this.#decompress(buffer, 'br');
+        buffer = await decompress(buffer, 'br');
         const offsets = new Float64Array(block.tileCount);
         const lengths = new Float64Array(block.tileCount);
         for (let i = 0; i < block.tileCount; i++) {

package/dist/{decompress.d.ts → lib/decompress.d.ts}

@@ -1,5 +1,5 @@
-/// <reference types="node" resolution-mode="require"/>
-import type { Compression } from './interfaces.js';
+/// <reference types="node" />
+import type { Compression } from './interfaces';
 /**
  * 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.

package/dist/{interfaces.d.ts → lib/interfaces.d.ts}

@@ -1,13 +1,13 @@
-/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" />
 /**
  * Supported compression.
  * `null` signifies that the data is uncompressed.
  */
-export type Compression = 'br' | 'gzip' | null;
+export type Compression = 'br' | 'gzip' | 'raw';
 /**
  * Supported tile formats.
  */
-export type Format = 'avif' | 'bin' | 'geojson' | 'jpeg' | 'json' | 'pbf' | 'png' | 'svg' | 'topojson' | 'webp' | null;
+export type Format = 'avif' | 'bin' | 'geojson' | 'jpg' | 'json' | 'pbf' | 'png' | 'svg' | 'topojson' | 'webp';
 /**
  * Type definition for a function that decompresses data.
  *
@@ -35,6 +35,7 @@ export type Reader = (position: number, length: number) => Promise<Buffer>;
  * @property {string} magic - Identifier for the container format, usually "versatiles_v02".
  * @property {string} version - Version of the container format, typically "v02".
  * @property {Format} tileFormat - The format used for storing tiles.
+ * @property {string} tileMime - The MIME type of the tiles.
  * @property {Compression} tileCompression - The type of compression applied to tiles.
  * @property {number} zoomMin - The minimum zoom level.
  * @property {number} zoomMax - The maximum zoom level.
@@ -48,6 +49,7 @@ export interface Header {
     magic: string;
     version: string;
     tileFormat: Format;
+    tileMime: string;
     tileCompression: Compression;
     zoomMin: number;
     zoomMax: number;

package/dist/{reader_file.d.ts → lib/reader_file.d.ts}

@@ -1,4 +1,4 @@
-import type { Reader } from './interfaces.js';
+import type { Reader } from './interfaces';
 /**
  * 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.

package/dist/{reader_http.d.ts → lib/reader_http.d.ts}

@@ -1,4 +1,4 @@
-import type { Reader } from './interfaces.js';
+import type { Reader } from './interfaces';
 /**
  * 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

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@versatiles/container",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "A client library for reading VersaTiles containers",
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "check": "npm run lint && npm run test && npm run build",
+    "check": "npm run lint && npm run build && npm run test",
     "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"
+    "prepack": "npm run build && npm run doc",
+    "release": "npx vrt release-npm",
+    "test-coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "upgrade": "npm-check-updates -u && rm -f package-lock.json; rm -rf node_modules; npm i && npm update"
   },
   "files": [
     "dist/**/*.js",
@@ -18,7 +21,7 @@
     "type": "git",
     "url": "git+https://github.com/versatiles-org/node-versatiles.git"
   },
-  "homepage": "https://github.com/versatiles-org/node-versatiles/blob/main/container/README.md",
+  "homepage": "https://github.com/versatiles-org/node-versatiles/blob/main/versatiles-container/README.md",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -46,9 +49,17 @@
     "versatiles"
   ],
   "devDependencies": {
-    "@types/node": "^20.9.0",
-    "tsx": "^4.1.0",
-    "typescript": "^5.2.2",
-    "@versatiles/release-tool": "^1.0.0"
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.20",
+    "@typescript-eslint/eslint-plugin": "^7.0.2",
+    "@typescript-eslint/parser": "^7.0.2",
+    "@versatiles/release-tool": "^1.2.2",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "npm-check-updates": "^16.14.15",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3"
   }
-}
+}