@versatiles/versatiles-rs 4.6.1 → 4.8.0

package/README.md

@@ -9,6 +9,7 @@ Node.js bindings for [VersaTiles](https://github.com/versatiles-org/versatiles-r
 - 🗺️ **Tile Server** - Built-in HTTP tile server with dynamic source management
 - 📊 **Metadata Access** - Read TileJSON and inspect container details
 - 🌍 **Coordinate Utils** - Convert between tile and geographic coordinates
+- 🧩 **VPL Pipelines** - Build, parse and losslessly edit VersaTiles Pipeline Language
 - ⚡ **Async API** - Non-blocking operations with Promise-based interface
 - 📦 **Dual Format** - Supports both ESM and CommonJS
 
@@ -349,6 +350,83 @@ Get JSON representation.
 - `coord.x` (number): Column
 - `coord.y` (number): Row
 
+### VPL — the VersaTiles Pipeline Language
+
+Everything below is exported from `@versatiles/versatiles-rs/vpl` and shares one grammar with the
+Rust engine, so anything it writes is something the engine will read.
+
+#### Building and running a pipeline
+
+```javascript
+import { VPL } from '@versatiles/versatiles-rs/vpl';
+
+const pipeline = VPL.fromContainer({ filename: 'world.versatiles' })
+  .filter({ levelMin: 0, levelMax: 14 })
+  .rasterFormat({ format: 'webp', quality: '80' });
+
+pipeline.toString();
+// "from_container filename=world.versatiles | filter level_max=14 level_min=0 | raster_format format=webp quality=80"
+
+// resolve relative filenames against a directory, then execute
+const source = await pipeline.fromPath('./data');
+```
+
+Values are quoted by the grammar rather than by the caller, so spaces, quotes and newlines need no
+special handling. Note that parameters come out in alphabetical order: the pipeline a `VPL` object
+describes is a set of parameters, not a sequence of them.
+
+#### Parsing
+
+```javascript
+const pipeline = VPL.parse("from_container filename='world.versatiles'");
+
+// Errors as data, for an editor that re-parses on every keystroke:
+const error = VPL.parseError('from_container filename=a | vector_filter zoom');
+error.span; // { start: 46, end: 46 } — byte offsets into the text
+error.message; // "expected '=', got end of input"
+error.trace; // the caret-annotated rendering the CLI prints
+```
+
+`VPL.parse` throws a `SyntaxError` instead, with the same object attached as `error.vpl`.
+
+Offsets are **bytes**, not characters, so a caller can convert to whatever unit it counts in — an
+editor in characters, a language server in UTF-16 units. Anything non-ASCII earlier in the line
+makes the two differ.
+
+#### Editing a file somebody wrote
+
+`VPL` is the _semantic_ pipeline: it forgets comments, formatting and parameter order, which is
+right for building a pipeline and wrong for saving one. To edit a `.vpl` file without rewriting the
+parts nobody touched, use the concrete syntax tree, which keeps every byte:
+
+```javascript
+import { parseCst, stringifyCst } from '@versatiles/versatiles-rs/vpl';
+
+const source = "# where the data lives\nfrom_container  filename = 'berlin.versatiles'\n";
+const cst = parseCst(source);
+
+stringifyCst(cst) === source; // true — nothing was lost on the way in
+
+const value = cst.pipeline.nodes[0].value.properties[0].value;
+value.token.text = 'hamburg.versatiles';
+value.quote = 'bare';
+
+stringifyCst(cst);
+// "# where the data lives\nfrom_container  filename = hamburg.versatiles\n"
+```
+
+The comment, the double space and the spaces around `=` all survive, because only the bytes you
+changed are rewritten. `parseCstResult` returns the error as data where `parseCst` throws.
+
+Every token carries a `span` of byte offsets into the parsed text, and `leading` holds the
+whitespace and comments before it. Both may be omitted when building a tree by hand — the minimum
+is `{ pipeline: { nodes: [{ value: { name: { text: 'from_debug' } } }] } }`.
+
+One caveat: `span` describes where a token **was**. After an edit the spans are stale; parse the
+printed text again to get fresh ones.
+
+To run an edited tree, print it and hand it to `TileSource.fromVpl(stringifyCst(cst))`.
+
 ## Supported Formats
 
 - **VersaTiles** (`.versatiles`) - Native format

package/index.cjs

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-android-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-android-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-android-arm-eabi')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-x64-gnu')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-x64-msvc')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-ia32-msvc')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-arm64-msvc')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('@versatiles/versatiles-rs-darwin-universal')
       const bindingPackageVersion = require('@versatiles/versatiles-rs-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-darwin-x64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-darwin-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-freebsd-x64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-freebsd-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-x64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-x64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm-musleabihf')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-loong64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-loong64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-riscv64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-riscv64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-linux-ppc64-gnu')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-linux-s390x-gnu')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-openharmony-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-openharmony-x64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-openharmony-arm')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -648,8 +648,8 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('@versatiles/versatiles-rs-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '4.6.1') {
-            throw new Error(`WASI binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0') {
+            throw new Error(`WASI binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('@versatiles/versatiles-rs-wasm32-wasi')
@@ -707,3 +707,7 @@ module.exports.TileServer = nativeBinding.TileServer
 module.exports.TileSource = nativeBinding.TileSource
 module.exports.convert = nativeBinding.convert
 module.exports.generateVplTypescript = nativeBinding.generateVplTypescript
+module.exports.parseVpl = nativeBinding.parseVpl
+module.exports.parseVplCst = nativeBinding.parseVplCst
+module.exports.stringifyVpl = nativeBinding.stringifyVpl
+module.exports.stringifyVplCst = nativeBinding.stringifyVplCst

package/index.d.ts

@@ -984,6 +984,44 @@ export interface MessageData {
   message: string
 }
 
+/**
+ * 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
+
 /** Probe result with container information */
 export interface ProbeResult {
   /** Source name or path */
@@ -1171,6 +1209,33 @@ export interface SourceMetadata {
   maxZoom: number
 }
 
+/**
+ * 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

package/index.js

@@ -81,8 +81,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-android-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-android-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -97,8 +97,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-android-arm-eabi')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -118,8 +118,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-x64-gnu')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -134,8 +134,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-x64-msvc')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -151,8 +151,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-ia32-msvc')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -167,8 +167,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-win32-arm64-msvc')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -186,8 +186,8 @@ function requireNative() {
     try {
       const binding = require('@versatiles/versatiles-rs-darwin-universal')
       const bindingPackageVersion = require('@versatiles/versatiles-rs-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -202,8 +202,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-darwin-x64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -218,8 +218,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-darwin-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -238,8 +238,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-freebsd-x64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -254,8 +254,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-freebsd-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -275,8 +275,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-x64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -291,8 +291,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-x64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -309,8 +309,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -325,8 +325,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -343,8 +343,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm-musleabihf')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -359,8 +359,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -377,8 +377,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-loong64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -393,8 +393,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-loong64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -411,8 +411,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-riscv64-musl')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -427,8 +427,8 @@ function requireNative() {
         try {
           const binding = require('@versatiles/versatiles-rs-linux-riscv64-gnu')
           const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -444,8 +444,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-linux-ppc64-gnu')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -460,8 +460,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-linux-s390x-gnu')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -480,8 +480,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-openharmony-arm64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -496,8 +496,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-openharmony-x64')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -512,8 +512,8 @@ function requireNative() {
       try {
         const binding = require('@versatiles/versatiles-rs-openharmony-arm')
         const bindingPackageVersion = require('@versatiles/versatiles-rs-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '4.6.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '4.8.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -652,8 +652,8 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('@versatiles/versatiles-rs-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '4.6.1') {
-            throw new Error(`WASI binding package version mismatch, expected 4.6.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '4.8.0') {
+            throw new Error(`WASI binding package version mismatch, expected 4.8.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('@versatiles/versatiles-rs-wasm32-wasi')
@@ -703,7 +703,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { Progress, SourceType, TileCoord, TileServer, TileSource, convert, generateVplTypescript } = nativeBinding
+const { Progress, SourceType, TileCoord, TileServer, TileSource, convert, generateVplTypescript, parseVpl, parseVplCst, stringifyVpl, stringifyVplCst } = nativeBinding
 export { Progress }
 export { SourceType }
 export { TileCoord }
@@ -711,3 +711,7 @@ export { TileServer }
 export { TileSource }
 export { convert }
 export { generateVplTypescript }
+export { parseVpl }
+export { parseVplCst }
+export { stringifyVpl }
+export { stringifyVplCst }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/versatiles-rs",
-  "version": "4.6.1",
+  "version": "4.8.0",
   "description": "Node.js bindings for VersaTiles - convert, serve, and process map tiles",
   "main": "index.js",
   "types": "index.d.ts",
@@ -87,32 +87,32 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@napi-rs/cli": "^3.8.0",
-    "@types/node": "^26.1.2",
+    "@napi-rs/cli": "^3.8.6",
+    "@types/node": "^26.2.0",
     "@vitest/ui": "^4.1.10",
     "chalk": "^6.0.0",
-    "eslint": "^10.8.0",
+    "eslint": "^10.8.1",
     "eslint-config-prettier": "^10.1.8",
-    "npm-check-updates": "^23.0.0",
+    "npm-check-updates": "^23.0.2",
     "prettier": "^3.9.6",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.12",
     "typedoc": "^0.28.20",
-    "typescript": "~6.0.3",
-    "typescript-eslint": "^8.65.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.10"
   },
   "optionalDependencies": {
-    "@versatiles/versatiles-rs-darwin-arm64": "4.6.1",
-    "@versatiles/versatiles-rs-darwin-x64": "4.6.1",
-    "@versatiles/versatiles-rs-linux-arm64-gnu": "4.6.1",
-    "@versatiles/versatiles-rs-linux-arm64-musl": "4.6.1",
-    "@versatiles/versatiles-rs-linux-x64-gnu": "4.6.1",
-    "@versatiles/versatiles-rs-linux-x64-musl": "4.6.1",
-    "@versatiles/versatiles-rs-win32-arm64-msvc": "4.6.1",
-    "@versatiles/versatiles-rs-win32-x64-msvc": "4.6.1"
+    "@versatiles/versatiles-rs-darwin-arm64": "4.8.0",
+    "@versatiles/versatiles-rs-darwin-x64": "4.8.0",
+    "@versatiles/versatiles-rs-linux-arm64-gnu": "4.8.0",
+    "@versatiles/versatiles-rs-linux-arm64-musl": "4.8.0",
+    "@versatiles/versatiles-rs-linux-x64-gnu": "4.8.0",
+    "@versatiles/versatiles-rs-linux-x64-musl": "4.8.0",
+    "@versatiles/versatiles-rs-win32-arm64-msvc": "4.8.0",
+    "@versatiles/versatiles-rs-win32-x64-msvc": "4.8.0"
   },
   "allowScripts": {
-    "esbuild@0.28.1": true,
-    "fsevents@2.3.3": true
+    "esbuild": true,
+    "fsevents": true
   }
 }

package/vpl.d.ts

@@ -1,4 +1,105 @@
 import { TileSource } from './index.js';
+/** A pipeline step in the JSON form the native bindings exchange. */
+export interface VplStep {
+    name: string;
+    params: Record<string, unknown>;
+    sources?: VplStep[][];
+}
+/** A VPL syntax error. `span` and `offset` are **byte** offsets into the parsed text. */
+export interface VplSyntaxError {
+    span: {
+        start: number;
+        end: number;
+    };
+    message: string;
+    context: {
+        label: string;
+        offset: number;
+    }[];
+    /** The caret-annotated rendering, as printed by the CLI. */
+    trace: string;
+}
+/**
+* A stretch of source text, with the whitespace and comments immediately before it.
+*
+* `span` holds **byte** offsets into the text this was parsed from, and covers `text`
+* only. It is absent for tokens you build yourself, and stale after an edit.
+*/
+export interface CstToken {
+    leading?: string;
+    text: string;
+    span?: {
+        start: number;
+        end: number;
+    };
+}
+/** An element of a separated list. The first element has no separator. */
+export interface CstItem<T> {
+    separator?: CstToken;
+    value: T;
+}
+/** How a value was spelled: unquoted, `'single'`, or `\"double\"`. */
+export type CstQuote = 'bare' | 'single' | 'double';
+/** A value, keeping its quotes and escapes exactly as written. */
+export interface CstString {
+    token: CstToken;
+    quote: CstQuote;
+}
+/** The right-hand side of a parameter: one value, or a bracketed list. */
+export type CstValue = ({
+    kind: 'single';
+} & CstString) | {
+    kind: 'array';
+    open: CstToken;
+    items: CstItem<CstString>[];
+    close: CstToken;
+};
+/** A single `key=value` parameter. */
+export interface CstProperty {
+    key: CstToken;
+    equals: CstToken;
+    value: CstValue;
+}
+/** A bracketed list of child pipelines. */
+export interface CstSources {
+    open: CstToken;
+    pipelines: CstItem<CstPipeline>[];
+    close: CstToken;
+}
+/** One operation, with its parameters in the order they were written. */
+export interface CstNode {
+    name: CstToken;
+    properties?: CstProperty[];
+    sources?: CstSources;
+}
+/** Nodes separated by `|`. */
+export interface CstPipeline {
+    nodes: CstItem<CstNode>[];
+}
+/**
+* A whole VPL file, losslessly.
+*
+* Printing an unedited tree reproduces the source byte for byte — comments, indentation,
+* parameter order and quote style included — so editing one value leaves the rest of a
+* hand-written file untouched.
+*/
+export interface CstFile {
+    pipeline: CstPipeline;
+    trailing?: string;
+}
+type CstParseResult = {
+    ok: true;
+    cst: CstFile;
+} | {
+    ok: false;
+    error: VplSyntaxError;
+};
+/** Parse VPL text into a lossless syntax tree, returning the error rather than throwing. */
+export declare function parseCstResult(vpl: string): CstParseResult;
+/** Parse VPL text into a lossless syntax tree, throwing on a syntax error. */
+export declare function parseCst(vpl: string): CstFile;
+/** Write a lossless syntax tree back out as VPL text. */
+export declare function stringifyCst(cst: CstFile): string;
 export interface FromColorOptions {
     /** Hex color in RGB or RGBA format (e.g., "FF5733" or "FF573380"). Defaults to "000000" (black). */
     color?: string;
@@ -42,6 +143,8 @@ export interface FromCsvOptions {
     pointReductionValue?: number;
     /** Tile-compression applied before the tiles leave this operation: `gzip` (default), `brotli`, `zstd`, or `none`. */
     compression?: "none" | "gzip" | "brotli" | "zstd";
+    /** Maximum encoded tile size in bytes before a tile is considered broken and dropped (streaming path) / errors out (single-tile path). Defaults to 1048576 (1 MiB). Raise it when a legitimate low-zoom tile exceeds the default (e.g. `max_tile_bytes=2097152` for 2 MiB), or set `max_tile_bytes=none` to emit tiles at any size. The soft-cap warning threshold (200 KB at the default cap) scales with this value. */
+    maxTileBytes?: number | "none";
 }
 export interface FromDebugOptions {
     /** Target tile format: one of `"mvt"` (default), `"avif"`, `"jpg"`, `"png"` or `"webp"` */
@@ -76,6 +179,8 @@ export interface FromGeoOptions {
     pointReductionValue?: number;
     /** Tile-compression applied before the tiles leave this operation: `gzip` (default), `brotli`, `zstd`, or `none`. */
     compression?: "none" | "gzip" | "brotli" | "zstd";
+    /** Maximum encoded tile size in bytes before a tile is considered broken and dropped (streaming path) / errors out (single-tile path). Defaults to 1048576 (1 MiB). Raise it when a legitimate low-zoom tile exceeds the default (e.g. `max_tile_bytes=2097152` for 2 MiB), or set `max_tile_bytes=none` to emit tiles at any size. The soft-cap warning threshold (200 KB at the default cap) scales with this value. */
+    maxTileBytes?: number | "none";
     /** If `true`, drop the GeoJSON / Shapefile `id` field from every feature before encoding. Useful for sources where the id is a string (e.g. USGS earthquakes — those would be silently dropped at MVT encode anyway, since MVT requires `uint64` ids), or when the id is just noise. Defaults to `false` — keep the id when it's a non-negative integer. */
     ignoreId?: boolean;
 }
@@ -320,6 +425,13 @@ export declare class VPL {
     toString(): string;
     /** Convert this VPL pipeline to a JSON-serializable array of steps. */
     toJSON(): object[];
+    /** A syntax error, with byte offsets into the parsed text. */
+    static parseError(vpl: string): VplSyntaxError | undefined;
+    /** Rebuild a pipeline from the JSON form, nesting child pipelines as VPL. */
+    static fromJSON(steps: VplStep[]): VPL;
+    /** Parse VPL text, throwing on a syntax error. */
+    static parse(vpl: string): VPL;
     /** Execute this VPL pipeline and return a TileSource. */
     fromPath(dir?: string): Promise<TileSource>;
 }
+export {};

package/vpl.js

@@ -1,21 +1,23 @@
 // AUTO-GENERATED — DO NOT EDIT
 // Generated from Rust VPL operation metadata
-import { TileSource } from './index.js';
-function serializeParam(key, value) {
-    if (typeof value === 'boolean') {
-        return `${key}=${value}`;
-    }
-    if (typeof value === 'number') {
-        return `${key}=${value}`;
-    }
-    if (Array.isArray(value)) {
-        return `${key}=[${value.join(',')}]`;
-    }
-    const str = String(value);
-    if (/^[a-zA-Z0-9._-]+$/.test(str)) {
-        return `${key}=${str}`;
-    }
-    return `${key}="${str.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+import { TileSource, parseVpl, parseVplCst, stringifyVpl, stringifyVplCst } from './index.js';
+/** Parse VPL text into a lossless syntax tree, returning the error rather than throwing. */
+export function parseCstResult(vpl) {
+    return JSON.parse(parseVplCst(vpl));
+}
+/** Parse VPL text into a lossless syntax tree, throwing on a syntax error. */
+export function parseCst(vpl) {
+    const result = parseCstResult(vpl);
+    if (!result.ok) {
+        const error = new SyntaxError(result.error.message);
+        error.vpl = result.error;
+        throw error;
+    }
+    return result.cst;
+}
+/** Write a lossless syntax tree back out as VPL text. */
+export function stringifyCst(cst) {
+    return stringifyVplCst(JSON.stringify(cst));
 }
 export class VPL {
     steps;
@@ -69,6 +71,8 @@ export class VPL {
             params['point_reduction_value'] = options.pointReductionValue;
         if (options.compression !== undefined)
             params['compression'] = options.compression;
+        if (options.maxTileBytes !== undefined)
+            params['max_tile_bytes'] = options.maxTileBytes;
         return new VPL([{ name: 'from_csv', params }]);
     }
     /** Generates debug tiles that display their coordinates as text. */
@@ -108,6 +112,8 @@ export class VPL {
             params['point_reduction_value'] = options.pointReductionValue;
         if (options.compression !== undefined)
             params['compression'] = options.compression;
+        if (options.maxTileBytes !== undefined)
+            params['max_tile_bytes'] = options.maxTileBytes;
         if (options.ignoreId !== undefined)
             params['ignore_id'] = options.ignoreId;
         return new VPL([{ name: 'from_geo', params }]);
@@ -354,17 +360,7 @@ export class VPL {
     }
     /** Serialize this VPL pipeline to a string. */
     toString() {
-        return this.steps.map(step => {
-            let result = step.name;
-            if (step.sources && step.sources.length > 0) {
-                const pipelines = step.sources.map(s => s.toString());
-                result += ' [ ' + pipelines.join(', ') + ' ]';
-            }
-            for (const [key, value] of Object.entries(step.params)) {
-                result += ' ' + serializeParam(key, value);
-            }
-            return result;
-        }).join(' | ');
+        return stringifyVpl(JSON.stringify(this.toJSON()));
     }
     /** Convert this VPL pipeline to a JSON-serializable array of steps. */
     toJSON() {
@@ -376,6 +372,29 @@ export class VPL {
             return obj;
         });
     }
+    /** A syntax error, with byte offsets into the parsed text. */
+    static parseError(vpl) {
+        const result = JSON.parse(parseVpl(vpl));
+        return result.ok ? undefined : result.error;
+    }
+    /** Rebuild a pipeline from the JSON form, nesting child pipelines as VPL. */
+    static fromJSON(steps) {
+        return new VPL(steps.map(step => ({
+            name: step.name,
+            params: step.params,
+            sources: step.sources?.map(source => VPL.fromJSON(source)),
+        })));
+    }
+    /** Parse VPL text, throwing on a syntax error. */
+    static parse(vpl) {
+        const result = JSON.parse(parseVpl(vpl));
+        if (!result.ok) {
+            const error = new SyntaxError(result.error.message);
+            error.vpl = result.error;
+            throw error;
+        }
+        return VPL.fromJSON(result.pipeline);
+    }
     /** Execute this VPL pipeline and return a TileSource. */
     async fromPath(dir) {
         return TileSource.fromPipeline(JSON.stringify(this.toJSON()), dir);