env/resolve.ts

Environment variable $$VAR$$ resolution suite.

Resolves $$VAR$$ references in strings and object trees, scans configs for references, and validates/formats missing vars.

The double-dollar bookending syntax is: - Visually distinct from shell $VAR syntax - Unambiguous about variable boundaries - Easy to grep: grep '\$\$' - Fails loud if accidentally shell-processed ($$=PID in shell)

Declarations
#

11 declarations

view source

EnvValidationResult
#

env/resolve.ts view source

EnvValidationResult

Result of env var validation.

Uses discriminated union for better type narrowing: - ok: true, missing: null — all vars present - ok: false, missing: EnvVarRef[] — some vars missing

EnvVarRef
#

env/resolve.ts view source

EnvVarRef

An env var reference found in a config.

name

Variable name (without $$ delimiters).

type string

path

Path where the reference was found (e.g., "target.host", "resources[3].path").

type string

format_missing_env_vars
#

env/resolve.ts view source

(missing: EnvVarRef[], options?: FormatMissingEnvVarsOptions | undefined): string

Format missing env vars error message.

Groups refs by variable name so each missing var is shown once with all paths where it's referenced.

missing

missing env var references (may contain duplicate names)

type EnvVarRef[]

options?

formatting options

type FormatMissingEnvVarsOptions | undefined
optional

returns

string

formatted error message for display

FormatMissingEnvVarsOptions
#

get_env_var_names
#

env/resolve.ts view source

(value: string): string[]

Get list of env var names referenced in a string.

value

string to scan

type string

returns

string[]

array of variable names (without $$ delimiters)

has_env_vars
#

env/resolve.ts view source

(value: string): boolean

Check if a string contains unresolved env var references.

value

string to check

type string

returns

boolean

true if string contains $$VAR$$ patterns

resolve_env_vars
#

env/resolve.ts view source

(runtime: Pick<EnvDeps, "env_get">, value: string): string

Resolve environment variable references in a string.

Uses $$VAR$$ syntax (bookended double-dollar signs). Only resolves variables that are actually set in the environment. Unset variables are left as-is for clear error messages.

runtime

runtime with env_get capability

type Pick<EnvDeps, "env_get">

value

string that may contain $$VAR$$ references

type string

returns

string

string with env vars resolved

resolve_env_vars_in_object
#

env/resolve.ts view source

<T extends Record<string, unknown>>(runtime: Pick<EnvDeps, "env_get">, obj: T): T

Resolve env vars in an object's string values (shallow).

runtime

runtime with env_get capability

type Pick<EnvDeps, "env_get">

obj

object with string values

type T

returns

T

new object with env vars resolved

resolve_env_vars_required
#

env/resolve.ts view source

(runtime: Pick<EnvDeps, "env_get">, value: string, context: string): string

Resolve env vars and throw if any are missing/empty.

Use this for values that must be present.

runtime

runtime with env_get capability

type Pick<EnvDeps, "env_get">

value

string with $$VAR$$ references

type string

context

description for error message (e.g., "target.host")

type string

returns

string

resolved string

throws

  • error - if any referenced env var is missing or empty

scan_env_vars
#

env/resolve.ts view source

(obj: unknown): EnvVarRef[]

Recursively scan an object for $$VAR$$ env var references.

Walks all string values in the object tree and extracts env var names with their path context for error reporting.

obj

object to scan (typically a config)

type unknown

returns

EnvVarRef[]

array of env var references with paths

validate_env_vars
#

env/resolve.ts view source

(runtime: Pick<EnvDeps, "env_get">, refs: EnvVarRef[]): EnvValidationResult

Validate that all referenced env vars exist in the environment.

Returns all missing refs (including duplicates by name). Grouping and deduplication is handled by format_missing_env_vars at display time.

runtime

runtime with env_get capability

type Pick<EnvDeps, "env_get">

refs

env var references from scan_env_vars

type EnvVarRef[]

returns

EnvValidationResult

validation result with any missing vars