Documentation
¶
Overview ¶
Package model defines model-owned foundational values without depending on a database driver or runtime. Generated model APIs build on these contracts.
Index ¶
- Constants
- type ID
- type Identifiable
- type Identity
- func (Identity) Format(state fmt.State, _ rune)
- func (i Identity) IsZero() bool
- func (i Identity) KeyJSON() (string, error)
- func (i Identity) MarshalJSON() ([]byte, error)
- func (i Identity) ModelName() string
- func (i *Identity) UnmarshalJSON(data []byte) error
- func (i Identity) Validate() error
- func (i Identity) WithModelName(name string) (Identity, error)
- type KeyCodec
- type MorphName
- type Morphable
- type Reference
- func (Reference[M, K]) Format(state fmt.State, _ rune)
- func (r Reference[M, K]) Identity() (Identity, error)
- func (r Reference[M, K]) Key() K
- func (r Reference[M, K]) ModelName() string
- func (r Reference[M, K]) Parse(identity Identity) (Reference[M, K], error)
- func (r Reference[M, K]) Validate() error
Constants ¶
const MaxIdentityKeyBytes = 4096
MaxIdentityKeyBytes bounds the encoded SQL key, including its kind and JSON envelope. It limits attribution metadata, not database column capacity.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ID ¶
type ID[M any] struct { // contains filtered or unexported fields }
ID is a comparable UUID whose owner is checked by the Go compiler. The zero value is the nil UUID, not a newly generated identity. M need not be comparable. Bytes/ParseID are explicit serialization boundaries that discard/reapply owner information; they do not establish record existence or authorization.
func IDFromBytes ¶
IDFromBytes is the explicit binary decoding boundary.
func NewIDAt ¶
NewIDAt generates a UUIDv7 from an explicit clock reading and 74 random bits, following RFC 9562 section 5.7. Ordering within a millisecond, across clock rollback, or across hosts is not guaranteed. IDs are not authentication secrets.
func ParseID ¶
ParseID accepts exactly the canonical 8-4-4-4-12 hexadecimal UUID shape, case-insensitively. Existing UUID versions and the nil UUID are preserved.
func (ID[M]) MarshalText ¶
MarshalText encodes the identifier's UUID string as text.
func (*ID[M]) UnmarshalJSON ¶
UnmarshalJSON decodes a JSON identifier, replacing the receiver only on success.
func (*ID[M]) UnmarshalText ¶
UnmarshalText parses an identifier, replacing the receiver only on success.
type Identifiable ¶
type Identifiable interface {
// FoundryIdentity returns the model's persistence identity.
FoundryIdentity() (Identity, error)
}
Identifiable is implemented by generated model metadata. Framework adapters capture the stored identity without another database lookup or an Actor.
type Identity ¶
type Identity struct {
// contains filtered or unexported fields
}
Identity is immutable serialized model attribution. Model/key types are erased only at this explicit transport boundary. Received metadata grants no authority. Routine formatting omits the key; JSON deliberately exports it.
func ParseIdentity ¶
ParseIdentity validates an explicit model namespace and tagged SQL key JSON. Generated references perform the typed restoration; parsing alone grants no trust. Scalar Go JSON and presentation values are not accepted as stored keys.
func (Identity) KeyJSON ¶
KeyJSON exports the tagged SQL key for a deliberate storage/transport boundary. The kind and exact text preserve integers, bytes and times without JSON number rounding. Ordinary application code uses the concrete Reference.Key value.
func (Identity) MarshalJSON ¶
MarshalJSON validates and encodes the model identity as JSON.
func (*Identity) UnmarshalJSON ¶
UnmarshalJSON decodes a bounded JSON identity, replacing the receiver only after key normalization succeeds.
func (Identity) Validate ¶
Validate checks the model name and bounded key and requires a canonical identity representation.
func (Identity) WithModelName ¶
WithModelName returns the same stored key attributed to another model name. It is the explicit boundary for a declared storage identity that predates a table rename; parsing still decodes the key through the expected codec.
type KeyCodec ¶
type KeyCodec[K any] interface { // Bind converts a typed key to a database driver value. Bind(K) (driver.Value, error) // Decode decodes a database value into a typed key. Decode(any) (K, error) }
KeyCodec is the small persistence boundary implemented by database codecs. Generated references reuse the primary field's existing codec. Custom codecs must be pure, safe for concurrent use, and return owned decoded values.
type MorphName ¶
type MorphName string
MorphName is the stored discriminator naming one model in polymorphic relationships. Store it in a model field of this type.
type Morphable ¶
type Morphable interface {
// MorphName returns the model's polymorphic name.
MorphName() MorphName
}
Morphable is implemented by a model that takes part in polymorphic relationships. Declaring the name once on the model is the typed morph map: relationship constructors read it from the model type, so call sites never pass discriminator strings.
func (Post) MorphName() model.MorphName { return "post" }
type Reference ¶
type Reference[M, K any] struct { // contains filtered or unexported fields }
Reference retains a model and its concrete stored primary-key type. Generated FoundryReference methods supply its table, key and codec without calling getters. A reference does not hydrate a model or establish existence or authorization.
func NewReference ¶
NewReference is the explicit generated metadata boundary. Applications normally obtain references from a model's FoundryReference method rather than repeating names or codecs. Identity freezes the key when transport metadata is needed.
func (Reference[M, K]) Identity ¶
Identity snapshots only the stored key through its database codec. Read getters and presentation JSON marshalers do not run. Custom codec failures are isolated without exposing panic payloads. SQL NULL is never a valid identity.
func (Reference[M, K]) Key ¶
func (r Reference[M, K]) Key() K
Key returns the reference's typed key.
func (Reference[M, K]) Parse ¶
Parse restores a serialized identity using this reference's expected model and primary-key codec. Its current key is ignored. At a transport boundary use a generated zero model's FoundryReference().Parse(identity); no lookup occurs. Parsing validates metadata, never authentication, authorization or existence.
Source Files