delta

package
v0.5.2 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package delta ports Chord's immutable JSON deltas (@earendil-works/chord 1.0.4 `delta`: operations, the immutable applier and the overlay draft tracker) onto the ordered value model of package jv.

A draft is a mutation log over an immutable base revision. Preparing it emits the same operation batch Chord's tracker emits for the same mutations, which is what Pi stores in a document delta, and applies the batch to the base to obtain the next revision. The package uses no reflection and no encoding/json, and keeps no package-level mutable state.

Index

Constants

This section is empty.

Variables

View Source
var (
	// Read-only: assigned once at initialization.
	ErrInvalidOp = errors.New("invalid delta operation")
	// Read-only: assigned once at initialization.
	ErrUnsafePath = errors.New("unsafe path segment")
	// Read-only: assigned once at initialization.
	ErrPath = errors.New("unresolvable path")
)

Errors reported by the applier and the operation decoder.

View Source
var ErrNotJSON = errors.New("value is not strict JSON")

ErrNotJSON reports a placement that is not a value of the model. Read-only: assigned once at initialization.

View Source
var ErrRevoked = errors.New("Cannot use a settled overlay")

ErrRevoked is the panic value for any use of a draft handle after its change settled, was aborted, or became stale (tracker.ts "Cannot use a settled overlay"). Using a settled handle is a contract violation, so it panics like upstream's TypeError instead of returning an error every read must check. Read-only: assigned once at initialization.

View Source
var ErrSparseArray = errors.New("Overlay arrays cannot contain holes")

ErrSparseArray reports an array write that would leave a hole. Read-only: assigned once at initialization.

Functions

func Apply

func Apply(target any, ops []Op) (any, error)

Apply applies one batch without mutating target. The result shares unchanged containers with target and adopts operation payloads without copying them.

func IsBase

func IsBase(ops []Op) bool

IsBase reports whether a batch begins with a root replacement.

func OpsValue

func OpsValue(ops []Op) []any

OpsValue returns the operations as a JSON array value.

func Overlap

func Overlap(a, b string, scan int) int

Overlap returns the longest suffix of a that is a prefix of b, in UTF-16 code units, considering at most the last scan units of a. It probes a long head of b first, then one unit, and gives up after eight candidates per probe; giving up returns 0, which emits a set: larger, never wrong.

Types

type Arr

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

Arr is a draft handle of a JSON array with the same lifetime as Obj. Held handles follow elements through reindexing.

func (*Arr) Arr

func (a *Arr) Arr(index int) *Arr

Arr returns the array handle at index, or nil.

func (*Arr) Get

func (a *Arr) Get(index int) any

Get returns the element at index, or nil when out of range.

func (*Arr) Len

func (a *Arr) Len() int

Len returns the array length.

func (*Arr) Obj

func (a *Arr) Obj(index int) *Obj

Obj returns the object handle at index, or nil.

func (*Arr) Pop

func (a *Arr) Pop() any

Pop removes and returns a detached copy of the last element's present value.

func (*Arr) Push

func (a *Arr) Push(values ...any) (int, error)

Push appends validated clones and returns the new length. When any value is not strict JSON nothing is inserted.

func (*Arr) Set

func (a *Arr) Set(index int, value any) error

Set places a validated clone of value at index; index may append one past the end.

func (*Arr) SetLen

func (a *Arr) SetLen(length int)

SetLen grows the array with nulls or shrinks it.

func (*Arr) Shift

func (a *Arr) Shift() any

Shift removes and returns a detached copy of the first element's present value.

func (*Arr) Snapshot

func (a *Arr) Snapshot() []any

Snapshot returns a detached copy of the present content.

func (*Arr) Splice

func (a *Arr) Splice(start, remove int, items ...any) ([]any, error)

Splice removes remove elements at start, inserts validated clones of items, and returns detached copies of the removed present values.

func (*Arr) Unshift

func (a *Arr) Unshift(values ...any) (int, error)

Unshift inserts validated clones at the front and returns the new length.

type Change

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

Change is one open overlay draft.

func (*Change) Abort

func (change *Change) Abort()

Abort discards the change, or the preparation it produced.

func (*Change) BaseRoot

func (change *Change) BaseRoot() any

BaseRoot returns the revision an open change started from: a *jv.Object or a []any. It is nil once the change settled.

func (*Change) Elements

func (change *Change) Elements() *Arr

Elements returns the mutable draft of an array root, and nil for an object root. It panics with ErrRevoked once the change settled.

func (*Change) Prepare

func (change *Change) Prepare() (*Prepared, error)

Prepare materializes the candidate revision and its operations without changing authority. Every draft handle is unusable afterwards.

func (*Change) PrepareThen

func (change *Change) PrepareThen(ops []Op) (*Prepared, error)

PrepareThen is Prepare for a draft the core edited and a host's Chord tracker then continued: ops were emitted against the draft's present content, so they follow the draft's own operations. The candidate's operations are both lists in order, and its value the base with them applied.

func (*Change) State

func (change *Change) State() *Obj

State returns the mutable draft of an object root, and nil for an array root. It panics with ErrRevoked once the change settled.

type Obj

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

Obj is a draft handle of a JSON object. It is usable only while its change is open; any later use panics with ErrRevoked. Containers read through it are returned as *Obj or *Arr handles, numbers as float64.

func (*Obj) Arr

func (o *Obj) Arr(key string) *Arr

Arr returns the array handle at key, or nil when the value is not an array.

func (*Obj) Delete

func (o *Obj) Delete(key string)

Delete removes key; it is upstream's `draft.key = undefined` or `delete`.

func (*Obj) Get

func (o *Obj) Get(key string) any

Get returns the value at key, or nil when absent.

func (*Obj) Has

func (o *Obj) Has(key string) bool

Has reports whether key is present.

func (*Obj) Keys

func (o *Obj) Keys() []string

Keys returns the present keys in JavaScript's own-key order: integer-like keys ascending, then the other keys in base order, then keys added by this change in write order; a key deleted and added again counts as added.

func (*Obj) Len

func (o *Obj) Len() int

Len returns the number of present keys.

func (*Obj) Lookup

func (o *Obj) Lookup(key string) (any, bool)

Lookup returns the value at key and whether it is present.

func (*Obj) Obj

func (o *Obj) Obj(key string) *Obj

Obj returns the object handle at key, or nil when the value is not an object.

func (*Obj) Set

func (o *Obj) Set(key string, value any) error

Set places a validated clone of value at key. A value that is not strict JSON returns an error and leaves the draft unchanged.

func (*Obj) Snapshot

func (o *Obj) Snapshot() *jv.Object

Snapshot returns a detached copy of the draft's present content.

type Op

type Op struct {
	Verb   Verb
	Path   Path
	Value  any    // Replace, Set
	Text   string // Append
	Count  int    // Trim
	Index  int    // Splice
	Remove int    // Splice
	Items  []any  // Splice
	Perm   []int  // Permute
}

Op is one operation. Which fields are meaningful depends on Verb.

func DecodeOp

func DecodeOp(value any) (Op, error)

DecodeOp decodes one stored operation tuple and checks its verb, arity and payload shape.

func DecodeOps

func DecodeOps(value any) ([]Op, error)

DecodeOps decodes a stored operation array.

func (Op) Tuple

func (op Op) Tuple() any

Tuple returns the operation as the tuple Chord stores: a []any whose path is an array of strings and numbers.

type Path

type Path []Seg

Path addresses a value below the root.

type Prepared

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

Prepared is a materialized candidate revision.

func (*Prepared) Abort

func (prepared *Prepared) Abort()

Abort prevents adoption. The candidate stays readable.

func (*Prepared) Base

func (prepared *Prepared) Base() *jv.Object

Base returns the revision the change started from, for an object root (nil for an array root; see BaseRoot).

func (*Prepared) BaseRevision

func (prepared *Prepared) BaseRevision() int

BaseRevision returns the tracker revision the change started from.

func (*Prepared) BaseRoot

func (prepared *Prepared) BaseRoot() any

BaseRoot returns the revision the change started from: a *jv.Object or a []any.

func (*Prepared) Ops

func (prepared *Prepared) Ops() []Op

Ops returns the exact operations that transform Base into Value. Payloads may be the same containers as parts of Value.

func (*Prepared) Value

func (prepared *Prepared) Value() *jv.Object

Value returns the candidate revision of an object root (nil for an array root; see ValueRoot). Empty Ops means Value is Base.

func (*Prepared) ValueRoot

func (prepared *Prepared) ValueRoot() any

ValueRoot returns the candidate revision: a *jv.Object or a []any. Empty Ops means ValueRoot is BaseRoot.

type Seg

type Seg struct {
	Key     string
	Index   int
	IsIndex bool
}

Seg is one path segment: an object key or an array index.

func Idx

func Idx(i int) Seg

Idx returns the segment for an array index.

func Key

func Key(k string) Seg

Key returns the segment for an object key.

type Tracker

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

Tracker owns one sequence of immutable revisions of an object or array root, as tracker.ts's track(initial: T extends object).

func Track

func Track(initial *jv.Object) *Tracker

Track takes immutable ownership of an alias-free JSON root in O(1). The caller must never mutate initial again.

func TrackArray

func TrackArray(initial []any) *Tracker

TrackArray is Track for an array root. Its Change drafts through Elements, and its operations address the root with the empty path.

func (*Tracker) Adopt

func (tracker *Tracker) Adopt(prepared *Prepared) error

Adopt makes a prepared revision the tracker's latest and stales every competing change.

func (*Tracker) BeginChange

func (tracker *Tracker) BeginChange() *Change

BeginChange opens an overlay draft over the latest revision. The draft never modifies that revision.

func (*Tracker) Revision

func (tracker *Tracker) Revision() int

Revision returns the number of adoptions.

func (*Tracker) Root

func (tracker *Tracker) Root() any

Root returns the latest adopted revision: a *jv.Object or a []any.

func (*Tracker) Value

func (tracker *Tracker) Value() *jv.Object

Value returns the latest adopted revision of an object root, and nil for an array root; Root returns either.

type Verb

type Verb byte

Verb names an operation kind: the first element of an operation tuple.

const (
	Replace Verb = 'r' // ["r", value]
	Set     Verb = 's' // ["s", path, value]
	Delete  Verb = 'd' // ["d", path]
	Append  Verb = 'a' // ["a", path, text]
	Trim    Verb = 't' // ["t", path, count]: drop count UTF-16 units from the front of a string
	Splice  Verb = 'p' // ["p", path, index, remove, items]
	Permute Verb = 'm' // ["m", path, permutation]: new[i] = old[permutation[i]]
)

The operation verbs.

Jump to

Keyboard shortcuts

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