@versatiles/container/dist/index.d.ts

A client library for reading VersaTiles containers

/**
 * @module
 *
 * This module provides functionality to interact with and retrieve tile data from `.versatiles` container files,
 * typically used for storing geospatial tile data in a compressed, optimized format. The module supports
 * multiple file and compression formats.
 *
 * Dependencies:
 * - `HttpReader` and `FileReader`: Adapters for reading data from HTTP/HTTPS URLs or local files, respectively.
 * - `decompress`: Utility for decompressing tile data in supported formats.
 * - Type definitions (`Block`, `Compression`, `Format`, `Header`, `OpenOptions`, `Reader`, and `TileIndex`)
 *   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).
 * - `MIMETYPES`: Maps supported tile formats to their respective MIME types for handling and delivery.
 *
 * Exported Types:
 * - The module re-exports `Compression`, `Format`, `Header`, `OpenOptions`, and `Reader` types for use in other modules.
 *
 * Primary Class:
 * - `Container`: A main wrapper class that provides methods to access tile data, metadata, and configuration settings
 *   for `.versatiles` containers. Methods include `getHeader`, `getMetadata`, `getTile`, and `getTileUncompressed`,
 *   which enable detailed control and retrieval of tile information, metadata, and decompressed content.
 *
 * @example
 * ```ts
 * import { Container } from '@versatiles/container';
 * const container = new Container('path/to/versatiles-file');
 * const tile = await container.getTile(12, 2200, 1343);
 * const metadata = await container.getMetadata();
 * ```
 */
import type { Block, Header, OpenOptions, Reader, TileIndex } from './lib/interfaces.js';
export type { Block, Compression, Format, Header, OpenOptions, Reader, TileIndex, } from './lib/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.
 */
export declare class Container {
    #private;
    /**
     * Constructs a new instance of the VersaTiles class.
     *
     * @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.
     * @throws Will throw an error if the provided source is neither a string nor a Reader function.
     */
    constructor(source: Reader | string, options?: OpenOptions);
    /**
     * Asynchronously retrieves the header information from the `.versatiles` 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.
     */
    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`.
     *
     * @returns A promise that resolves with an object representing the metadata.
     */
    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.
     * 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.
     */
    getTile(z: number, x: number, y: number): Promise<Buffer | null>;
    /**
     * 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.
     */
    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
     */
    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
     */
    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>;
}