8.5 KiB
Typed value access from a result
Status: agreed feature scope; not implemented. Remaining decisions are below.
Baseline: v1.3.0, commit 652ddb6.
Purpose and baseline
Let an application load configuration once and pass the whole result to libraries such as PromptKit and FeedKit. Each library selects its conventional section, checks its public settings type, and constructs its runtime objects. Section names remain library conventions, not ConfigKit reserved keys.
Today, Result.Config supplies trusted typed values, but its generic root type prevents a library from selecting a field without knowing the application type or adding its own traversal. Existing metadata and source contexts already support field provenance and resource lookup. Redacted inspection snapshots are not execution inputs.
PromptKit has accepted this narrower direction. Its earlier request for scoped inspection and independent source-version policies is background, not acceptance criteria for this addition. Those capabilities, a component registry, and a new configuration conversion API are outside this roadmap.
Targeted end state
Add one public method:
func (r *Result[T]) Value(path Path) (any, bool)
The method selects a current value from r.Config. It performs no loading,
decoding, defaulting, normalization, validation, resource acquisition, or secret
lookup. It does not invoke application text codecs or render configuration.
Libraries perform ordinary Go type assertions; ConfigKit does not convert the
selected value into a requested component type.
Values, ownership, and inspection
- Return the actual terminal Go value, preserving named types, pointers, and
resolved
Secretvalues. Do not dereference a terminal pointer automatically. An interface contributes its current dynamic value under ordinary Go semantics. - Use ordinary Go assignment semantics. Structs and arrays are copied as values;
pointers, maps, and slices can share underlying state with
Result.Config. There is no deep-copy or additional frozen execution snapshot guarantee. - Read current configuration state, including caller changes made after loading. Existing inspection continues to describe the completed load. Document the distinction and recommend handoff before mutations invalidate that evidence; do not add mutation detection or synchronization.
- This is trusted access, like
Result.Config, and does not redact. Consumers capture owned settings where needed and use existing inspection for safe output. - A found nil pointer, map, slice, or interface is distinct from an unavailable
path. In particular,
(nil, true)is possible. A zero/defaulted struct field may be found without YAML input; source presence remains a metadata question.
Path traversal
Use the existing Path and
schema binding rules. The root path
selects Config. Struct paths use YAML names or the existing default field names,
including flattened inline fields and inline maps. Ignored and unexported fields
do not become navigable paths. Typed scalars, including text-codec types and
Secret, remain leaves even when their Go representation is a struct.
Mapping keys and sequence indices retain their semantic distinction; parsed numeric tokens resolve according to the containing value. Check current map membership and slice/array bounds. Follow non-nil intermediate pointers and interfaces only when navigation continues. Do not allocate missing maps or pointer targets, including nil inline embeddings, to satisfy a lookup.
Return (nil, false) for malformed paths, missing keys, out-of-range indices,
incompatible segments, or traversal through nil or a scalar. Declared schema
validity alone does not make a runtime descendant available. Receiver handling
and dynamic values changed after loading are addressed in the open decisions.
Consumer integration
A library may define its own interface; ConfigKit need not introduce a shared interface or wrapper:
type Configuration interface {
Value(configkit.Path) (any, bool)
Metadata() configkit.Metadata
SourceContext(string) (configkit.ResourceContext, bool)
}
PromptKit selects Value(configkit.Keys("promptkit")) and asserts its settings
type. FeedKit can use a smaller interface if it needs only values. Both receive
the same application result. Paths remain application-root paths. Resource lookup
uses effective field origins and original source contexts; historical evidence
does not restore a lost effective origin.
Before loading, library-owned helpers incorporate public settings, defaults,
normalization, validation, sensitivity, and sequence identities into the
application's existing Definition[T]. One typed field selector per library is
acceptable registration wiring. Helpers preserve application rules, keep callback
ordering explicit, and avoid shared mutable per-load state. Desired bundled
resources enter the original load as ordinary underlays.
Representative one-library and two-library probes passed using existing lifecycle
APIs and a limited stand-in for Value. They establish feasibility, not completion
of real PromptKit integration. PromptKit still owns its public settings model,
presence-state handling, resource capture, and settings ownership refactoring.
Work needed
- Settle the open decisions and record representative lookup outcomes, including nil values and the difference between typed-value availability and input presence.
- Add the root-owned method and reuse existing schema bindings and semantic path logic for typed traversal. Keep any supporting implementation private. Do not route through inspection projection or add another complete load-time snapshot.
- Add focused public tests for root/nested lookup, named and pointer types, inline fields/maps, dynamic containers, numeric keys versus indices, bounds, missing/nil values, scalar leaves, and the selected receiver/mutation rules. Verify ordinary aliasing and unchanged frozen inspection without promising concurrent mutation safety. Check trusted secret access and existing redaction with disposable values.
- Add maintained one-library and two-library consumer examples. Demonstrate one load, typed registration, whole-result handoff, composed callbacks and identity checks, and resource contexts retained through placement and existing structural operations. Keep library-specific runtime construction outside ConfigKit.
- Document the method beside its declaration, extend the configuration ownership contract and consumer guidance, and run the relevant public tests and normal repository checks. This is an additive API; existing loading, inspection, comparison, and shared source-version behavior remain as documented.
Completion means both representative library consumers can obtain their typed settings and existing provenance from one application result without application extraction, reshaping, serialization, or a second load. No new scoped reporting or independently versioned source support is required for completion.
Open Decisions
OD-1: Nil and manually constructed results
Recommendation: return (nil, false) for a nil receiver or a result without
successful-load inspection state, including &Result[T]{Config: value}. This
keeps the method on the completed-result boundary and consistent with the
inspection methods a library may use alongside it. This is a proposed eligibility
rule, not a claim that caller changes to a successful result are revalidated.
Alternative: allow any non-nil result to expose its Config, even without
load state. This matches direct field access and simplifies hand-built fixtures,
but a library can then obtain values from a result with no corresponding load
evidence. Nil receivers would still return (nil, false).
OD-2: Traversal after arbitrary changes inside any
Recommendation: navigate current dynamic values using ConfigKit's supported dynamic container shapes. Return false if further traversal needs an unsupported shape. At a reached terminal, return the current value without revalidating it; lookup is not a new configuration validation pass. This follows current-value ownership while reusing ConfigKit's existing navigation model.
Alternative: reflect through arbitrary Go shapes inserted into any after
loading, including new struct types. This offers more flexibility for mutated
results, but requires additional runtime binding and failure rules for values
the load never supported. Neither demonstrated consumer needs that expansion.