Why Go
- Case Studies
  
  Common problems companies solve with Go
- Use Cases
  
  Stories about how and why companies use Go
- Security
  
  How Go can help keep you secure by default
Learn
Docs
- Effective Go
  
  Tips for writing clear, performant, and idiomatic Go code
- Go User Manual
  
  A complete introduction to building software with Go
- Standard library
  
  Reference documentation for Go's standard library
- Release Notes
  
  Learn what's new in each Go release
- API
  
  Reference documentation for the pkg.go.dev API
Packages
Community
- Recorded Talks
  
  Videos from prior events
- Meetups
  
  Meet other local Go developers
- Conferences
  
  Learn and network with Go developers from around the world
- Go blog
  
  The Go project's official blog.
- Go project
  
  Get help and stay informed from Go
- Get connected

recon

package module

Go to main page

Versions in this module

v1

v1.0.2

Jun 15, 2026

Changes in this version

+ type EnvFamily struct

+ Base string

+ Separator string

+ Target Path

type EnvOption

+ func WithEnvVars(vars map[string]string) EnvOption

type Source

+ func NewEnvFamilySource(name string, families ...EnvFamily) Source

v1.0.1

Jun 10, 2026

v1.0.0

May 18, 2026

Changes in this version

+ const DefaultDelimiter

+ const FormatDotenv

+ const FormatJSON

+ const FormatJSONC

+ const FormatTOML

+ const FormatYAML

+ const TagName

+ var ErrAliasCycle = errors.New("recon: alias cycle")

+ var ErrCoercion = errors.New("recon: coercion failed")

+ var ErrEmptyValue = errors.New("recon: empty value")

+ var ErrImmutableChanged = errors.New("recon: immutable key changed")

+ var ErrInvalidPath = errors.New("recon: invalid path")

+ var ErrKeyNotFound = errors.New("recon: key not found")

+ var ErrMissingRequired = errors.New("recon: missing required value")

+ var ErrNilContext = errors.New("recon: nil context")

+ var ErrReadOnlySource = errors.New("recon: source is read-only")

+ var ErrRegistryClosed = errors.New("recon: registry closed")

+ var ErrSchemaInvalid = errors.New("recon: schema invalid")

+ var ErrSourceConflict = errors.New("recon: source name conflict")

+ var ErrTypeMismatch = errors.New("recon: type mismatch")

+ var ErrUnknownKey = errors.New("recon: unknown key (strict mode)")

+ var ErrUnsupportedFormat = errors.New("recon: unsupported format")

+ var ErrValidation = errors.New("recon: validation failed")

+ func DetectFormat(path string) (string, bool)

+ func DotTransform(p Path) string

+ func FormatError(reg *Registry, err error, color ...bool) string

+ func FormatErrorColor(reg *Registry, err error) string

+ func Get[T any](r *Registry, key string) (T, bool, error)

+ func IdentityTransform(p Path) string

+ func KebabTransform(p Path) string

+ func MustGet[T any](r *Registry, key string) T

+ func SnakeUpperTransform(p Path) string

+ type AliasCycleError struct

+ Chain []Path

+ func (e *AliasCycleError) Error() string

+ func (e *AliasCycleError) Is(target error) bool

+ type BackendWatcher interface

+ Watch func(ctx context.Context) (<-chan struct{}, error)

+ type BufferOption func(*bufferOptions)

+ func WithBufferCodec(c Codec) BufferOption

+ type BufferSource struct

+ func (s *BufferSource) Codec() Codec

+ func (s *BufferSource) Format() string

+ type Codec interface

+ Decode func(data []byte) (map[string]any, error)

+ Encode func(v map[string]any) ([]byte, error)

+ Extensions func() []string

+ Name func() string

+ var Dotenv Codec = dotenvCodec{}

+ var JSON Codec = jsonCodec{}

+ var JSONC Codec = jsoncCodec{}

+ var TOML Codec = tomlCodec{}

+ var YAML Codec = yamlCodec{}

+ type Codecs struct

+ func DefaultCodecs() *Codecs

+ func NewCodecs(initial ...Codec) *Codecs

+ func (c *Codecs) ByExtension(ext string) (Codec, bool)

+ func (c *Codecs) ByName(name string) (Codec, bool)

+ func (c *Codecs) Clone() *Codecs

+ func (c *Codecs) Names() []string

+ func (c *Codecs) Register(codec Codec)

+ func (c *Codecs) Unregister(name string)

+ type CoercionError struct

+ Cause error

+ Path Path

+ Secret bool

+ Source string

+ Target string

+ WireType string

+ func (e *CoercionError) Error() string

+ func (e *CoercionError) Is(target error) bool

+ func (e *CoercionError) Unwrap() error

+ type Configs struct

+ func NewConfigs() *Configs

+ func (c *Configs) Close() error

+ func (c *Configs) Events() <-chan NamedEvent

+ func (c *Configs) Get(name string) (*Registry, bool)

+ func (c *Configs) MustGet(name string) *Registry

+ func (c *Configs) Names() []string

+ func (c *Configs) Register(name string, r *Registry) error

+ func (c *Configs) Remove(name string) error

+ type DecodeOption func(*decodeOptions)

+ func WithCustomDecoder[T any](fn func(Value) (T, error)) DecodeOption

+ func WithDecodeContext(ctx context.Context) DecodeOption

+ func WithDecodeErrorBehavior(b ErrorBehavior) DecodeOption

+ func WithDecodeLenient() DecodeOption

+ func WithDecodeStrict() DecodeOption

+ func WithDecodeTag(name string) DecodeOption

+ type DeprecationWarning struct

+ Message string

+ Path Path

+ Replacement Path

+ Source string

+ func (w DeprecationWarning) String() string

+ type Description struct

+ Keys []KeyDescription

+ type EmptyValueError struct

+ Path Path

+ Source string

+ func (e *EmptyValueError) Error() string

+ func (e *EmptyValueError) Is(target error) bool

+ type EnvOption func(*envOptions)

+ func WithEnvKeyParser(fn func(name string) Path) EnvOption

+ func WithEnvPrefix(prefix string) EnvOption

+ func WithEnvTransform(fn KeyTransform) EnvOption

+ type ErrorBehavior int

+ const FailCollect

+ const FailFast

+ type Event struct

+ Changed []Path

+ Err error

+ Source string

+ Time time.Time

+ Warnings []DeprecationWarning

+ type FSWatcher struct

+ func NewFSWatcher(opts ...FSWatcherOption) *FSWatcher

+ func (w *FSWatcher) Watch(ctx context.Context, path string) (<-chan SourceChange, error)

+ type FSWatcherOption func(*FSWatcher)

+ func WithFSWatcherDebounce(d time.Duration) FSWatcherOption

+ func WithFSWatcherLogger(l *slog.Logger) FSWatcherOption

+ func WithFSWatcherPollInterval(d time.Duration) FSWatcherOption

+ type FieldTag struct

+ Aliases []string

+ Base64 bool

+ DefaultValue string

+ Deprecated bool

+ DeprecationMessage string

+ Expand bool

+ Format string

+ FromFile bool

+ HasDefault bool

+ Hex bool

+ Immutable bool

+ Inline bool

+ KVSeparator string

+ Layout string

+ Name string

+ NotEmpty bool

+ Path string

+ Required bool

+ Secret bool

+ Separator string

+ Skip bool

+ Source string

+ Transform string

+ Unset bool

+ Validate string

+ func ParseTag(s string) FieldTag

+ type FileOption func(*fileOptions)

+ func WithFileCodec(c Codec) FileOption

+ func WithFileFormat(name string) FileOption

+ func WithFileWatcher(w WatcherFactory) FileOption

+ func WithOptional(optional bool) FileOption

+ func WithPathExpansion(enabled bool) FileOption

+ func WithSearchPaths(dirs ...string) FileOption

+ type FileSource struct

+ func (s *FileSource) Format() string

+ func (s *FileSource) Path() string

+ func (s *FileSource) Reload() error

+ func (s *FileSource) SetWatcher(w WatcherFactory)

+ func (s *FileSource) Watch(ctx context.Context) (<-chan SourceChange, error)

+ type FileSourceFS struct

+ func (s *FileSourceFS) Format() string

+ func (s *FileSourceFS) Path() string

+ type FlagAdapter interface

+ Lookup func(name string) (value any, set bool)

+ Names func() []string

+ type FlagOption func(*flagOptions)

+ func WithFlagName(name string) FlagOption

+ func WithFlagPathTransform(fn func(flagName string) Path) FlagOption

+ type FlagSource struct

+ func NewFlagSource(adapter FlagAdapter, opts ...FlagOption) (*FlagSource, error)

+ func (s *FlagSource) Close() error

+ func (s *FlagSource) Get(path Path) (Value, bool, error)

+ func (s *FlagSource) Keys() []Path

+ func (s *FlagSource) Name() string

+ type ImmutableChangedError struct

+ New string

+ Old string

+ Path Path

+ func (e *ImmutableChangedError) Error() string

+ func (e *ImmutableChangedError) Is(target error) bool

+ type JSONSchemaValidator struct

+ func NewJSONSchemaValidator(schemaJSON []byte) (*JSONSchemaValidator, error)

+ func NewJSONSchemaValidatorFromSchema(s *jsonschema.Schema) *JSONSchemaValidator

+ func NewJSONSchemaValidatorJSONC(schemaJSONC []byte) (*JSONSchemaValidator, error)

+ func NewJSONSchemaValidatorTOML(schemaTOML []byte) (*JSONSchemaValidator, error)

+ func NewJSONSchemaValidatorYAML(schemaYAML []byte) (*JSONSchemaValidator, error)

+ func (v *JSONSchemaValidator) Validate(snapshot map[string]any) error

+ type KeyDescription struct

+ Aliases []Path

+ Path Path

+ Schema string

+ Secret bool

+ Source string

+ Sources []string

+ Value string

+ type KeyTransform func(p Path) string

+ func SnakeUpperPrefixTransform(prefix string) KeyTransform

+ type Live struct

+ func NewLive[T any](reg *Registry, opts ...DecodeOption) (*Live[T], error)

+ func (l *Live[T]) Close() error

+ func (l *Live[T]) Events() <-chan Event

+ func (l *Live[T]) Get() *T

+ func (l *Live[T]) LastError() error

+ func (l *Live[T]) Reload(ctx context.Context) error

+ type MapSource struct

+ func NewMapSource(name string, m map[string]any) *MapSource

+ func (s *MapSource) Close() error

+ func (s *MapSource) Get(path Path) (Value, bool, error)

+ func (s *MapSource) Keys() []Path

+ func (s *MapSource) Name() string

+ func (s *MapSource) Replace(m map[string]any)

+ type MemoryBackend struct

+ func NewInMemoryBackend() *MemoryBackend

+ func (m *MemoryBackend) Close() error

+ func (m *MemoryBackend) Delete(key string)

+ func (m *MemoryBackend) Get(_ context.Context, key string) (string, bool, error)

+ func (m *MemoryBackend) List(_ context.Context, prefix string) ([]string, error)

+ func (m *MemoryBackend) Put(key, value string)

+ func (m *MemoryBackend) PutAll(kv map[string]string)

+ func (m *MemoryBackend) Snapshot() map[string]string

+ func (m *MemoryBackend) Watch(ctx context.Context) (<-chan struct{}, error)

+ type MergeStrategy int

+ const MergeAppend

+ const MergeReplace

+ const MergeShadow

+ type MissingRequiredError struct

+ Path Path

+ Sources []string

+ func (e *MissingRequiredError) Error() string

+ func (e *MissingRequiredError) Is(target error) bool

+ type MultiError struct

+ Errors []error

+ func (m *MultiError) Append(err error)

+ func (m *MultiError) Error() string

+ func (m *MultiError) Unwrap() []error

+ type NamedEvent struct

+ Name string

+ type OSEnvSource struct

+ func NewOSEnvSource(opts ...EnvOption) *OSEnvSource

+ func (s *OSEnvSource) Close() error

+ func (s *OSEnvSource) Get(path Path) (Value, bool, error)

+ func (s *OSEnvSource) Keys() []Path

+ func (s *OSEnvSource) Name() string

+ func (s *OSEnvSource) Refresh() int

+ type Option func(*registryOptions)

+ func WithCodec(c Codec) Option

+ func WithCodecs(cs *Codecs) Option

+ func WithErrorBehavior(b ErrorBehavior) Option

+ func WithEventBufferSize(n int) Option

+ func WithLenient() Option

+ func WithLogger(l *slog.Logger) Option

+ func WithMerge(strategy MergeStrategy) Option

+ func WithPoll(interval time.Duration) Option

+ func WithPrecedence(order ...string) Option

+ func WithReloadDebounce(d time.Duration) Option

+ func WithSchema(schemaJSON []byte) Option

+ func WithSecretRedactor(fn func(string) string) Option

+ func WithSource(s Source) Option

+ func WithSources(s ...Source) Option

+ func WithStrict() Option

+ func WithValidator(v SchemaValidator) Option

+ func WithWatcher(w WatcherFactory) Option

+ func WithoutCodec(name string) Option

+ type ParseError struct

+ Cause error

+ Path string

+ Position Position

+ Source string

+ func (e *ParseError) Error() string

+ func (e *ParseError) Unwrap() error

+ type Path []string

+ func MakePath(segments ...string) Path

+ func ParsePath(s string) Path

+ func (p Path) After(prefix Path) Path

+ func (p Path) Append(seg ...string) Path

+ func (p Path) Clone() Path

+ func (p Path) Equal(other Path) bool

+ func (p Path) HasPrefix(prefix Path) bool

+ func (p Path) String() string

+ type PerSource struct

+ Default ValueSource[T]

+ Explicit ValueSource[T]

+ Path Path

+ Resolved ValueSource[T]

+ Sources []ValueSource[T]

+ func PerSourceForPath[T any](r *Registry, p Path) (PerSource[T], error)

+ func PerSourceFor[T any](r *Registry, key string) (PerSource[T], error)

+ func (p PerSource[T]) BySource(name string) ValueSource[T]

+ type PollWatcher struct

+ func NewPollWatcher(interval time.Duration) *PollWatcher

+ func (w *PollWatcher) Watch(ctx context.Context, path string) (<-chan SourceChange, error)

+ type Position struct

+ Column int

+ Line int

+ func (p Position) String() string

+ type RawValue struct

+ Data []byte

+ Format string

+ func (rv RawValue) Decode(v any) error

+ type Registry struct

+ func New(opts ...Option) (*Registry, error)

+ func (r *Registry) AddSource(s Source) error

+ func (r *Registry) AllKeys() []string

+ func (r *Registry) Bind(target any, opts ...DecodeOption) error

+ func (r *Registry) BindContext(ctx context.Context, target any, opts ...DecodeOption) error

+ func (r *Registry) Close() error

+ func (r *Registry) Describe() Description

+ func (r *Registry) DescribeKey(key string) (KeyDescription, bool)

+ func (r *Registry) DrainWarnings() []DeprecationWarning

+ func (r *Registry) Events() <-chan Event

+ func (r *Registry) GenerateTemplate(format string, opts ...SaveOption) ([]byte, error)

+ func (r *Registry) Get(key string) (Value, bool, error)

+ func (r *Registry) GetAny(key string) (any, bool, error)

+ func (r *Registry) GetBool(key string) (bool, bool, error)

+ func (r *Registry) GetDuration(key string) (time.Duration, bool, error)

+ func (r *Registry) GetFloat(key string) (float64, bool, error)

+ func (r *Registry) GetInt(key string) (int, bool, error)

+ func (r *Registry) GetInt64(key string) (int64, bool, error)

+ func (r *Registry) GetPath(p Path) (Value, bool, error)

+ func (r *Registry) GetString(key string) (string, bool, error)

+ func (r *Registry) GetStringMap(key string) (map[string]string, bool, error)

+ func (r *Registry) GetStringSlice(key string) ([]string, bool, error)

+ func (r *Registry) GetTime(key string) (time.Time, bool, error)

+ func (r *Registry) InsertSource(at int, s Source) error

+ func (r *Registry) IsImmutable(key string) bool

+ func (r *Registry) IsSecret(key string) bool

+ func (r *Registry) IsSet(key string) bool

+ func (r *Registry) MarkSecret(key string)

+ func (r *Registry) PinSource(key, sourceName string) error

+ func (r *Registry) Prefix() Path

+ func (r *Registry) RegisterAlias(alias, canonical string) error

+ func (r *Registry) Reload() error

+ func (r *Registry) ReloadContext(ctx context.Context) error

+ func (r *Registry) RemoveSource(name string) error

+ func (r *Registry) Save(w io.Writer, opts ...SaveOption) error

+ func (r *Registry) SaveString(opts ...SaveOption) (string, error)

+ func (r *Registry) SaveTo(path string, opts ...SaveOption) error

+ func (r *Registry) Set(key string, value any) error

+ func (r *Registry) SetDefault(key string, value any) error

+ func (r *Registry) Snapshot() *Snapshot

+ func (r *Registry) Sources() []string

+ func (r *Registry) Sub(prefix string) *Registry

+ func (r *Registry) TemplateKeys(opts ...SaveOption) []Path

+ func (r *Registry) Unmarshal(target any, opts ...DecodeOption) error

+ func (r *Registry) UnmarshalKey(key string, target any, opts ...DecodeOption) error

+ func (r *Registry) Unpin(key string) error

+ func (r *Registry) Unset(key string) error

+ func (r *Registry) Validate() error

+ func (r *Registry) Validator() SchemaValidator

+ type RemoteBackend interface

+ Close func() error

+ Get func(ctx context.Context, key string) (string, bool, error)

+ List func(ctx context.Context, prefix string) ([]string, error)

+ type RemoteOption func(*remoteOptions)

+ func WithRemotePollInterval(d time.Duration) RemoteOption

+ func WithRemotePrefix(prefix string) RemoteOption

+ func WithRemoteTrimPrefix(trim bool) RemoteOption

+ type RemoteSource struct

+ func NewRemoteSource(name string, backend RemoteBackend, opts ...RemoteOption) (*RemoteSource, error)

+ func (s *RemoteSource) Close() error

+ func (s *RemoteSource) Get(path Path) (Value, bool, error)

+ func (s *RemoteSource) Keys() []Path

+ func (s *RemoteSource) Name() string

+ func (s *RemoteSource) Refresh(ctx context.Context) error

+ func (s *RemoteSource) Watch(ctx context.Context) (<-chan SourceChange, error)

+ type SaveOption func(*saveOptions)

+ func WithSaveFormat(format string) SaveOption

+ func WithSaveIncludeDefaults() SaveOption

+ func WithSaveIncludeSecrets() SaveOption

+ func WithSaveOnly(prefix string) SaveOption

+ type SchemaValidator interface

+ Validate func(snapshot map[string]any) error

+ type Secret = env.Secret[T]

+ func NewSecret[T any](v T) Secret[T]

+ type Snapshot struct

+ func (s *Snapshot) AsMap() map[string]any

+ func (s *Snapshot) Get(p Path) (Value, bool)

+ func (s *Snapshot) IsSecret(p Path) bool

+ func (s *Snapshot) Keys() []Path

+ func (s *Snapshot) SourceFor(p Path) []string

+ func (s *Snapshot) String() string

+ type Source interface

+ Close func() error

+ Get func(path Path) (Value, bool, error)

+ Keys func() []Path

+ Name func() string

+ func NewBufferSource(name, format string, data []byte, opts ...BufferOption) (Source, error)

+ func NewDotenvSource(path string, opts ...FileOption) (Source, error)

+ func NewFileSource(path string, opts ...FileOption) (Source, error)

+ func NewFileSourceFS(name string, fsys fs.FS, path string, opts ...FileOption) (Source, error)

+ func NewJSONCSource(path string, opts ...FileOption) (Source, error)

+ func NewJSONSource(path string, opts ...FileOption) (Source, error)

+ func NewStdinSource(format string, opts ...StdinOption) (Source, error)

+ func NewTOMLSource(path string, opts ...FileOption) (Source, error)

+ func NewYAMLSource(path string, opts ...FileOption) (Source, error)

+ type SourceChange struct

+ Err error

+ Keys []Path

+ type SourceError struct

+ Cause error

+ Op string

+ Source string

+ func (e *SourceError) Error() string

+ func (e *SourceError) Unwrap() error

+ type StdinOption func(*stdinOptions)

+ func WithStdinCodec(c Codec) StdinOption

+ type UnknownKeyError struct

+ Path Path

+ Source string

+ func (e *UnknownKeyError) Error() string

+ func (e *UnknownKeyError) Is(target error) bool

+ type Unmarshaler interface

+ UnmarshalRecon func(v Value) error

+ type ValidationError struct

+ Msg string

+ Path Path

+ Rule string

+ Secret bool

+ func (e *ValidationError) Error() string

+ func (e *ValidationError) Is(target error) bool

+ type Validator interface

+ Validate func() error

+ type ValidatorContext interface

+ Validate func(ctx context.Context) error

+ type Value struct

+ func NewRawValue(format string, data []byte) Value

+ func NewValue(v any) Value

+ func (v Value) Any() any

+ func (v Value) AsBool() (bool, error)

+ func (v Value) AsDuration() (time.Duration, error)

+ func (v Value) AsFloat64() (float64, error)

+ func (v Value) AsInt64() (int64, error)

+ func (v Value) AsMap() (map[string]Value, error)

+ func (v Value) AsRaw() (RawValue, error)

+ func (v Value) AsSlice() ([]Value, error)

+ func (v Value) AsString() (string, error)

+ func (v Value) AsTime() (time.Time, error)

+ func (v Value) IsZero() bool

+ func (v Value) Kind() ValueKind

+ func (v Value) Source() string

+ func (v Value) String() string

+ type ValueKind int

+ const BoolKind

+ const DurationKind

+ const FloatKind

+ const IntKind

+ const MapKind

+ const NullKind

+ const RawKind

+ const SliceKind

+ const StringKind

+ const TimeKind

+ func (k ValueKind) String() string

+ type ValueSource struct

+ Err error

+ IsSet bool

+ Source string

+ Value T

+ type Watcher interface

+ Watch func(ctx context.Context) (<-chan SourceChange, error)

+ type WatcherFactory interface

+ Watch func(ctx context.Context, path string) (<-chan SourceChange, error)