`avro`

Apache Avro schema definition and binary codec - define schemas in ilusm, encode and decode binary Avro data.

Load with: use avro

What this module does

avro lets you define Apache Avro schemas as ilusm objects and use them to encode data to binary Avro format and decode it back. You build schemas by composing typed fields, enums, arrays, maps, unions, and fixed-size types, then call avenc to serialise and avdec to deserialise. You can also export a schema as a JSON string for sharing or storing, and validate an object against a schema without encoding.

Both raw names (avsch, avfld, etc.) and avro.* aliases are available.

Encoding and decoding delegate to host natives __avro_encode and __avro_decode with the schema serialised to JSON via jsn.

Quick example

use avro

# Define a schema
sch = avro.sch("User", [
    avfld("name", avstr(), nil),
    avfld("age",  avint(), 0),
    avfld("email", avstr(), "")
])

# Encode an object
data = avro.enc(sch, {name: "Alex", age: 30, email: "alex@example.com"})

# Decode it back
obj = avro.dec(sch, data)
prn(obj.name)  # "Alex"

# Check if an object is valid for a schema (no error = valid)
prn(avro.ok(sch, {name: "Alex", age: 30, email: "alex@example.com"}))  # tru

Functions

Schema construction

avsch(name, flds) / avro.sch(n, f)

Creates a record schema with a name and a list of field definitions from avfld. Returns {t: "record", name, ns: "", flds}. Namespace starts empty - set it with avns.

avfld(name, tp, dflt) / avro.fld(n, t, d)

Creates a field definition. tp is the type (a primitive string or a nested schema object). If dflt is not nil, a dflt key is included in the field.

avns(sch, ns) / avro.ns(s, n)

Sets the namespace on a record schema. Returns the updated schema.

Complex types

avenm(name, syms) / avro.enm(n, s)

Creates an enum schema. syms is a list of symbol strings. Returns {t: "enum", name, syms}.

avarr(items) / avro.arr(i)

Creates an array schema where every element must match items (a type string or schema). Returns {t: "array", items}.

avmap(vals) / avro.map(v)

Creates a map schema where string keys map to values of type vals. Returns {t: "map", vals}.

avuni(types) / avro.uni(t)

Creates a union schema - a value that can be any of the types in the list. Returns {t: "union", types}. Use this to make a field nullable: avuni(["null", avstr()]).

avfix(name, sz)

Creates a fixed-size bytes schema with exactly sz bytes. Returns {t: "fixed", name, sz}. Useful for things like UUIDs or MAC addresses.

Primitive types

These return the Avro primitive type name as a string - pass them as the tp argument of avfld.

avnul() → "null"

avbol() → "boolean"

avint() → "int"

avlng() → "long"

avflt() → "float"

avdbl() → "double"

avstr() → "string"

avbyt() → "bytes"

Encoding and decoding

avenc(sch, obj) / avro.enc(s, o)

Encodes obj to binary Avro format according to sch. The schema is serialised to JSON via jsn.jsnen and passed to the host native __avro_encode.

avdec(sch, data) / avro.dec(s, d)

Decodes binary Avro data back to an ilusm object according to sch. Calls the host native __avro_decode.

Schema utilities

avjsn(sch) / avro.jsn(s)

Serialises a schema to a JSON string via jsn.jsnen. Use this to store or share the schema.

avprs(s)

Parses a JSON string back into a schema object via jsn.jsndec.

avok(sch, obj) / avro.ok(s, o)

Returns tru if encoding obj with sch succeeds without error. Returns fls if encoding throws. A lightweight way to validate before committing to encode.

Notes

Actual binary encoding and decoding are handled by host natives - the ilusm module handles schema construction and JSON serialisation only.
avok validates by attempting a full encode and catching any error - it is not a schema-only validator and will call the host native.
Use avro.* aliases for clarity: avro.sch, avro.fld, avro.enc, avro.dec, etc.