Skip to main content

Crate grafeo_loro

Crate grafeo_loro 

Source
Expand description

§grafeo-loro

Local-first, in-process, dual-store graph database with CRDT consensus (Loro) + execution (Grafeo). Issue #1 compliance: granular feature gates, WASM target support, trait-abstracted runtime, tree-as-graph adapter.

§Feature matrix (issue #1 item 7)

FeaturePullsWASM-safe
bridgelorosurgeon, parking_lotyes
batcherbridge + tokio (sync, time)no
compressionlz4_flex, zstd (C lib)no*
treebridgeyes
storageasync-traityes
grafeobridge + grafeo (native only)no
onnxgrafeo + ort (native only)no
webrtcwebrtc-rs (native only)no
telemetryopentelemetry, tracingyes
wasmwasm-bindgen, js-sys, web-sysrequired
parallelrayonno
serdeserde, serde_jsonyes
fullall native featuresno

* compression uses zstd which binds to a C library; do NOT enable it in WASM builds. Use lz4_flex only via a future compression-lz4 sub-feature, or disable compression entirely in the browser.

§Issue #4: OfflineOpQueue + EpochTracker (WASM-accessible)

Issue #4 factored OfflineOpQueue, LineageEpoch, EpochMismatchError, and the new standalone EpochTracker out of src/bridge/sync_engine.rs into src/bridge/queue.rs. The new module is gated only by feature = "bridge" — no batcher (tokio), no grafeo (native ONNX/ort), no telemetry (opentelemetry native). Browser consumers on wasm32-unknown-unknown can name these types directly via grafeo_loro::OfflineOpQueue / grafeo_loro::EpochTracker.

§bridge queue + epoch tracker sub-API

TypeFeature gatePurpose
OfflineOpQueuebridgeCap-bounded FIFO of serialized LoroOps
LineageEpochbridgeu64 type alias for the epoch counter
EpochMismatchErrorbridgeError raised on remote/local epoch drift
EpochTrackerbridgeStandalone Arc<AtomicU64> epoch store
grafeo-loro = { version = "0.4", default-features = false, features = ["bridge", "batcher", "compression", "tree"] }

§Minimal WASM smoke test

grafeo-loro = { version = "0.4", default-features = false, features = ["bridge", "tree", "wasm"] }

§MSRV

Rust 1.80+ (verified via cargo msrv against the dep tree).

§Issue #3 sub-issue → feature mapping

Issue #3 (“Browser WASM consumers Support”) has 10 sub-issues. Their feature gates are:

Sub-issueTopicFeature gate
#1WASM target compile + binary sizewasm + bridge,tree,compression
#2Trait-abstracted runtime (Mailbox)bridge (trait); batcher (Tokio impl)
#3LoroDoc ownership APIbridge,storage,grafeo,batcher
#4Merge semantics(no feature — use doc.import())
#5Offline op-queue + lineage epochbridge (factored out in issue #4)
#6FTS + SAB + shadow commitsfts, sab, shadow
#7Graph invariants (cycle, root)bridge,tree
#8Presence (ephemeral overlay)bridge (always available with bridge)
#9Storage backend traitstorage
#10Observability hooksobservability

§No merge / awareness / persistence feature

If you saw a feature flag named merge, awareness, or persistence in a downstream consumer’s Cargo.toml, it was invented — grafeo-loro has never declared these. Enabling them now produces a compile_error! pointing at the correct alternative:

Invented nameCorrect alternative
mergedoc.import(other.export(loro::ExportFormat::Snapshot))
awarenesspresence module (always available with bridge)
persistencestorage feature (StorageBackend trait + InMemoryStorage)

§WASM binary size

With the full WASM-safe feature set (bridge,tree,compression,wasm,serde, fts,sab,shadow,observability) and opt-level="z" + lto=true + codegen-units=1 + strip=true, the raw .wasm (before wasm-opt -Oz) is approximately 2.26 MB. After wasm-opt -Oz (configured in [package.metadata.wasm-pack.profile.release]), it shrinks ~15-20%.

For size-constrained consumers (e.g. <1.8 MB budget), drop fts (inverted index) and shadow (Git DAG shadow commits) first — they together add ~400 KB. The minimal smoke feature set bridge,tree,wasm produces a ~800 KB .wasm after wasm-opt -Oz.

Re-exports§

pub use config::CompressionType;
pub use config::SsotMode;
pub use error::GrafeoLoroError;
pub use error::Result;

Modules§

config
constants
error
types
Shared type vocabulary: ids, events, presence, values.