config

type Entry ¶

type Entry struct {
	Name   string
	Source string
	Secret bool
}

Entry records provenance without storing or formatting a setting's value.

type Field ¶

type Field[T any] interface {
	// contains filtered or unexported methods
}

Field is a sealed typed setting declaration, normally generated from a feature's settings type. It does not expose untyped getters to consumers.

type Inputs ¶

type Inputs[T any] struct {
	Files       []Values
	Environment Lookup
	Environ     func() []string
	Prefix      string
	Overrides   []Override[T]
	Validate    func(T) error
}

Inputs always applies files in order, then environment, then typed overrides. Environment names use PREFIX__SECTION__FIELD for a section.field declaration. NAME_FILE instead reads the value from the named regular file (at most MaxTableBytes, one trailing newline removed); setting both is an error.

Environ, such as os.Environ, additionally enables per-entry overrides inside named collections: PREFIX__SERVICES__DATABASE__CONNECTIONS__MAIN__PRIMARY__PASSWORD sets primary.password of entry "main" (entry names of lowercase letters, digits and single underscores). They merge into the collection supplied by a file or the collection's own variable, or create entries in an empty one, then decode through the same element schema. _FILE applies to them too.

type Key ¶

type Key[T, V any] struct {
	// contains filtered or unexported fields
}

Key couples a configuration identifier to its concrete Go field and decoder. The field accessor is compiler-checked; no reflection-based field-name lookup or automatic dependency injection is performed.

func Bool[T any](name string, field func(*T) *bool) Key[T, bool]

func Duration[T any](name string, field func(*T) *time.Duration) Key[T, time.Duration]

func Enum[T any, V enum.Scalar](name string, field func(*T) *V, descriptor enum.Descriptor[V]) Key[T, V]

func Int[T any](name string, field func(*T) *int) Key[T, int]

func JSON[T, V any](name string, field func(*T) *V) Key[T, V]

func NewKey[T, V any](name string, field func(*T) *V, parse func(string) (V, error)) Key[T, V]

func Scalar[T any, V ScalarValue](name string, field func(*T) *V) Key[T, V]

func Secret[T any](name string, field func(*T) *secret.String) Key[T, secret.String]

func String[T any](name string, field func(*T) *string) Key[T, string]

func Text[T, V any, P interface {
	*V
	encoding.TextUnmarshaler
}](name string, field func(*T) *V) Key[T, V]

func (k Key[T, V]) Name() string

func (k Key[T, V]) Sensitive() Key[T, V]

func (k Key[T, V]) Set(value V) Override[T]

type Lookup ¶

type Lookup func(string) (string, bool)

Lookup matches os.LookupEnv and is injectable for deterministic tests.

type Override ¶

type Override[T any] struct {
	// contains filtered or unexported fields
}

Override is produced by Key.Set, preserving the value type at the call site.

type PublicKind ¶ added in v0.3.0

type PublicKind string

PublicKind classifies the browser validation and decoding applied to a public setting.

const (
	PublicString       PublicKind = "string"
	PublicBoolean      PublicKind = "boolean"
	PublicNumber       PublicKind = "number"
	PublicLocale       PublicKind = "locale"
	PublicFormatLocale PublicKind = "format_locale"
	PublicCurrency     PublicKind = "currency"
	PublicTimeZone     PublicKind = "time_zone"
	PublicEnum         PublicKind = "enum"
)

func (k PublicKind) Validate() error

type PublicSetting ¶ added in v0.3.0

type PublicSetting struct {
	Name        string     `json:"name"`
	Env         string     `json:"env"`
	Description string     `json:"description,omitempty"`
	Fallback    string     `json:"fallback,omitzero"`
	Optional    bool       `json:"optional,omitempty"`
	Kind        PublicKind `json:"kind"`
	MaxLength   int        `json:"max_length,omitzero"`
	EnumCases   []string   `json:"enum_cases,omitempty"`
}

PublicSetting is a browser-visible configuration setting declared in Go. Optional settings decode missing or blank browser values as undefined and cannot declare a non-empty fallback.

type Report ¶

type Report struct {
	// contains filtered or unexported fields
}

Report is immutable provenance, suitable for diagnostics without credentials.

func (r Report) Entries() []Entry

type ScalarValue ¶

type ScalarValue interface {
	~string | ~bool | ~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64
}

ScalarValue preserves named Go scalar types at the configuration boundary. Complex numbers, pointers and machine addresses are not configuration values.

type Schema ¶

type Schema[T any] struct {
	// contains filtered or unexported fields
}

Schema owns validated, ordered field declarations. It is safe for concurrent Load calls provided caller-supplied accessors/decoders are themselves safe.

func New[T any](fields ...Field[T]) (*Schema[T], error)

func (s *Schema[T]) Load(defaults T, inputs Inputs[T]) (result T, report Report, err error)

func (s *Schema[T]) Names() []string

func (s *Schema[T]) WithinNamespace(namespace string) error

type Values ¶

type Values struct {
	Name string
	Data map[string]string
}

Values is the text-value boundary implemented by file format adapters. Values use declared setting names; unknown file entries are errors, never ignored.

func DecodeObject[T any](object map[string]any, schema *Schema[T], source string) (Values, error)