msgpack

Kind	kit
Categories	encoding data-format serialization
Keywords	msgpack messagepack serialization binary encoding

MessagePack binary serialization for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic usage example with simple values, maps, arrays, and nested data
`examples/comparison.kit`	MessagePack vs JSON size comparison
`kit.toml`	Package manifest with metadata, package excludes, and tasks
`src/msgpack.kit`	MessagePack value model, encoder, decoder, constructors, and accessors
`tests/msgpack.test.kit`	Encoder, decoder, constructor, accessor, and nested structure tests
`tests/types.test.kit`	Local ADT, error type, trait, and pattern matching tests

Dependencies

No Kit package dependencies.

Installation

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

Usage

import Kit.Msgpack as MsgPack

main = fn =>
  # Create a MessagePack map value
  person = MsgPack.map [
    ("name", MsgPack.string "Alice"),
    ("age", MsgPack.int 30),
    ("active", MsgPack.bool true),
    ("score", MsgPack.float 98.5)
  ]

  # Encode to MessagePack bytes
  bytes = MsgPack.encode person
  println "Encoded size: ${Int.to-string (List.length bytes)} bytes"

  # Decode bytes back to a MessagePack value
  match MsgPack.decode bytes
    | Err err -> println "Decode failed: ${err}"
    | Ok decoded ->
      match MsgPack.get decoded "name"
        | Some name-val ->
          match MsgPack.as-string name-val
            | Some name -> println "Name: ${name}"
            | None -> println "Name was not a string"
        | None -> println "Missing name"

  # Arrays and binary payloads are supported too
  numbers = MsgPack.array [
    MsgPack.int 1,
    MsgPack.int 2,
    MsgPack.int 3
  ]
  binary = MsgPack.binary [0, 1, 2, 255]

  println "Array bytes: ${Int.to-string (List.length (MsgPack.encode numbers))}"
  println "Binary bytes: ${Int.to-string (List.length (MsgPack.encode binary))}"

main

API Overview

Value Constructors

Use constructors to build MessagePack values explicitly:

MsgPack.nil
MsgPack.bool true
MsgPack.int 42
MsgPack.float 3.14
MsgPack.string "hello"
MsgPack.binary [1, 2, 3]
MsgPack.array [MsgPack.int 1, MsgPack.int 2]
MsgPack.map [("key", MsgPack.string "value")]
MsgPack.ext 1 [0, 1, 2, 3]

Encoding and Decoding

Function	Description
`MsgPack.encode value`	Encode a `Value` to `List Int` bytes
`MsgPack.decode bytes`	Decode `List Int` bytes into `Result Value MsgPackError`
`MsgPack.to-bytes value`	Alias for `encode`
`MsgPack.from-bytes bytes`	Alias for `decode`
`MsgPack.pack value`	Encode and convert bytes to a binary `String`
`MsgPack.unpack binary-str`	Decode a binary `String`

The encoder chooses the smallest integer, string, array, and map representation supported by MessagePack for the given size. Floats are currently encoded as float64.

Accessors and Type Checks

Use type checks when the decoded shape is not known:

MsgPack.is-int? value
MsgPack.is-string? value
MsgPack.is-array? value
MsgPack.is-map? value

Use accessors to safely extract typed data:

MsgPack.as-int value
MsgPack.as-string value
MsgPack.as-bool value
MsgPack.as-float value
MsgPack.as-binary value
MsgPack.as-array value
MsgPack.as-map value

For containers:

MsgPack.get map-value "key"
MsgPack.at array-value 0

Supported MessagePack Types

MessagePack concept	Kit representation
nil	`MsgPack.nil`
boolean	`MsgPack.bool`
signed/unsigned integer	`MsgPack.int`
float	`MsgPack.float`
string	`MsgPack.string`
binary	`MsgPack.binary`
array	`MsgPack.array`
map	`MsgPack.map`
extension	`MsgPack.ext`

Maps use string keys in this package. Decoding a map with non-string keys returns MsgPackFormatError.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit
kit run examples/comparison.kit

Compile examples to native binaries:

kit build examples/basic.kit && ./basic
kit build examples/comparison.kit && ./comparison

Running Parity Checks

Run interpreter/compiler parity checks for examples:

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

Parity builds and runs the examples through both execution paths and reports failures or output mismatches.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

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

kit dev

This will:

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

Generating Documentation

Generate API documentation from doc comments:

kit doc

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

Cleaning Build Artifacts

Remove generated files, caches, parity results, coverage data, docs, lock files, package installs, and native build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

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

License

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

MessagePack is an open binary serialization format. See msgpack.org for the format specification and ecosystem information.

Exported Functions & Types

`MsgPackError`

MsgPack error type for typed error handling.

Variants

MsgPackDecodeError {message}

MsgPackFormatError {message}

`MsgPack`

Marker type for the MessagePack format. Used with BinaryEncode/BinaryDecode traits to distinguish MessagePack serialization.

Variants

MsgPack

`Value`

MessagePack value representation

Variants

MsgNil

MsgBool {Bool}

MsgInt {Int}

MsgFloat {Float}

MsgString {String}

MsgBinary {List, Int}

MsgArray {List, Value}

MsgMap {List}

MsgExt {Int, List, Int}

`encode`

Value -> List Int

`decode`

List Int -> Result Value MsgPackError

`nil`

Value

`bool`

Bool -> Value

`int`

Int -> Value

`float`

Float -> Value

`string`

String -> Value

`binary`

List Int -> Value

`array`

List Value -> Value

`map`

List (String, Value) -> Value

`ext`

Int -> List Int -> Value

`to-bytes`

Value -> List Int

`from-bytes`

List Int -> Result Value MsgPackError

`pack`

Value -> String

`unpack`

String -> Result Value MsgPackError

`is-nil?`

Value -> Bool

`is-bool?`

Value -> Bool

`is-int?`

Value -> Bool

`is-float?`

Value -> Bool

`is-string?`

Value -> Bool

`is-binary?`

Value -> Bool

`is-array?`

Value -> Bool

`is-map?`

Value -> Bool

`is-ext?`

Value -> Bool

`as-bool`

Value -> Option Bool

`as-int`

Value -> Option Int

`as-float`

Value -> Option Float

`as-string`

Value -> Option String

`as-binary`

Value -> Option (List Int)

`as-array`

Value -> Option (List Value)

`as-map`

Value -> Option (List (String, Value))

`get`

Value -> String -> Option Value

`at`

Value -> NonNegativeInt -> Option Value