eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Decode typed configuration over defaults

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-06 19:52:45 +00:00
parent 15172294b5
commit 21e3f633bc
8 changed files with 884 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/config.md
View File

@@ -1,8 +1,9 @@
# Configuration Input Contract
This document owns ConfigKit's currently implemented source-input and YAML syntax
contracts. The parser and owned document representation are private; a public typed
loading lifecycle has not been implemented yet.
This document owns ConfigKit's currently implemented source-input, YAML syntax,
schema, typed-decoding, and ownership contracts. The parser, owned document
representation, and decoder are private; a public typed loading lifecycle has not
been implemented yet.
## Sources
@@ -101,8 +102,50 @@ tokens become indices only in a sequence. Sequence indices cannot have leading
zeroes; fixed-array indices are bounds checked. Dynamic `any` and inline-map entries
remain schema-valid for application-defined descendants.
Descriptors do not yet decode documents. Document decoding will reuse this graph as
its implementation lands.
Descriptors are reused by typed decoding, projection, and cloning so those operations
cannot acquire different field bindings.
## Defaults and typed decoding
The private decoder starts from an independently owned clone of the application's
typed defaults and applies only explicitly present input nodes. Defaults therefore
never become explicit, while equal-valued input remains explicit. Successful decode
produces detached typed state, baseline and final canonical trees, an input-presence
index, and default/input origins for the later public loading lifecycle.
| Configured input | Effect on the typed baseline |
| --- | --- |
| Absent field | Retain the default |
| Explicit false, zero, or empty string | Replace the default |
| Partial mapping or string-keyed map | Recurse and retain omitted default children or entries |
| Empty mapping | Retain existing mapping children |
| Sequence, including an empty sequence | Replace the entire sequence |
| Pointer object | Recurse into a non-nil default; otherwise allocate an object whose omitted children have ordinary Go zero values |
| Allowed null | Replace the value with nil and suppress its default |
Null is allowed only for pointers, maps, slices, and dynamic `any` values. It is an
error for scalars, structs, and arrays. New map entries and sequence elements begin
from their Go zero values; ConfigKit does not invent entry-level defaults.
Decoding is strict at every typed depth. Unknown struct fields, type mismatches,
invalid nulls, numeric overflow, and arrays with the wrong length are errors at the
original semantic path and source coordinates. String-keyed maps accept arbitrary
keys but preserve the strict schema of their values; inline maps accept unmatched
keys according to their element descriptor. Multiple independent field failures are
collected without publishing the partially decoded object.
Booleans and strings are not coerced. Integer destinations require integer syntax
and a value in the destination type's range. Float destinations accept finite JSON
numbers representable by their destination precision. Dynamic numbers become
`int64` for integer syntax and `float64` for fractional or exponent syntax, with
range and finiteness checks. Named scalar types retain their identity. Durations
decode only from strings accepted by `time.ParseDuration`; integers are rejected.
Paired text scalars decode only from strings through `encoding.TextUnmarshaler`, and
codec failures are classified without exposing application error text or input
values.
This decoder is currently an internal lifecycle foundation, not a public conversion
API. Applications cannot call typed loading until `Load` is introduced.
## Typed projection and ownership