README
¶
record
github.com/dal-go/record
defines the small, persistence-neutral vocabulary for identifying records,
carrying record data, and describing changes to records.
It exists so API, rendering, command, and facade layers can depend on a stable
record model without importing database sessions, queries, transactions, or an
adapter. Database access belongs to
DALgo: DALgo accepts these values at its
boundary and executes a record.Changes
envelope through dal.ApplyChanges.
The module contains two packages:
recordfor identity, data, envelopes, and change batches.record/updatefor declarative field-update commands.
API
Every exported type and function is listed below. Links lead to its API documentation.
record
Errors
- Variables:
ErrNoError,ErrRecordNotFound,ErrRecordExists. - Functions:
IsNotFound,IsAlreadyExists.
Keys and composite IDs
- Types:
Key,KeyOption, andFieldVal. - Key constructors:
NewKeyWithID,NewKeyWithParentAndID,NewIncompleteKey,NewKeyWithFields, andNewKeyWithOptions. - Key options:
WithKeyID,WithStringID,WithIntID,WithFields, andWithParentKey. - Key helpers:
EscapeIDandEqualKeys. - Methods:
Key.String,Key.CollectionPath,Key.Level,Key.Parent,Key.Collection,Key.Validate,Key.Equal, andFieldVal.Validate.
Record envelopes
- Types:
Record,WithID, andDataWithID. - Constructors:
NewRecord,NewRecordWithData,NewRecordWithIncompleteKey,NewRecordWithoutKey,NewWithID, andNewDataWithID. - Helper:
AnyRecordWithError. - Method:
WithID.String.
Change envelopes and data mapping
- Types:
UpdatesandChanges. Changesmethods:RecordsToInsert,QueueForInsert, andReset.- Mapping functions:
DataToMapandMapToData.
record/update
- Types:
FieldPathandUpdate. - Functions:
ByFieldName,ByFieldPath,DeleteByFieldName, andDeleteByFieldPath. - Values:
DeleteFieldandServerTimestamp.
Documentation
¶
Index ¶
- Variables
- func AnyRecordWithError(records ...Record) error
- func DataToMap(data any) (map[string]any, error)
- func EqualKeys(k1, k2 *Key) bool
- func EscapeID(id string) string
- func IsAlreadyExists(err error) bool
- func IsNotFound(err error) bool
- func MapToData(target any, src map[string]any) error
- func ValidateStringID(id string) error
- type Changes
- type DataWithID
- type FieldVal
- type Key
- func NewIncompleteKey(collection string, idKind reflect.Kind, parent *Key) *Key
- func NewKeyWithFields(collection string, fields ...FieldVal) *Key
- func NewKeyWithID[T comparable](collection string, id T) *Key
- func NewKeyWithOptions(collection string, options ...KeyOption) (*Key, error)
- func NewKeyWithParentAndID[T comparable](parent *Key, collection string, id T) *Key
- type KeyOption
- type Record
- type Updates
- type WithID
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidStringID = errors.New("record: invalid string ID")
ErrInvalidStringID indicates that a string ID cannot be represented as one unambiguous non-empty key-path segment by EscapeID.
var ErrNoError = errors.New("no error")
ErrNoError is the internal success sentinel used by Record state.
var ErrRecordExists = errors.New("record already exists")
ErrRecordExists indicates that an insert failed because a record with the same key already exists. It is the mirror image of ErrRecordNotFound: an adapter that can reliably tell "this key is taken" from any other insert failure wraps this sentinel (e.g. with fmt.Errorf("%w: %s", ErrRecordExists, key)) so callers can distinguish the two with errors.Is or IsAlreadyExists, instead of having to treat every insert failure as a duplicate key.
var ErrRecordNotFound = errors.New("record not found")
ErrRecordNotFound indicates that a requested record does not exist.
Functions ¶
func AnyRecordWithError ¶
AnyRecordWithError returns the first non-not-found record error.
func DataToMap ¶
DataToMap converts record data into a map keyed by field name. A db tag takes precedence over a json tag at the top level.
func IsAlreadyExists ¶
IsAlreadyExists reports whether err represents a record that already exists. It positively identifies a duplicate-key conflict: true means the adapter itself classified this failure as one. False is NOT proof the failure was something else — an adapter that cannot yet distinguish a duplicate key from any other insert failure never returns ErrRecordExists, so it will report false here even on an actual conflict. Callers should use this predicate to detect a confirmed conflict, and keep treating an unclassified insert failure conservatively (i.e. not assume "not a conflict") until every adapter they rely on has adopted the sentinel.
func IsNotFound ¶
IsNotFound reports whether err represents a missing record.
func MapToData ¶
MapToData populates target from src. A db tag takes precedence over a json tag at the top level.
func ValidateStringID ¶
ValidateStringID verifies that EscapeID can represent id as one stable, unambiguous key-path segment. A literal percent sign is reserved because EscapeID uses percent-encoded substitutions; accepting it would make values such as "a/b" and "a%2Fb" serialize to the same path.
Types ¶
type Changes ¶
type Changes struct {
RecordsToUpdate []*Updates
RecordsToDelete []*Key
// contains filtered or unexported fields
}
Changes is an in-memory envelope of record mutations to be applied by a DAL facade.
func (*Changes) QueueForInsert ¶
QueueForInsert adds records to the insert queue.
func (*Changes) RecordsToInsert ¶
RecordsToInsert returns a copy of the queued insert records.
type DataWithID ¶
type DataWithID[K comparable, D any] struct { WithID[K] Data D }
DataWithID is a typed record envelope with strongly typed data.
func NewDataWithID ¶
func NewDataWithID[K comparable, D any](id K, key *Key, data D) DataWithID[K, D]
NewDataWithID creates a typed data envelope. data must be a non-nil pointer or interface holding a struct or map.
type Key ¶
Key represents the full identity path of a record.
func NewIncompleteKey ¶
NewIncompleteKey creates a key whose ID will be supplied later.
func NewKeyWithFields ¶
NewKeyWithFields creates a key with a composite ID.
func NewKeyWithID ¶
func NewKeyWithID[T comparable](collection string, id T) *Key
NewKeyWithID creates a key with id.
func NewKeyWithOptions ¶
NewKeyWithOptions creates a key configured by options.
func NewKeyWithParentAndID ¶
func NewKeyWithParentAndID[T comparable](parent *Key, collection string, id T) *Key
NewKeyWithParentAndID creates a key below parent with id.
func (*Key) CollectionPath ¶
CollectionPath returns the collection path of k.
type KeyOption ¶
KeyOption configures a Key during construction.
func WithFields ¶
WithFields sets composite key fields during construction.
func WithKeyID ¶
func WithKeyID[T comparable](id T) KeyOption
WithKeyID sets a key ID during construction.
func WithParentKey ¶
WithParentKey sets a parent key during construction.
func WithStringID ¶
WithStringID sets a string key ID during construction.
type Record ¶
type Record interface {
Key() *Key
Error() error
Exists() bool
SetError(error) Record
Data() any
HasChanged() bool
MarkAsChanged()
}
Record is a mutable envelope for record identity, data, and retrieval state.
func NewRecordWithData ¶
NewRecordWithData creates an envelope carrying data the caller already has.
The error is set to ErrNoError because the data was supplied, not retrieved: there is nothing to wait for, so Data() may be read immediately. This is the same reasoning NewRecordWithIncompleteKey already applies. Contrast NewRecord, which creates an empty envelope awaiting a load and deliberately leaves the error unset so Data() panics until a loader has said how the load went.
func NewRecordWithIncompleteKey ¶
NewRecordWithIncompleteKey creates an envelope for a record whose ID will be supplied later.
func NewRecordWithoutKey ¶
NewRecordWithoutKey creates an envelope for data that has no key.
type WithID ¶
type WithID[K comparable] struct { ID K `json:"id"` FullID string `json:"fullID,omitempty"` Key *Key `json:"-"` Record Record `json:"-"` }
WithID is a record envelope with a strongly typed ID.
Source Files
Directories