@muxion/cabi-runtime-js

Zero-copy TypeScript access to fixed little-endian binary buffers. This package has no runtime dependencies. It works with Uint8Array, Node Buffer views, and WebAssembly memory views.

Use @muxion/cabi-generate-cli-node to compile version-2 YAML schemas to TypeScript, Rust, and C. Generated TypeScript imports this runtime. The compiler, YAML parser, and CLI are in the generator package.

import { BinaryView, validateRange } from '@muxion/cabi-runtime-js'
import type {
  u8,
  i8,
  u16,
  i16,
  u32,
  i32,
  u64,
  i64,
  f32,
  f64,
  Primitive,
  Uint64Words,
} from '@muxion/cabi-runtime-js'

BinaryView borrows a buffer and provides little-endian scalar access through distinct methods: readU8, readI8, readU16, readI16, readU32, readI32, readU64, readI64, readF32, and readF64. Each has a matching write method, such as writeU64(value, offset). Reads take an optional byte offset; writes take the value followed by an optional byte offset. Offsets default to zero. readU64 returns u64, and readI64 returns i64; their matching writes take those types. Its bytes property returns a borrowed byte view. Generated classes add typed struct, array, pointer, slice, and union accessors. Buffer offsets are relative to the start of the supplied Uint8Array, including subarrays.

validateRange(buffer, offset, length, itemSize, itemAlignment) checks relative references for bounds, null rules, alignment, and overflow. Pointer offset zero is null. An empty slice is canonically {offset: 0, length: 0}. A zero offset with nonzero length is invalid.

Scalar types are compile-time intersections: u8 = number & { cabi: 'u8' }, u64 = bigint & { cabi: 'u64' }, and matching tags for all other scalars. u64 and i64 use bigint; the other scalars use number. All buffer offsets, lengths, sizes, alignments, indexes, and Uint64Words elements use u32.

Callers apply type-only casts. There are no scalar conversion functions or scalar range checks. Reads return ordinary numbers or bigints with a static tag; they do not create tagged objects. Writes trust the scalar tag and use DataView's fixed-width encoding. Buffer and reference checks still apply.

const view = new BinaryView(new Uint8Array(16), 0 as u32, 16 as u32, 8 as u32)
view.writeU8(7 as u8)
view.writeU64(42n as u64, 8 as u32)
const value: u64 = view.readU64(8 as u32)

Uint64Words stores full-width bits as tagged unsigned low and high words. readWords() and writeWords() remain available.

Keep the backing buffer alive while views exist. Create new views after WebAssembly memory grows. The runtime provides no synchronization for concurrent writers.

npm run build --workspace=@muxion/cabi-runtime-js
npm test --workspace=@muxion/cabi-runtime-js
npm run lint --workspace=@muxion/cabi-runtime-js