eidetica::crdt::doc

Struct Doc

pub struct Doc { /* private fields */ }

Implementations§

Source §

impl Doc

Source

pub fn new() -> Self

Creates a new empty document.

Source

pub fn atomic() -> Self

Creates a new empty atomic document.

The atomic flag means “this data is a complete replacement — take all of it.” During merge (left ⊕ right):

right.atomic → LWW: return right (always replaces left entirely)
left.atomic, !right.atomic → structural field merge, result stays atomic (the flag is contagious)
Neither atomic → structural field merge, result non-atomic

The contagious property preserves associativity: in a chain 1⊕2⊕3⊕4 where 3 is atomic and 4 edits subfields, 3⊕4 produces an atomic result, so (1⊕2) ⊕ (3⊕4) correctly overwrites everything before 3.

Use this for config or metadata that must always be written as a consistent whole. Types that need atomicity should convert into Doc::atomic() (e.g., via impl From<MyType> for Doc) to declare replacement semantics.

§Examples

let mut doc1 = Doc::atomic();
doc1.set("x", 1);
doc1.set("y", 2);

let mut doc2 = Doc::atomic();
doc2.set("x", 10);
doc2.set("z", 30);

// Atomic merge replaces entirely (LWW), no field-level merge
let merged = doc1.merge(&doc2).unwrap();
assert_eq!(merged.get_as::<i64>("x"), Some(10));
assert_eq!(merged.get_as::<i64>("z"), Some(30));
assert_eq!(merged.get_as::<i64>("y"), None); // Not carried from doc1

Source

pub fn is_atomic(&self) -> bool

Returns true if this document uses atomic merge semantics.

Source

pub fn is_empty(&self) -> bool

Returns true if this document has no data (excluding tombstones).

Source

pub fn len(&self) -> usize

Returns the number of direct keys (excluding tombstones).

Source

pub fn contains_key(&self, key: impl AsRef<Path>) -> bool

Returns true if the document contains the given key.

Source

pub fn is_tombstone(&self, key: impl AsRef<Path>) -> bool

Returns true if the exact path points to a tombstone (Value::Deleted).

This method checks if the specific key has been deleted. Note that this only returns true if the exact path is a tombstone - it does not check if an ancestor was deleted (which would make the path inaccessible).

To check if a path is inaccessible (either deleted or has a deleted ancestor), use get(path).is_none() instead.

§Examples

let mut doc = Doc::new();
doc.set("user.profile.name", "Alice");
doc.remove("user.profile.name");

assert!(doc.is_tombstone("user.profile.name"));
assert!(!doc.is_tombstone("user.profile")); // parent is not tombstoned

// Deleting a parent makes children inaccessible but not directly tombstoned
doc.set("settings.theme.color", "blue");
doc.remove("settings.theme");
assert!(doc.is_tombstone("settings.theme")); // exact path is tombstoned
assert!(!doc.is_tombstone("settings.theme.color")); // child path is NOT a tombstone
assert!(doc.get("settings.theme.color").is_none()); // but it's still inaccessible

Source

pub fn get(&self, key: impl AsRef<Path>) -> Option<&Value>

Gets a value by key or path (immutable reference).

Supports both simple keys and dot-separated paths for nested access. Returns None if the key doesn’t exist or has been deleted (tombstone).

§Examples

let mut doc = Doc::new();
doc.set("name", "Alice");
doc.set("user.profile.age", 30);

assert!(doc.get("name").is_some());
assert!(doc.get("user.profile.age").is_some());
assert!(doc.get("nonexistent").is_none());

// Deleted keys return None
doc.remove("name");
assert!(doc.get("name").is_none());

Source

pub fn get_mut(&mut self, key: impl AsRef<Path>) -> Option<&mut Value>

Gets a mutable reference to a value by key or path

Source

pub fn get_as<'a, T>(&'a self, key: impl AsRef<Path>) -> Option<T>
where T: TryFrom<&'a Value, Error = CRDTError>,

Gets a value by key with automatic type conversion using TryFrom

Returns Some(T) if the value exists and can be converted to type T. Returns None if the key doesn’t exist or type conversion fails.

This is the recommended method for type-safe value retrieval as it provides a cleaner Option-based interface compared to the Result-based get_as() method.

§Examples

let mut doc = Doc::new();
doc.set("name", "Alice");
doc.set("age", 30);
doc.set("active", true);

// Returns Some when value exists and type matches
assert_eq!(doc.get_as::<&str>("name"), Some("Alice"));
assert_eq!(doc.get_as::<i64>("age"), Some(30));
assert_eq!(doc.get_as::<bool>("active"), Some(true));

// Returns None when key doesn't exist
assert_eq!(doc.get_as::<String>("missing"), None);

// Returns None when type doesn't match
assert_eq!(doc.get_as::<i64>("name"), None);

Source

pub fn set( &mut self, key: impl AsRef<Path>, value: impl Into<Value>, ) -> Option<Value>

Sets a value at the given key or path, returns the old value if present.

This method automatically creates intermediate Doc nodes for nested paths. For example, doc.set("a.b.c", value) will create a and b as Doc nodes if they don’t exist.

§Examples

let mut doc = Doc::new();

// Simple key
doc.set("name", "Alice");

// Nested path - creates intermediate nodes automatically
doc.set("user.profile.age", 30);

assert_eq!(doc.get_as("name"), Some("Alice"));
assert_eq!(doc.get_as("user.profile.age"), Some(30));

Source

pub fn remove(&mut self, key: impl AsRef<Path>) -> Option<Value>

Removes a value by key or path, returns the old value if present.

This method implements CRDT semantics by always creating a tombstone marker. For nested paths, intermediate Doc nodes are created if they don’t exist.

§Examples

let mut doc = Doc::new();
doc.set("user.profile.name", "Alice");

let old = doc.remove("user.profile.name");
assert_eq!(old.and_then(|v| v.as_text().map(|s| s.to_string())), Some("Alice".to_string()));
assert!(doc.get("user.profile.name").is_none());

Source

pub fn iter(&self) -> impl Iterator<Item = (&String, &Value)>

Returns an iterator over all key-value pairs (excluding tombstones)

Source

pub fn keys(&self) -> impl Iterator<Item = &String>

Returns an iterator over all keys (excluding tombstones)

Source

pub fn values(&self) -> impl Iterator<Item = &Value>

Returns an iterator over all values (excluding tombstones)

Source

pub fn to_json_string(&self) -> String

Converts this Doc to a JSON string representation.

This produces a valid JSON object string from the document’s contents, excluding tombstones.

Source §

impl Doc

Source

pub fn set_json<T>( &mut self, key: impl AsRef<Path>, value: T, ) -> Result<&mut Self>
where T: Serialize,

Set a key-value pair with automatic JSON serialization for any Serialize type.

The value is serialized to a JSON string and stored as Value::Text.

§Examples

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, PartialEq, Debug)]
struct User { name: String, age: i32 }

let mut doc = Doc::new();
doc.set_json("user", User { name: "Alice".into(), age: 30 })?;

let user: User = doc.get_json("user")?;
assert_eq!(user, User { name: "Alice".into(), age: 30 });

Source

pub fn get_json<T>(&self, key: impl AsRef<Path>) -> Result<T>
where T: for<'de> Deserialize<'de>,

Get a value by key with automatic JSON deserialization for any Deserialize type.

The value must be a Value::Text containing valid JSON.

§Errors

Returns an error if:

The key doesn’t exist
The value is not a Value::Text
The JSON deserialization fails

Source

pub fn get_or_insert( &mut self, key: impl AsRef<Path> + Clone, default: impl Into<Value>, ) -> &mut Value

Gets or inserts a value with a default, returns a mutable reference.

If the key doesn’t exist, the default value is inserted. Returns a mutable reference to the value (existing or newly inserted).

§Examples

let mut doc = Doc::new();

// Key doesn't exist - will insert default
doc.get_or_insert("counter", 0);
assert_eq!(doc.get_as::<i64>("counter"), Some(0));

// Key exists - will keep existing value
doc.set("counter", 5);
doc.get_or_insert("counter", 100);
assert_eq!(doc.get_as::<i64>("counter"), Some(5));

Trait Implementations§

Source §

impl CRDT for Doc

Source §

fn merge(&self, other: &Self) -> Result<Self>

Merges another document into this one using CRDT semantics.

This implements the core CRDT merge operation at the document level, providing deterministic conflict resolution following CRDT semantics.

Merge combines the key-value pairs from both documents, resolving conflicts deterministically using CRDT rules.

Source §

impl Clone for Doc

Source §

fn clone(&self) -> Doc

Returns a duplicate of the value. Read more

1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Source §

impl Debug for Doc

Source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Source §

impl Default for Doc

Source §

fn default() -> Self

Returns the “default value” for a type. Read more

Source §

impl<'de> Deserialize<'de> for Doc

Source §

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more

Source §

impl Display for Doc

Source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Source §