crdt

package

v5.0.1 Latest Latest Go to latest Published: Mar 25, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/brunoga/deep

Links

Open Source Insights

Documentation ¶

Overview ¶

Package crdt provides Conflict-free Replicated Data Types (CRDTs) built on top of the deep patch engine.

The central type is CRDT, a concurrency-safe wrapper around any value of type T. It tracks causal history using a per-field Hybrid Logical Clock (HLC) and resolves concurrent edits with Last-Write-Wins (LWW) semantics.

Basic workflow ¶

Create nodes: nodeA := crdt.NewCRDT(initial, "node-a")
Edit locally: delta := nodeA.Edit(func(v *T) { v.Field = newVal })
Distribute: send delta (JSON-serializable) to peers
Apply remotely: nodeB.ApplyDelta(delta)

For full-state synchronization between two nodes use CRDT.Merge.

Text CRDT ¶

Text is a convergent, ordered sequence of TextRun segments. It supports concurrent insertions and deletions across nodes and is integrated with CRDT directly — no separate registration required.

Index ¶

type CRDT
- func NewCRDT[T any](initial T, nodeID string) *CRDT[T]
type Delta
- func (d Delta[T]) MarshalJSON() ([]byte, error)
- func (d *Delta[T]) UnmarshalJSON(data []byte) error
type LWW
- func (l *LWW[T]) Set(v T, ts hlc.HLC) bool
type Text
- func MergeTextRuns(a, b Text) Text
type TextRun

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type CRDT ¶

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

CRDT represents a Conflict-free Replicated Data Type wrapper around type T.

func NewCRDT ¶

func NewCRDT[T any](initial T, nodeID string) *CRDT[T]

NewCRDT creates a new CRDT wrapper.

func (*CRDT[T]) ApplyDelta ¶

func (c *CRDT[T]) ApplyDelta(delta Delta[T]) bool

ApplyDelta applies a delta from a remote peer using Last-Write-Wins resolution. Returns true if any operations were accepted.

func (*CRDT[T]) Clock ¶

func (c *CRDT[T]) Clock() *hlc.Clock

Clock returns the internal hybrid logical clock.

func (*CRDT[T]) Edit ¶

func (c *CRDT[T]) Edit(fn func(*T)) Delta[T]

Edit applies fn to a copy of the current value, computes a delta, advances the local clock, and returns the delta for distribution to peers. Returns an empty Delta if the edit produces no changes.

func (*CRDT[T]) MarshalJSON ¶

func (c *CRDT[T]) MarshalJSON() ([]byte, error)

func (*CRDT[T]) Merge ¶

func (c *CRDT[T]) Merge(other *CRDT[T]) bool

Merge performs a full state-based merge with another CRDT node. For each changed field the node with the strictly newer effective timestamp (max of write clock and tombstone) wins. Text fields are always merged convergently via MergeTextRuns, bypassing LWW.

func (*CRDT[T]) NodeID ¶

func (c *CRDT[T]) NodeID() string

NodeID returns the unique identifier for this CRDT instance.

func (*CRDT[T]) UnmarshalJSON ¶

func (c *CRDT[T]) UnmarshalJSON(data []byte) error

func (*CRDT[T]) View ¶

func (c *CRDT[T]) View() T

View returns a deep copy of the current value.

type Delta ¶

type Delta[T any] struct {
	Timestamp hlc.HLC `json:"t"`
	// contains filtered or unexported fields
}

Delta represents a set of changes with a causal timestamp. Obtain a Delta via CRDT.Edit; apply it on remote nodes via CRDT.ApplyDelta.

func (Delta[T]) MarshalJSON ¶

func (d Delta[T]) MarshalJSON() ([]byte, error)

func (*Delta[T]) UnmarshalJSON ¶

func (d *Delta[T]) UnmarshalJSON(data []byte) error

type LWW ¶

type LWW[T any] struct {
	Value     T       `json:"v"`
	Timestamp hlc.HLC `json:"t"`
}

LWW represents a Last-Write-Wins register for type T. Embed LWW fields in a struct to track per-field causality. Use Set to update the value; it accepts the write only if ts is strictly newer.

func (*LWW[T]) Set ¶

func (l *LWW[T]) Set(v T, ts hlc.HLC) bool

Set updates the register's value and timestamp if ts is after the current timestamp. Returns true if the update was accepted.

type Text ¶

type Text []TextRun

Text represents a CRDT-friendly text structure using runs.

func MergeTextRuns ¶

func MergeTextRuns(a, b Text) Text

MergeTextRuns merges two Text states into a single convergent state.

func (Text) Delete ¶

func (t Text) Delete(pos, length int) Text

Delete removes length characters starting at pos.

func (Text) Diff ¶

func (t Text) Diff(other Text) deep.Patch[Text]

Diff compares t with other and returns a Patch.

func (Text) Insert ¶

func (t Text) Insert(pos int, value string, clock *hlc.Clock) Text

Insert inserts a string at the given character position.

func (*Text) Patch ¶

func (t *Text) Patch(p deep.Patch[Text], logger *slog.Logger) error

Patch applies p to t.

func (Text) String ¶

func (t Text) String() string

String returns the full text content, skipping deleted runs.

type TextRun ¶

type TextRun struct {
	ID      hlc.HLC `deep:"key" json:"id"`
	Value   string  `json:"v"`
	Prev    hlc.HLC `json:"p,omitempty"`
	Deleted bool    `json:"d,omitempty"`
}

TextRun represents a contiguous run of characters with a unique starting ID.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
hlc Package hlc implements a Hybrid Logical Clock (HLC) for distributed causality tracking.	Package hlc implements a Hybrid Logical Clock (HLC) for distributed causality tracking.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL