README
¶
delta
Change-tracking containers. delta.Slice[T] wraps a []T and records which elements were Added and Deleted relative to its starting state, so a caller can compute and apply a minimal diff. Part of rosetta.
What matters here
- Only
Valuesis serialized;AddedandDeletedare transient. Both carryjson:"-" bson:"-"tags — the diff bookkeeping exists only for the lifetime of the in-memory object and is intentionally not persisted. A round-trip through JSON/BSON yields aSlicewith the current values but an empty change set, as if freshly constructed. SetValue(any)is the schema-integration seam (it satisfies theValueSetterinterface used by schema). It accepts a generic value and coerces it into[]T; that is why the element type is constrained tocomparable(membership checks drive the Added/Deleted tracking).SetValuemust never assume it is handed a[]T. Multi-value form widgets (multiselect, check-button-group) post a*sliceof.String, because that is the only shape satisfying theArrayGetterSettervalidation thatschema.validate_Arrayrequires. Conversion is delegated toconvert.SliceOfOk[T], which unwraps pointers, named slice types, andconvert.ArrayGettervalues; a strict type assertion here silently discarded every multiselect write for six weeks.- Conversion is as loose as the
convertpackage allows, including LOSSY.SetValuediscards convert's lossless flag, soSlice[string]handed3.14159stores["3.14"]. The flip side: aSlice[int]handed"not a number"stores[0]rather than erroring. Only a value that is not a collection at all — a struct, a map, a channel — is an error, checked up front withconvert.SliceOfAnyOkso that a rejected write cannot emptyValuesand fillDeleted. - A value that cannot be read leaves the Slice untouched. Coercion completes before any state is written, so a failed
SetValuecannot emptyValuesand fillDeleted— which would read downstream as "the user removed everything." Valuesis copied, not aliased. The incoming slice arrives straight from aurl.Valuesentry that the caller still owns.UnmarshalJSONparses untrusted input and is fuzzed (FuzzSliceUnmarshalJSON). When changing the unmarshal path, keep that fuzzer green — it guards against panics on malformed JSON.
Documentation
¶
Overview ¶
Package delta provides collection types that track their own changes.
A delta.Slice[T] wraps an ordinary []T and records which elements have been added and which have been deleted relative to the values it started with, so a caller can compute a minimal diff and apply only what actually moved. The element type is constrained to comparable because membership checks are what drive that bookkeeping.
Only the values are serialized. The Added and Deleted sets are marked json:"-" and bson:"-" on purpose: they describe one in-memory editing session, not durable state, so a value that round-trips through storage comes back with its current contents and an empty change set.
SetValue is the seam that the schema package writes through, and it converts whatever it is handed rather than asserting a []T: form widgets deliver array values as a *sliceof.String, and several other shapes are possible besides. The conversion is delegated to convert.SliceOfOk, so it is as forgiving as that package allows -- lossy renderings included -- and only a value that is not a collection at all is reported, without disturbing the slice.
Index ¶
- type Slice
- func (s Slice[T]) GetIndex(index int) (any, bool)
- func (s Slice[T]) GetValue() any
- func (s Slice[T]) IsChanged() bool
- func (s Slice[T]) Length() int
- func (s Slice[T]) MarshalJSON() ([]byte, error)
- func (s *Slice[T]) Reset()
- func (s *Slice[T]) SetIndex(index int, value any) bool
- func (s *Slice[T]) SetValue(value any) error
- func (s Slice[T]) Unchanged() []T
- func (s *Slice[T]) UnmarshalJSON(data []byte) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Slice ¶
type Slice[T comparable] struct { Values []T `json:"values" bson:"values"` Added []T `json:"-" bson:"-"` Deleted []T `json:"-" bson:"-"` }
Slice tracks changes to a slice of generic values. As items are added or removed from the slice, they are tracked in the "Added" and "Deleted" lists.
func NewSlice ¶
func NewSlice[T comparable](values ...T) Slice[T]
NewSlice returns a fully initialized Slice object
func (Slice[T]) GetIndex ¶ added in v0.29.0
GetIndex implements schema.ArrayGetter, returning the value at the provided index and TRUE, or (nil, false) if the index is out of range.
func (Slice[T]) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface and serializes the Slice into a JSON array
func (*Slice[T]) SetIndex ¶ added in v0.29.0
SetIndex implements schema.ArraySetter, storing a value at the provided index (growing the slice to fit if necessary) and tracking any newly-added value. Returns FALSE if the value is not assignable to the slice's element type.
func (*Slice[T]) SetValue ¶
SetValue implements schema.ValueSetter and updates the current value, tracking changes to the added and deleted lists.
func (Slice[T]) Unchanged ¶ added in v0.25.4
func (s Slice[T]) Unchanged() []T
Unchanged returns the values that have not been added or removed
func (*Slice[T]) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface and deserializes the Slice from a JSON array
Source Files