lite3

Lite3 zero-copy serialization format bindings for Kit

Files

Dependencies

No Kit package dependencies.

This package is an ffi-zig package and requires the ffi and file capabilities declared in kit.toml.

Installation

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

Usage

import Kit.Lite3 as Lite3

main = fn =>
  # Create a new object context
  match Lite3.create
    | Err e -> println ("Failed to create Lite3 context: " ++ Error.message e)
    | Ok ctx ->
      # Contexts own native resources; destroy them when finished.
      defer Lite3.destroy ctx

      # Write values by key
      match Lite3.set-str ctx "name" "Kit"
        | Err e -> println ("set-str failed: " ++ Error.message e)
        | Ok _ -> ()

      Lite3.set-int ctx "version" 1
      Lite3.set-bool ctx "active" true
      Lite3.set-float ctx "score" 98.5
      Lite3.set-bytes ctx "signature" [1, 2, 3, 4]

      # Read typed values
      match Lite3.get-str ctx "name"
        | Some name -> println ("name = " ++ name)
        | None -> println "name missing"

      match Lite3.get-int ctx "version"
        | Some version -> println ("version = " ++ Int.to-string version)
        | None -> println "version missing"

      println ("has active? " ++ show (Lite3.has-key? ctx "active"))
      println ("entry count = " ++ Int.to-string (Lite3.count ctx))

      # Convert to JSON for interop
      json = Lite3.to-json-string ctx
      println json

      # Convert to a byte buffer and restore a new context
      bytes = Lite3.to-bytes ctx
      match Lite3.from-bytes bytes
        | Err e -> println ("from-bytes failed: " ++ Error.message e)
        | Ok restored ->
          defer Lite3.destroy restored
          println (Lite3.to-json-string restored)

main

Development

Running Examples

Run an example with the interpreter:

kit run examples/01-building-messages.kit

Compile an example to a native binary:

kit build examples/01-building-messages.kit && ./01-building-messages

Running Tests

Run the Kit test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Run the Zig unit tests:

zig test zig/lite3.zig

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Running Parity Checks

Run interpreter/compiler parity checks:

kit parity --no-spinner --failures-only

The parity check runs the examples through the interpreter and compiler and reports only failures or output mismatches.

The examples intentionally import ../src/lite3 so they exercise the local checkout during package development.

Generating Documentation

Generate API documentation from doc comments:

kit doc src/lite3.kit

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Developer Notes

API Overview

Pure Kit Values

Lite3Value is a Kit-side representation for working with Lite3-like values without a native context:

value = Lite3.object [
  ("name", Lite3.string "Kit"), 
  ("version", Lite3.int 1), 
  ("active", Lite3.bool true)
]

json-value = Lite3.to-json-value value
round-trip = Lite3.from-json-value json-value

Helpers include Lite3.null, Lite3.bool, Lite3.int, Lite3.float, Lite3.bytes, Lite3.string, Lite3.object, Lite3.array, and predicates such as Lite3.is-string? and Lite3.is-object?.

Implementation Notes

The Zig implementation uses an integer handle registry so Kit code never receives raw native pointers. Always call Lite3.destroy for each context returned by Lite3.create, Lite3.create-array, Lite3.from-json-string, or Lite3.from-bytes.

to-json-string and from-json-string provide the stable text interchange format. The current to-bytes/from-bytes implementation serializes the same data as JSON bytes, which keeps the buffer portable and easy to inspect during development.

The package includes a local zig/kit_ffi.zig helper for Zig unit tests. At runtime, the Kit interpreter generates its own kit_ffi.zig wrapper ABI, so zig/lite3.zig should use the shared helper functions such as kit_ffi.getInt, kit_ffi.makeString, kit_ffi.makeOk, and kit_ffi.makeTypedErr rather than depending on method-style accessors.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/lite3/, making it available for import as Kit.Lite3 in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

Lite3Type

Lite3 value types

Lite3Error

Lite3 error type for error handling.

match Lite3.get-str ctx "key"
  | Ok value -> println "Value: ${value}"
  | Err (Lite3Error { message }) -> println "Error: ${message}"

Lite3Handle

Opaque handle to a Lite3 context. This is an integer ID that references a context in the Zig registry.

Lite3Value

Lite3 value - a Kit representation of data stored in Lite3 format.

This type is used for working with Lite3 data in a type-safe way.

to-json-value

Converts a Lite3Value to a JSONValue.

Parameters:

Returns:

Lite3Value -> JSONValue

from-json-value

Converts a JSONValue to a Lite3Value.

Parameters:

Returns:

JSONValue -> Lite3Value

is-null?

Checks if value is null.

Lite3Value -> Bool

is-bool?

Checks if value is a boolean.

Lite3Value -> Bool

is-int?

Checks if value is an integer.

Lite3Value -> Bool

is-float?

Checks if value is a float.

Lite3Value -> Bool

is-bytes?

Checks if value is bytes.

Lite3Value -> Bool

is-string?

Checks if value is a string.

Lite3Value -> Bool

is-object?

Checks if value is an object.

Lite3Value -> Bool

is-array?

Checks if value is an array.

Lite3Value -> Bool

null

Creates a null value.

Lite3Value

bool

Creates a boolean value.

Bool -> Lite3Value

int

Creates an integer value.

Int -> Lite3Value

float

Creates a float value.

Float -> Lite3Value

bytes

Creates a bytes value.

[Int] -> Lite3Value

string

Creates a string value.

String -> Lite3Value

object

Creates an object value.

[(String, Lite3Value)] -> Lite3Value

array

Creates an array value.

[Lite3Value] -> Lite3Value