Documentation
¶
Overview ¶
Package countries supplies an ordinary typed country model and an explicitly invoked, versioned reference-data seeder. Construction never seeds a database.
Index ¶
- Constants
- Variables
- func Default(ctx context.Context, store *extensions.Store) (value.Optional[Country], error)
- func Exists(ctx context.Context, store *extensions.Store, code Code) (bool, error)
- func Find(ctx context.Context, store *extensions.Store, code Code) (value.Optional[Country], error)
- func Migrations() []migrate.Definition
- func Seeder(store *extensions.Store) seed.Definition
- func SetDefault(ctx context.Context, store *extensions.Store, code Code) error
- func StatusCodec() codec.Codec[Status]
- type Code
- type Country
- type CountryTable
- type Currency
- type SeedResult
- type Status
- func (Status) EnumDescriptor() enum.Descriptor[Status]
- func (v Status) IsValid() bool
- func (v Status) MarshalJSON() ([]byte, error)
- func (v Status) MarshalText() ([]byte, error)
- func (v *Status) Scan(source any) error
- func (v *Status) UnmarshalJSON(data []byte) error
- func (v *Status) UnmarshalText(data []byte) error
- func (v Status) Validate() error
- func (v Status) Value() (driver.Value, error)
Constants ¶
const ( MigrationOrigin migrate.Origin = "foundry.countries" CreateCountries migrate.ID = "000001_create_countries" SingleDefaultCountry migrate.ID = "000002_single_default_country" Introduced migrate.Version = "v0.1.0" )
const ( BuiltinVersion = "foundry-countries-v1" TimezoneVersion = "2026a" BuiltinCount = 250 )
const MaxCountries = 1000
const SeederID seed.ID = "foundry.countries"
Variables ¶
var Countries = orm.Define("foundry_countries", func(b orm.Builder[Country], m *Country) CountryTable { table := orm.TableOf(b, &m.ISO2) return CountryTable{Table: table, ISO2: table.Key(), ISO3: orm.TextOf(b, &m.ISO3), ISONumeric: orm.NullableTextOf(b, &m.ISONumeric), Name: orm.TextOf(b, &m.Name), OfficialName: orm.NullableTextOf(b, &m.OfficialName), Capital: orm.NullableTextOf(b, &m.Capital), Region: orm.NullableTextOf(b, &m.Region), Subregion: orm.NullableTextOf(b, &m.Subregion), Currencies: orm.JSONOf(b, &m.Currencies), PrimaryCurrencyCode: orm.NullableTextOf(b, &m.PrimaryCurrencyCode), CallingCode: orm.NullableTextOf(b, &m.CallingCode), CallingRoot: orm.NullableTextOf(b, &m.CallingRoot), CallingSuffixes: orm.JSONOf(b, &m.CallingSuffixes), TLDs: orm.JSONOf(b, &m.TLDs), Timezones: orm.JSONOf(b, &m.Timezones), Latitude: orm.NullableNumberOf(b, &m.Latitude), Longitude: orm.NullableNumberOf(b, &m.Longitude), Independent: orm.NullableColumnOf(b, &m.Independent), UNMember: orm.NullableColumnOf(b, &m.UNMember), FlagEmoji: orm.NullableTextOf(b, &m.FlagEmoji), Status: orm.EnumOf(b, &m.Status), ConversionRate: orm.NullableColumnOf(b, &m.ConversionRate), IsDefault: orm.ColumnOf(b, &m.IsDefault), ReferenceVersion: orm.TextOf(b, &m.ReferenceVersion), CreatedAt: orm.CreatedAtOf(b, &m.CreatedAt), UpdatedAt: orm.UpdatedAtOf(b, &m.UpdatedAt), } })
Countries owns the immutable Country declaration. Example: Countries.Query().First(ctx, tx).
Functions ¶
func Default ¶
Default returns the application's default country, if one is marked. The single-default migration guarantees at most one row.
func Migrations ¶
func Migrations() []migrate.Definition
Migrations returns the country table history. The second migration allows at most one default country. It refuses to guess when existing data already has several defaults: clear the extra is_default flags, then run it again.
func Seeder ¶
func Seeder(store *extensions.Store) seed.Definition
Seeder plugs into the ordinary explicit transactional seeder registry. It never installs itself, migrates tables, fetches data or runs during app boot.
func SetDefault ¶
SetDefault atomically moves the default flag to an existing country. The previous default is cleared first in the same transaction, so the unique single-default index never observes two defaults. A missing code returns database.NotFound and leaves the current default unchanged.
func StatusCodec ¶
StatusCodec applies the generated membership rule at both SQL boundaries.
Types ¶
type Code ¶
type Code string
Code is an uppercase alpha-2 country identifier, including user-assigned codes in the bundled reference. ParseCode normalizes explicit transport input.
type Country ¶
type Country struct {
ISO2 Code `foundry:"column=iso2"`
ISO3 string `foundry:"column=iso3"`
ISONumeric value.Nullable[string] `foundry:"column=iso_numeric"`
Name string
OfficialName value.Nullable[string]
Capital value.Nullable[string]
Region value.Nullable[string]
Subregion value.Nullable[string]
Currencies value.JSON[[]Currency]
PrimaryCurrencyCode value.Nullable[string]
CallingCode value.Nullable[string]
CallingRoot value.Nullable[string]
CallingSuffixes value.JSON[[]string]
TLDs value.JSON[[]string] `foundry:"column=tlds"`
Timezones value.JSON[[]string]
Latitude value.Nullable[float64]
Longitude value.Nullable[float64]
Independent value.Nullable[bool]
UNMember value.Nullable[bool] `foundry:"column=un_member"`
FlagEmoji value.Nullable[string]
Status Status
ConversionRate value.Nullable[decimal.Decimal]
IsDefault bool
ReferenceVersion string
// CreatedAt preserves an explicit creation time; omitted inserts use the application clock.
// Updates do not automatically change it. Example: Country{CreatedAt: createdAt}.
CreatedAt temporal.DateTime
// UpdatedAt is replaced by the application clock on writes, after before hooks and before field mutators.
// Explicit assignments do not override this management. Example: Countries.UpdatedAt.Desc().
UpdatedAt temporal.DateTime
}
Country uses an explicit ORM declaration with its natural primary key. Status, ConversionRate and IsDefault belong to the application; reference seeding never overwrites those fields on existing rows.
type CountryTable ¶
type CountryTable struct {
// Table provides Country queries and writes. Example: Countries.Query().Limit(10).
orm.Table[Country, Code]
// ISO2 binds the persisted Country.ISO2 column.
// Example: Countries.ISO2.Eq(iSO2).
ISO2 orm.Key[Country, Code]
// ISO3 binds the persisted Country.ISO3 column.
// Example: Countries.ISO3.Set(iSO3).
ISO3 orm.Text[Country, string]
// ISONumeric binds the persisted Country.ISONumeric column.
// Example: Countries.ISONumeric.SetNull().
ISONumeric orm.NullableText[Country, string]
// Name binds the persisted Country.Name column.
// Example: Countries.Name.Set(name).
Name orm.Text[Country, string]
// OfficialName binds the persisted Country.OfficialName column.
// Example: Countries.OfficialName.SetNull().
OfficialName orm.NullableText[Country, string]
// Capital binds the persisted Country.Capital column.
// Example: Countries.Capital.SetNull().
Capital orm.NullableText[Country, string]
// Region binds the persisted Country.Region column.
// Example: Countries.Region.SetNull().
Region orm.NullableText[Country, string]
// Subregion binds the persisted Country.Subregion column.
// Example: Countries.Subregion.SetNull().
Subregion orm.NullableText[Country, string]
// Currencies binds the persisted Country.Currencies column.
// Example: encoded, err := value.NewJSON(currencies); if err == nil { _ = Countries.Currencies.Set(encoded) }.
Currencies orm.JSON[Country, []Currency]
// PrimaryCurrencyCode binds the persisted Country.PrimaryCurrencyCode column.
// Example: Countries.PrimaryCurrencyCode.SetNull().
PrimaryCurrencyCode orm.NullableText[Country, string]
// CallingCode binds the persisted Country.CallingCode column.
// Example: Countries.CallingCode.SetNull().
CallingCode orm.NullableText[Country, string]
// CallingRoot binds the persisted Country.CallingRoot column.
// Example: Countries.CallingRoot.SetNull().
CallingRoot orm.NullableText[Country, string]
// CallingSuffixes binds the persisted Country.CallingSuffixes column.
// Example: encoded, err := value.NewJSON(callingSuffixes); if err == nil { _ = Countries.CallingSuffixes.Set(encoded) }.
CallingSuffixes orm.JSON[Country, []string]
// TLDs binds the persisted Country.TLDs column.
// Example: encoded, err := value.NewJSON([]string{".my"}); if err == nil { _ = Countries.TLDs.Set(encoded) }.
TLDs orm.JSON[Country, []string]
// Timezones binds the persisted Country.Timezones column.
// Example: encoded, err := value.NewJSON(timezones); if err == nil { _ = Countries.Timezones.Set(encoded) }.
Timezones orm.JSON[Country, []string]
// Latitude binds the persisted Country.Latitude column.
// Example: Countries.Latitude.SetNull().
Latitude orm.NullableNumber[Country, float64]
// Longitude binds the persisted Country.Longitude column.
// Example: Countries.Longitude.SetNull().
Longitude orm.NullableNumber[Country, float64]
// Independent binds the persisted Country.Independent column.
// Example: Countries.Independent.SetNull().
Independent orm.NullableColumn[Country, bool]
// UNMember binds the persisted Country.UNMember column.
// Example: Countries.UNMember.SetNull().
UNMember orm.NullableColumn[Country, bool]
// FlagEmoji binds the persisted Country.FlagEmoji column.
// Example: Countries.FlagEmoji.SetNull().
FlagEmoji orm.NullableText[Country, string]
// Status binds the persisted Country.Status column.
// Example: Countries.Status.Set(status).
Status orm.Enum[Country, Status]
// ConversionRate binds the persisted Country.ConversionRate column.
// Example: Countries.ConversionRate.SetNull().
ConversionRate orm.NullableColumn[Country, decimal.Decimal]
// IsDefault binds the persisted Country.IsDefault column.
// Example: Countries.IsDefault.Set(isDefault).
IsDefault orm.Column[Country, bool]
// ReferenceVersion binds the persisted Country.ReferenceVersion column.
// Example: Countries.ReferenceVersion.Set(referenceVersion).
ReferenceVersion orm.Text[Country, string]
// CreatedAt preserves an explicitly assigned creation time; when omitted on insert, the ORM uses the application clock.
// The insert default is applied after before hooks and before field mutators; updates do not automatically change it.
// Example: Countries.CreatedAt.Set(createdAt).
CreatedAt orm.CreatedAt[Country, temporal.DateTime]
// UpdatedAt is managed: writes replace assigned or omitted values with the application clock after before hooks and before field mutators.
// Example: Countries.UpdatedAt.Desc().
UpdatedAt orm.UpdatedAt[Country, temporal.DateTime]
}
CountryTable binds the persisted Country columns. Example: Countries.Query().Limit(10).
type SeedResult ¶
func Seed ¶
func Seed(ctx context.Context, store *extensions.Store) (SeedResult, error)
func SeedIn ¶
func SeedIn(ctx context.Context, tx *database.Tx, store *extensions.Store) (SeedResult, error)
SeedIn joins the caller's exact pool/transaction under an isolated savepoint. A successful result is provisional until the parent transaction commits.
type Status ¶
type Status string
func ParseStatus ¶
ParseStatus decodes and validates an enum's text representation.
func StatusValues ¶
func StatusValues() []Status
StatusValues returns declared values in source order, with independent slice ownership.
func (Status) EnumDescriptor ¶
func (Status) EnumDescriptor() enum.Descriptor[Status]
EnumDescriptor describes this enum type independently of the receiver's value.
func (Status) IsValid ¶
IsValid checks membership; a Go cast alone does not validate external values.
func (Status) MarshalJSON ¶
func (Status) MarshalText ¶
func (*Status) Scan ¶
Scan changes the receiver only after successful decoding. SQL NULL is rejected.