#mizchi/rkyv

#Release contract

• little-endian;
• aligned archives; and
• 32-bit relative pointers and archived usize values.

#Features

• Bounds-checked reader for the default rkyv format.
• Bit-compatible u8–u64, i8–i64, f32, f64, and bool reads.
• Relative pointers, ArchivedVec<T> headers, and ArchivedOption<T> value offsets.
• A bounds-checked, zero-copy BytesView for raw archive ranges.
• A zero-copy ArchivedVec<u32> view with lazy access, Array/ FixedArray materialization, and caller-owned buffer copies.
• Default-format schema-directed encoders for primitives, strings, vectors, options, structs, and explicit tagged unions.
• Little- and big-endian primitive readers with 16-, 32-, or 64-bit pointers.
• Experimental Rust code generation for typed MoonBit views of named structs.
• Experimental MoonBit-owned schemas for Rust-free default-format encoding and schema-directed zero-copy views, including the JavaScript target.
• Optional RMBT v1 envelopes with format flags, payload length, CRC-32, and a caller-provided payload limit for untrusted transport data.

#Usage

import {
  "mizchi/rkyv" @rkyv,
}

let reader = @rkyv.Reader::new(archive_bytes)
let view = reader.read_vec_u32(archive_bytes.length() - 8) catch {
  error => abort("invalid rkyv archive: \{error}")
}

#Transport envelope

///|
let envelope = @rkyv.encode_envelope(archive)

///|
let decoded = @rkyv.decode_envelope_with_limit(envelope, 16 * 1024 * 1024) catch {
  error => abort("invalid archive transport: \{error}")
}

///|
let view = @catalog.CatalogView::validate(decoded.payload_bytes()) catch {
  error => abort("invalid rkyv archive: \{error}")
}

///|
let view = reader.read_vec_u32(root_offset) catch {
  error => abort("invalid rkyv archive: \{error}")
}

///|
let selected = view.get(index)

#Generated MoonBit schemas and JavaScript

#Direct host-defined schema API

///|
let user = @rkyv.Schema::Struct([
  { name: "id", schema: @rkyv.Schema::U32 },
  { name: "active", schema: @rkyv.Schema::Bool },
  { name: "name", schema: @rkyv.Schema::String },
  { name: "scores", schema: @rkyv.Schema::VecU32 },
])

///|
let archive = user.encode(
  @rkyv.Value::Struct([
    { name: "id", value: @rkyv.Value::U32(42U) },
    { name: "active", value: @rkyv.Value::Bool(true) },
    { name: "name", value: @rkyv.Value::String("Ada") },
    { name: "scores", value: @rkyv.Value::VecU32([7U, 11U, 13U]) },
  ]),
) catch {
  _ => abort("schema and value do not match")
}

///|
let root = user.root(archive) catch { _ => abort("invalid archive") }

///|
let name = root.field("name")

///|
let scores = root.field("scores")

#In-place archive updates

///|
let archive = user.encode_mut(
  @rkyv.Value::Struct([
    { name: "id", value: @rkyv.Value::U32(42U) },
    { name: "active", value: @rkyv.Value::Bool(true) },
    { name: "name", value: @rkyv.Value::String("Ada") },
    { name: "scores", value: @rkyv.Value::VecU32([7U, 11U, 13U]) },
  ]),
)

///|
let root = user.root_mut(archive.mut_view())

///|
match root.field("id") {
  Some(id) => ignore(id.set_u32(99U))
  None => abort("missing id")
}

///|
match root.field("scores") {
  Some(scores) => match scores.vec_u32_mut() {
    Some(scores) => ignore(scores.set(1, 42U))
    None => abort("scores is not Vec<u32>")
  }
  None => abort("missing scores")
}

///|
let user = {
  name: "User",
  fields: [
    { name: "id", typ: UInt32 },
    { name: "active", typ: Bool },
    { name: "name", typ: Text },
    { name: "scores", typ: UInt32Array },
  ],
}
emit_schema(user)

///|
import {
  "mizchi/rkyv/examples/host_codegen/generated" @user,
}

///|
let archive = @user.encode(42U, true, "Ada", [7U, 11U, 13U])

///|
let root = @user.UserView::root(Bytes::from_array(archive))

///|
let name : String = root.name()

///|
let scores : @rkyv.U32VecView = root.scores()

///|
let archive = @user.encode(42U, true, "Ada", [7U, 11U, 13U])

///|
let writer = @user.UserMutView::root(archive.mut_view())

///|
writer.set_id(99U)
writer.set_active(false)
let patched : Bool = writer.set_name_same_length("Eve")
let scores = writer.scores_mut()
ignore(scores.set(1, 42U))

just host-schema
just host-js
# Eve: 3 scores

#Dogfooding: static product catalog

just catalog-generate
moon test --target js examples/catalog/client
just catalog-js
# Moon Mug: 1800 cents
just catalog-roundtrip

#Benchmarks

just bench
just bench-profile
just bench-compare
just profile
just host-js

#Rust interoperability

• MoonBit reads bytes generated by Rust rkyv::to_bytes.
• Rust rkyv::access accepts bytes generated by MoonBit encode_vec_u32 and encode_string.
• The catalog example proves generated MoonBit-to-Rust archives for nested structs, primitive vectors, Vec<String>, Option<Vec<T>>, and fieldless enums.

#Experimental typed code generation

#Development

just fmt
just check
just test
just conformance
just codegen

#License