lizpack

A MessagePack Library for Zig

Zero allocations.
Zero encoding errors.
Simple control flow.
All messages validated for you.

A simple API:

// encode
try lizpack.encode(T{}, writer, .{})

// decode to stack allocated memory
const result: T = try lizpack.decode(T, reader, .{})

// decode to heap allocated memory
const result: *T = try lizpack.decodeAlloc(allocator, *T, reader, .{})

Combines with your definition of your message structure:

const CustomerComplaint = struct {
    user_id: u64,
    status: enum(u8) {
        received,
        reviewed,
        awaiting_response,
        finished,
    },
};

Default Formats

Zig Type	MessagePack Type
`bool`	bool
`null`	nil
`u3`,`u45`, `i6`	integer
`?T`	nil or T
`enum`	integer
`[N]T`	N length array of T
`[N:x]T`	N+1 length array of T ending in x
`[N]u8`	str
`@Vector(N, T)`	N length array of T
`struct`	map, str: field value
`union (enum)`	map (single key-value pair)
`[]T`	N length array of T
`[:x]T`	N + 1 length array of T ending in x
`[]u8`	str
`[:x]u8`	str ending in x
`*T`	T

Decoding unions is currently not supported.

str is the default MessagePack type for []u8 because it is the smallest for short slices.

Decoding requires a buffer size of at least 1 byte (must be able to peek at least 1 byte). For decoding optionals. This may change in the future if decoding unions is supported.

Unsupported types:

Zig Type	Reason
`union` (untagged)	Decoding cannot determine active field, and neither can you.
`error`	I can add this, if someone asks. Perhaps as `str`?

Note: pointer types require allocation to decode.

Customizing Formats

You can customize how types are formatted in message pack:

Zig Type	Available Encodings
`enum`	string, int
`[]u8`,`[N]u8`, `@Vector(N, u8)`	string, int, array
`struct`	map, array
`union (enum)`	map (single key-value pair), active field
`[] struct {key: ..., value: ...}`	map, array
`[N] struct {key: ..., value: ...}`	map, array

See examples for how to do it.

Manual Encoding / Decoding

If you require the finest level of control over how data is encoded and decoded, the lizpack.manual API may suit your use case.

See examples for how to do it.

Examples

const std = @import("std");

const lizpack = @import("lizpack");

test {
    const CustomerComplaint = struct {
        user_id: u64,
        status: enum(u8) {
            received,
            reviewed,
            awaiting_response,
            finished,
        },
    };

    var out: [1000]u8 = undefined;
    const expected: CustomerComplaint = .{ .user_id = 2345, .status = .reviewed };
    const slice: []u8 = try lizpack.encode(expected, &out, .{});
    try std.testing.expectEqual(expected, lizpack.decode(@TypeOf(expected), slice, .{}));
}

More examples can be found in examples/.

Installation

To add lizpack to your project as a dependency, run:

zig fetch --save git+https://github.com/kj4tmp/lizpack

Then add the following to your build.zig:

// assuming you have an existing executable called `exe`
const lizpack = b.dependency("lizpack", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("lizpack", lizpack.module("lizpack"));

And import the library to begin using it:

const lizpack = @import("lizpack");

Zig Version

Please refer to the minimum_zig_version field of the build.zig.zon.

TODO

refactor: use of has_sentinel
refactor: use of std.builtin.Type.Pointer.Sentinel

README