`bson`

BSON encode/decode - the MongoDB wire format. Encode ilusm objects to BSON bytes, decode BSON bytes back to objects, and construct BSON-typed values like ObjectId, date, regex, binary data, and fixed-width integers.

Load with: use bson

What this module does

BSON (Binary JSON) is the binary serialisation format used by MongoDB. bson wraps the host natives __bson_encode and __bson_decode to round-trip ilusm values through BSON, and provides type-tagged value constructors for BSON-specific types that have no direct ilusm equivalent - ObjectId, UTC datetime, regex, binary subtype, int32, int64, double, timestamp, MinKey, MaxKey, and null.

All functions are available both as bare names (bsone, bsond, etc.) and as the bson object (bson.enc, bson.dec, etc.).

Quick example

use bson

# Encode an ilusm object to BSON bytes
data = bsone({name: "Alice", age: 30, score: bsoni6(9999999999)})

# Decode back
obj = bsond(data)
prn(obj.name)   # Alice

# Generate a MongoDB ObjectId
id = bsonid()

# Construct typed values
dt = bsondt(1700000000000)  # Unix ms timestamp as BSON date
rx = bsonrx("^hello", "i")  # BSON regex with flags
bn = bsonbn("\x00\x01\x02")  # binary data, subtype 0

# Validate
prn(bsonok(data))  # tru

Functions

Encode and decode

bsone(obj) / bson.enc(obj)

Encodes an ilusm object (or any value) to BSON binary via __bson_encode. Returns the BSON byte string.

bsond(data) / bson.dec(data)

Decodes a BSON byte string back to an ilusm object via __bson_decode. Returns the decoded value.

bsonok(data) / bson.ok(data)

Returns tru if data can be decoded without error, fls otherwise. Uses try to catch decoding errors.

bsonsz(data)

Returns the size of the BSON data (as the length of its string representation).

BSON type constructors

bsonid() / bson.oid()

Generates a new MongoDB ObjectId via __bson_objectid. ObjectIds are 12-byte values encoding timestamp, machine ID, and sequence counter.

bsondt(ms) / bson.dt(ms)

Creates a BSON UTC datetime value from a Unix millisecond timestamp. Returns {t: "date", v: int(ms)}.

bsonrx(pattern, flags) / bson.rx(pattern, flags)

Creates a BSON regex value. flags defaults to "" if nil. Returns {t: "regex", pat, fl}.

bsonbn(data) / bson.bin(data)

Creates a BSON binary value with subtype 0 (generic binary). Returns {t: "bin", v, st: 0}.

bsoni3(v) / bson.i32(v)

Creates a BSON int32 value. Returns {t: "int32", v: int(v)}. Use this when you need to store an integer that must round-trip as exactly 32 bits.

bsoni6(v) / bson.i64(v)

Creates a BSON int64 value. Returns {t: "int64", v: int(v)}. Use for values that exceed 32-bit range.

bsondl(v)

Creates a BSON double value. Returns {t: "dbl", v}. Useful when you need to distinguish a double from an integer in the BSON document.

bsonts(s, i) / bson.ts(s, i)

Creates a BSON timestamp with seconds s and increment i. Returns {t: "ts", s: int(s), i: int(i)}. BSON timestamps are used internally by MongoDB for replication.

bsonmn()

Creates a MinKey value - a special BSON type that sorts less than all other types. Returns {t: "minkey"}.

bsonmx()

Creates a MaxKey value - sorts greater than all other types. Returns {t: "maxkey"}.

bsonnu()

Creates an explicit BSON null value. Returns {t: "null"}.

Notes

Encode and decode delegate to host natives - the runtime must have BSON support compiled in.
Regular ilusm numbers encode as BSON doubles by default. Use bsoni3 or bsoni6 when you need exact 32/64-bit integer types in the wire format.
Requires trl, txt, and enc.