crdt

package

v5.0.0 Latest Latest Go to latest Published: Mar 24, 2026 License: Apache-2.0 Imports: 7 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.

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