Documentation
¶
Overview ¶
Package transform provides composable, post-merge / pre-decode transformations on the merged configuration tree.
FastConf's reload pipeline is conceptually:
discover → decode → merge/patch → [TRANSFORMERS] → decodeInto(*T)
→ validate → publish
A Transformer is a pure function `func(map[string]any) error` that may mutate the in-place merged map before it is decoded into the user's strongly-typed struct. Built-in transformers cover the most common cases (defaults, env interpolation, key aliasing, deletion). Users can also write their own.
Transformers run in declaration order and are wired via `fastconf.WithTransformers(...)`. Failures abort the reload and the previously committed state is preserved (same guarantee as every other stage).
Design notes:
- Transformers operate on `map[string]any` rather than `*T` so they remain decoupled from the user type and can be reused across multiple Manager[T] instances.
- Path syntax used by helpers below is dotted: "a.b.c". Numeric indices into slices are NOT supported (config trees are usually small maps; complex array surgery belongs in RFC 6902 patches).
- All helpers tolerate a nil root map (treated as empty); they never panic on missing intermediate nodes.
Index ¶
- Variables
- func Wrap(name string, err error) error
- type RawCapture
- type Transformer
- func Aliases(mapping map[string]string) Transformer
- func Defaults(values map[string]any) Transformer
- func DeletePaths(paths ...string) Transformer
- func EnvSubst() Transformer
- func EnvSubstWith(lookup func(string) string) Transformer
- func MergeByKey(dotPath, keyField string) Transformer
- func SetIfAbsent(path string, value any) Transformer
- type TransformerFunc
Constants ¶
This section is empty.
Variables ¶
var ErrTransform = errors.New("fastconf/internal/transform")
ErrTransform is returned wrapped by built-in transformers on failure.
Functions ¶
Types ¶
type RawCapture ¶ added in v0.8.1
type RawCapture struct {
// contains filtered or unexported fields
}
RawCapture is a Transformer that snapshots one or more dotted-path values as json.RawMessage after the merge phase but before decoding into *T. This is the recommended solution for map[string][]json.RawMessage protocol blocks: register a RawCapture transformer, decode *T normally, then call rawCapture.Get(path) to retrieve the opaque bytes.
RawCapture is safe for concurrent reads (Get/All) after a reload.
Usage:
rc := transform.CaptureRaw("listeners", "upstreams")
mgr, _ := fastconf.New[Config](ctx,
fastconf.WithTransformers(rc),
// ... other options
)
cfg := mgr.Get()
raw, _ := rc.Get("listeners") // raw is json.RawMessage
func CaptureRaw ¶ added in v0.8.1
func CaptureRaw(paths ...string) *RawCapture
CaptureRaw returns a new RawCapture transformer that will snapshot the values at the given dotted paths on every reload.
func (*RawCapture) All ¶ added in v0.8.1
func (r *RawCapture) All() map[string]json.RawMessage
All returns a snapshot of all captured path → JSON bytes. The returned map is a copy and is safe for the caller to retain.
func (*RawCapture) Get ¶ added in v0.8.1
func (r *RawCapture) Get(path string) (json.RawMessage, bool)
Get returns the most recently captured JSON bytes for the given path. Returns false if the path was not registered or was missing at last reload.
func (*RawCapture) Name ¶ added in v0.8.1
func (r *RawCapture) Name() string
Name implements Transformer.
type Transformer ¶
Transformer mutates the merged configuration tree. Returning an error aborts the reload. Implementations MUST be safe to call concurrently with reads of unrelated Manager instances but are guaranteed to be invoked serially within a single reload.
func Aliases ¶
func Aliases(mapping map[string]string) Transformer
Aliases returns a Transformer that rewrites legacy keys to their new home. If the target path already has a value the new world wins and the alias is dropped.
func Defaults ¶
func Defaults(values map[string]any) Transformer
Defaults returns a Transformer that recursively merges the supplied values into the tree, only filling keys that are missing.
func DeletePaths ¶
func DeletePaths(paths ...string) Transformer
DeletePaths returns a Transformer that removes the specified dotted-path keys from the tree. Missing paths are silently ignored.
func EnvSubst ¶
func EnvSubst() Transformer
EnvSubst returns a Transformer that walks every string value in the tree and substitutes occurrences of ${VAR} or ${VAR:-default}.
func EnvSubstWith ¶
func EnvSubstWith(lookup func(string) string) Transformer
EnvSubstWith is like EnvSubst but reads variables through the supplied lookup function.
func MergeByKey ¶ added in v0.8.1
func MergeByKey(dotPath, keyField string) Transformer
MergeByKey returns a Transformer that merges an array of maps by a key field, enabling overlay files to modify individual entries without replacing the entire array.
The array at the given dotted path is expected to contain map[string]any items each with a distinguishing field (keyField). Items from the current array are merged on top of items from the same-keyed base item. If a key appears only once the item is kept as-is.
This is useful for protocol-block patterns where each entry has an identifier:
listeners:
- name: http
port: 80
- name: https
port: 443
A subsequent overlay with only the https entry will update port 443 without discarding the http entry.
func SetIfAbsent ¶
func SetIfAbsent(path string, value any) Transformer
SetIfAbsent sets a single dotted-path key only when it has no value.
type TransformerFunc ¶
TransformerFunc adapts a plain function to the Transformer interface.
func (TransformerFunc) Name ¶
func (t TransformerFunc) Name() string
Source Files