deep

package module
v2.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 12, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

Deep Copy and Patch for Go

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.

Quick Start

1. Deep Copy

Create a decoupled clone of any value.

dst, err := deep.Copy(src)
2. Diff and Apply

Transform an object from one state to another.

// 1. Calculate the difference
patch := deep.Diff(oldConfig, newConfig)

if patch != nil {
    // 2. Apply to a target (must be a pointer)
    err := patch.ApplyChecked(&oldConfig)
}

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
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.

type Document struct {
    Text []Char `deep:"key"` // Enable semantic list merging
}

Core Concepts

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).

// 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.
  • Resolved: Use ApplyResolved to handle concurrent edits via a custom resolution strategy.

The Manual Patch Builder

While Diff is great for sync logic, the Builder is ideal for API-driven updates or migrations.

builder := deep.NewBuilder[Config]()

builder.Root().
    Field("Version").Put(2). // "Put" is a blind set (bypasses strict checks)
    Field("Metadata").
        MapKey("env").Set("dev", "prod") // "Set" requires old value for strict check

patch, _ := builder.Build()
patch.ApplyChecked(&myConfig)
Navigation

You can jump to any path using Go-style notation or JSON Pointers:

builder.Root().Navigate("/network/settings/port").Put(8080)
builder.Root().Navigate("Metadata.Tags[0]").Put("admin")

Conditional Patching

Condition DSL

You can attach logic to any node in a patch using a string-based DSL via ParseCondition or AddCondition.

Syntax Examples:

  • "Version > 5" (Literal comparison)
  • "Stock < MinAlertThreshold" (Cross-field comparison)
  • "Network.Port == 8080 AND Status == 'active'" (Logical groups)

Interoperability

JSON Pointer (RFC 6901)

Use standard pointers to navigate or query your structures:

cond, _ := deep.ParseCondition[Config]("/network/settings/port > 1024")
builder.Root().Navigate("/meta/tags/0").Put("new")
JSON Patch (RFC 6902)

Export any deep.Patch to a standard JSON Patch array:

jsonBytes, err := patch.ToJSONPatch()

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.

Cycle Detection

The library tracks pointers during recursive operations. Circular references are handled correctly without entering infinite loops.

License

Apache 2.0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrConditionSkipped = fmt.Errorf("condition skipped")

Functions

func Copy 

func Copy[T any](src T, opts ...CopyOption) (T, error)

Copy creates a deep copy of src. It returns the copy and a nil error in case of success and the zero value for the type and a non-nil error on failure.

It correctly handles cyclic references and unexported fields.

func CopySkipUnsupported deprecated 

func CopySkipUnsupported[T any](src T) (T, error)

CopySkipUnsupported creates a deep copy of src. It returns the copy and a nil error in case of success and the zero value for the type and a non-nil error on failure. Unsupported types (e.g. non-nil functions, channels or unsafe pointers) are skipped (the copy will have the zero value for the type) instead of returning an error.

Deprecated: Use Copy with the SkipUnsupported() option instead.

func IgnorePath 

func IgnorePath(path string) interface {
	DiffOption
	CopyOption
}

IgnorePath returns an option that tells both Diff and Copy to ignore changes at the specified path. The path should use Go-style notation (e.g., "Field.SubField", "Map.Key", "Slice[0]").

func MustCopy 

func MustCopy[T any](src T, opts ...CopyOption) T

MustCopy creates a deep copy of src. It returns the copy on success or panics in case of any failure.

It correctly handles cyclic references and unexported fields.

func Register 

func Register[T any]()

Register registers the Patch implementation for type T with the gob package. This is required if you want to use Gob serialization with Patch[T].

Types

type AndCondition 

type AndCondition[T any] struct {
	Conditions []Condition[T]
}

AndCondition represents a logical AND of multiple conditions.

func (AndCondition[T]) Evaluate 

func (c AndCondition[T]) Evaluate(v *T) (bool, error)

func (AndCondition[T]) MarshalJSON 

func (c AndCondition[T]) MarshalJSON() ([]byte, error)

type Builder 

type Builder[T any] struct {
	// contains filtered or unexported fields
}

Builder allows constructing a Patch[T] manually with on-the-fly type validation.

func NewBuilder 

func NewBuilder[T any]() *Builder[T]

NewBuilder returns a new Builder for type T.

func (*Builder[T]) AddCondition 

func (b *Builder[T]) AddCondition(expr string) *Builder[T]

AddCondition parses a string expression and attaches it to the appropriate node in the patch tree based on the paths used in the expression. It finds the longest common prefix of all paths in the expression and navigates to that node before attaching the condition.

func (*Builder[T]) Build 

func (b *Builder[T]) Build() (Patch[T], error)

Build returns the constructed Patch or an error if any operation was invalid.

func (*Builder[T]) Root 

func (b *Builder[T]) Root() *Node

Root returns a Node representing the root of the value being patched.

type CompareCondition 

type CompareCondition[T any] struct {
	Path       Path
	Val        any
	Op         string
	IgnoreCase bool
}

CompareCondition represents a comparison between a path and a literal value.

func (CompareCondition[T]) Evaluate 

func (c CompareCondition[T]) Evaluate(v *T) (bool, error)

func (CompareCondition[T]) MarshalJSON 

func (c CompareCondition[T]) MarshalJSON() ([]byte, error)

type CompareFieldCondition 

type CompareFieldCondition[T any] struct {
	Path1      Path
	Path2      Path
	Op         string
	IgnoreCase bool
}

CompareFieldCondition represents a comparison between two paths.

func (CompareFieldCondition[T]) Evaluate 

func (c CompareFieldCondition[T]) Evaluate(v *T) (bool, error)

func (CompareFieldCondition[T]) MarshalJSON 

func (c CompareFieldCondition[T]) MarshalJSON() ([]byte, error)

type Condition 

type Condition[T any] interface {
	// Evaluate evaluates the condition against the given value.
	Evaluate(v *T) (bool, error)

	// MarshalJSON returns the JSON representation of the condition.
	MarshalJSON() ([]byte, error)
	// contains filtered or unexported methods
}

Condition represents a logical check against a value of type T.

func And 

func And[T any](conds ...Condition[T]) Condition[T]

And returns a condition that represents a logical AND of multiple conditions.

func Contains 

func Contains[T any](path, val string) Condition[T]

Contains returns a condition that checks if the string value at the path contains the given substring.

func ContainsFold 

func ContainsFold[T any](path, val string) Condition[T]

ContainsFold returns a condition that checks if the string value at the path contains the given substring (case-insensitive).

func Defined 

func Defined[T any](path string) Condition[T]

Defined returns a condition that checks if the value at the path is defined.

func EndsWith 

func EndsWith[T any](path, val string) Condition[T]

EndsWith returns a condition that checks if the string value at the path ends with the given suffix.

func EndsWithFold 

func EndsWithFold[T any](path, val string) Condition[T]

EndsWithFold returns a condition that checks if the string value at the path ends with the given suffix (case-insensitive).

func Equal 

func Equal[T any](path string, val any) Condition[T]

Equal returns a condition that checks if the value at the path is equal to the given value.

func EqualField 

func EqualField[T any](path1, path2 string) Condition[T]

EqualField returns a condition that checks if the value at path1 is equal to the value at path2.

func EqualFieldFold 

func EqualFieldFold[T any](path1, path2 string) Condition[T]

EqualFieldFold returns a condition that checks if the value at path1 is equal to the value at path2 (case-insensitive).

func EqualFold 

func EqualFold[T any](path string, val any) Condition[T]

EqualFold returns a condition that checks if the value at the path is equal to the given value (case-insensitive).

func Greater 

func Greater[T any](path string, val any) Condition[T]

Greater returns a condition that checks if the value at the path is greater than the given value.

func GreaterEqual 

func GreaterEqual[T any](path string, val any) Condition[T]

GreaterEqual returns a condition that checks if the value at the path is greater than or equal to the given value.

func GreaterEqualField 

func GreaterEqualField[T any](path1, path2 string) Condition[T]

GreaterEqualField returns a condition that checks if the value at path1 is greater than or equal to the value at path2.

func GreaterField 

func GreaterField[T any](path1, path2 string) Condition[T]

GreaterField returns a condition that checks if the value at path1 is greater than the value at path2.

func In 

func In[T any](path string, values ...any) Condition[T]

In returns a condition that checks if the value at the path is one of the given values.

func InFold 

func InFold[T any](path string, values ...any) Condition[T]

InFold returns a condition that checks if the value at the path is one of the given values (case-insensitive).

func Less 

func Less[T any](path string, val any) Condition[T]

Less returns a condition that checks if the value at the path is less than the given value.

func LessEqual 

func LessEqual[T any](path string, val any) Condition[T]

LessEqual returns a condition that checks if the value at the path is less than or equal to the given value.

func LessEqualField 

func LessEqualField[T any](path1, path2 string) Condition[T]

LessEqualField returns a condition that checks if the value at path1 is less than or equal to the value at path2.

func LessField 

func LessField[T any](path1, path2 string) Condition[T]

LessField returns a condition that checks if the value at path1 is less than the value at path2.

func Log 

func Log[T any](message string) Condition[T]

Log returns a condition that logs the given message during evaluation.

func Matches 

func Matches[T any](path, pattern string) Condition[T]

Matches returns a condition that checks if the string value at the path matches the given regex pattern.

func MatchesFold 

func MatchesFold[T any](path, pattern string) Condition[T]

MatchesFold returns a condition that checks if the string value at the path matches the given regex pattern (case-insensitive).

func Not 

func Not[T any](c Condition[T]) Condition[T]

Not returns a condition that represents a logical NOT of a condition.

func NotEqual 

func NotEqual[T any](path string, val any) Condition[T]

NotEqual returns a condition that checks if the value at the path is not equal to the given value.

func NotEqualField 

func NotEqualField[T any](path1, path2 string) Condition[T]

NotEqualField returns a condition that checks if the value at path1 is not equal to the value at path2.

func NotEqualFieldFold 

func NotEqualFieldFold[T any](path1, path2 string) Condition[T]

NotEqualFieldFold returns a condition that checks if the value at path1 is not equal to the value at path2 (case-insensitive).

func NotEqualFold 

func NotEqualFold[T any](path string, val any) Condition[T]

NotEqualFold returns a condition that checks if the value at the path is not equal to the given value (case-insensitive).

func Or 

func Or[T any](conds ...Condition[T]) Condition[T]

Or returns a condition that represents a logical OR of multiple conditions.

func ParseCondition 

func ParseCondition[T any](expr string) (Condition[T], error)

ParseCondition parses a string expression into a Condition[T] tree.

func StartsWith 

func StartsWith[T any](path, val string) Condition[T]

StartsWith returns a condition that checks if the string value at the path starts with the given prefix.

func StartsWithFold 

func StartsWithFold[T any](path, val string) Condition[T]

StartsWithFold returns a condition that checks if the string value at the path starts with the given prefix (case-insensitive).

func Type 

func Type[T any](path, typeName string) Condition[T]

Type returns a condition that checks if the value at the path has the given type.

func Undefined 

func Undefined[T any](path string) Condition[T]

Undefined returns a condition that checks if the value at the path is undefined.

type ConflictResolver 

type ConflictResolver interface {
	// Resolve allows the resolver to intervene before an operation is applied.
	// It returns true if the operation should be applied, false to skip it.
	// The resolver can also modify the operation or target value directly.
	Resolve(path string, op OpKind, key, prevKey any, val reflect.Value) bool
}

ConflictResolver allows custom logic to be injected during patch application. It is used to implement CRDTs, 3-way merges, and other conflict resolution strategies.

type Copier 

type Copier[T any] interface {
	// Copy returns a deep copy of the receiver.
	Copy() (T, error)
}

Copier is an interface that types can implement to provide their own custom deep copy logic. The type T in Copy() (T, error) must be the same concrete type as the receiver that implements this interface.

type CopyOption 

type CopyOption interface {
	// contains filtered or unexported methods
}

CopyOption allows configuring the behavior of the Copy function.

func CopyIgnorePath 

func CopyIgnorePath(path string) CopyOption

CopyIgnorePath returns an option that tells Copy to ignore the specified path. The ignored path will have the zero value for its type in the resulting copy.

func SkipUnsupported 

func SkipUnsupported() CopyOption

SkipUnsupported returns an option that tells Copy to skip unsupported types (like non-nil functions or channels) instead of returning an error.

type DefinedCondition 

type DefinedCondition[T any] struct {
	Path Path
}

DefinedCondition checks if a path is defined (non-zero).

func (DefinedCondition[T]) Evaluate 

func (c DefinedCondition[T]) Evaluate(v *T) (bool, error)

func (DefinedCondition[T]) MarshalJSON 

func (c DefinedCondition[T]) MarshalJSON() ([]byte, error)

type DiffOption 

type DiffOption interface {
	// contains filtered or unexported methods
}

DiffOption allows configuring the behavior of the Diff function.

func DiffIgnorePath 

func DiffIgnorePath(path string) DiffOption

DiffIgnorePath returns an option that tells Diff to ignore changes at the specified path. The path should use Go-style notation (e.g., "Field.SubField", "Map.Key", "Slice[0]").

type Differ 

type Differ[T any] interface {
	// Diff returns a patch that transforms the receiver into other.
	Diff(other T) (Patch[T], error)
}

Differ is an interface that types can implement to provide their own custom diff logic. The type T in Diff(other T) (Patch[T], error) must be the same concrete type as the receiver that implements this interface.

type InCondition 

type InCondition[T any] struct {
	Path       Path
	Values     []any
	IgnoreCase bool
}

InCondition checks if the value at a path is one of the given values.

func (InCondition[T]) Evaluate 

func (c InCondition[T]) Evaluate(v *T) (bool, error)

func (InCondition[T]) MarshalJSON 

func (c InCondition[T]) MarshalJSON() ([]byte, error)

type LogCondition 

type LogCondition[T any] struct {
	Message string
}

LogCondition logs a message during evaluation.

func (LogCondition[T]) Evaluate 

func (c LogCondition[T]) Evaluate(v *T) (bool, error)

func (LogCondition[T]) MarshalJSON 

func (c LogCondition[T]) MarshalJSON() ([]byte, error)

type Node 

type Node struct {
	// contains filtered or unexported fields
}

Node represents a specific location within a value's structure.

func (*Node) Add 

func (n *Node) Add(i int, val any) error

Add appends an addition operation to a slice node.

func (*Node) AddMapEntry 

func (n *Node) AddMapEntry(key, val any) error

AddMapEntry adds a new entry to a map node.

func (*Node) Copy 

func (n *Node) Copy(from string) *Node

Copy copies a value from another path to the current node.

func (*Node) Delete 

func (n *Node) Delete(keyOrIndex any, oldVal any) error

Delete appends a deletion operation to a slice or map node.

func (*Node) Elem 

func (n *Node) Elem() *Node

Elem returns a Node for the element type of a pointer or interface.

func (*Node) Field 

func (n *Node) Field(name string) (*Node, error)

Field returns a Node for the specified struct field. It automatically descends into pointers and interfaces if necessary.

func (*Node) FieldOrMapKey 

func (n *Node) FieldOrMapKey(key string) (*Node, error)

FieldOrMapKey returns a Node for the specified field or map key.

func (*Node) If 

func (n *Node) If(c any) *Node

If attaches an 'if' condition to the current node. If the condition evaluates to false, the operation at this node is skipped.

func (*Node) Index 

func (n *Node) Index(i int) (*Node, error)

Index returns a Node for the specified array or slice index.

func (*Node) Log 

func (n *Node) Log(message string) *Node

Log adds a log operation to the current node. It prints a message and the current value at the node during patch application.

func (*Node) MapKey 

func (n *Node) MapKey(key any) (*Node, error)

MapKey returns a Node for the specified map key.

func (*Node) Move 

func (n *Node) Move(from string) *Node

Move moves a value from another path to the current node.

func (*Node) Navigate 

func (n *Node) Navigate(path string) (*Node, error)

navigate returns a Node for the specified path relative to the current node. Navigate returns a Node for the specified path relative to the current node. It supports both Go-style paths ("Field.Sub") and JSON Pointers ("/Field/Sub").

func (*Node) Put 

func (n *Node) Put(value any) *Node

Put replaces the value at the current node without requiring the 'old' value. Strict consistency checks for this specific value will be disabled.

func (*Node) Set 

func (n *Node) Set(old, new any) *Node

Set replaces the value at the current node. It requires the 'old' value to enable patch reversibility and strict application checking.

func (*Node) Test 

func (n *Node) Test(expected any) *Node

Test adds a test operation to the current node. The patch application will fail if the value at this node does not match the expected value.

func (*Node) Unless 

func (n *Node) Unless(c any) *Node

Unless attaches an 'unless' condition to the current node. If the condition evaluates to true, the operation at this node is skipped.

func (*Node) WithCondition 

func (n *Node) WithCondition(c any) *Node

WithCondition attaches a local condition to the current node. This condition is evaluated against the value at this node during ApplyChecked.

type NotCondition 

type NotCondition[T any] struct {
	C Condition[T]
}

NotCondition represents a logical NOT of a condition.

func (NotCondition[T]) Evaluate 

func (c NotCondition[T]) Evaluate(v *T) (bool, error)

func (NotCondition[T]) MarshalJSON 

func (c NotCondition[T]) MarshalJSON() ([]byte, error)

type OpKind 

type OpKind int

OpKind represents the type of operation in a patch. 

const (
	OpAdd OpKind = iota
	OpRemove
	OpReplace
	OpMove
	OpCopy
	OpTest
	OpLog
)

func (OpKind) String 

func (k OpKind) String() string

type OrCondition 

type OrCondition[T any] struct {
	Conditions []Condition[T]
}

OrCondition represents a logical OR of multiple conditions.

func (OrCondition[T]) Evaluate 

func (c OrCondition[T]) Evaluate(v *T) (bool, error)

func (OrCondition[T]) MarshalJSON 

func (c OrCondition[T]) MarshalJSON() ([]byte, error)

type Patch 

type Patch[T any] interface {
	fmt.Stringer

	// Apply applies the patch to the value pointed to by v.
	// The value v must not be nil.
	Apply(v *T)

	// ApplyChecked applies the patch only if specific conditions are met.
	// 1. If the patch has a global Condition, it must evaluate to true.
	// 2. If Strict mode is enabled, every modification must match the 'oldVal' recorded in the patch.
	// 3. Any local per-field conditions must evaluate to true.
	ApplyChecked(v *T) error

	// ApplyResolved applies the patch using a custom ConflictResolver.
	// This is used for convergent synchronization (CRDTs).
	ApplyResolved(v *T, r ConflictResolver) error

	// Walk calls fn for every operation in the patch.
	// The path is a Go-style dot-notation path (e.g. "Field.SubField[0]").
	// If fn returns an error, walking stops and that error is returned.
	Walk(fn func(path string, op OpKind, old, new any) error) error

	// WithCondition returns a new Patch with the given global condition attached.
	WithCondition(c Condition[T]) Patch[T]

	// WithStrict returns a new Patch with the strict consistency check enabled or disabled.
	WithStrict(strict bool) Patch[T]

	// Reverse returns a new Patch that undoes the changes in this patch.
	Reverse() Patch[T]

	// ToJSONPatch returns an RFC 6902 compliant JSON Patch representation of this patch.
	ToJSONPatch() ([]byte, error)
}

Patch represents a set of changes that can be applied to a value of type T.

func Diff 

func Diff[T any](a, b T, opts ...DiffOption) Patch[T]

Diff compares two values a and b and returns a Patch that can be applied to a to make it equal to b.

It uses a combination of Myers' Diff algorithm for slices and recursive type-specific comparison for structs, maps, and pointers.

If a and b are deeply equal, it returns nil.

func NewPatch 

func NewPatch[T any]() Patch[T]

NewPatch returns a new, empty patch for type T.

type Path 

type Path string

Path represents a path to a field or element within a structure. Syntax: "Field", "Field.SubField", "Slice[0]", "Map.Key", "Ptr.Field". It also supports JSON Pointers (RFC 6901) like "/Field/SubField".

type StringCondition 

type StringCondition[T any] struct {
	Path       Path
	Val        string
	Op         string
	IgnoreCase bool
}

StringCondition checks a string value at a path against a pattern.

func (StringCondition[T]) Evaluate 

func (c StringCondition[T]) Evaluate(v *T) (bool, error)

func (StringCondition[T]) MarshalJSON 

func (c StringCondition[T]) MarshalJSON() ([]byte, error)

type TypeCondition 

type TypeCondition[T any] struct {
	Path     Path
	TypeName string
}

TypeCondition checks if the value at a path has a specific type.

func (TypeCondition[T]) Evaluate 

func (c TypeCondition[T]) Evaluate(v *T) (bool, error)

func (TypeCondition[T]) MarshalJSON 

func (c TypeCondition[T]) MarshalJSON() ([]byte, error)

type UndefinedCondition 

type UndefinedCondition[T any] struct {
	Path Path
}

UndefinedCondition checks if a path is undefined (zero value).

func (UndefinedCondition[T]) Evaluate 

func (c UndefinedCondition[T]) Evaluate(v *T) (bool, error)

func (UndefinedCondition[T]) MarshalJSON 

func (c UndefinedCondition[T]) MarshalJSON() ([]byte, error)

Source Files

View all Source files

Directories

Path Synopsis
hlc
examples
audit_logging command
business_rules command
config_manager command
crdt_sync command
http_patch_api command
json_interop command
keyed_inventory command
state_management command
text_sync command
websocket_sync command
internal
unsafe
resolvers
crdt

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.