@subvertic/vrl-core

Framework-free core for Vertical Route Language.

This package parses compact VRL source, validates route semantics, normalizes route models, computes elevation-aware vertical layout data, and exports JSON. It has no framework, DOM, file-system, or network dependencies.

Install

npm install @subvertic/vrl-core

Usage

import { compileRoute, formatDiagnostic } from "@subvertic/vrl-core";

const source = `
route "Quebrada Gata"
metadata entrance_elevation=1300m exit_elevation=1100m difficulty="V3 A4 III"
start "Quebrada Pilas entrance"
rappel "R1" height=28m rope=60m anchor=bolts inclination=90%
pool type=shallow
exit "Old metal ladder"
`;

const result = compileRoute(source, {
  layout: {
    width: 900,
    horizontalScale: 1.15,
    pixelsPerMeter: 6,
    minNodeGap: 68
  }
});

if (result.ok === false) {
  console.error(result.diagnostics.map(formatDiagnostic).join("\n"));
} else {
  console.log(result.model.summary.requiredRopeMeters);
  console.log(result.layout.nodes.length);
  console.log(result.json);
}

Main Exports

import {
  parseVrl,
  validateRoute,
  normalizeRoute,
  computeVerticalLayout,
  compileRoute,
  createRouteCompiler,
  exportRouteJson
} from "@subvertic/vrl-core";

• parseVrl(source) returns { ast, diagnostics }.
• validateRoute(ast) returns semantic diagnostics.
• normalizeRoute(ast) returns a stable route model with generated element IDs and summary fields.
• computeVerticalLayout(model, options) computes SVG-ready node positions.
• compileRoute(source, options) runs the full parser, validation, normalization, layout, and JSON export pipeline.
• createRouteCompiler(overrides) creates an injectable compiler for tests or alternate ports.
• exportRouteJson(model) serializes normalized route data.

Diagnostics

Diagnostics are plain objects:

{
  kind: "syntax",
  severity: "error",
  message: "Unknown statement \"teleport\".",
  location: { line: 3, column: 1 },
  suggestion: "Use route, metadata, start, walk, rappel, downclimb, climb, pool, hazard, note, or exit."
}

Use formatDiagnostic(diagnostic) for readable CLI, build, or editor output.

Layout Options

compileRoute(source, {
  layout: {
    width: 900,
    spineX: 120,
    horizontalScale: 1.15,
    marginY: 120,
    marginBottom: 80,
    pixelsPerMeter: 6,
    minNodeGap: 68
  }
});

horizontalScale controls how far route nodes advance across the canvas. Values above 1 use more horizontal space while preserving the vertical profile. minNodeGap keeps dense elevation-aware diagrams readable by adding visual spacing when nearby route nodes would overlap. Set it to 0 for strict elevation scale.

License

MIT. Copyright (c) 2026 Pedro Guzmán.