Merge pull request #25 from brunoga/feat/crdt-support

feat: implement CRDT support and efficient run-based text synchronization

Author: brunoga

README.md

@@ -1,12 +1,13 @@
 # Deep Copy and Patch for Go
 
-`deep` is a high-performance, reflection-based library for manipulating complex Go data structures. It provides three primary capabilities: recursive deep copying, structural diffing to produce patches, and a fluent API for manual patch construction.
+`deep` is a high-performance, reflection-based library for manipulating complex Go data structures. It provides recursive deep copying, structural diffing to produce patches, a fluent API for manual patch construction, and first-class support for distributed state synchronization (CRDTs).
 
 ## Features
 
 *   **Deep Copy**: Full recursive cloning of structs, maps, slices, and pointers.
 *   **Deep Diff**: Calculate the semantic difference between two objects.
 *   **Rich Patching**: Apply patches with atomicity, move/copy operations, and logging.
+*   **Conflict Resolution**: Pluggable resolvers for convergent synchronization (CRDTs).
 *   **Conditional Logic**: A built-in DSL for cross-field validation and soft-skipping (`If`/`Unless`).
 *   **Standard Compliant**: Full support for JSON Pointer (RFC 6901) and JSON Patch (RFC 6902).
 *   **Production Ready**: Handles circular references and unexported fields transparently.
@@ -35,14 +36,54 @@ if patch != nil {
 
 ---
 
+## Distributed State (CRDT)
+
+`deep` includes a first-class CRDT engine for synchronizing complex Go structures across multiple nodes without a central coordinator.
+
+### Why Deep CRDTs?
+Most CRDT libraries only handle primitives. `deep` uses its structural awareness to provide **granular, field-level convergence** for your existing Go types.
+
+### Basic Usage
+```go
+import "github.com/brunoga/deep/v2/crdt"
+
+// 1. Initialize a CRDT wrapper
+nodeA := crdt.NewCRDT(Config{Title: "Initial"}, "node-a")
+
+// 2. Edit the state
+delta := nodeA.Edit(func(c *Config) {
+    c.Title = "Updated Title"
+})
+
+// 3. Apply changes from other nodes
+nodeB.ApplyDelta(delta)
+```
+
+### Semantic Slices
+By tagging slice elements with `deep:"key"`, `deep` enables **Yjs-style semantic patching**. This ensures that concurrent insertions into a list interleave correctly rather than overwriting each other or failing due to index shifts.
+
+```go
+type Document struct {
+    Text []Char `deep:"key"` // Enable semantic list merging
+}
+```
+
+---
+
 ## Core Concepts
 
-### The Patch Model
-A `Patch[T]` is a tree of operations. Unlike simple key-value maps, `deep` patches understand the structure of your data. A single patch can contain replacements, slice insertions/deletions, map manipulations, and even data movement between paths.
+### Pluggable Resolution
+You can provide custom logic to mediate how patches are applied using the `ConflictResolver` interface. This is how the CRDT package implements Last-Write-Wins (LWW) via Hybrid Logical Clocks (HLC).
+
+```go
+// Use a custom resolver to implement business-specific merge rules
+err := patch.ApplyResolved(&target, myResolver)
+```
 
 ### Consistency Modes
 *   **Strict (Default)**: `ApplyChecked` ensures the target value matches the `old` value recorded during the `Diff`. If the target has changed since the diff was taken, the patch fails.
-*   **Flexible**: Disable strict checking using `patch.WithStrict(false)` to apply changes regardless of the current value, relying instead on custom Conditions.
+*   **Flexible**: Disable strict checking using `patch.WithStrict(false)` to apply changes regardless of the current value.
+*   **Resolved**: Use `ApplyResolved` to handle concurrent edits via a custom resolution strategy.
 
 ---
 
@@ -68,13 +109,6 @@ builder.Root().Navigate("/network/settings/port").Put(8080)
 builder.Root().Navigate("Metadata.Tags[0]").Put("admin")
 ```
 
-### Advanced Operations
-The builder supports more than just "Set":
-*   **Move**: `Root().Field("Backup").Move("/Active")`
-*   **Copy**: `Root().Field("Template").Copy("/Target")`
-*   **Test**: `Root().Field("Status").Test("ready")` (Fails patch if value doesn't match)
-*   **Log**: `Root().Log("Applying update...")` (Prints to stdout during application)
-
 ---
 
 ## Conditional Patching
@@ -86,16 +120,6 @@ You can attach logic to any node in a patch using a string-based DSL via `ParseC
 *   `"Version > 5"` (Literal comparison)
 *   `"Stock < MinAlertThreshold"` (Cross-field comparison)
 *   `"Network.Port == 8080 AND Status == 'active'"` (Logical groups)
-*   `"NOT (Tags[0] == 'internal')"` (Slice access)
-
-### Soft Conditions (If/Unless)
-Standard conditions fail the entire patch. Soft conditions simply skip a specific operation while allowing the rest of the patch to proceed.
-
-```go
-builder.Root().Field("BetaFeatures").
-    If(deep.Equal[Config]("Tier", "premium")).
-    Put(true)
-```
 
 ---
 
@@ -104,7 +128,6 @@ builder.Root().Field("BetaFeatures").
 ### JSON Pointer (RFC 6901)
 Use standard pointers to navigate or query your structures:
 ```go
-// Both the DSL and the Builder support JSON pointers
 cond, _ := deep.ParseCondition[Config]("/network/settings/port > 1024")
 builder.Root().Navigate("/meta/tags/0").Put("new")
 ```
@@ -117,38 +140,16 @@ jsonBytes, err := patch.ToJSONPatch()
 
 ---
 
-## Advanced Options
-
-### Ignoring Paths
-Ignore specific fields during a diff or copy (e.g., timestamps or secrets):
-```go
-// Works for both Copy and Diff
-dst, _ := deep.Copy(src, deep.IgnorePath("SecretToken"))
-patch := deep.Diff(old, new, deep.IgnorePath("UpdatedAt"))
-```
-
-### Skipping Unsupported Types
-Tell `Copy` to zero-out types it cannot handle (like functions or channels) instead of returning an error:
-```go
-dst, _ := deep.Copy(src, deep.SkipUnsupported())
-```
-
----
-
 ## Technical Details
 
+### Hybrid Logical Clocks (HLC)
+The CRDT package uses HLCs to provide causal ordering of events without requiring perfect clock synchronization between nodes.
+
 ### Unexported Fields
-`deep` uses `unsafe` pointers to read and write unexported struct fields. This is required for true deep copying of third-party or internal types where fields are not public.
+`deep` uses `unsafe` pointers to read and write unexported struct fields. This is required for true deep copying of third-party or internal types.
 
 ### Cycle Detection
 The library tracks pointers during recursive operations. Circular references are handled correctly without entering infinite loops.
 
-### Custom Copiers
-Types can control their own cloning logic by implementing `Copier[T]`:
-```go
-type Token string
-func (t Token) Copy() (Token, error) { return "REDACTED", nil }
-```
-
 ## License
 Apache 2.0

builder.go

@@ -267,12 +267,12 @@ func (n *Node) ensurePatch() {
 			p = &slicePatch{}
 		case reflect.Map:
 			p = &mapPatch{
-				added:    make(map[interface{}]reflect.Value),
-				removed:  make(map[interface{}]reflect.Value),
-				modified: make(map[interface{}]diffPatch),
+				added:    make(map[any]reflect.Value),
+				removed:  make(map[any]reflect.Value),
+				modified: make(map[any]diffPatch),
 				keyType:  n.typ.Key(),
 			}
-		case reflect.Ptr:
+		case reflect.Pointer:
 			p = &ptrPatch{}
 		case reflect.Interface:
 			p = &interfacePatch{}
@@ -413,9 +413,9 @@ func (n *Node) MapKey(key any) (*Node, error) {
 	mp, ok := n.current.(*mapPatch)
 	if !ok {
 		mp = &mapPatch{
-			added:    make(map[interface{}]reflect.Value),
-			removed:  make(map[interface{}]reflect.Value),
-			modified: make(map[interface{}]diffPatch),
+			added:    make(map[any]reflect.Value),
+			removed:  make(map[any]reflect.Value),
+			modified: make(map[any]diffPatch),
 			keyType:  n.typ.Key(),
 		}
 		n.update(mp)
@@ -433,12 +433,12 @@ func (n *Node) MapKey(key any) (*Node, error) {
 
 // Elem returns a Node for the element type of a pointer or interface.
 func (n *Node) Elem() *Node {
-	if n.typ == nil || (n.typ.Kind() != reflect.Ptr && n.typ.Kind() != reflect.Interface) {
+	if n.typ == nil || (n.typ.Kind() != reflect.Pointer && n.typ.Kind() != reflect.Interface) {
 		return n
 	}
 	updateFunc := n.update
 	var currentPatch diffPatch
-	if n.typ.Kind() == reflect.Ptr {
+	if n.typ.Kind() == reflect.Pointer {
 		pp, ok := n.current.(*ptrPatch)
 		if !ok {
 			pp = &ptrPatch{}
@@ -458,7 +458,7 @@ func (n *Node) Elem() *Node {
 		currentPatch = ip.elemPatch
 	}
 	var nextTyp reflect.Type
-	if n.typ.Kind() == reflect.Ptr {
+	if n.typ.Kind() == reflect.Pointer {
 		nextTyp = n.typ.Elem()
 	}
 	return &Node{
@@ -528,9 +528,9 @@ func (n *Node) Delete(keyOrIndex any, oldVal any) error {
 		mp, ok := n.current.(*mapPatch)
 		if !ok {
 			mp = &mapPatch{
-				added:    make(map[interface{}]reflect.Value),
-				removed:  make(map[interface{}]reflect.Value),
-				modified: make(map[interface{}]diffPatch),
+				added:    make(map[any]reflect.Value),
+				removed:  make(map[any]reflect.Value),
+				modified: make(map[any]diffPatch),
 				keyType:  n.typ.Key(),
 			}
 			n.update(mp)
@@ -558,9 +558,9 @@ func (n *Node) AddMapEntry(key, val any) error {
 	mp, ok := n.current.(*mapPatch)
 	if !ok {
 		mp = &mapPatch{
-			added:    make(map[interface{}]reflect.Value),
-			removed:  make(map[interface{}]reflect.Value),
-			modified: make(map[interface{}]diffPatch),
+			added:    make(map[any]reflect.Value),
+			removed:  make(map[any]reflect.Value),
+			modified: make(map[any]diffPatch),
 			keyType:  n.typ.Key(),
 		}
 		n.update(mp)

builder_test.go

@@ -748,3 +748,30 @@ func TestBuilder_Log(t *testing.T) {
 		t.Errorf("Unexpected JSON for log: %s", string(jsonBytes))
 	}
 }
+
+func TestBuilder_Put(t *testing.T) {
+	type State struct {
+		Data map[string]int
+	}
+	b := NewBuilder[State]()
+	node, _ := b.Root().Navigate("Data")
+	node.Put(map[string]int{"a": 1})
+	p, _ := b.Build()
+
+	s := State{Data: make(map[string]int)}
+	p.Apply(&s)
+	if s.Data["a"] != 1 {
+		t.Errorf("expected 1, got %d", s.Data["a"])
+	}
+}
+
+func TestPatch_ToJSONPatch_ReadOnly(t *testing.T) {
+	patch := Diff(1, 2)
+	ro := &readOnlyPatch{inner: patch.(patchUnwrapper).unwrap()}
+
+	// readOnlyPatch toJSONPatch currently returns nil
+	json := ro.toJSONPatch("/")
+	if json != nil {
+		t.Errorf("expected nil for readOnly toJSONPatch")
+	}
+}

condition.go

@@ -241,7 +241,7 @@ func (p Path) delete(v reflect.Value) error {
 }
 
 func dereference(v reflect.Value) (reflect.Value, error) {
-	for v.Kind() == reflect.Ptr || v.Kind() == reflect.Interface {
+	for v.Kind() == reflect.Pointer || v.Kind() == reflect.Interface {
 		if v.IsNil() {
 			return reflect.Value{}, fmt.Errorf("path traversal failed: nil pointer/interface")
 		}
@@ -416,7 +416,7 @@ func toReflectValue(v any) reflect.Value {
 		return rv
 	}
 	rv := reflect.ValueOf(v)
-	for rv.Kind() == reflect.Ptr {
+	for rv.Kind() == reflect.Pointer {
 		rv = rv.Elem()
 	}
 	return rv

condition_impl.go

@@ -83,7 +83,7 @@ func (c *rawTypeCondition) evaluateAny(v any) (bool, error) {
 		return target.Kind() == reflect.Slice || target.Kind() == reflect.Array, nil
 	case "null":
 		k := target.Kind()
-		return (k == reflect.Ptr || k == reflect.Interface || k == reflect.Slice || k == reflect.Map) && target.IsNil(), nil
+		return (k == reflect.Pointer || k == reflect.Interface || k == reflect.Slice || k == reflect.Map) && target.IsNil(), nil
 	case "undefined":
 		return false, nil
 	default:

condition_serialization.go

@@ -28,7 +28,7 @@ func marshalConditionAny(c any) (any, error) {
 
 	// Use reflection to extract the underlying fields regardless of T.
 	v := reflect.ValueOf(c)
-	if v.Kind() == reflect.Ptr {
+	if v.Kind() == reflect.Pointer {
 		v = v.Elem()
 	}
 

copy.go

@@ -89,7 +89,7 @@ func Copy[T any](src T, opts ...CopyOption) (T, error) {
 	// For cyclic reference detection to work reliably for root value types,
 	// they must be addressable. We ensure this by taking the address.
 	var rv reflect.Value
-	if v.Kind() == reflect.Ptr {
+	if v.Kind() == reflect.Pointer {
 		rv = v
 	} else {
 		pv := reflect.New(v.Type())
@@ -186,12 +186,12 @@ func recursiveCopy(v reflect.Value, pointers pointersMap,
 		typ := v.Type()
 		key := pointersMapKey{ptr, typ}
 		if dst, ok := pointers[key]; ok {
-			if dst.Kind() == reflect.Ptr && v.Kind() != reflect.Ptr {
+			if dst.Kind() == reflect.Pointer && v.Kind() != reflect.Pointer {
 				return dst.Elem(), nil
 			}
 			return dst, nil
 		}
-	} else if kind == reflect.Ptr && !v.IsNil() {
+	} else if kind == reflect.Pointer && !v.IsNil() {
 		ptr := v.Pointer()
 		typ := v.Type()
 		key := pointersMapKey{ptr, typ}
@@ -210,14 +210,14 @@ func recursiveCopy(v reflect.Value, pointers pointersMap,
 	// preserves type safety for the user.
 	if v.IsValid() && v.CanInterface() {
 		attemptCopier := true
-		if kind == reflect.Interface || kind == reflect.Ptr {
+		if kind == reflect.Interface || kind == reflect.Pointer {
 			if v.IsNil() {
 				attemptCopier = false
 			}
 		}
 
 		if attemptCopier {
-			if kind == reflect.Struct || kind == reflect.Ptr {
+			if kind == reflect.Struct || kind == reflect.Pointer {
 				method := v.MethodByName("Copy")
 				if method.IsValid() && method.Type().NumIn() == 0 && method.Type().NumOut() == 2 {
 					if method.Type().Out(0) == v.Type() && method.Type().Out(1).Implements(reflect.TypeOf((*error)(nil)).Elem()) {
@@ -239,7 +239,7 @@ func recursiveCopy(v reflect.Value, pointers pointersMap,
 		return recursiveCopyInterface(v, pointers, config, path)
 	case reflect.Map:
 		return recursiveCopyMap(v, pointers, config, path)
-	case reflect.Ptr:
+	case reflect.Pointer:
 		return recursiveCopyPtr(v, pointers, config, path)
 	case reflect.Slice:
 		return recursiveCopySlice(v, pointers, config, path)
@@ -444,7 +444,7 @@ func deepCopyValue(v reflect.Value) reflect.Value {
 
 	// We ensure the root is addressable for cycle detection.
 	var rv reflect.Value
-	isPtr := v.Kind() == reflect.Ptr
+	isPtr := v.Kind() == reflect.Pointer
 	if isPtr {
 		rv = v
 	} else {
@@ -458,7 +458,7 @@ func deepCopyValue(v reflect.Value) reflect.Value {
 		return v
 	}
 
-	if !isPtr && copied.Kind() == reflect.Ptr {
+	if !isPtr && copied.Kind() == reflect.Pointer {
 		return copied.Elem()
 	}