runtime:serialization

XML, YAML, TOML, CSV, MessagePack, CBOR and JSONL parse in Rust — the text or bytes cross the op boundary once and a JavaScript value comes back. BSON is encoded and decoded by the engine itself, straight from and into JavaScript objects, and JSONC and JSON5 are parsed the same way. Protobuf is the exception: it is a reflective pure-JavaScript implementation, because a .proto is compiled at run time rather than by a build step.

Import

import {
  JSONL, JSONC, JSON5, XML, YAML, TOML, CSV, MessagePack, CBOR, BSON, Protobuf
} from "runtime:serialization";

Every build/encode throws TypeError on a circular value and RangeError past 256 levels of nesting.

JSONL (JSON Lines)

Stream-based parsing and serializing of JSON Lines data. JSONL is heavily optimized for large file handling natively over streams.

JSONC and JSON5

JSON with comments and JSON5 (D191). Both mirror the global JSON.

Values follow JSON.parse: a __proto__ key is an own property and never sets the prototype, a repeated key keeps its first place and its last value, and a \u escape may spell a lone surrogate. Text that is not in the dialect is a SyntaxError whose message names it and ends at line L column C; nesting past 256 levels is a RangeError. JSON5.stringify skips and refuses what JSON.stringify does: undefined, functions and symbols are skipped (null in an array), and a BigInt or a circular value is a TypeError.

XML

Synchronous parsing, building, and validation of XML data, plus streaming support for massive documents.

parse returns an object with the root element as its one key: attributes are @name, an element's text is $text, a repeated name is an array, and an empty element (<a/> or <a></a>) is "". References and CDATA are text.

build writes @name keys as attributes, $text as text, an array as a repeated element and null/undefined as an empty element. Numbers are written as String(n), a BigInt exactly. An invalid name, NaN/±Infinity, bytes, a character XML 1.0 cannot contain, or an array at the top level is a TypeError. DecoderStream emits one { name: value } per direct child of the root, read by the same reader: a malformed record or a truncated document errors the stream.

YAML

Synchronous parsing, building, and validation of YAML 1.2.

parse reads one document; an empty stream is null. Plain scalars resolve by the YAML 1.2 core schema: 017 is 17, yes is "yes", .inf and .nan are Infinity and NaN. Keys keep their source text (1: a gives the key "1"). Merge keys (<<) are applied, and a key written in the mapping wins over a merged one.

build writes block style with two-space indentation. A string is quoted when, written plain, it would read back as something else — under the core schema, or under the wider schema js-yaml applies by default and YAML 1.1 readers (PyYAML, SnakeYAML) use: the 1.1 booleans (yes, off, y), timestamps (2001-12-14), base-60 numbers (1:20), 0b integers and _-separated numbers. js-yaml's dumper quotes the same set. A number is written as String(n), a BigInt exactly, NaN and ±Infinity as .nan and ±.inf, a Date as its ISO-8601 string, and undefined as null. Bytes, a function or a symbol is a TypeError.

TOML

Synchronous parsing, building, and validation of TOML data.

Keys keep their document order. An integer past 2⁵³ parses to a BigInt (TOML integers are lossless); datetimes parse to RFC 3339 strings.

CSV

Synchronous parsing, building, and validation of CSV. CSV.parse returns arrays of fields (string[][]) by default and only keys objects when asked; every field is a string unless cast is set.

A quoted field keeps delimiters and newlines, and "" reads back as one ". With header set, every row must match the header's field count unless relaxColumnCount is on. A duplicate column name (inferred or explicit), a stray character after a closing quote, and a delimiter or quote that is a line break (or a delimiter equal to the quote, or a comment equal to either) are errors. build writes an absent (null/undefined) field empty, a number as String(n) spells it and a BigInt exactly, and quotes a field that starts with the comment byte. Unlike XML/YAML/TOML, CSV.validate forwards the options, because a ragged row is valid without a header and invalid with one.

MessagePack

Synchronous parsing, building, and validation of binary MessagePack data.

Type mapping

A non-string map key becomes a property name by the CBOR rule below. A reserved marker (0xc1), a truncated value, a str that is not UTF-8, nesting past 256 levels, or a byte after the top-level value is a SyntaxError; validate agrees with decode.

CBOR

Synchronous decoding, encoding, and validation of CBOR (RFC 8949, Concise Binary Object Representation). encode writes the deterministic form: shortest integer and length forms, the shortest float that preserves the value, and bytewise-sorted map keys.

Type mapping

An integer-valued number inside the safe range (±(2⁵³−1)) encodes as an integer, so a decoded 100000.0 re-encodes as 100000; past it a number is the shortest exact float and decodes back as a number, while a BigInt takes the integer form. A reserved initial byte, a stray break, a trailing byte, a malformed or oversized length, an unassigned simple value (or one below 32 in the two-byte form), a tag, or nesting past 256 levels is a SyntaxError.

BSON

MongoDB's document format. The BSON types are classes on the namespace.

const bytes = BSON.encode({ _id: new BSON.ObjectId(), count: 5n, at: new Date() });
const doc = BSON.decode(bytes); // { _id: ObjectId, count: 5n, at: Date }

Type mapping

A decoded double that is a whole number re-encodes as int32, as in the official driver; BSON.Double keeps it a double. A repeated key decodes with its last value. A NUL in a key, a cycle, a function, a symbol, a Set or a typed array other than Uint8Array is a TypeError; a bigint outside int64, an Invalid Date or nesting past 256 levels is a RangeError; malformed bytes are a SyntaxError.

Protobuf

Schema-aware Protobuf decoding and encoding. Pure-JS and reflective: the .proto is compiled at runtime (proto3 and editions 2023/2024; proto2-only constructs are rejected). Decoded objects use camelCase keys, BigInt for 64-bit ints, enum value-names, and Uint8Array for bytes.

Errors