@philiprehberger/env-expand
v0.1.5638 downloadsMIT
Interpolate variables within environment values
$
npm install @philiprehberger/env-expandREADME
@philiprehberger/env-expand
Interpolate variables within environment values. Supports ${VAR}, $VAR, default values, alternate values, required values, and circular reference detection
Installation
npm install @philiprehberger/env-expand
Usage
import { expand, expandString } from '@philiprehberger/env-expand';
// Expand all variable references in an env record
const env = {
HOST: 'localhost',
PORT: '3000',
BASE_URL: 'http://${HOST}:${PORT}',
API_URL: '${BASE_URL}/api',
};
const result = expand(env);
// result.API_URL → 'http://localhost:3000/api'
// Default values
expand({ URL: '${HOST:-localhost}:${PORT:-8080}' });
// → { URL: 'localhost:8080' }
// Alternate values (use value only when variable IS set)
expand({ DEBUG: 'true', FLAG: '${DEBUG:+--verbose}' });
// → { DEBUG: 'true', FLAG: '--verbose' }
// Required values (throw if missing)
expand({ REF: '${SECRET:?Secret must be configured}' });
// throws MissingVariableError
// Expand a single template string
expandString('Hello, ${NAME}!', { NAME: 'world' });
// → 'Hello, world!'
API
expand(env, options?)
Expand variable references in all values of an environment record.
Parameters:
| Parameter | Type | Description |
|---|---|---|
env | Record<string, string> | Key-value pairs to expand |
options.inPlace | boolean | Modify the input record in place (default: false) |
options.defaults | Record<string, string> | Fallback variables (lower priority than env keys) |
options.maxDepth | number | Maximum expansion depth (default: 50) |
Returns: Record<string, string> — expanded environment record.
Supported syntax:
| Syntax | Description |
|---|---|
${VAR} / $VAR | Substitute variable value (empty string if unset) |
${VAR:-default} | Use default if VAR is unset or empty |
${VAR:+alternate} | Use alternate only if VAR is set and non-empty |
${VAR:?error} | Throw MissingVariableError if VAR is unset or empty |
expandString(template, vars?)
Expand variable references within a single template string.
Parameters:
| Parameter | Type | Description |
|---|---|---|
template | string | The string containing variable references |
vars | Record<string, string> | Variables available for substitution |
Returns: string — the expanded string.
CircularReferenceError
Thrown when a circular variable reference is detected. Properties:
variable— the variable that caused the cyclechain— the reference chain leading to the cycle
MissingVariableError
Thrown when a required variable (${VAR:?...}) is not set. Properties:
variable— the missing variable name
Development
npm install
npm run build
npm run typecheck
npm test
Support
If you find this project useful: