Documentation
¶
Overview ¶
Package settings provides typed access to protobuf-backed settings.
Product code works exclusively with generated protobuf messages and typed Field values. JSON is an implementation detail of the persistence boundary.
Index ¶
- Constants
- Variables
- type Field
- func MustBool[M proto.Message](prototype M, path string, defaultValue bool) Field[M, bool]
- func MustEnum[M proto.Message, E ~int32](prototype M, path string, defaultValue E) Field[M, E]
- func MustInt32[M proto.Message](prototype M, path string, defaultValue int32) Field[M, int32]
- func MustInt64[M proto.Message](prototype M, path string, defaultValue int64) Field[M, int64]
- func MustString[M proto.Message](prototype M, path, defaultValue string) Field[M, string]
- func (field Field[M, T]) ApplyDefault(message M) (bool, error)
- func (field Field[M, T]) Clear(message M) error
- func (field Field[M, T]) Default() T
- func (field Field[M, T]) Get(message M) (T, error)
- func (field Field[M, T]) Has(message M) (bool, error)
- func (field Field[M, T]) Lookup(message M) (T, bool, error)
- func (field Field[M, T]) Path() string
- func (field Field[M, T]) Set(message M, value T) error
- type JSONCodec
Constants ¶
const DefaultMaximumJSONBytes = 128 * 1024
Variables ¶
var ErrNilMessage = errors.New("settings message is nil")
Functions ¶
This section is empty.
Types ¶
type Field ¶
Field is a typed path from a generated protobuf settings message M to a scalar value T. Paths are resolved and validated once when the field catalog is initialized. Set materializes missing parent messages automatically.
func MustEnum ¶
MustEnum defines an optional enum settings field. E is the generated enum type (whose underlying type is int32). Set rejects values unknown to the field's enum descriptor.
func MustString ¶
MustString defines an optional string settings field and panics when the path is invalid. Field catalogs should be package-level values so schema mistakes fail during process initialization rather than on a request.
func (Field[M, T]) ApplyDefault ¶ added in v0.1.60
ApplyDefault writes the configured default only when the field is absent. It returns true when the message changed. Existing values, including explicit false, empty string, zero, or the zero enum, are never overwritten.
func (Field[M, T]) Clear ¶
Clear removes a value. Empty parent messages created solely for the cleared path are pruned, so ProtoJSON does not persist meaningless {"parent": {}}.
func (Field[M, T]) Default ¶ added in v0.1.60
func (field Field[M, T]) Default() T
Default returns the field's configured fallback value.
func (Field[M, T]) Get ¶
Get returns the explicitly stored value, or the field's configured default when the field or any of its parent messages is absent.
func (Field[M, T]) Lookup ¶
Lookup returns the value and its protobuf presence. An explicit scalar zero (false, "", 0, or the zero enum) remains distinguishable from an unset field when the schema declares presence, as settings protos should.
type JSONCodec ¶
JSONCodec is the only conversion boundary between typed protobuf settings and their JSONB representation. UseProtoNames keeps persisted keys stable across Go and TypeScript, while DiscardUnknown allows safe rolling schema removal without deleting older keys from the database.
Source Files