vars-expand

library0.0.3jsnpmunverified

A zero-dependency template transpiler that performs shell-like variable expansion with support for default values, alternate values, and substitution operators (:- :- :+ + :? ? etc.). Inspired by Bash's Shell Parameter Expansion syntax. Current stable version is 0.0.3, released infrequently. Key differentiators: lightweight (no dependencies), TypeScript-first with bundled typings, and full support for POSIX-style expansion patterns. Unlike general template engines (e.g., Handlebars), it strictly mirrors shell semantics, making it ideal for CI/CD pipelines, configuration loaders, and environment variable interpolation.

devops serialization

npm install vars-expand

github ↗package ↗

INSTALL

IMPORT

SIG · VARS-EXPAND

vars-expand

devopsjavascriptv0.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

varsBraceExpand

✓ import varsBraceExpand from 'vars-expand'

✗ const varsBraceExpand = require('vars-expand')

Package uses ESM default export. CommonJS require() will work but may need .default access depending on bundler.

varsBraceExpand

✓ import { varsBraceExpand } from 'vars-expand'

✗ import { varsBraceExpand } from 'vars-expand/varsBraceExpand'

Named export is aliased to default; both styles work identically.

VarsExpandOptions

✓ import type { VarsExpandOptions } from 'vars-expand'

TypeScript type export (if available in future versions; not present in 0.0.3). Currently no explicit type export.

Demonstrates shell-like variable expansion with default values using the varsBraceExpand function.

import varsBraceExpand from 'vars-expand'; const data = { NAME: 'Alice', GREETING: '', }; const template = `Hello, ${NAME:-World}! Today is ${DAY:-Monday}.`; const result = varsBraceExpand(template, data); console.log(result); // 'Hello, Alice! Today is Monday.'

Debug

Known issues

gotchaEmpty strings are treated as set, so ${VAR:-default} will not replace an empty VAR with default. Use ${VAR:?error} to flag empty variables.

fix

For empty string fallback, use ${VAR:-default} only if VAR is unset; to treat empty as unset, preprocess data or use a different operator.

affects: >=0.0.0

gotchaTemplate syntax uses backtick or single-quoted strings must be careful with JavaScript template literals to avoid double interpolation. Use \${} or raw strings.

fix

Use String.raw`...` or escape dollar signs in JavaScript to prevent premature interpolation.

affects: >=0.0.0

gotchaThe library only supports brace expansion syntax (${...}), not $VAR without braces. Attempting to use $VAR will leave it unexpanded.

fix

Always wrap variable names in curly braces: ${VAR}, not $VAR.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: varsBraceExpand is not a function

CommonJS require() returns an object with default property but is not directly callable in strict ESM environments.

fix

Use import varsBraceExpand from 'vars-expand' or const { default: varsBraceExpand } = require('vars-expand').

ReferenceError: VAR is not defined

Variable name in the template (${VAR}) does not exist in the data object and no default is provided.

fix

Provide a default value with ${VAR:-default} or ensure the variable exists in the data object.

SyntaxError: Invalid or unexpected token

Template contains a dollar sign that JavaScript interprets as template literal interpolation. Occurs when template is defined as a template literal (backticks) without escaping.

fix

Use String.raw`...` or escape $ as \$ in the template string.

Upgrade

Version history

0.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/allex/vars-expand ↗

packagehttps://www.npmjs.com/package/vars-expand ↗