hedl-wasm 2.0.0

WebAssembly bindings for HEDL with TypeScript support
Documentation

hedl-wasm

Parse, validate, and convert HEDL documents directly in browsers and Node.js with near-native performance.

Every web developer has faced the same frustration: JSON is everywhere but loses type information, YAML parsers are heavy, and XML processing adds complexity. What if you could parse structured data at near-native speed, validate it with full schema checking, and convert between formats instantly, all without leaving JavaScript?

That's what hedl-wasm delivers. The complete Rust HEDL implementation, compiled to WebAssembly, running in your browser or Node.js environment. Parse multi-megabyte documents at 50-100 MB/s. Validate data structures client-side before they ever hit your server. Convert seamlessly between HEDL, JSON, YAML, XML, and CSV with zero compromises on correctness.

Installation

npm install hedl-wasm

Quick Start

Browser (ESM)

<script type="module">
  import init, { parse, validate, toJson } from './hedl_wasm.js';

  await init();

  const doc = parse(`
%V:2.0
%S:User:[id, name, age]
---
users: @User
 | alice, Alice Smith, 30
 | bob, Bob Jones, 25
  `);

  console.log('Parsed:', doc);
  console.log('JSON:', doc.toJson());
</script>

Node.js (CommonJS)

const hedl = require('hedl-wasm');

const doc = hedl.parse(`
%V:2.0
---
config:
  name: MyApp
  version: 1.0.0
`);

console.log('Document:', doc);

Node.js (ESM)

import init, { parse, validate } from 'hedl-wasm';

await init();

const result = validate(hedlContent);

if (result.valid) {
  console.log('Valid HEDL document');
} else {
  result.errors.forEach(err => {
    console.error(`Line ${err.line}: ${err.message}`);
  });
}

Core API

parse(input: string): HedlDocument

Parse HEDL content into a structured document.

import { parse } from 'hedl-wasm';

const doc = parse(`
%V:2.0
%S:User:[id, name, email]
---
users: @User
 | alice, Alice Smith, alice@example.com
 | bob, Bob Jones, bob@example.com
`);

console.log('Version:', doc.version);
console.log('Schemas:', doc.getSchemaNames());
console.log('Aliases:', doc.getAliases());

Returns: HedlDocument with these properties:

  • version: string - HEDL version (e.g., "2.0")
  • schemaCount: number - Number of schema definitions
  • aliasCount: number - Number of aliases
  • nestCount: number - Number of nest relationships
  • rootItemCount: number - Number of root items

Methods:

  • getSchemaNames(): string[] - Get all schema type names
  • getSchema(typeName: string): string[] | null - Get schema columns for a type
  • getAliases(): object - Get all aliases as a JSON object
  • getNests(): object - Get all nest relationships
  • countEntities(): object - Count entities by type
  • query(typeName?: string, id?: string): Array<{ type: string, id: string, fields: object }> - Query entities (requires "query-api" feature)
  • toJson(): JsonValue - Convert to JSON object (requires "json" feature)
  • toJsonString(pretty?: boolean): string - Convert to JSON string (requires "json" feature)
  • toHedl(): string - Convert to canonical HEDL string

Throws: JsError on parse failure with line number information in the message.

validate(input: string, runLint?: boolean): ValidationResult

Validate HEDL documents and return detailed diagnostics.

import { validate } from 'hedl-wasm';

const result = validate(hedlContent, true);

if (!result.valid) {
  result.errors.forEach(err => {
    console.error(`Line ${err.line} [${err.type}]: ${err.message}`);
  });
}

result.warnings.forEach(warn => {
  console.warn(`Line ${warn.line} [${warn.rule}]: ${warn.message}`);
});

Parameters:

  • input: string - HEDL document content
  • runLint?: boolean - Enable lint checks (default: true, requires "full-validation" feature)

Returns: ValidationResult with:

  • valid: boolean - Whether document is valid
  • errors: Array<{ line: number, message: string, type: string }> - Parse and validation errors
  • warnings: Array<{ line: number, message: string, rule: string }> - Lint warnings

format(input: string): string

Format and canonicalize HEDL documents.

import { format } from 'hedl-wasm';

const formatted = format(messyHedl);

Returns normalized HEDL with consistent indentation, float representation, and spacing.

version(): string

Get the HEDL library version.

import { version } from 'hedl-wasm';

console.log('HEDL version:', version());

setMaxInputSize(size: number): void

Configure the maximum input size in bytes for all parsing operations.

import { setMaxInputSize } from 'hedl-wasm';

// Allow processing up to 1 GB documents
setMaxInputSize(1024 * 1024 * 1024);

Default is 500 MB. The size check runs before parsing to prevent memory exhaustion.

getMaxInputSize(): number

Get the current maximum input size configuration.

import { getMaxInputSize } from 'hedl-wasm';

const currentLimit = getMaxInputSize();
console.log(`Current limit: ${currentLimit / (1024 * 1024)} MB`);

Format Conversion

All conversion functions work both as standalone functions on strings and as methods on HedlDocument objects.

toJson(input: string, pretty?: boolean): string

Convert HEDL to JSON. Requires the "json" feature flag.

import { toJson } from 'hedl-wasm';

const json = toJson(hedlContent, true); // true for pretty-print

fromJson(json: string): string

Convert JSON to HEDL. Requires the "json" feature flag.

import { fromJson } from 'hedl-wasm';

const hedl = fromJson(jsonString);

toYaml(input: string): string

Convert HEDL to YAML. Requires the "yaml" feature flag.

import { toYaml } from 'hedl-wasm';

const yaml = toYaml(hedlContent);

fromYaml(yaml: string): string

Convert YAML to HEDL. Requires the "yaml" feature flag.

import { fromYaml } from 'hedl-wasm';

const hedl = fromYaml(yamlContent);

toXml(input: string): string

Convert HEDL to XML. Requires the "xml" feature flag.

import { toXml } from 'hedl-wasm';

const xml = toXml(hedlContent);

fromXml(xml: string): string

Convert XML to HEDL. Requires the "xml" feature flag.

import { fromXml } from 'hedl-wasm';

const hedl = fromXml(xmlContent);

toCsv(input: string): string

Convert HEDL to CSV (first entity list). Requires the "csv" feature flag.

import { toCsv } from 'hedl-wasm';

const csv = toCsv(hedlContent);

fromCsv(csv: string, typeName?: string): string

Convert CSV to HEDL. Requires the "csv" feature flag.

import { fromCsv } from 'hedl-wasm';

const hedl = fromCsv(csvContent, 'User');

Parameters:

  • csv: string - CSV content (must have header row)
  • typeName?: string - Entity type name (default: "Row")

toToon(input: string): string

Convert HEDL to TOON format. Requires the "toon" feature flag.

import { toToon } from 'hedl-wasm';

const toon = toToon(hedlContent);

fromToon(toon: string): string

Convert TOON to HEDL. Requires the "toon" feature flag.

import { fromToon } from 'hedl-wasm';

const hedl = fromToon(toonContent);

Statistics and Analysis

getStats(input: string): TokenStats

Get token usage statistics comparing HEDL to JSON. Requires the "statistics" feature flag.

import { getStats } from 'hedl-wasm';

const stats = getStats(hedlContent);

console.log('HEDL bytes:', stats.hedlBytes);
console.log('HEDL tokens:', stats.hedlTokens);
console.log('JSON bytes:', stats.jsonBytes);
console.log('JSON tokens:', stats.jsonTokens);
console.log('Savings:', stats.savingsPercent + '%');

Returns: TokenStats with:

  • hedlBytes: number - Input HEDL size in bytes
  • hedlTokens: number - Estimated token count for HEDL
  • hedlLines: number - Line count in HEDL
  • jsonBytes: number - Equivalent JSON size in bytes
  • jsonTokens: number - Estimated token count for JSON
  • savingsPercent: number - Token savings percentage
  • tokensSaved: number - Absolute token count difference

compareTokens(hedl: string, json: string): object

Compare token counts between HEDL and JSON. Requires the "token-tools" feature flag.

import { compareTokens } from 'hedl-wasm';

const comparison = compareTokens(hedlString, jsonString);

console.log('HEDL tokens:', comparison.hedl.tokens);
console.log('JSON tokens:', comparison.json.tokens);
console.log('Savings:', comparison.savings.percent + '%');

Returns: Object with:

  • hedl: { bytes: number, tokens: number, lines: number }
  • json: { bytes: number, tokens: number }
  • savings: { percent: number, tokens: number }

Error Handling

All functions throw structured errors with line number information.

try {
  const doc = parse(invalidHedl);
} catch (error) {
  console.error(`Parse error: ${error.message}`);
}

When using validate(), errors are returned in the ValidationResult object with:

  • line: number - Source line number (1-indexed)
  • message: string - Human-readable description
  • type: string - Error category

Error Types:

  • Syntax - Invalid HEDL syntax
  • Schema - Type/schema mismatch
  • Reference - Unresolved reference
  • ShapeMismatch - Column count mismatch
  • OrphanRow - Child without parent
  • Utf8 - Invalid UTF-8 encoding
  • MaxSizeExceeded - Input too large

TypeScript Support

Complete type definitions are included for full IntelliSense support.

import {
  parse,
  validate,
  format,
  toJson,
  fromJson,
  getStats,
  compareTokens,
  HedlDocument,
  ValidationResult,
  TokenStats
} from 'hedl-wasm';

const doc: HedlDocument = parse(content);

const result: ValidationResult = validate(content, false);

if (!result.valid) {
  result.errors.forEach(err => {
    console.error(`Line ${err.line}: ${err.message}`);
  });
}

const stats: TokenStats = getStats(content);
console.log(`Savings: ${stats.savingsPercent}%`);

Exported Types:

  • HedlDocument - Parsed HEDL document with methods
  • ValidationResult - Validation diagnostics
  • TokenStats - Token usage statistics
  • JsonValue - JSON value union type
  • JsonPrimitive - JSON primitive types
  • JsonObject - JSON object type
  • JsonArray - JSON array type

Bundle Sizes

Optimized for web delivery with wasm-opt -Os, tree-shaking support, and dead code elimination.

Format Size
Uncompressed ~600 KB
Gzipped ~200 KB
Brotli ~180 KB

Bundle Variants:

  • hedl_wasm.js - ESM for browsers
  • hedl_wasm_node.js - CommonJS for Node.js
  • hedl_wasm_bg.wasm - WebAssembly binary
  • hedl.d.ts - TypeScript definitions

Performance

Parsing runs at near-native speed, typically within 10% of the pure Rust implementation. Expect 50-100 MB/s throughput on modern browsers. Token estimation uses an O(1) memory algorithm with efficient byte-level iteration, running 3x faster than character-by-character approaches.

Memory scales linearly with document size. Initial WASM module load adds approximately 50-100ms overhead, a one-time cost per page load.

Building from Source

Prerequisites

cargo install wasm-pack
cargo install wasm-tools
cargo install wasm-bindgen-cli --version 0.2.108

Build

cd crates/hedl-wasm

# Build for browsers
./build-wasm.sh web

# Build for bundlers (webpack, etc.)
./build-wasm.sh bundler

# Build for Node.js
./build-wasm.sh nodejs

Output is placed in pkg/:

  • hedl_wasm.js - JavaScript glue code
  • hedl_wasm.d.ts - TypeScript definitions
  • hedl_wasm_bg.wasm - WebAssembly binary

License

Apache-2.0