Project Tom Hagen: bind environment sources

[cowboyd]

Motivation

Programs need to bind environment variables into the same typed route models as CLI and JavaScript configuration without Configliere reading ambient process state. Environment keys also need predictable route-aware defaults, explicit overrides, deterministic precedence, and behavior that remains correct across dynamic phases.

Approach

Model environments as named, explicitly supplied address sources: Configliere never reads ambient process state. A parameter's default key is derived from its complete route address, giving sibling routes isolated names such as AUTH0_PORT; an explicit env() mapping replaces that convention when interoperability requires another key. Sources mounted on the current route are considered before ancestors, while declaration order resolves competing sources at the same mount.

Environment values remain text, so they share decoding semantics with CLI input before entering Standard Schema validation; JavaScript values continue directly to validation. The phase scheduler therefore becomes CLI → environment → JavaScript values → schema absence. As with every source, a present but invalid environment value blocks fallback, preserving precedence as an error-reporting rule rather than merely a successful-value preference. Because mounts and claims travel with parse state, the same rules continue to hold across dynamic phases.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/configliere@25

commit: 68c0540