model

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package model defines wowapi's base model primitives: embeddable structs for identity, tenancy, audit, versioning, temporal validity, and status; plus kernel-wide value objects for money, references, and time ranges.

Composition rules and anti-patterns are specified in docs/blueprint/04-project-and-primitives.md §3. The key principle is composition over a god BaseModel — each entity embeds only the structs whose corresponding columns it actually carries.

Import boundary: stdlib + github.com/google/uuid + github.com/shopspring/decimal only. This package is at the base of the dependency graph; adding anything else here pulls it into every consumer.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActorKind 

type ActorKind string

ActorKind identifies the kind of principal performing an action. 

const (
	// KindUser represents a human user principal.
	KindUser ActorKind = "user"
	// KindSystem represents an automated system principal.
	KindSystem ActorKind = "system"
)

type ActorRef 

type ActorRef struct {
	Kind       ActorKind
	UserID     uuid.UUID
	CapacityID uuid.UUID
	System     string
}

ActorRef identifies who performed an action. Only one of UserID, CapacityID, or System is meaningful for a given Kind; the others carry zero values.

type Auditable 

type Auditable struct {
	CreatedAt time.Time  `db:"created_at"`
	CreatedBy uuid.UUID  `db:"created_by"`
	UpdatedAt *time.Time `db:"updated_at"`
	UpdatedBy *uuid.UUID `db:"updated_by"`
}

Auditable records who created and last modified a row. Embed in mutable entities. NOT for append-only rows — use CreatedOnly there.

type BaseFields 

type BaseFields struct {
	ID uuid.UUID `db:"id"`
}

BaseFields carries identity only. Embed in every persisted entity.

type CreatedOnly 

type CreatedOnly struct {
	CreatedAt time.Time `db:"created_at"`
	CreatedBy uuid.UUID `db:"created_by"`
}

CreatedOnly is the append-only variant of Auditable. Once a row is inserted its authorship is immutable; there is no UpdatedAt/UpdatedBy column.

type ExternalRef 

type ExternalRef struct {
	System string
	ID     string
}

ExternalRef is a pointer into an external system (e.g. Stripe, Salesforce).

type IDGen 

type IDGen interface {
	New() uuid.UUID
}

IDGen produces primary keys. Injected everywhere IDs are minted so tests can run deterministic sequences (docs/blueprint/03 §1: UUIDv7, app-generated).

func UUIDv7 

func UUIDv7() IDGen

UUIDv7 returns the production generator (time-ordered UUIDv7).

type Metadata 

type Metadata map[string]any

Metadata is a schema-free extension bag for module-declared display extras. It must never drive core logic — the moment code branches on a key, promote that key to a typed column.

type Money 

type Money struct {
	Amount   decimal.Decimal
	Currency string
}

Money is an exact monetary amount. Amount uses shopspring/decimal to avoid floating-point error. The DB representation is numeric + char(3).

type ResourceRef 

type ResourceRef struct {
	Type string
	ID   uuid.UUID
}

ResourceRef is a kernel-wide pointer to any domain object. It is used wherever code must reference an entity without importing that entity's package.

type Statused 

type Statused[S ~string] struct {
	Status S `db:"status"`
}

Statused carries a lifecycle status using a typed string constant. Embed instead of soft-delete booleans; status vocabulary is per-entity.

type Temporal 

type Temporal struct {
	ValidFrom time.Time  `db:"valid_from"`
	ValidTo   *time.Time `db:"valid_to"`
}

Temporal carries a validity window for history-aware rows (assignments, relationships, grants). Only embed where "as-of" queries are a real requirement — every temporal table pays query complexity forever.

func (Temporal) ActiveAt 

func (t Temporal) ActiveAt(at time.Time) bool

ActiveAt reports whether the temporal row is active at the given instant.

Boundary semantics: at == ValidFrom is active; at == ValidTo is NOT active (half-open interval [ValidFrom, ValidTo)).

type TenantScoped 

type TenantScoped struct {
	TenantID uuid.UUID `db:"tenant_id"`
}

TenantScoped marks an entity as tenant-owned. Repo helpers key on the presence of this struct — an entity without it cannot use TenantDB write helpers.

type TimeRange 

type TimeRange struct {
	From time.Time
	To   *time.Time
}

TimeRange is a half-open time interval [From, To). To == nil means open-ended.

type Versioned 

type Versioned struct {
	Version int `db:"version"`
}

Versioned supports optimistic locking. Embed in user-editable aggregates. Anti-pattern: embedding on append-only tables or high-frequency counters.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.