@vexil-lang/runtime

TypeScript runtime for code generated by the Vexil schema compiler. This package is a dependency of generated TypeScript code -- you add it alongside code produced by vexilc codegen --target typescript.

Zero dependencies. ESM-only. Node >= 18.

Install

npm install @vexil-lang/runtime

API

BitWriter

Packs fields LSB-first at the bit level. Sub-byte fields accumulate within a byte; multi-byte writes align to a byte boundary first, then append little-endian bytes.

import { BitWriter } from '@vexil-lang/runtime';

const w = new BitWriter();
w.writeBits(5, 4);      // 4 bits
w.writeU16(1000);       // aligns, then 2 bytes LE
w.writeVarint(42n);     // unsigned LEB128
w.writeZigzag(-7n);     // ZigZag-encoded signed LEB128
w.writeString('hello'); // length-prefixed UTF-8
const bytes: Uint8Array = w.finish();

BitReader

Reads fields LSB-first from a Uint8Array. Mirrors BitWriter method-for-method.

import { BitReader } from '@vexil-lang/runtime';

const r = new BitReader(bytes);
const bits = r.readBits(4);       // 4-bit unsigned integer
const val  = r.readU16();         // aligns, reads 2 bytes LE
const v    = r.readVarint();      // unsigned LEB128 -> bigint
const s    = r.readZigzag();      // ZigZag LEB128 -> bigint
const str  = r.readString();      // length-prefixed UTF-8

SchemaHandshake

Exchanges BLAKE3 schema hashes between peers to detect mismatches before data transfer:

import { SchemaHandshake } from '@vexil-lang/runtime';

const handshake = new SchemaHandshake(schemaHash);
const offer = handshake.createOffer();      // send to peer
const accepted = handshake.accept(offer);   // peer validates hash match

Wire compatibility

BitWriter and BitReader produce and consume the same byte sequences as the Rust vexil-runtime crate. This is verified by the compliance vector suite.

Safety limits

• Max recursion depth: 64
• Max byte array / string length: 64 MiB
• Length prefix: up to 4 bytes (LEB128)

License

Licensed under either of MIT or Apache-2.0 at your option.