@nejs/yamltag

A string-tag processor for YAML. Tag a template literal with yaml (or its alias yml) and get back the parsed JavaScript value — with any interpolated ${value} injected by identity instead of being stitched into the source text.

import { yaml } from '@nejs/yamltag'

const limits = { cpu: '500m', memory: '256Mi' }

const config = yaml`
  name: my-service
  retries: ${3}
  limits: ${limits}
`

config.retries        // 3            (a number, not the string "3")
config.limits === limits  // true     (the exact same object reference)

Why a tag?

Most YAML helpers take a string and parse it. That forces you to serialize your data into YAML text first, which is awkward and lossy — a Date becomes a string, an object has to be indented correctly, and untrusted values can break the document's structure.

yamltag works the other way around. Your interpolated values never touch the YAML parser. Each ${value} is swapped for a private placeholder token, the surrounding YAML is parsed, and then the real values are slotted back into the result. Objects, arrays, Dates, and other references survive untouched.

Install

npm install @nejs/yamltag

Requires an ES-module environment ("type": "module" or .mjs). Node 14+.

Import

Pick whichever name reads best in your code. yaml and yml are the same function — both a named export, plus a default export — so you never need a dynamic import or a local rename.

import yaml from '@nejs/yamltag'          // default
import { yaml } from '@nejs/yamltag'        // named
import { yml } from '@nejs/yamltag'         // alias, identical to yaml
import { yaml, yml } from '@nejs/yamltag'   // both

Usage

As a tag

import { yaml } from '@nejs/yamltag'

const obj = yaml`
  name: widget
  count: 3
  tags:
    - a
    - b
`
// { name: 'widget', count: 3, tags: ['a', 'b'] }

Injecting values

A ${value} that occupies an entire scalar keeps its JavaScript identity:

const ports = [80, 443]
const when  = new Date('2026-06-01T12:00:00Z')

const result = yaml`
  ports: ${ports}
  startedAt: ${when}
`

result.ports === ports          // true
result.startedAt instanceof Date  // true — not round-tripped to a string

A ${value} embedded inside other text is coerced with String(value), matching ordinary template-literal intuition:

const name = 'world'
yaml`greeting: hello ${name}!`   // { greeting: 'hello world!' }

const n = 42
yaml`label: item-${n}-end`       // { label: 'item-42-end' }

Configuring behavior

Call the tag with an options object first to get a configured tag. This works because the function detects whether it was called as a template tag or as a plain configurator.

const safeYaml = yaml({ throws: false })

safeYaml`name: ok`     // { name: 'ok' }
safeYaml`: : : broken` // null  (instead of throwing)

You can also configure inline:

yaml({ throws: false })`value: 1`   // { value: 1 }

Options

| Option | Type | Default | Behavior | | -------- | --------- | ------- | --------------------------------------------------------------------- | | throws | boolean | true | On a parse error: true rethrows the error; false returns null. |

Behavior notes

• Whole-value vs. embedded interpolation. A ${value} that is the entire scalar preserves identity; a ${value} that is part of a longer string is string-coerced. If you need a structured value, give it its own line/scalar.
• Errors. By default, YAML parse errors propagate from the underlying parser (js-yaml). Use { throws: false } to receive null instead.
• Empty documents. An empty template parses to undefined; a comment-only template parses to null — matching what the underlying js-yaml parser returns in each case.

API

yaml`...` / yml`...`

Used as a template tag, returns the parsed JavaScript value with interpolated values restored.

yaml(options) → tag

Used as a configurator, returns a new tag function bound to the given options.

Testing

npm test          # run once
npm run test:watch

License

MIT © Brielle Harrison