Skip to content
neudingerPublic

About

Pure Zig FlatBuffers implementation with schema compiler, zero-copy readers, serialization, verification, and in-place updates.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

Flatzz

Flatzz — Zig for FlatBuffers. A Rocket FBS schema becomes Zig declarations beside a single rocket piloted by Ziguana.

License: EUPL-1.2 Zig 0.17.0 Documented API Runnable examples

Generate Zig from FlatBuffers schemas. Serialize native values. Borrow views from existing bytes.

Quick start · Copyable examples · Runtime API · Compiler API · WebAssembly compiler · More examples

Flatzz website Flatzz documentation Runtime API reference Compiler API reference Open the compiler playground

1. Serialize and read back

The build generates a rocket module from rocket.fbs. Inside a function with std imported, an allocator, and the generated Rocket type:

const rocket: Rocket = .{
    .id = 7,
    .fuel = 80,
    .pilot = "Ziguana",
    .payload = &.{ 1, 2, 3 },
};

const result = try rocket.serialize(allocator, .{});
defer result.deinit(allocator);

try Rocket.verify(result.bytes, .{});
const view = try Rocket.read(result.bytes);
try std.testing.expectEqual(@as(u32, 7), view.id);
try std.testing.expectEqual(@as(f32, 80), view.fuel);
try std.testing.expectEqualStrings("Ziguana", view.pilot.?);

Or for comptime buffer

const rocket: Rocket = .{
    .id = 7,
    .fuel = 80,
    .pilot = "Ziguana",
    .payload = &.{ 1, 2, 3 },
};
const capacity = comptime flatzz.storage.capacityFor(Rocket.Schema, rocket, .{});
var storage: [capacity]u8 align(flatzz.storage_alignment) = undefined;
const bytes = try rocket.serialize(&storage, .{});
try Rocket.verify(bytes, .{});
const before = try Rocket.read(bytes);

try std.testing.expect(try Rocket.update(bytes, .fuel, 79));
try std.testing.expect(try Rocket.update(bytes, .pilot, "Pilot01"));
try Rocket.verify(bytes, .{});
const after = try Rocket.read(bytes);

try std.testing.expectEqual(@as(f32, 80), before.fuel);
try std.testing.expectEqual(@as(f32, 79), after.fuel);
try std.testing.expectEqualStrings("Pilot01", after.pilot.?);
try std.testing.expectEqualStrings("Pilot01", before.pilot.?);
try std.testing.expectError(error.LengthMismatch, Rocket.update(bytes, .pilot, "short"));
try std.testing.expectEqualStrings("Pilot01", (try Rocket.read(bytes)).pilot.?);

Copy complete test · Complete runner · Runnable source and tests

result owns the allocation. Release it once with the same allocator and keep it alive while using borrowed views. view.fuel is the decoded scalar 80; view.pilot borrows the string "Ziguana" from result.bytes.

The same serialize(target, options) operation accepts an allocator or an aligned mutable buffer. Its argument type determines whether the result owns an allocation or borrows supplied storage; the values and storage remain runtime inputs.

2. Use caller-owned storage

One caller-owned buffer contains spare capacity and a FlatBuffer frame. The fuel field is decoded by value; the pilot string borrows bytes from the frame.

Copy code · Runnable source and tests

rocket.serialize(&storage, .{}) writes into an aligned caller-owned buffer without heap allocation. The returned bytes borrow part of that storage; reusing it invalidates the frame and its views. Serialization writes data into the frame. The illustration is conceptual, not an exact byte layout.

3. From FBS to generated Zig

A Rocket FBS schema on the left and an excerpt of its generated native Zig fields and operations on the right. The FBS panel occupies one third and generated Zig two thirds.

Copy schema and full generated source · Schema · Runnable source

Generation happens on the host at build time. The application imports the generated module and the Flatzz runtime. The illustration omits field metadata; the copyable example includes the complete generated output.

4. Read and edit existing bytes

Operation Purpose
verify Traverse known schema fields and validate their reachable wire data
read Decode scalars and borrow strings and structured views
update Replace a present scalar, string, struct, or vector without growing the frame
borrowMutable Borrow a structured field; inline structs retain mutable access

Copy read/edit test · Mutable nested struct example · More examples · Browse online examples

update returns false when a field is absent. Strings and vectors must keep their lengths; replacing tables or whole unions requires rebuilding. Read scalars again after an edit. Borrowed strings still refer to the same bytes, so edits can also be visible through earlier views.

For mapped input, the application supplies the byte slice and manages the mapping and buffer lifetime. Use explicit Builder handles when child tables must be shared; see the Builder example.

Build and development

Build commands and compatibility

Run from this directory. Zig fetches the pinned Zast package when schema tools or the Wasm compiler are enabled. Runtime, parsing, reflection, and BFBS APIs can be checked without Zast. The default check and test steps include README example generation through the schema tools.

Command Action
zig build Install the compiler, both examples, and generated Reading
zig build compiler Build and install only zig-out/bin/flatzz
zig build wasm Install the reusable freestanding Wasm compiler
zig build run-readme Generate Rocket; allocate, serialize, receive, read, and edit
zig build run-mission Generate Mission from two FBS files; serialize with comptime-sized storage and read it
zig build run-monster Generate Monster; serialize with comptime-sized storage and read its fields and union
zig build run Generate Reading; serialize with buffers sized at comptime
zig build run-builder Run construction, mutation, and unions with Builder
zig build check Compile examples, tests, and contracts
zig build test Test native runtime, FBS parsing, generated Zig, and contracts
zig build fmt Check Zig formatting
zig build docs Generate runtime/compiler API references into zig-out/docs
zig build examples Compile the native Zig examples and their tests
zig build check test -Dschema-tools=false Check and test runtime/compiler APIs without Zast
zig build generate-reading Regenerate tests/fixtures/reading/reading.zig
zig build update-zast Update the Zast commit and package hash from GitHub main
zig build --help List targets and options

The generated example executable is zig-out/bin/flatzz-example.

All example commands and independent example builds: example/README.md. The sibling flatzz-site project prepares the website, API theme, and example catalogue.

The WebAssembly compiler provides FBS to Zig/schema JSON/BFBS and BFBS to Zig/schema JSON. Other projects can request the flatzz-compiler-wasm artifact with .@"wasm-compiler" = true; no site-specific compiler setup is needed.

Implementation layout and ownership

The public entry points are runtime.zig (flatzz) and compiler.zig (flatzz_compiler). Applications can use the runtime, FBS parser, reflection model, and BFBS codec without Zast. Zig source generation uses a separate Zast-based backend; generated modules import only flatzz.

Responsibility Implementation
Descriptors, schema composition, and public adapters schema.zig
Native graph preflight and packing native_graph.zig
Checked local buffer access, ranges, and scalar reads/writes buffer_access.zig
Result types and field reads from checked tables field_access.zig
Storage bounds, native sizing, and owned serialized buffers storage.zig
Buffer construction and table state Builder.zig, table_builder.zig
Known-schema wire traversal and resource limits Verifier.zig
Public FBS API, diagnostics, and options parser.zig
Compiler and parser tests test_compiler.zig, test_parser.zig
Sources, symbols, semantic resolution, defaults, and layout Compilation.zig
Source cursor and declaration grammar Parser.zig
Shared unresolved declarations and spelling helpers model.zig
Reflection records and primitive facts reflection.zig
Portable schema JSON writing json.zig
Public BFBS API, encoding, decoding, and shared record layout bfbs.zig, Encoder.zig, Decoder.zig, record_layout.zig
Source generation lifetime, lowering, and scratch expression construction codegen.zig, Generator.zig, Syntax.zig
Freestanding compiler ABI and virtual source map compiler.zig, Sources.zig

Detailed ownership and implementation notes.

License

Licensed under the European Union Public Licence v1.2.

About

Pure Zig FlatBuffers implementation with schema compiler, zero-copy readers, serialization, verification, and in-place updates.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages