@versatiles/versatiles-rs 4.7.0 → 4.9.0

package/index.d.ts

@@ -499,6 +499,8 @@ export declare class TileSource {
    * # Arguments
    *
    * * `path` - File path or URL to the tile container
+   * * `options` - Optional source options; `sshIdentity` names a private key
+   *   file for an `sftp://` path
    *
    * # Returns
    *
@@ -519,9 +521,14 @@ export declare class TileSource {
    *
    * // Open remote file
    * const reader = await ContainerReader.from_path('https://example.com/tiles.pmtiles');
+   *
+   * // Open an SFTP file with a specific key
+   * const reader = await TileSource.fromPath('sftp://host/tiles.pmtiles', {
+   *   sshIdentity: '/home/deploy/.ssh/id_ed25519',
+   * });
    * ```
    */
-  static fromPath(path: string): Promise<TileSource>
+  static fromPath(path: string, options?: SourceOptions | undefined | null): Promise<TileSource>
   /**
    * Create a TileSource from a VPL (VersaTiles Pipeline Language) string
    *
@@ -586,7 +593,7 @@ export declare class TileSource {
    * VPL sources can be converted using `convertTo()` just like any other tile source.
    * The conversion will process the pipeline and write the output tiles to the target format.
    */
-  static fromVpl(vpl: string, dir?: string | undefined | null): Promise<TileSource>
+  static fromVpl(vpl: string, dir?: string | undefined | null, options?: SourceOptions | undefined | null): Promise<TileSource>
   /**
    * Create a TileSource from a pipeline definition (JSON)
    *
@@ -598,8 +605,10 @@ export declare class TileSource {
    * * `steps_json` - JSON string describing the pipeline steps
    * * `dir` - Optional base directory for resolving relative file paths.
    *   Defaults to the current working directory if not specified.
+   * * `options` - Optional source options; `sshIdentity` names a private key
+   *   file for `sftp://` sources inside the pipeline
    */
-  static fromPipeline(stepsJson: string, dir?: string | undefined | null): Promise<TileSource>
+  static fromPipeline(stepsJson: string, dir?: string | undefined | null, options?: SourceOptions | undefined | null): Promise<TileSource>
   /**
    * Convert this tile source to another format
    *
@@ -609,7 +618,7 @@ export declare class TileSource {
    *
    * # Arguments
    *
-   * * `output` - Path to the output tile container
+   * * `output` - Path to the output tile container, or an `sftp://` URL
    * * `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
@@ -621,7 +630,11 @@ export declare class TileSource {
    * - `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
+   * - `swapXy`: Swap X and Y tile coordinates
+   * - `writerOptions`: Format-specific settings for the output writer, keyed by the
+   *   writer's own `snake_case` names, e.g. `{ allow_unclustered: 'true' }` for PMTiles
+   * - `sshIdentity`: Private key file for an `sftp://` input, defaulting to
+   *   `VERSATILES_SSH_IDENTITY`
    *
    * # Progress Callbacks
    *
@@ -780,6 +793,33 @@ export declare class TileSource {
   sourceType(): SourceType
 }
 
+/**
+ * Checks VPL text against the known operations, without building the pipeline.
+ *
+ * Building opens files and fetches URLs, so it cannot run on a keystroke — and it conflates two
+ * failures. `from_container filename=missing.mbtiles` is the *world* being wrong; `from_debug
+ * format=png nonsense=1` is the *pipeline* being wrong. This reports only the second kind, and
+ * performs no I/O.
+ *
+ * Returns a JSON string, with the same result shape as [`parse_vpl`]:
+ *
+ * - on success, `{"ok": true, "problems": [{"message": "...", "path": [0], "property": "nonsense"}]}`
+ *   — an empty `problems` array means nothing is wrong with the pipeline
+ * - on failure, `{"ok": false, "error": {...}}` — the text did not parse at all
+ *
+ * `path` addresses the offending node by index: `[2]` is the third node of the pipeline, and
+ * descending into a node's bracketed sources appends the source index and then the node index.
+ * The same walk applies to the tree from `parseVplCst`, which is how this becomes a span.
+ *
+ * Two things are deliberately *not* reported, because doing so would reject VPL that runs:
+ * parameter values are never validated (`color=red` passes here and fails at build time), and
+ * neither are enum values, since the accepted set includes aliases the metadata does not list.
+ *
+ * @param vpl - the VPL text to check
+ * @returns a JSON string describing either the problems found or a parse error
+ */
+export declare function checkVpl(vpl: string): string
+
 /**
  * Convert tiles from one container format to another
  *
@@ -790,7 +830,7 @@ export declare class TileSource {
  * # Arguments
  *
  * * `input` - Path or URL to the input tile container
- * * `output` - Path to the output tile container
+ * * `output` - Path to the output tile container, or an `sftp://` URL
  * * `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
@@ -802,7 +842,11 @@ export declare class TileSource {
  * - `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
+ * - `swapXy`: Swap X and Y tile coordinates
+ * - `writerOptions`: Format-specific settings for the output writer, keyed by the
+ *   writer's own `snake_case` names, e.g. `{ allow_unclustered: 'true' }` for PMTiles
+ * - `sshIdentity`: Private key file for an `sftp://` input, defaulting to
+ *   `VERSATILES_SSH_IDENTITY`
  *
  * # Progress Callbacks
  *
@@ -951,6 +995,51 @@ export interface ConvertOptions {
    * **Default:** `false` (no swapping)
    */
   swapXy?: boolean
+  /**
+   * Format-specific options for the output writer
+   *
+   * Which options exist depends on the output format. An option the chosen
+   * writer does not accept is an error, not a no-op, and the message lists
+   * what that format does accept.
+   *
+   * Keys reach the writer verbatim, so they keep the writer's own spelling —
+   * `snake_case`, unlike the camelCase fields around them here.
+   *
+   * PMTiles accepts three; every other format accepts none:
+   * - `allow_unclustered` — write an archive that is not physically clustered,
+   *   in a single pass, at the cost of more range requests when serving it
+   * - `reorder` — stay clustered by writing the tile data twice, at the cost of
+   *   a second pass and temporary disk the size of the output
+   * - `temp_dir` — where `reorder` puts that temporary file (default: the
+   *   output file's own directory)
+   *
+   * They matter only for a source that cannot supply Hilbert order, such as a
+   * pipeline containing `raster_overview`; writing one to `.pmtiles` without
+   * either opt-in is an error. Asking for both is also an error, since they buy
+   * different things. Booleans are strings — `'true'`, `'1'` or `'yes'`,
+   * case-insensitively, and likewise for false.
+   *
+   * **Example:** `{ allow_unclustered: 'true' }` when writing PMTiles
+   *
+   * **Default:** No writer options
+   */
+  writerOptions?: Record<string, string>
+  /**
+   * SSH identity (private key) file used for `sftp://` sources
+   *
+   * A path to a private key file on disk — the same thing the CLI's
+   * `--ssh-identity` names. It is read when the input is an `sftp://` URL, and
+   * ignored otherwise.
+   *
+   * Without it, the `VERSATILES_SSH_IDENTITY` environment variable is used;
+   * without that, a password in the URL, the SSH agent and the usual `~/.ssh`
+   * defaults still apply.
+   *
+   * **Example:** `'/home/deploy/.ssh/id_ed25519'`
+   *
+   * **Default:** `VERSATILES_SSH_IDENTITY`, if set
+   */
+  sshIdentity?: string
 }
 
 /**
@@ -961,6 +1050,77 @@ export interface ConvertOptions {
  */
 export declare function generateVplTypescript(): string
 
+/**
+ * Compute the per-layer byte breakdown of an uncompressed vector tile.
+ *
+ * # Arguments
+ *
+ * * `tile` - Uncompressed MVT bytes, as returned by `TileSource.getTile()`.
+ *
+ * # Returns
+ *
+ * One entry per layer, in the order the layers appear in the tile. A tile with
+ * no layers — including a zero-byte buffer, which is what an empty tile encodes
+ * to — yields an empty array. `getTile()` signals a missing tile with `null`,
+ * so an empty buffer means an empty tile rather than a mistake.
+ *
+ * # Errors
+ *
+ * Returns an error if the buffer is not an uncompressed vector tile. Compressed
+ * input and raster input are named as such rather than surfacing as a protobuf
+ * parse failure.
+ *
+ * # Examples
+ *
+ * ```javascript
+ * const { TileSource, layerStats } = require('@versatiles/versatiles-rs');
+ *
+ * const source = await TileSource.fromPath('berlin.mbtiles');
+ * const tile = await source.getTile(14, 8802, 5373);
+ * if (tile) {
+ *   for (const layer of layerStats(tile)) {
+ *     console.log(layer.name, layer.geometryBytes, layer.propertyBytes, layer.encodedBytes);
+ *   }
+ * }
+ * ```
+ */
+export declare function layerStats(tile: Buffer): Array<LayerStats>
+
+/**
+ * Byte breakdown of a single layer within a vector tile.
+ *
+ * All figures are uncompressed MVT content — what can actually be shrunk.
+ * The named categories plus `otherBytes` sum exactly to `encodedBytes`, so a
+ * stacked bar built from them adds up without a fudge factor.
+ */
+export interface LayerStats {
+  /** Layer name. */
+  name: string
+  /** Number of features in the layer. */
+  featureCount: number
+  /** Total number of geometry vertices across all features. */
+  vertexCount: number
+  /** Geometry command streams. */
+  geometryBytes: number
+  /** Per-feature property references (the packed `tag_ids` varints). */
+  tagBytes: number
+  /** Key strings in the property table. */
+  keyBytes: number
+  /** Encoded value messages in the property table. */
+  valueBytes: number
+  /** `keyBytes + valueBytes` — the whole property table. */
+  propertyBytes: number
+  /** Feature ids. Zero for sources that carry none. */
+  idBytes: number
+  /**
+   * Framing, geometry-type fields and the layer name: whatever the named
+   * categories do not account for.
+   */
+  otherBytes: number
+  /** Exact serialized size of the layer. */
+  encodedBytes: number
+}
+
 /**
  * Status or diagnostic message from an operation
  *
@@ -984,17 +1144,43 @@ export interface MessageData {
   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 */
-  tileJsonRaw: string
-  /** Reader parameters */
-  parameters: SourceMetadata
-}
+/**
+ * Parses VPL text into the JSON pipeline representation.
+ *
+ * Returns a JSON string rather than throwing, because an editor parses on every keystroke and a
+ * syntax error there is an expected state rather than an exception:
+ *
+ * - on success, `{"ok": true, "pipeline": [...]}` — the same shape `VPL.toJSON()` produces
+ * - on failure, `{"ok": false, "error": {"span": {...}, "message": "...", "context": [...],
+ *   "trace": "..."}}`
+ *
+ * `span` holds **byte** offsets into the input, so a caller can convert to whatever unit it
+ * counts in. `trace` is the caret-annotated rendering the CLI prints.
+ *
+ * @param vpl - the VPL text to parse
+ * @returns a JSON string describing either the pipeline or the error
+ */
+export declare function parseVpl(vpl: string): string
+
+/**
+ * Parses VPL text into the lossless syntax tree.
+ *
+ * Unlike [`parse_vpl`], which returns the semantic pipeline the engine runs, this keeps
+ * everything the file contains — comments, whitespace, the order the parameters were written in,
+ * and which quotes the author chose. Hold this tree if you mean to edit a file somebody wrote:
+ * [`stringify_vpl_cst`] prints it back byte for byte, so the parts nobody touched stay untouched.
+ *
+ * Returns a JSON string, with the same result shape as [`parse_vpl`]:
+ *
+ * - on success, `{"ok": true, "cst": {...}}`
+ * - on failure, `{"ok": false, "error": {...}}`
+ *
+ * Every token carries a `span` of **byte** offsets into the input.
+ *
+ * @param vpl - the VPL text to parse
+ * @returns a JSON string describing either the syntax tree or the error
+ */
+export declare function parseVplCst(vpl: string): string
 
 /**
  * Progress information for long-running operations
@@ -1157,6 +1343,20 @@ export interface ServerOptions {
    * **Default:** `false` (optimal recompression)
    */
   minimalRecompression?: boolean
+  /**
+   * `Cache-Control` header sent with every tile
+   *
+   * Tile URLs are stable — built from a mount name and a coordinate — so
+   * when the tiles behind a mount change, the URL does not, and the browser
+   * answers from its own cache. A dev server or an interactive preview that
+   * re-mounts under the same name will otherwise keep showing the previous
+   * edit.
+   *
+   * Example: `"no-cache"`.
+   *
+   * **Default:** `"public, max-age=2419200, no-transform"` (four weeks)
+   */
+  cacheControl?: string
 }
 
 /** Tile source metadata describing output characteristics */
@@ -1171,6 +1371,58 @@ export interface SourceMetadata {
   maxZoom: number
 }
 
+/**
+ * Options for opening a tile source
+ *
+ * Everything here is optional; an omitted field keeps the default behaviour.
+ */
+export interface SourceOptions {
+  /**
+   * SSH identity (private key) file used for `sftp://` sources
+   *
+   * A path to a private key file on disk — the same thing the CLI's
+   * `--ssh-identity` names. It is read when the source is an `sftp://` URL,
+   * including one reached through a pipeline, and ignored otherwise.
+   *
+   * Without it, the `VERSATILES_SSH_IDENTITY` environment variable is used;
+   * without that, a password in the URL, the SSH agent and the usual `~/.ssh`
+   * defaults still apply. Set this to give one source a different key than the
+   * rest of the process.
+   *
+   * **Example:** `'/home/deploy/.ssh/id_ed25519'`
+   *
+   * **Default:** `VERSATILES_SSH_IDENTITY`, if set
+   */
+  sshIdentity?: string
+}
+
+/**
+ * Writes a pipeline as VPL text.
+ *
+ * Takes the JSON produced by `VPL.toJSON()` and returns text that `TileSource.fromVpl` accepts.
+ * Quoting is decided by the grammar, so values containing spaces, quotes or newlines are handled
+ * without the caller knowing the rules.
+ *
+ * @param stepsJson - JSON string describing the pipeline steps
+ * @returns the pipeline as VPL text
+ */
+export declare function stringifyVpl(stepsJson: string): string
+
+/**
+ * Writes a lossless syntax tree back out as VPL text.
+ *
+ * The inverse of [`parse_vpl_cst`]: an unedited tree prints back to exactly the text it was
+ * parsed from. Fields that describe formatting — `leading`, `trailing`, `span` — may be omitted
+ * when building a tree by hand, so a minimal node is `{"name": {"text": "from_debug"}}`.
+ *
+ * Note that `span` values are stale after an edit; they describe where a token *was*. Parse the
+ * printed text again to get fresh ones.
+ *
+ * @param cstJson - JSON string describing the syntax tree
+ * @returns the tree as VPL text
+ */
+export declare function stringifyVplCst(cstJson: string): string
+
 export interface TileJSON {
   version: string
   minzoom: number