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 ¶
- Variables
- func Apply(target any, ops []Op) (any, error)
- func IsBase(ops []Op) bool
- func OpsValue(ops []Op) []any
- func Overlap(a, b string, scan int) int
- type Arr
- func (a *Arr) Arr(index int) *Arr
- func (a *Arr) Get(index int) any
- func (a *Arr) Len() int
- func (a *Arr) Obj(index int) *Obj
- func (a *Arr) Pop() any
- func (a *Arr) Push(values ...any) (int, error)
- func (a *Arr) Set(index int, value any) error
- func (a *Arr) SetLen(length int)
- func (a *Arr) Shift() any
- func (a *Arr) Snapshot() []any
- func (a *Arr) Splice(start, remove int, items ...any) ([]any, error)
- func (a *Arr) Unshift(values ...any) (int, error)
- type Change
- type Obj
- func (o *Obj) Arr(key string) *Arr
- func (o *Obj) Delete(key string)
- func (o *Obj) Get(key string) any
- func (o *Obj) Has(key string) bool
- func (o *Obj) Keys() []string
- func (o *Obj) Len() int
- func (o *Obj) Lookup(key string) (any, bool)
- func (o *Obj) Obj(key string) *Obj
- func (o *Obj) Set(key string, value any) error
- func (o *Obj) Snapshot() *jv.Object
- type Op
- type Path
- type Prepared
- type Seg
- type Tracker
- type Verb
Constants ¶
This section is empty.
Variables ¶
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.
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.
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.
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 ¶
Apply applies one batch without mutating target. The result shares unchanged containers with target and adopts operation payloads without copying them.
func Overlap ¶
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) Push ¶
Push appends validated clones and returns the new length. When any value is not strict JSON nothing is inserted.
func (*Arr) Set ¶
Set places a validated clone of value at index; index may append one past the end.
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 ¶
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 ¶
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 ¶
Prepare materializes the candidate revision and its operations without changing authority. Every draft handle is unusable afterwards.
func (*Change) PrepareThen ¶
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.
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) Keys ¶
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.
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 ¶
DecodeOp decodes one stored operation tuple and checks its verb, arity and payload shape.
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 ¶
Base returns the revision the change started from, for an object root (nil for an array root; see BaseRoot).
func (*Prepared) BaseRevision ¶
BaseRevision returns the tracker revision the change started from.
func (*Prepared) BaseRoot ¶
BaseRoot returns the revision the change started from: a *jv.Object or a []any.
func (*Prepared) Ops ¶
Ops returns the exact operations that transform Base into Value. Payloads may be the same containers as parts of Value.
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 ¶
Track takes immutable ownership of an alias-free JSON root in O(1). The caller must never mutate initial again.
func TrackArray ¶
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 ¶
Adopt makes a prepared revision the tracker's latest and stales every competing change.
func (*Tracker) BeginChange ¶
BeginChange opens an overlay draft over the latest revision. The draft never modifies that revision.
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.