Source precedence
Typespun resolves every configuration leaf independently across five source kinds — typed overrides, an environment source, dotenv files, compiled defaults and inline defaults — and picks the highest defined candidate before coercion.
Typespun resolves each leaf independently. It selects the highest-precedence defined candidate before coercion, so an invalid lower source cannot break a valid higher source.
Text equivalent, highest to lowest:
- typed
overrides - explicit
source; if omitted, ambientprocess.env - dotenv files, with later array entries winning
- compiled JSON/YAML defaults
- inline declaration defaults
const config = loadConfig({
envFiles: ['.env', '.env.local'],
source: process.env,
overrides: { server: { port: 5000 } },
});Here the override wins for server.port; process.env wins for other keys it
defines; .env.local wins over .env; then compiled and inline defaults fill
remaining leaves.
undefined means "no candidate." An empty string is a candidate and is
validated for its field type. source: {} disables ambient environment input.
Empty override objects are merge no-ops; unknown or cyclic override paths are
reported as issues.