s-exp.hako — com.s-exp/hako 1.0.0-alpha31

Public API for hako — schemaless, low-alloc Clojure serialization.

decode clj

(decode src)

(decode src opts)

Decode a hako-format value from src — a byte[] or a MemorySegment.

Options: :zero-copy — return MemorySegment slices for byte payloads instead of copying to byte[] (default false). Slices are valid only while the source segment / arena remain alive. :tolerate-unknown-tags — unknown user-tag ids resolve to TaggedValue rather than throwing (default false). :cache-idents — consult a JVM-global cache when interning decoded keywords / symbols. Wins on keyword-heavy payloads (~2x on 50+ unique kw), slight overhead on tiny maps (default false).

decode-into! clj

(decode-into! rd src)

(decode-into! rd src opts)

Decode a value using the reusable Reader rd rebound to src. Rebinds via .reset on each call.

The Reader must have been produced by the reader fn (or otherwise have r/configure! called on it); .reset preserves the extension handler and array-map thresholds.

decode-many clj

(decode-many src)

(decode-many src opts)

Convenience wrapper. Equivalent to (into [] (decoder src opts)).

decoder clj

(decoder src)

(decoder src opts)

Return a reducible + iterable source over all values in src (a byte[] or MemorySegment). Terminates cleanly on both stream outputs from encode-many and single-value outputs from encode.

Compose with standard Clojure fns:

(into #{} (filter :active) (hako/decoder bs)) (sequence xform (hako/decoder bs)) (eduction xform (hako/decoder bs)) (reduce f init (hako/decoder bs)) (transduce xform f init (hako/decoder bs)) (run! process! (hako/decoder bs))

Each reduction / iteration spins up a fresh Reader — the source is safe to walk multiple times, and early termination via reduced or a short .hasNext stops the reader immediately without over-reading.

Distinct from reader: reader returns a mutable Reader instance (for decode-into!); decoder returns a lazy value-stream source.

Options — same as decode: :zero-copy, :tolerate-unknown-tags, :cache-idents.

encode clj

(encode value)

(encode value opts)

Encode value and return a fresh byte[].

For arena-backed zero-copy output use encode-to-segment.

Options: :initial-size — starting buffer size in bytes (default 256). :preserve-meta — preserve metadata on collections / IObjs (default false). :pack-homogeneous — detect all-Long / all-Double vectors and emit them as packed prim arrays (default false). :coerce-custom-comparator — allow encoding sorted-set-by / sorted-map-by as default-cmp sorted collections. Comparator is lost on decode. Warns once per JVM.

encode-into! clj

(encode-into! wr value)

(encode-into! wr value opts)

Encode value using the reusable wr. Returns a MemorySegment slice covering the encoded bytes. The slice is valid until the next encode-into! call on this writer, or close.

The Writer must have had w/install-handler! called at least once (the writer fn does this). .reset preserves the handler.

encode-many clj

(encode-many values)

(encode-many values opts)

Encode values (a sequence) into a single byte[] sharing one symbol table across the whole stream. Reads compact when many values repeat the same keyword / symbol identifiers.

The output has one envelope prefix followed by concatenated encoded values. Use decode-many to read back.

encode-to-segment clj

(encode-to-segment arena value)

(encode-to-segment arena value opts)

Encode value into a MemorySegment owned by arena. Returns the segment.

reader clj

(reader src)

Allocate a reusable Reader bound to src (byte[] or MemorySegment). Rebind via .reset(newSeg). Not thread-safe.

writer clj

(writer)

(writer initial-size)

Allocate a reusable Writer with an initial buffer of initial-size bytes (default 4096). Close via .close when done. Use encode-into! for each message; the writer's arena is retained between calls.