README
¶
Lifecycle registrations
CountObservers[M](set) returns a RegistrationCounts value with Write,
Retrieval and DeletionOnly integer counts for exactly M. Inspection does not
construct callbacks or expose adapter types, factories or capabilities. Changing
the returned value cannot change registrations. Counts remain available through
rows.Observers() after row closure. Counting set.ForDeletion() describes that
merged view: Write includes deletion-only registrations and DeletionOnly is zero.
Documentation
¶
Overview ¶
Package lifecycle defines typed model lifecycle data shared by generated hooks, observers and audit integrations.
Index ¶
- func HasDeletionObservers[M any](set Observers) bool
- func HasObservers[M any](set Observers) bool
- func HasRetrievalObservers[M any](set Observers) bool
- func ObserverFactories[M, H any](set Observers) ([]func() H, error)
- func RetrievalObserverFactories[M, H any](set Observers) ([]func() H, error)
- type Declaration
- type FieldChange
- func CompareField[V any](c codec.Codec[V], before, after value.Optional[V], assigned bool) (FieldChange[V], error)
- func CompareFieldPolicy[V any](policy FieldPolicy[V], before, after value.Optional[V], assigned bool) (FieldChange[V], error)
- func CompareModelField[M, V any](c codec.Codec[V], before, after value.Optional[M], assigned bool, ...) (FieldChange[V], error)
- type FieldPolicy
- type Observer
- type Observers
- type Operation
- type RegistrationCounts
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasDeletionObservers ¶
HasDeletionObservers reports registrations that observe deletions of exactly M: write observers and deletion observers.
func HasObservers ¶
HasObservers reports write registrations for exactly M without invoking factories. A retrieval-only model does not enter the write-hook pipeline.
func HasRetrievalObservers ¶
HasRetrievalObservers reports retrieval registrations for exactly M without constructing either retrieval or write hooks.
func ObserverFactories ¶
ObserverFactories supplies independent typed write factories to an adapter. Callers invoke factories inside the owning operation, never during metadata inspection. Requesting an incompatible hook type fails before any callback.
func RetrievalObserverFactories ¶
RetrievalObserverFactories supplies only typed retrieval factories. It never instantiates or returns write factories, including for a model with both kinds. The returned slice is independent of the immutable registry.
Types ¶
type Declaration ¶
type Declaration struct {
// contains filtered or unexported fields
}
Declaration holds an opaque, typed model/factory pair for database assembly. Construct declarations through Observer.Declare; the zero value is invalid.
type FieldChange ¶
type FieldChange[V any] struct { // contains filtered or unexported fields }
FieldChange preserves one field's snapshots and distinguishes assignment from a change in its stored value. An absent snapshot means the model did not exist; a present Nullable value can independently represent a NULL field. The zero FieldChange contains no snapshots and does not represent a completed write. Values follow their codec's ownership policy. Built-in binary fields own their buffers; custom values containing references must be treated as read-only.
func CompareField ¶
func CompareField[V any](c codec.Codec[V], before, after value.Optional[V], assigned bool) (FieldChange[V], error)
CompareField constructs change data from stored snapshots, using the field's codec for validation and canonical comparison. It never runs write mutators, read accessors or database operations. Generated lifecycle adapters supply the locked original and fully hydrated write result, with the effective assignment flag. Creation/deletion changes existence even for a NULL field; an assignment whose canonical value is unchanged still reports Assigned.
At least one snapshot is required. A deletion cannot assign a value. Codecs must bind canonical finite driver scalars, byte buffers or timestamps. Interval codecs preserve calendar components; SQL relation-key equality is deliberately a separate contract. A failure returns no partial change data.
func CompareFieldPolicy ¶
func CompareFieldPolicy[V any](policy FieldPolicy[V], before, after value.Optional[V], assigned bool) (FieldChange[V], error)
CompareFieldPolicy reuses declared codec metadata without reconstructing a codec. Its snapshots and errors follow CompareField. Example: CompareFieldPolicy(policy, value.Set(before), value.Set(after), true).
func CompareModelField ¶
func CompareModelField[M, V any](c codec.Codec[V], before, after value.Optional[M], assigned bool, get func(M) V) (FieldChange[V], error)
CompareModelField is a generated declaration boundary. One concrete M owns both snapshots and the persisted-field getter, and V owns the codec and change result. The getter must only extract its persisted field, without I/O or read accessors. Generated model comparisons enumerate these declarations.
func (FieldChange[V]) After ¶
func (c FieldChange[V]) After() value.Optional[V]
After returns the optional post-write snapshot using the field's clone policy when present.
func (FieldChange[V]) Assigned ¶
func (c FieldChange[V]) Assigned() bool
Assigned reports whether the field was effectively assigned during the write.
func (FieldChange[V]) Before ¶
func (c FieldChange[V]) Before() value.Optional[V]
Before returns the optional pre-write snapshot using the field's clone policy when present.
func (FieldChange[V]) Changed ¶
func (c FieldChange[V]) Changed() bool
Changed reports whether stored value or model existence changed.
func (FieldChange[V]) GoString ¶
func (c FieldChange[V]) GoString() string
GoString returns a fixed label without exposing snapshot values.
func (FieldChange[V]) String ¶
func (FieldChange[V]) String() string
String and GoString keep snapshot values out of routine diagnostics.
type FieldPolicy ¶
type FieldPolicy[V any] struct { // contains filtered or unexported fields }
FieldPolicy is immutable codec comparison and snapshot ownership metadata. Its zero value is invalid. Example: policy := FieldPolicyOf(codec.Bytes[[]byte]()).
func FieldPolicyOf ¶
func FieldPolicyOf[V any](c codec.Codec[V]) FieldPolicy[V]
FieldPolicyOf retains the original codec's binding, equality and ownership. It constructs no representation adapter. Example: FieldPolicyOf(codec.String[string]()).
type Observer ¶
type Observer[M, H any] struct { // contains filtered or unexported fields }
Observer identifies one model-owned hook factory. M and H retain the concrete model and its hook declaration at the adapter boundary. Names are semantic identifiers, unique within a database's observer set.
func NewDeletionObserver ¶
NewDeletionObserver declares a write factory that observes only deletions: delete, soft delete and force delete. Other writes neither construct it nor take the hooked path because of it, and set-based writes other than deletions need no WithoutModelHooks for it. Its hooks share the model's write hook type; only their deletion callbacks run.
func NewObserver ¶
NewObserver declares a factory for a model's normal write pipeline.
func NewRetrievalObserver ¶
NewRetrievalObserver declares a separate factory for complete-model reads. It shares database registration and naming rules with write observers but is excluded from write lookup. Declaration and inspection never invoke factories.
func (Observer[M, H]) Declare ¶
func (o Observer[M, H]) Declare(factory func() H) (Declaration, error)
Declare retains a factory without invoking it. The factory creates fresh operation-local hooks at dispatch; captured application services must be safe for concurrent operations. A declaration is immutable after construction.
type Observers ¶
type Observers struct {
// contains filtered or unexported fields
}
Observers is an immutable set of explicitly declared factories, grouped by exact model type and write/retrieval/deletion kind, retaining declaration order within each group. Its zero value is empty. It holds no mutable registration API or process-global application state.
func NewObservers ¶
func NewObservers(declarations ...Declaration) (Observers, error)
NewObservers validates the complete set before publication. It neither runs hook factories nor retains the caller's declaration slice. Duplicate names and conflicting hook types for one model/kind fail without a partial result. Write and retrieval factories for the same model may have different types.
func (Observers) ForDeletion ¶
ForDeletion is the set a deletion dispatches: write observers joined by deletion observers. Other writes use the set itself, which excludes them.
type Operation ¶
type Operation uint8
Operation identifies a normal model write. Bulk statements have separate semantics and do not dispatch per-model hooks.
type RegistrationCounts ¶
type RegistrationCounts struct {
// Write counts ordinary write registrations. Example: counts.Write == 2.
Write int
// Retrieval counts complete-model read registrations. Example: counts.Retrieval == 1.
Retrieval int
// DeletionOnly counts registrations restricted to deletion operations.
// Example: counts.Write + counts.DeletionOnly is the deletion dispatch count.
DeletionOnly int
}
RegistrationCounts is an owned value containing registration counts only. It cannot dispatch callbacks or identify their adapters. Example: counts.Write == 2.
func CountObservers ¶
func CountObservers[M any](set Observers) RegistrationCounts
CountObservers inspects exactly M without invoking or exposing factories. The zero set has zero counts. It describes the supplied view: ForDeletion merges deletion-only registrations into Write and leaves DeletionOnly zero. Example: counts := lifecycle.CountObservers[Order](rows.Observers()).
Source Files