flatbuf

Kind	kit
Categories	encoding data-format serialization
Keywords	flatbuffers serialization binary zero-copy encoding

FlatBuffers binary serialization for Kit - zero-copy read access

Files

File	Description
`kit.toml`	Package manifest with metadata and dependencies
`src/builder.kit`	Buffer construction with scalars, strings, and vtables
`src/context.kit`	Pipe-friendly API with named offset tracking
`src/encoding.kit`	Little-endian byte encoding and decoding
`src/flatbuf.kit`	Main module re-exporting builder and reader APIs
`src/reader.kit`	Zero-copy buffer reading with vtable lookup
`src/types.kit`	Error types, builder state, and buffer definitions
`tests/flatbuf.test.kit`	Builder, reader, and roundtrip verification
`examples/basic.kit`	Building and reading with schema evolution
`examples/piped.kit`	Fluent pipe syntax with nested vectors
`LICENSE`	MIT license file

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-flatbuf.git

Usage

import Kit.Flatbuf

License

MIT License - see LICENSE for details.

Exported Functions & Types

`new`

Create a new empty builder

() -> BuilderState

`create-string`

Create a string in the buffer

Returns:

BuilderState -> String -> (BuilderState, Int)

`create-vector-int32`

Create a vector of 32-bit integers

Returns:

BuilderState -> [Int] -> (BuilderState, Int)

`create-vector-offset`

Create a vector of offsets (for string/table arrays)

Returns:

BuilderState -> [Int] -> (BuilderState, Int)

`start-object`

Start building a table object

BuilderState -> Int -> BuilderState

`end-object`

End object and write vtable

Returns:

BuilderState -> (BuilderState, Int)

`add-int32`

Add a 32-bit integer field

BuilderState -> Int -> Int -> Int -> BuilderState

`add-int64`

Add a 64-bit integer field

BuilderState -> Int -> Int -> Int -> BuilderState

`add-bool`

Add a boolean field

BuilderState -> Int -> Bool -> Bool -> BuilderState

`add-string`

Add a string field (by offset)

BuilderState -> Int -> Int -> BuilderState

`add-offset`

Add an offset field (table, vector, etc.)

BuilderState -> Int -> Int -> BuilderState

`finish`

Finish buffer and return bytes

BuilderState -> Int -> [Int]

`finish-with-identifier`

Finish buffer with file identifier

BuilderState -> Int -> String -> [Int]

`from-bytes`

Parse a byte list into a buffer reader

[Int] -> Result Buffer String

`from-size-prefixed`

Parse size-prefixed bytes into a buffer reader

[Int] -> Result Buffer String

`get-root`

Get root table position

Buffer -> Int

`read-int32`

Read a 32-bit integer field

Buffer -> Int -> Int -> Int -> Result Int String

`read-int64`

Read a 64-bit integer field

Buffer -> Int -> Int -> Int -> Result Int String

`read-uint8`

Read an 8-bit unsigned integer field

Buffer -> Int -> Int -> Int -> Result Int String

`read-bool`

Read a boolean field

Buffer -> Int -> Int -> Bool -> Result Bool String

`read-string`

Read a string field

Returns:

Buffer -> Int -> Int -> Result (Option String) String

`read-table`

Read a nested table field

Returns:

Buffer -> Int -> Int -> Result (Option Int) String

`read-vector`

Read a vector field position

Returns:

Buffer -> Int -> Int -> Result (Option Int) String

`vector-length`

Get vector length

Buffer -> Int -> Result Int String

`vector-get-int32`

Get int32 from vector by index

Buffer -> Int -> Int -> Result Int String

`vector-get-offset`

Get offset from vector by index (for table/string vectors)

Buffer -> Int -> Int -> Result Int String

`vector-get-string`

Get string from string vector by index

Buffer -> Int -> Int -> Result String String

`read-struct`

Read inline struct field position

Buffer -> Int -> Int -> Result (Option Int) String

`struct-read-int32`

Read int32 from struct at byte offset

Buffer -> Int -> Int -> Result Int String

`struct-read-int16`

Read int16 from struct at byte offset

Buffer -> Int -> Int -> Result Int String

`struct-read-int8`

Read int8 from struct at byte offset

Buffer -> Int -> Int -> Result Int String

`has-identifier?`

Check file identifier

Buffer -> String -> Bool

`get-bytes`

Get raw buffer bytes

Buffer -> [Int]

`Ctx`

Pipe-friendly context API module

`new`

Create a new empty builder

Returns:

() -> BuilderState

`write-int8`

Write an 8-bit signed integer

BuilderState -> Int -> BuilderState

`write-uint8`

Write an 8-bit unsigned integer

BuilderState -> Int -> BuilderState

`write-int16`

Write a 16-bit signed integer

BuilderState -> Int -> BuilderState

`write-uint16`

Write a 16-bit unsigned integer

BuilderState -> Int -> BuilderState

`write-int32`

Write a 32-bit signed integer

BuilderState -> Int -> BuilderState

`write-uint32`

Write a 32-bit unsigned integer

BuilderState -> Int -> BuilderState

`write-int64`

Write a 64-bit integer

BuilderState -> Int -> BuilderState

`write-bool`

Write a boolean (as 1-byte value)

BuilderState -> Bool -> BuilderState

`create-string`

Create a string in the buffer

Parameters:

Returns:

BuilderState -> String -> (BuilderState, Int)

`start-vector`

Start building a vector

Parameters:

Returns:

BuilderState -> Int -> Int -> Int -> BuilderState

`end-vector`

End vector and return its offset

Parameters:

Returns:

BuilderState -> Int -> (BuilderState, Int)

`create-vector-int32`

Create a vector of 32-bit integers

Parameters:

Returns:

BuilderState -> [Int] -> (BuilderState, Int)

`create-vector-offset`

Create a vector of offsets (for strings, nested tables)

Parameters:

Returns:

BuilderState -> [Int] -> (BuilderState, Int)

`start-object`

Start building a table object

Parameters:

Returns:

BuilderState -> Int -> BuilderState

`add-int32`

Add a 32-bit integer field to current object

Parameters:

Returns:

BuilderState -> Int -> Int -> Int -> BuilderState

`add-int64`

Add a 64-bit integer field to current object

BuilderState -> Int -> Int -> Int -> BuilderState

`add-bool`

Add a boolean field to current object

Parameters:

Returns:

BuilderState -> Int -> Bool -> Bool -> BuilderState

`add-offset`

Add an offset field (string, table, vector) to current object

Parameters:

Returns:

BuilderState -> Int -> Int -> BuilderState

`add-string`

Add a string field (convenience wrapper for add-offset)

BuilderState -> Int -> Int -> BuilderState

`end-object`

End object and write vtable

Parameters:

Returns:

BuilderState -> (BuilderState, Int)

`finish`

Finish the buffer with root table offset

Parameters:

Returns:

BuilderState -> Int -> [Int]

`finish-with-identifier`

Finish with a file identifier (4-character string)

Parameters:

Returns:

BuilderState -> Int -> String -> [Int]

`from-bytes`

Create a buffer reader from a byte list

Parameters:

Returns:

[Int] -> Result Buffer String

`get-root`

Get the root table position from the buffer

Parameters:

Returns:

Buffer -> Int

`read-int32`

Read a 32-bit integer field from a table

Parameters:

Returns:

Buffer -> Int -> Int -> Int -> Result Int String

`read-int64`

Read a 64-bit integer field from a table

Buffer -> Int -> Int -> Int -> Result Int String

`read-uint8`

Read an 8-bit unsigned integer field from a table

Buffer -> Int -> Int -> Int -> Result Int String

`read-bool`

Read a boolean field from a table

Parameters:

Returns:

Buffer -> Int -> Int -> Bool -> Result Bool String

`read-string`

Read a string field from a table

Parameters:

Returns:

Buffer -> Int -> Int -> Result (Option String) String

`read-table`

Read a nested table field, returns table position

Parameters:

Returns:

Buffer -> Int -> Int -> Result (Option Int) String

`read-vector`

Read a vector field position

Parameters:

Returns:

Buffer -> Int -> Int -> Result (Option Int) String

`vector-length`

Get the length of a vector

Parameters:

Returns:

Buffer -> Int -> Result Int String

`vector-get-int32`

Read a 32-bit integer from a vector

Parameters:

Returns:

Buffer -> Int -> Int -> Result Int String

`vector-get-offset`

Read an offset from a vector (for string/table vectors)

Parameters:

Returns:

Buffer -> Int -> Int -> Result Int String

`vector-get-string`

Read a string from a string vector

Parameters:

Returns:

Buffer -> Int -> Int -> Result String String

`read-struct`

Read an inline struct field position

Structs are stored inline in the parent (not via offset).

Parameters:

Returns:

Buffer -> Int -> Int -> Result (Option Int) String

`struct-read-int32`

Read a 32-bit integer from a struct at given byte offset

Parameters:

Returns:

Buffer -> Int -> Int -> Result Int String

`struct-read-int16`

Read a 16-bit integer from a struct at given byte offset

Buffer -> Int -> Int -> Result Int String

`struct-read-int8`

Read an 8-bit integer from a struct

Buffer -> Int -> Int -> Result Int String

`has-identifier?`

Check if buffer has a specific file identifier

File identifiers are 4 bytes at offset 4 in the buffer.

Parameters:

Returns:

Buffer -> String -> Bool

`from-size-prefixed`

Create buffer from size-prefixed bytes

Some FlatBuffer protocols prefix the buffer with its size.

Parameters:

Returns:

[Int] -> Result Buffer String

`get-bytes`

Get raw bytes from buffer (for debugging/inspection)

Buffer -> [Int]

`write-u8`

Write an 8-bit unsigned integer to a single byte

Parameters:

Returns:

Int -> [Int]

`write-u16`

Write a 16-bit unsigned integer to 2 bytes (little-endian)

Parameters:

Returns:

Int -> [Int]

`write-u32`

Write a 32-bit unsigned integer to 4 bytes (little-endian)

Parameters:

Returns:

Int -> [Int]

`write-i32`

Write a 32-bit signed integer to 4 bytes (little-endian)

Parameters:

Returns:

Int -> [Int]

`write-i64`

Write a 64-bit integer to 8 bytes (little-endian)

Parameters:

Returns:

Int -> [Int]

`read-u8`

Read an 8-bit unsigned integer from a byte list

Parameters:

Returns:

[Int] -> Int -> Result Int String

`read-u16`

Read a 16-bit unsigned integer (little-endian)

Parameters:

Returns:

[Int] -> Int -> Result Int String

`read-u32`

Read a 32-bit unsigned integer (little-endian)

Parameters:

Returns:

[Int] -> Int -> Result Int String

`read-i32`

Read a 32-bit signed integer (little-endian)

Parameters:

Returns:

[Int] -> Int -> Result Int String

`read-i64`

Read a 64-bit integer (little-endian)

Parameters:

Returns:

[Int] -> Int -> Result Int String

`new`

Create a new empty context

Returns:

() -> Context

`string`

Create a string and store its offset by name

Parameters:

Returns:

String -> String -> Context -> Context

`vector-int32`

Create a vector of int32s and store its offset by name

Parameters:

Returns:

String -> [Int] -> Context -> Context

`vector-offset`

Create a vector of offsets and store its offset by name

Parameters:

Returns:

String -> [String] -> Context -> Context

`start-object`

Start building a table object

Parameters:

Returns:

Int -> Context -> Context

`end-object`

End object and store its offset by name

Parameters:

Returns:

String -> Context -> Context

`add-int32`

Add an int32 field to current object

Parameters:

Returns:

Int -> Int -> Int -> Context -> Context

`add-int64`

Add an int64 field to current object

Parameters:

Returns:

Int -> Int -> Int -> Context -> Context

`add-bool`

Add a boolean field to current object

Parameters:

Returns:

Int -> Bool -> Bool -> Context -> Context

`add-string`

Add a string field by offset name

Parameters:

Returns:

Int -> String -> Context -> Context

`add-offset`

Add an offset field (table, vector) by offset name

Parameters:

Returns:

Int -> String -> Context -> Context

`finish`

Finish the buffer with root table by name

Parameters:

Returns:

String -> Context -> [Int]

`finish-with-id`

Finish with a file identifier

Parameters:

Returns:

String -> String -> Context -> [Int]

`get-builder`

Get the underlying builder from context

Useful when you need to mix pipe-style with low-level operations

Context -> BuilderState

`get-offset-value`

Get a raw offset value by name

Returns:

String -> Context -> Int

`set-builder`

Set the builder in context

Useful when mixing with low-level operations

BuilderState -> Context -> Context

`store-offset`

Store a raw offset value by name

Useful when mixing with low-level operations

String -> Int -> Context -> Context

`FlatBufError`

FlatBufError - Error type for FlatBuffers operations

Variants

BuildError {message}

Error during buffer construction

ReadError {message}

Error during buffer reading (out of bounds, invalid data)

OffsetError {message}

Invalid offset reference

`Offset`

Offset - Position in buffer (32-bit unsigned in FlatBuffers spec) Stored as Kit Int (i64) but values should be 0 to 2^32-1

Variants

Int

`SOffset`

SOffset - Signed offset (used for vtable references) 32-bit signed in FlatBuffers spec

Variants

Int

`VOffset`

VOffset - VTable offset (16-bit unsigned) Used for field offsets within vtables

Variants

Int

FieldSlot - Tracks a field's position during table construction

Fields: - id: Field index (0-based, matches schema order) - offset: Absolute offset in buffer where field data is stored

VTable - Virtual table for field lookup

FlatBuffers tables use vtables to enable schema evolution. Fields can be added or removed without breaking compatibility.

Fields: - size: Total vtable size in bytes - object-size: Size of the object data in bytes - offsets: List of field offsets (0 means field not present)

BuilderState - Mutable state for buffer construction

FlatBuffers are built backwards - data is prepended to the buffer. This allows efficient construction without knowing final size upfront.

Fields: - buffer: Byte buffer (built in reverse order) - current-offset: Current position from end of buffer - vtables: Previously created vtables (for deduplication) - nested: True if currently building an object/vector - field-slots: Fields added to current object - object-start: Start offset of current object being built

Buffer - Wrapper for reading FlatBuffer data

Provides zero-copy access to serialized data. The bytes are never copied during reading - accessors return views into the original buffer.

Fields: - bytes: Raw byte data as list of integers (0-255) - pos: Position of root table in buffer