@versatiles/versatiles-rs 3.0.2 → 3.0.3

package/index.d.ts

@@ -0,0 +1,1141 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * Progress monitor for long-running operations
+ *
+ * This class allows monitoring the progress of tile conversion and other
+ * long-running operations through event listeners.
+ */
+export declare class Progress {
+  /**
+   * Register a progress event listener
+   *
+   * The callback receives ProgressData with position, total, percentage, speed, eta, and message.
+   * The eta field is a JavaScript Date object representing the estimated time of completion.
+   */
+  onProgress(callback: (data: ProgressData) => void): this
+  /**
+   * Register a message event listener for step, warning, and error messages
+   *
+   * The callback receives (type, message) where type is 'step', 'warning', or 'error'
+   */
+  onMessage(callback: (type: string, message: string) => void): this
+}
+
+/**
+ * Information about the tile source type and origin
+ *
+ * Provides metadata about how the tile source was created and what it represents.
+ * This is useful for debugging and understanding the source of tiles being served.
+ *
+ * # Source Kinds
+ *
+ * - **Container**: A file-based tile container (MBTiles, PMTiles, VersaTiles, TAR, or directory)
+ * - **Processor**: A tile source with transformations applied (e.g., from VPL pipelines)
+ * - **Composite**: Multiple tile sources combined together
+ *
+ * # Properties
+ *
+ * All source types have:
+ * - `kind`: The type of source ("container", "processor", or "composite")
+ * - `name`: A descriptive name for the source
+ *
+ * Container sources also have:
+ * - `uri`: The file path or URL of the container
+ *
+ * Processor sources also have:
+ * - `input`: The source being processed
+ *
+ * Composite sources also have:
+ * - `inputs`: Array of combined sources
+ */
+export declare class SourceType {
+  /**
+   * Get the kind of source
+   *
+   * Returns one of:
+   * - `"container"`: File-based tile container
+   * - `"processor"`: Transformed tile source (e.g., VPL pipeline)
+   * - `"composite"`: Multiple sources combined
+   */
+  get kind(): string
+  /**
+   * Get the name of the source
+   *
+   * Returns a descriptive name indicating the source format or type.
+   * For containers, this is typically the format name (e.g., "MBTiles", "PMTiles").
+   * For processors, this describes the transformation (e.g., "filter", "transform").
+   */
+  get name(): string
+  /**
+   * Get the file path or URL (for Container sources only)
+   *
+   * Returns the full path or URL of the tile container file.
+   * Returns `null` for Processor and Composite sources.
+   *
+   * # Example
+   *
+   * ```javascript
+   * const source = await TileSource.open('tiles.mbtiles');
+   * const type = source.sourceType();
+   * console.log(type.uri);  // "/path/to/tiles.mbtiles"
+   * ```
+   */
+  get uri(): string | null
+  /**
+   * Get the input source being processed (for Processor sources only)
+   *
+   * Returns the source that this processor is transforming.
+   * Returns `null` for Container and Composite sources.
+   *
+   * # Example
+   *
+   * ```javascript
+   * const source = await TileSource.fromVpl(
+   *   'from_container filename="tiles.mbtiles" | filter level_min=5',
+   *   '.'
+   * );
+   * const type = source.sourceType();
+   * console.log(type.kind);  // "processor"
+   * console.log(type.name);  // "filter"
+   * const inputType = type.input;
+   * console.log(inputType.kind);  // "container"
+   * ```
+   */
+  get input(): SourceType | null
+  /**
+   * Get the array of combined sources (for Composite sources only)
+   *
+   * Returns an array of all sources that have been combined together.
+   * Returns `null` for Container and Processor sources.
+   *
+   * # Example
+   *
+   * ```javascript
+   * // For a composite source combining multiple tile sets
+   * const type = source.sourceType();
+   * if (type.kind === 'composite') {
+   *   const sources = type.inputs;
+   *   console.log(`Combined ${sources.length} tile sources`);
+   * }
+   * ```
+   */
+  get inputs(): Array<SourceType> | null
+}
+
+/**
+ * Tile coordinate in the Web Mercator tile grid
+ *
+ * Represents a specific tile in the standard Web Mercator (EPSG:3857) tiling scheme.
+ * Uses XYZ coordinate convention where:
+ * - **z** (zoom): Zoom level (0-32), where 0 is the world in one tile
+ * - **x** (column): Tile column, from 0 (west) to 2^z - 1 (east)
+ * - **y** (row): Tile row, from 0 (north) to 2^z - 1 (south)
+ *
+ * # Coordinate System
+ *
+ * This implementation uses the **XYZ** (Slippy Map) convention:
+ * - Origin (0,0) is at the top-left (north-west)
+ * - Y increases going south
+ * - X increases going east
+ *
+ * Note: This differs from **TMS** (Tile Map Service) where Y increases going north.
+ * Use the `flipY` option in conversion if you need TMS coordinates.
+ */
+export declare class TileCoord {
+  /**
+   * Create a new tile coordinate
+   *
+   * # Arguments
+   *
+   * * `z` - Zoom level (0-32)
+   * * `x` - Tile column (0 to 2^z - 1)
+   * * `y` - Tile row (0 to 2^z - 1)
+   *
+   * # Errors
+   *
+   * Returns an error if coordinates are out of valid range for the zoom level.
+   * At zoom level z, valid coordinates are:
+   * - x: 0 to 2^z - 1
+   * - y: 0 to 2^z - 1
+   *
+   * # Examples
+   *
+   * ```javascript
+   * // Berlin tile at zoom 10
+   * const tile = new TileCoord(10, 550, 335);
+   *
+   * // World tile at zoom 0
+   * const world = new TileCoord(0, 0, 0);
+   * ```
+   */
+  constructor(z: number, x: number, y: number)
+  /**
+   * Create a tile coordinate from geographic coordinates
+   *
+   * Converts WGS84 latitude/longitude to the tile containing that point.
+   *
+   * # Arguments
+   *
+   * * `lon` - Longitude in decimal degrees (-180 to 180)
+   * * `lat` - Latitude in decimal degrees (-85.0511 to 85.0511)
+   * * `z` - Zoom level (0-32)
+   *
+   * # Returns
+   *
+   * The tile coordinate containing the specified geographic point
+   *
+   * # Errors
+   *
+   * Returns an error if coordinates are outside valid Web Mercator range.
+   * Valid latitude range is approximately ±85.05° (Web Mercator limit).
+   *
+   * # Examples
+   *
+   * ```javascript
+   * // Find tile containing Berlin city center
+   * const berlin = TileCoord.fromGeo(13.405, 52.520, 10);
+   * console.log(`Tile: ${berlin.z}/${berlin.x}/${berlin.y}`);
+   *
+   * // Find tile for New York City
+   * const nyc = TileCoord.fromGeo(-74.006, 40.7128, 12);
+   * ```
+   */
+  static fromGeo(lon: number, lat: number, z: number): TileCoord
+  /**
+   * Get the geographic center point of this tile
+   *
+   * Returns the WGS84 coordinates of the tile's center point.
+   *
+   * # Returns
+   *
+   * Array of `[longitude, latitude]` in decimal degrees
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const tile = new TileCoord(10, 550, 335);
+   * const [lon, lat] = tile.toGeo();
+   * console.log(`Center: ${lat.toFixed(4)}°N, ${lon.toFixed(4)}°E`);
+   * ```
+   */
+  toGeo(): Array<number>
+  /**
+   * Get the geographic bounding box of this tile
+   *
+   * Returns the geographic extent of the tile in WGS84 coordinates.
+   *
+   * # Returns
+   *
+   * Array of `[west, south, east, north]` in decimal degrees:
+   * - **west**: Minimum longitude (left edge)
+   * - **south**: Minimum latitude (bottom edge)
+   * - **east**: Maximum longitude (right edge)
+   * - **north**: Maximum latitude (top edge)
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const tile = new TileCoord(10, 550, 335);
+   * const [west, south, east, north] = tile.toGeoBbox();
+   * console.log(`Bbox: ${west},${south},${east},${north}`);
+   * ```
+   */
+  toGeoBbox(): Array<number>
+  /**
+   * Get the zoom level (0-32)
+   *
+   * Returns the tile's zoom level. At zoom 0, the entire world is one tile.
+   * Each zoom level doubles the number of tiles in each dimension.
+   */
+  get z(): number
+  /**
+   * Get the tile column (x coordinate)
+   *
+   * Returns the horizontal position in the tile grid (0 to 2^z - 1).
+   * Lower values are further west, higher values are further east.
+   */
+  get x(): number
+  /**
+   * Get the tile row (y coordinate)
+   *
+   * Returns the vertical position in the tile grid (0 to 2^z - 1).
+   * In XYZ convention: lower values are further north, higher values are further south.
+   */
+  get y(): number
+  /**
+   * Convert to JSON string representation
+   *
+   * Returns a JSON object with z, x, and y properties.
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const tile = new TileCoord(10, 550, 335);
+   * console.log(tile.toJson());  // '{"z":10,"x":550,"y":335}'
+   * ```
+   */
+  toJson(): string
+}
+
+/**
+ * HTTP tile server for serving tiles and static content
+ *
+ * A high-performance HTTP server for serving map tiles and static files.
+ * Supports multiple tile sources with hot-reload capability, allowing you
+ * to add or remove tile sources without restarting the server.
+ *
+ * # URL Endpoints
+ *
+ * When a tile source named "osm" is added, the following endpoints become available:
+ * - `GET /tiles/osm/{z}/{x}/{y}` - Retrieve a tile
+ * - `GET /tiles/osm/tiles.json` - TileJSON metadata
+ *
+ * Static files are served according to their configured URL prefix.
+ *
+ * # Examples
+ *
+ * ```javascript
+ * const server = new TileServer({ port: 8080 });
+ *
+ * // Add tile sources
+ * await server.addTileSource('osm', 'tiles/osm.versatiles');
+ * await server.addTileSource('terrain', 'tiles/terrain.mbtiles');
+ *
+ * // Add static content
+ * await server.addStaticSource('public/', '/');
+ *
+ * // Start the server
+ * await server.start();
+ * console.log(`Server running on port ${await server.port}`);
+ *
+ * // Hot reload: add more sources while running
+ * await server.addTileSource('satellite', 'tiles/satellite.pmtiles');
+ *
+ * // Clean up
+ * await server.stop();
+ * ```
+ */
+export declare class TileServer {
+  /**
+   * Create a new tile server
+   *
+   * Creates a new HTTP tile server with the specified configuration.
+   * The server is not started until `start()` is called.
+   *
+   * # Arguments
+   *
+   * * `options` - Optional server configuration
+   *   - `ip`: IP address to bind to (default: "0.0.0.0")
+   *   - `port`: Port to listen on (default: 8080)
+   *   - `minimalRecompression`: Use minimal recompression for better performance (default: false)
+   *
+   * # Examples
+   *
+   * ```javascript
+   * // Default settings (0.0.0.0:8080)
+   * const server = new TileServer();
+   *
+   * // Custom port
+   * const server = new TileServer({ port: 3000 });
+   *
+   * // Custom IP and port with minimal recompression
+   * const server = new TileServer({
+   *   ip: '127.0.0.1',
+   *   port: 8080,
+   *   minimalRecompression: true
+   * });
+   * ```
+   */
+  constructor(options?: ServerOptions | undefined | null)
+  /**
+   * Add a tile source to the server from a TileSource object
+   *
+   * The tiles will be served at /tiles/{name}/...
+   *
+   * This method supports all types of TileSources:
+   * - File-based sources (MBTiles, PMTiles, VersaTiles, TAR, directories) - support hot reload and server restart
+   * - VPL pipeline sources (e.g., filtered or transformed tiles) - must be added before server starts
+   *
+   * File-based sources can be added before or after starting the server (hot reload).
+   * VPL sources must be added before calling start() and will be consumed when the server starts.
+   */
+  addTileSource(name: string, source: TileSource): Promise<void>
+  /**
+   * Add a tile source to the server from a file path
+   *
+   * The tiles will be served at /tiles/{name}/...
+   * Sources can be added before or after starting the server.
+   * Changes take effect immediately without requiring a restart (hot reload).
+   */
+  addTileSourceFromPath(name: string, path: string): Promise<void>
+  /**
+   * Remove a tile source from the server
+   *
+   * Changes take effect immediately without requiring a restart (hot reload).
+   * Returns true if the source was found and removed, false otherwise.
+   */
+  removeTileSource(name: string): Promise<boolean>
+  /**
+   * Add a static file source to the server
+   *
+   * Serves static files from a path (can be a .tar or directory)
+   * Changes take effect immediately without requiring a restart (hot reload).
+   */
+  addStaticSource(path: string, urlPrefix?: string | undefined | null): Promise<void>
+  /**
+   * Remove a static file source from the server by URL prefix
+   *
+   * Changes take effect immediately without requiring a restart (hot reload).
+   * Returns true if the source was found and removed, false otherwise.
+   */
+  removeStaticSource(urlPrefix: string): Promise<boolean>
+  /**
+   * Start the HTTP server
+   *
+   * Starts the HTTP server and begins listening for requests on the configured
+   * IP address and port. All tile and static sources that have been added will
+   * be immediately available.
+   *
+   * # Returns
+   *
+   * Returns `Ok(())` if the server started successfully
+   *
+   * # Errors
+   *
+   * Returns an error if:
+   * - The server is already running
+   * - The port is already in use
+   * - Unable to bind to the specified IP address
+   * - Configuration is invalid
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const server = new TileServer({ port: 8080 });
+   * await server.addTileSource('osm', 'tiles.versatiles');
+   * await server.start();
+   * console.log('Server started successfully');
+   * ```
+   */
+  start(): Promise<void>
+  /**
+   * Stop the HTTP server gracefully
+   *
+   * Gracefully shuts down the HTTP server, completing any in-flight requests
+   * before closing. After stopping, the server can be restarted by calling
+   * `start()` again.
+   *
+   * If the server is not running, this method does nothing and returns successfully.
+   *
+   * # Examples
+   *
+   * ```javascript
+   * await server.start();
+   * // ... server is running ...
+   * await server.stop();
+   * console.log('Server stopped');
+   *
+   * // Can restart later
+   * await server.start();
+   * ```
+   */
+  stop(): Promise<void>
+  /**
+   * Get the port the server is listening on
+   *
+   * Returns the port number the server is configured to use or is currently
+   * listening on. If the server was configured with port 0 (ephemeral port),
+   * this will return the actual port assigned by the operating system after
+   * the server has started.
+   *
+   * # Returns
+   *
+   * The port number (1-65535)
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const server = new TileServer({ port: 8080 });
+   * console.log(`Configured port: ${await server.port}`); // 8080
+   *
+   * await server.start();
+   * console.log(`Server listening on port: ${await server.port}`); // 8080
+   * ```
+   */
+  get port(): Promise<number>
+}
+
+/**
+ * Container reader for accessing tile data from various formats
+ *
+ * Provides async methods to read tiles and metadata from supported container formats.
+ * All operations are thread-safe and can be called concurrently from multiple tasks.
+ *
+ * # Supported Formats
+ *
+ * **Local files:**
+ * - `.versatiles` - VersaTiles native format
+ * - `.mbtiles` - MBTiles (SQLite-based)
+ * - `.pmtiles` - PMTiles (cloud-optimized)
+ * - `.tar` - TAR archives
+ * - Directories - Standard tile directory structure
+ *
+ * **Remote URLs:**
+ * - `.versatiles` files via HTTP/HTTPS
+ * - `.pmtiles` files via HTTP/HTTPS (with range request support)
+ */
+export declare class TileSource {
+  /**
+   * Open a tile container from a file path or URL
+   *
+   * Automatically detects the container format based on the file extension
+   * or content. Supports both local files and remote URLs.
+   *
+   * # Arguments
+   *
+   * * `path` - File path or URL to the tile container
+   *
+   * # Returns
+   *
+   * A `ContainerReader` instance ready to read tiles
+   *
+   * # Errors
+   *
+   * Returns an error if:
+   * - The file or URL doesn't exist or is inaccessible
+   * - The format is not recognized or supported
+   * - The file is corrupted or invalid
+   *
+   * # Examples
+   *
+   * ```javascript
+   * // Open local file
+   * const reader = await ContainerReader.open('tiles.versatiles');
+   *
+   * // Open remote file
+   * const reader = await ContainerReader.open('https://example.com/tiles.pmtiles');
+   * ```
+   */
+  static open(path: string): Promise<TileSource>
+  /**
+   * Create a TileSource from a VPL (VersaTiles Pipeline Language) string
+   *
+   * VPL allows you to define tile processing pipelines that can filter, transform,
+   * and combine tile sources. This is useful for on-the-fly tile manipulation without
+   * creating intermediate files.
+   *
+   * # Arguments
+   *
+   * * `vpl` - VPL pipeline definition string
+   * * `dir` - Optional base directory for resolving relative file paths in the VPL.
+   *   Defaults to the current working directory if not specified.
+   *
+   * # VPL Operations
+   *
+   * Common VPL operations include:
+   * - `from_container filename="..."` - Load tiles from a container file
+   * - `filter level_min=X level_max=Y` - Filter by zoom levels
+   * - `filter bbox=[west,south,east,north]` - Filter by geographic bounds
+   * - Pipeline operators can be chained with `|`
+   *
+   * # Returns
+   *
+   * A `TileSource` instance representing the VPL pipeline
+   *
+   * # Errors
+   *
+   * Returns an error if:
+   * - The VPL syntax is invalid
+   * - Referenced files don't exist or are inaccessible
+   * - Pipeline operations are incompatible
+   *
+   * # Examples
+   *
+   * ```javascript
+   * // Simple container loading with explicit directory
+   * const source = await TileSource.fromVpl(
+   *   'from_container filename="tiles.mbtiles"',
+   *   '/path/to/tiles'
+   * );
+   *
+   * // Using current directory (omit second argument)
+   * const source2 = await TileSource.fromVpl(
+   *   'from_container filename="tiles.mbtiles"'
+   * );
+   *
+   * // Filter by zoom level
+   * const filtered = await TileSource.fromVpl(
+   *   'from_container filename="tiles.mbtiles" | filter level_min=5 level_max=10',
+   *   '/path/to/tiles'
+   * );
+   *
+   * // Filter by geographic area
+   * const berlin = await TileSource.fromVpl(
+   *   'from_container filename="world.mbtiles" | filter bbox=[13.0,52.0,14.0,53.0]',
+   *   '/path/to/tiles'
+   * );
+   * ```
+   *
+   * # Note
+   *
+   * VPL sources cannot be converted using `convertTo()` since they may represent
+   * complex pipelines. To convert VPL output, use the `convert()` function instead.
+   */
+  static fromVpl(vpl: string, dir?: string | undefined | null): Promise<TileSource>
+  /**
+   * Convert this tile source to another format
+   *
+   * Converts the current tile source to a different container format with optional
+   * filtering, transformation, and compression changes. Supports real-time progress
+   * monitoring through callback functions.
+   *
+   * # Arguments
+   *
+   * * `output` - Path to the output tile container
+   * * `options` - Optional conversion options (zoom range, bbox, compression, etc.)
+   * * `on_progress` - Optional callback for progress updates
+   * * `on_message` - Optional callback for step/warning/error messages
+   *
+   * # Conversion Options
+   *
+   * - `minZoom` / `maxZoom`: Filter to specific zoom levels
+   * - `bbox`: Geographic bounding box `[west, south, east, north]`
+   * - `bboxBorder`: Add border tiles around bbox (in tile units)
+   * - `compress`: Output compression ("gzip", "brotli", "uncompressed")
+   * - `flipY`: Flip tiles vertically (TMS ↔ XYZ coordinate systems)
+   * - `swapXY`: Swap X and Y tile coordinates
+   *
+   * # Progress Callbacks
+   *
+   * **onProgress callback** receives:
+   * - `position`: Current tile count
+   * - `total`: Total tile count
+   * - `percentage`: Progress percentage (0-100)
+   * - `speed`: Processing speed (tiles/second)
+   * - `eta`: Estimated completion time (as JavaScript Date)
+   *
+   * **onMessage callback** receives:
+   * - `type`: Message type ("step", "warning", or "error")
+   * - `message`: The message text
+   *
+   * # Returns
+   *
+   * A Promise that resolves when conversion is complete
+   *
+   * # Errors
+   *
+   * Returns an error if:
+   * - Output path is invalid or not writable
+   * - Bbox coordinates are invalid (must be `[west, south, east, north]`)
+   * - Compression format is not recognized
+   * - An I/O error occurs during conversion
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const source = await TileSource.open('input.mbtiles');
+   *
+   * // Simple conversion
+   * await source.convertTo('output.versatiles');
+   *
+   * // Convert with compression
+   * await source.convertTo('output.versatiles', {
+   *   compress: 'brotli'
+   * });
+   *
+   * // Convert specific area and zoom range
+   * await source.convertTo('europe.versatiles', {
+   *   minZoom: 0,
+   *   maxZoom: 14,
+   *   bbox: [-10, 35, 40, 70], // Europe
+   *   bboxBorder: 1
+   * });
+   *
+   * // With progress monitoring
+   * await source.convertTo('output.versatiles', null,
+   *   (progress) => {
+   *     console.log(`${progress.percentage.toFixed(1)}% complete`);
+   *   },
+   *   (type, message) => {
+   *     if (type === 'error') console.error(message);
+   *   }
+   * );
+   * ```
+   */
+  convertTo(output: string, options?: ConvertOptions | undefined | null, onProgress?: (((arg: ProgressData) => unknown)) | undefined | null, onMessage?: (((arg: MessageData) => unknown)) | undefined | null): Promise<void>
+  /**
+   * Get a single tile at the specified coordinates
+   *
+   * Retrieves the tile data for the given zoom level (z) and tile coordinates (x, y).
+   * The tile is automatically decompressed and returned as a Buffer.
+   *
+   * # Arguments
+   *
+   * * `z` - Zoom level (0-32)
+   * * `x` - Tile column (0 to 2^z - 1)
+   * * `y` - Tile row (0 to 2^z - 1)
+   *
+   * # Returns
+   *
+   * - `Some(Buffer)` containing the uncompressed tile data if the tile exists
+   * - `None` if the tile doesn't exist at these coordinates
+   *
+   * # Errors
+   *
+   * Returns an error if:
+   * - The coordinates are invalid (out of bounds for the zoom level)
+   * - An I/O error occurs while reading the tile
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const tile = await reader.getTile(10, 512, 384);
+   * if (tile) {
+   *   console.log(`Tile size: ${tile.length} bytes`);
+   * }
+   * ```
+   */
+  getTile(z: number, x: number, y: number): Promise<Buffer | null>
+  /**
+   * Get TileJSON metadata as a JSON string
+   *
+   * Returns the container's metadata in TileJSON format, which includes
+   * information about tile bounds, zoom levels, attribution, and more.
+   *
+   * # Returns
+   *
+   * A JSON string containing TileJSON metadata
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const tileJson = await reader.tileJson();
+   * const metadata = JSON.parse(tileJson);
+   * console.log(`Zoom range: ${metadata.minzoom} - ${metadata.maxzoom}`);
+   * ```
+   */
+  tileJson(): TileJSON
+  /**
+   * Get reader metadata
+   *
+   * Returns detailed technical metadata about the tile container including
+   * format, compression, and available zoom levels.
+   *
+   * # Returns
+   *
+   * A [`SourceMetadata`] object containing:
+   * - `tileFormat`: The tile format (e.g., "png", "jpg", "mvt")
+   * - `tileCompression`: The compression method (e.g., "gzip", "brotli", "uncompressed")
+   * - `minZoom`: Minimum available zoom level
+   * - `maxZoom`: Maximum available zoom level
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const metadata = await reader.metadata();
+   * console.log(`Format: ${metadata.tileFormat}`);
+   * console.log(`Compression: ${metadata.tileCompression}`);
+   * console.log(`Zoom: ${metadata.minZoom}-${metadata.maxZoom}`);
+   * ```
+   */
+  metadata(): SourceMetadata
+  /**
+   * Get the source type
+   *
+   * Returns the name or path of the data source being read.
+   *
+   * # Returns
+   *
+   * The source type (typically the file path or URL)
+   *
+   * # Examples
+   *
+   * ```javascript
+   * const sourceType = await reader.sourceType();
+   * console.log(sourceType.kind);  // "container", "processor", or "composite"
+   * console.log(sourceType.name);  // e.g., "mbtiles"
+   * if (sourceType.kind === "container") {
+   *   console.log(sourceType.uri);  // file path or URL
+   * }
+   * ```
+   */
+  sourceType(): SourceType
+}
+
+/**
+ * Convert tiles from one container format to another
+ *
+ * Converts tiles between different container formats with optional filtering,
+ * transformation, and compression changes. Supports real-time progress monitoring
+ * through callback functions.
+ *
+ * # Arguments
+ *
+ * * `input` - Path or URL to the input tile container
+ * * `output` - Path to the output tile container
+ * * `options` - Optional conversion options (zoom range, bbox, compression, etc.)
+ * * `on_progress` - Optional callback for progress updates
+ * * `on_message` - Optional callback for step/warning/error messages
+ *
+ * # Conversion Options
+ *
+ * - `minZoom` / `maxZoom`: Filter to specific zoom levels
+ * - `bbox`: Geographic bounding box `[west, south, east, north]`
+ * - `bboxBorder`: Add border tiles around bbox (in tile units)
+ * - `compress`: Output compression ("gzip", "brotli", "uncompressed")
+ * - `flipY`: Flip tiles vertically (TMS ↔ XYZ coordinate systems)
+ * - `swapXY`: Swap X and Y tile coordinates
+ *
+ * # Progress Callbacks
+ *
+ * **onProgress callback** receives:
+ * - `position`: Current tile count
+ * - `total`: Total tile count
+ * - `percentage`: Progress percentage (0-100)
+ * - `speed`: Processing speed (tiles/second)
+ * - `eta`: Estimated completion time (as JavaScript Date)
+ *
+ * **onMessage callback** receives:
+ * - `type`: Message type ("step", "warning", or "error")
+ * - `message`: The message text
+ *
+ * # Returns
+ *
+ * A Promise that resolves when conversion is complete
+ *
+ * # Errors
+ *
+ * Returns an error if:
+ * - Input file/URL doesn't exist or is inaccessible
+ * - Output path is invalid or not writable
+ * - Bbox coordinates are invalid (must be `[west, south, east, north]`)
+ * - Compression format is not recognized
+ * - An I/O error occurs during conversion
+ *
+ * # Examples
+ *
+ * ```javascript
+ * // Simple conversion
+ * await convert('input.mbtiles', 'output.versatiles');
+ *
+ * // Convert with compression
+ * await convert('input.pmtiles', 'output.versatiles', {
+ *   compress: 'brotli'
+ * });
+ *
+ * // Convert specific area and zoom range
+ * await convert('world.mbtiles', 'europe.versatiles', {
+ *   minZoom: 0,
+ *   maxZoom: 14,
+ *   bbox: [-10, 35, 40, 70], // Europe
+ *   bboxBorder: 1
+ * });
+ *
+ * // With progress monitoring
+ * await convert('input.tar', 'output.versatiles', null,
+ *   (progress) => {
+ *     console.log(`${progress.percentage.toFixed(1)}% complete`);
+ *     console.log(`Speed: ${progress.speed.toFixed(0)} tiles/sec`);
+ *     console.log(`ETA: ${new Date(progress.eta)}`);
+ *   },
+ *   (type, message) => {
+ *     if (type === 'error') console.error(message);
+ *     else if (type === 'warning') console.warn(message);
+ *     else console.log(message);
+ *   }
+ * );
+ * ```
+ */
+export declare function convert(input: string, output: string, options?: ConvertOptions | undefined | null, onProgress?: (((arg: ProgressData) => unknown)) | undefined | null, onMessage?: (((arg: MessageData) => unknown)) | undefined | null): Promise<void>
+
+/**
+ * Options for tile conversion
+ *
+ * Configure how tiles are filtered, transformed, and compressed during conversion.
+ * All fields are optional - only specify the options you want to apply.
+ */
+export interface ConvertOptions {
+  /**
+   * Minimum zoom level to include (0-32)
+   *
+   * Tiles with zoom levels below this value will be excluded from the output.
+   * Must be less than or equal to `max_zoom` if both are specified.
+   *
+   * **Default:** No minimum filter (all zoom levels included)
+   */
+  minZoom?: number
+  /**
+   * Maximum zoom level to include (0-32)
+   *
+   * Tiles with zoom levels above this value will be excluded from the output.
+   * Must be greater than or equal to `min_zoom` if both are specified.
+   *
+   * **Default:** No maximum filter (all zoom levels included)
+   */
+  maxZoom?: number
+  /**
+   * Geographic bounding box filter in WGS84 coordinates
+   *
+   * Must be an array of exactly 4 numbers: `[west, south, east, north]`
+   * - **west**: Minimum longitude (-180 to 180)
+   * - **south**: Minimum latitude (-85.0511 to 85.0511)
+   * - **east**: Maximum longitude (-180 to 180)
+   * - **north**: Maximum latitude (-85.0511 to 85.0511)
+   *
+   * Only tiles that intersect this bounding box will be included.
+   * Coordinate system is WGS84 (EPSG:4326).
+   *
+   * **Example:** `[13.0, 52.0, 14.0, 53.0]` for Berlin area
+   *
+   * **Default:** No bounding box filter (world coverage)
+   */
+  bbox?: Array<number>
+  /**
+   * Number of extra tiles to include around the bounding box
+   *
+   * Adds a buffer of tiles around the `bbox` at each zoom level.
+   * The value is in tile units, not geographic degrees.
+   * Useful for ensuring smooth rendering at the edges of the bounding box.
+   *
+   * **Example:** A value of `1` adds one tile border on each side
+   *
+   * **Default:** `0` (no border)
+   */
+  bboxBorder?: number
+  /**
+   * Output tile compression format
+   *
+   * Valid values:
+   * - `"gzip"`: Good compression ratio, widely supported
+   * - `"brotli"`: Better compression than gzip, modern browsers only
+   * - `"uncompressed"`: No compression, fastest but largest files
+   *
+   * **Default:** Preserves the source compression format
+   */
+  compress?: string
+  /**
+   * Flip tiles vertically (swap TMS ↔ XYZ coordinate systems)
+   *
+   * - **TMS** (Tile Map Service): Y increases from south to north (origin at bottom-left)
+   * - **XYZ**: Y increases from north to south (origin at top-left)
+   *
+   * Set to `true` to convert between these coordinate systems.
+   *
+   * **Default:** `false` (no flipping)
+   */
+  flipY?: boolean
+  /**
+   * Swap X and Y tile coordinates
+   *
+   * Exchanges the column (x) and row (y) coordinates of each tile.
+   * Rarely needed except for specialized coordinate transformations.
+   *
+   * **Default:** `false` (no swapping)
+   */
+  swapXy?: boolean
+}
+
+/**
+ * Status or diagnostic message from an operation
+ *
+ * Provides step updates, warnings, and errors during processing.
+ */
+export interface MessageData {
+  /**
+   * Message type
+   *
+   * One of:
+   * - `"step"`: Normal progress step or status update
+   * - `"warning"`: Non-fatal issue that doesn't stop the operation
+   * - `"error"`: Fatal error that causes operation failure
+   */
+  type: string
+  /**
+   * The message text
+   *
+   * Human-readable description of the step, warning, or error.
+   */
+  message: string
+}
+
+/** Probe result with container information */
+export interface ProbeResult {
+  /** Source name or path */
+  sourceName: string
+  /** Container type (e.g., "mbtiles", "versatiles") */
+  containerName: string
+  /** TileJSON metadata as JSON string */
+  tileJson: string
+  /** Reader parameters */
+  parameters: SourceMetadata
+}
+
+/**
+ * Progress information for long-running operations
+ *
+ * Provides real-time progress updates during tile conversion and other
+ * operations. All numeric values are floating-point for precision.
+ */
+export interface ProgressData {
+  /**
+   * Current position in the operation
+   *
+   * Number of items (tiles, bytes, etc.) that have been processed so far.
+   * Compare with `total` to determine progress.
+   */
+  position: number
+  /**
+   * Total number of items to process
+   *
+   * The expected total number of items for the complete operation.
+   * May be an estimate and could change during processing.
+   */
+  total: number
+  /**
+   * Completion percentage (0-100)
+   *
+   * Calculated as `(position / total) * 100`.
+   * Useful for displaying progress bars.
+   *
+   * **Example:** `50.5` means 50.5% complete
+   */
+  percentage: number
+  /**
+   * Processing speed in items per second
+   *
+   * Average speed calculated from operation start.
+   * Units match the operation (tiles/sec, bytes/sec, etc.).
+   *
+   * **Example:** `1523.4` means 1523.4 items per second
+   */
+  speed: number
+  /**
+   * Estimated seconds until completion
+   *
+   * Time remaining based on current speed and remaining items.
+   * Returns `null` if insufficient data to estimate (early in operation).
+   *
+   * **Example:** `45.2` means approximately 45 seconds remaining
+   */
+  estimatedSecondsRemaining?: number
+  /**
+   * Estimated completion time as JavaScript Date
+   *
+   * Timestamp in milliseconds since UNIX epoch (January 1, 1970).
+   * Can be converted to a JavaScript Date object with `new Date(eta)`.
+   * Returns `null` if insufficient data to estimate.
+   *
+   * **Example:**
+   * ```javascript
+   * if (progress.eta) {
+   *   const completionTime = new Date(progress.eta);
+   *   console.log(`Expected completion: ${completionTime.toLocaleTimeString()}`);
+   * }
+   * ```
+   */
+  eta?: number
+  /**
+   * Current operation step or status message
+   *
+   * Descriptive text about what the operation is currently doing.
+   *
+   * **Examples:**
+   * - `"Reading tiles"`
+   * - `"Compressing data"`
+   * - `"Writing output"`
+   */
+  message?: string
+}
+
+/**
+ * Configuration options for the tile server
+ *
+ * All fields are optional and will use sensible defaults if not specified.
+ */
+export interface ServerOptions {
+  /**
+   * IP address or hostname to bind to
+   *
+   * Determines which network interface the server listens on:
+   * - `"0.0.0.0"`: Listen on all network interfaces (accessible from any network)
+   * - `"127.0.0.1"`: Listen only on localhost (local access only)
+   * - Specific IP: Listen only on that interface
+   *
+   * **Security Note:** Using `"0.0.0.0"` makes the server accessible from the network.
+   * Use `"127.0.0.1"` for development or when using a reverse proxy.
+   *
+   * **Default:** `"0.0.0.0"` (all interfaces)
+   */
+  ip?: string
+  /**
+   * TCP port number to listen on (1-65535)
+   *
+   * The port where the HTTP server will accept connections.
+   * - Use `0` to let the OS assign an available port automatically (ephemeral port)
+   * - Ports below 1024 typically require administrator/root privileges
+   * - Common choices: 8080, 3000, 8000
+   *
+   * **Default:** `8080`
+   */
+  port?: number
+  /**
+   * Enable minimal recompression for improved performance
+   *
+   * When enabled, the server performs minimal tile recompression to match
+   * client requirements, favoring speed over optimal compression ratio:
+   * - Tiles are served with their original compression when possible
+   * - Only recompresses when absolutely necessary for client compatibility
+   * - Reduces CPU usage and improves response times
+   * - May result in slightly larger tile sizes sent to clients
+   *
+   * When disabled (default), the server optimally recompresses tiles to match
+   * the client's preferred compression format, which provides better bandwidth
+   * efficiency but uses more CPU.
+   *
+   * **Recommended:** Enable for high-traffic servers or when CPU is limited.
+   *
+   * **Default:** `false` (optimal recompression)
+   */
+  minimalRecompression?: boolean
+}
+
+/** Tile source metadata describing output characteristics */
+export interface SourceMetadata {
+  /** Tile format (e.g., "png", "jpg", "mvt") */
+  tileFormat: string
+  /** Tile compression (e.g., "gzip", "brotli", "uncompressed") */
+  tileCompression: string
+  /** Minimum zoom level available */
+  minZoom: number
+  /** Maximum zoom level available */
+  maxZoom: number
+}
+
+export interface TileJSON {
+  tilejson: string
+  minzoom: number
+  maxzoom: number
+  /** Geographic bounding box. If `Some`, `[west, south, east, north]`. */
+  bounds?: Array<number>
+  /** Geographic center. If `Some`, `[longitude, latitude, zoom_level]`. */
+  center?: Array<number>
+  /** The collection of vector layers, if any. */
+  vectorLayers?: Array<VectorLayer>
+  /** Optional tile content type derived from format (raster/vector/unknown). */
+  tileType?: string
+  /** Optional tile format (e.g., "image/png", "application/x-protobuf"). */
+  tileFormat?: string
+  /** Optional tile schema describing the expected layer/attribute structure. */
+  tileSchema?: string
+  /** Optional tile size in pixels (typically 256 or 512). */
+  tileSize?: number
+}
+
+export interface VectorLayer {
+  id: string
+  fields: Record<string, string>
+  description?: string
+  minzoom?: number
+  maxzoom?: number
+}