Clarify result value lookup semantics

This commit is contained in:
2026-11-21 12:01:02 +00:00
parent ed5d57d061
commit d6fcfc62d9
2 changed files with 30 additions and 6 deletions

View File

@@ -2,11 +2,27 @@ package configkit
import "go.maximumdirect.net/configkit/internal/engine"
// Value returns the current Config value at path, including values absent from
// input. It returns false for a nil result, invalid path, or missing value.
// Values are trusted application data and may include resolved secrets. Ordinary
// Go assignment applies: maps, slices, and pointers can alias Config. Inspection
// methods continue to report the frozen completed load, not later mutations.
// Value returns the current Config value at path. The root [Path] selects Config.
// A non-nil result supports lookup even when constructed manually without load
// or inspection state. Success means value availability, not input presence or
// validation; use Metadata to inspect presence in the completed load.
//
// Navigation follows the shared YAML field names, inline bindings and supported
// shapes described in docs/config.md#application-schema-binding, with [Path]'s
// key/index rules. It follows non-nil intermediate pointers and interfaces,
// checks map membership and sequence bounds, and never allocates missing values.
// Scalars, including text-codec types and Secret, remain leaves.
// A nil receiver, invalid path, missing value, or unavailable traversal returns
// (nil, false). A present nil succeeds: a nil interface returns (nil, true), while
// typed nil pointers, maps and slices retain their types in the returned any.
//
// The terminal retains its actual Go type, including named types and pointers;
// terminal pointers are not dereferenced. Lookup performs no conversion or
// revalidation of the terminal and does not invoke codecs or resolve secrets.
// Values are trusted application data and may include resolved Secret values.
// Ordinary Go assignment applies: structs and arrays are copied, while maps,
// slices and pointers can alias Config. Inspection methods continue to report
// the frozen completed load, not later caller mutations.
func (r *Result[T]) Value(path Path) (any, bool) {
if r == nil {
return nil, false