@kagal/json-template

A TypeScript template engine for JSON documents with shell-style ${var:-default} variable substitution. Compiles once, renders to native JavaScript objects — types are preserved, not stringified.

Why

JavaScript template literals handle string interpolation well but don't understand JSON structure — a number like ${port} can silently become the string "8080", special characters in strings break JSON syntax, and there's no way to list which variables a template expects.

This engine treats JSON structure as a first-class concern. It parses the template at compile time, understands whether each variable sits in a bare value position or inside a string, and assembles a native JS object at render time — no string concatenation of JSON, no JSON.parse at render time.

Installation

npm install @kagal/json-template

Usage

import { compile } from '@kagal/json-template';

const tpl = compile(
  '{"host": "${host:-localhost}", "port": ${port:-3000}}'
);

tpl.render({});
// → { host: "localhost", port: 3000 }

tpl.render({ host: "10.0.0.1", port: 8080 });
// → { host: "10.0.0.1", port: 8080 }

tpl.toJSON({}, 2);
// → pretty-printed JSON string

Bare vs embedded variables

Bare variables (outside JSON strings) preserve their native type:

compile('{"port": ${port}}').render({ port: 8080 })
// → { port: 8080 }   ← number, not string

Embedded variables (inside "...") concatenate as strings:

compile('{"addr": "${host}:${port}"}')
  .render({ host: "localhost", port: 3000 })
// → { addr: "localhost:3000" }

The position is determined at compile time by tracking JSON string context, not with a runtime heuristic.

Shell-style defaults

Variables can specify a fallback value using the :- separator, matching POSIX shell parameter expansion:

compile(
  '{"host": "${host:-localhost}", "port": ${port:-3000}}'
).render({})
// → { host: "localhost", port: 3000 }

For bare variables, defaults are JSON-parsed to preserve type: ${port:-3000} defaults to the number 3000, ${flag:-true} to the boolean true. If the default isn't valid JSON, it falls back to a plain string.

For embedded variables, defaults are always treated as strings (they're inside a "..." already).

Defaults with nested JSON

Default values can contain nested JSON with balanced braces:

compile('{"cfg": ${cfg:-{"retries":3}}}').render({})
// → { cfg: { retries: 3 } }

Dotted key paths

Variable names can use dotted notation to traverse nested context objects. Resolution only follows own properties, so inherited keys like toString, constructor, and __proto__ are treated as missing:

compile('{"h": "${server.host}"}')
  .render({ server: { host: "10.0.0.1" } })
// → { h: "10.0.0.1" }

Static analysis

Extract variable metadata without compiling (does not require valid JSON):

import { listVariables } from '@kagal/json-template';

listVariables('{"a": "${name}", "b": ${port:-3000}}')
// → [
//   { name: "name", bare: false, ... },
//   { name: "port", bare: true, defaultValue: "3000", ... }
// ]

Strict mode

compile('{"v": ${required}}', { strict: true }).render({})
// throws UnresolvedVariableError

API

compile(template, options?)

Parses and compiles a JSON template string. Returns a Template instance.

const tpl = compile(
  '{"port": ${port:-3000}, "host": "${host:-localhost}"}'
);

tpl.variables  // readonly TemplateVariable[]
tpl.names      // ReadonlySet<string>

tpl.render({})              // → { port: 3000, ... }
tpl.render({ port: 8080 })  // → { port: 8080, ... }
tpl.toJSON({})              // → JSON string
tpl.toJSON({}, 2)           // → pretty-printed

Options:

| Option | Default | Description | |----------|---------|---------------------------------| | strict | false | Throw UnresolvedVariableError when a variable has no value and no default. When false, bare unresolved variables become null and embedded ones become "". |

listVariables(template)

Static analysis only — extracts variable metadata without requiring valid JSON. Useful for tooling, documentation generation, or validation.

listVariables('{"a": "${name}", "b": ${port:-3000}}')
// → [
//   { name: "name", bare: false, ... },
//   { name: "port", bare: true, ... }
// ]

TemplateVariable

Each variable occurrence exposes:

| Field | Type | Description | |----------------|-----------|------------------------| | raw | string | Full expression text | | name | string | Variable name | | defaultValue | string? | Raw default after :- | | bare | boolean | Bare vs embedded | | offset | number | $ offset in source |

Variable name rules

Names are dot-separated segments where each segment matches /^[a-zA-Z_][a-zA-Z0-9_-]*$/ — letters, digits, underscores, and hyphens, starting with a letter or underscore. Dots delimit path segments for nested context traversal.

Errors

| Error | When | |--------------------------|----------------------------| | TemplateParseError | Unterminated ${, empty expression, invalid name, variable in key, reserved sentinel character, or invalid JSON after extraction | | UnresolvedVariableError| strict: true and no value or default |

jsonNull

The null value used by bare unresolved variables (when strict is false). Use it when you need to explicitly pass or check for JSON null:

import { compile, jsonNull } from '@kagal/json-template';

compile('{"v": ${missing}}').render({})
// → { v: null }  (jsonNull)

isNull(value)

Type guard — returns true when value is null.

Unresolved variable behaviour

| Position | strict: true | strict: false | |--------------------|-----------------|-----------------| | Bare (no default) | throws | null | | Embedded (no def.) | throws | "" | | Any (with default) | uses default | uses default |

Embedded non-primitive coercion

When an object or array is resolved in an embedded (string) position, it is serialised via JSON.stringify rather than String():

compile('{"msg": "config=${cfg}"}')
  .render({ cfg: { retries: 3 } })
// → { msg: 'config={"retries":3}' }
//   not 'config=[object Object]'

Primitives (number, boolean, null) use String() as expected.

Provenance

Published with npm provenance via GitHub Actions OIDC — no long-lived tokens involved.

Licence

MIT