Repository navigation
v0.6.0 — nested-container ergonomics + structured map/list values
[0.6.0] — 2026-05-10
Both changes in this release are strictly additive — zero breaking
changes for callers of the 0.5.x API. Inputs that previously errored
now succeed; all previously-working calls keep their behavior.
Added
LoroEx.map_get_or_create_container/4and
LoroEx.list_get_or_create_container/4— idempotent,
race-free "ensure a child container exists" operations. The
check-and-insert happens under a single doc-mutex lock, so there
is no window where concurrent callers can both see a missing CID
and both insert. Directly retires the
map_get_child_cid || map_insert_containerdance and the
hydrate-safety footgun in super_loop's
Doc.Server.ensure_root_children_cid/1. Behavior:- Existing container of the same kind → return its CID unchanged.
- Existing container of a different kind →
{:error, {:invalid_container_kind, _}}. - Scalar at the key/index →
{:error, {:invalid_value, _}}
(never clobbers data). - Absent → insert and return new CID.
list_get_or_create_containeradditionally treats
index == lengthas "append at end" and
index > lengthas{:error, {:out_of_bound, _}}.
LoroEx.map_get_child_cid/3andLoroEx.list_get_child_cid/3
— return the serializedContainerIDof a child container, or
nilfor scalar/absent/out-of-bounds cases. The return shape
matchesmap_insert_container/4/list_insert_container/4
(a bare CID string, no{:ok, _}wrapping). Enables path-based
descent into nested container structures (e.g.
root.children[0].children) without going through
get_map_json/list_get_json, which call Loro'sget_deep_value
and strip container IDs. Two primary uses:- Nested block writes: agent-facing block-edit tools can now
resolve a path like[N, M, ...]to the CID of an arbitrary
descendant and pass it to any map/list/text function. - Hydrate-safe path caches: after
apply_update, consumers that
keep apath → cidcache can re-derive it instead of
re-creating containers (which would clobber content).
- Nested block writes: agent-facing block-edit tools can now
LoroEx.map_keys/2andLoroEx.map_size/2— cheap map
introspection. O(n) and O(1) respectively at the CRDT layer,
avoiding the full deep-JSON-encode cost ofget_map_json/2 |> Jason.decode!() |> Map.keys()when the caller only needs keys or
a count.LoroEx.list_length/2andLoroEx.list_get_json_at/3—
symmetric withmap_size/2/map_get_json/3.list_lengthis
O(1);list_get_json_atreturns one element as JSON (the literal
string"null"for out-of-bounds, matchingmap_get_json/3's
missing-key behavior). For nested container elements returns the
deep value; uselist_get_child_cid/3to recover the CID.LoroEx.list_insert/4— insert a JSON value at a specific
position (shifts tail). Closes the API symmetry gap vs
list_push/3(end) andlist_insert_container/4(container at
position). Same value rules aslist_push/3.
Changed
LoroEx.map_set/4andLoroEx.list_push/3now accept JSON-encoded
objects and arrays as values, not just scalars. The
parse_scalar_json/json_to_loro_valuehelpers now route
structured values through Loro's built-in
LoroValue::from(serde_json::Value)impl, producing
LoroValue::MapandLoroValue::Listvariants. The helpers keep
their names for source-compat; their@docstrings are updated.
Structured values are stored as frozen values inside the parent
— for CRDT-level merging on nested fields, use
map_insert_container/4/list_insert_container/4to materialize
a nested container instead. The same relaxation applies to
text_mark/6(which also goes throughparse_scalar_json), so
structured mark values (e.g. complex attribute objects) now
round-trip throughtext_to_delta/2.- Tests reflecting the old scalar-only behavior were updated:
themap mutation,list mutation, andbad inputs to new NIFs
describes previously asserted{:error, {:invalid_value, _}}for
objects/arrays. They now verify successful round-trips.