nano-var-template 1.0.0 → 2.0.1

package/README.md

@@ -1,83 +1,215 @@
 # nano-var-template
-The smallest safe variable template engine possible (without eval / new function / injecting ES6 backticks or other things you can't expose in userland).
 
-This engine even (optionally) throws descriptive errors if you type a variable path wrong.  Catch or route them as you see fit.
+The smallest safe variable template engine with N-pass composition.
 
-This template engine only handles variable injection into strings, just like ES6 backtick strings, but usable anywhere in your code. Designed specifically for userland.  Let your users define i18n strings, etc. without worry that they'll hack you.
+No `eval`. No `new Function`. No ES6 backtick injection. Just `String.replace()` with a configurable regex — safe for userland input.
 
-Supports full paths in variables, not just shallow variables. i.e. user.data.name.first
+## Why this exists
 
-805 bytes uncompressed source with comments.
-274 bytes minified/gzipped
+Most template engines are single-pass: they take a template and a data object and produce output. nano-var-template is a **composable pipeline**. You create multiple instances with different delimiters, and pipe the output of one into the next. Each pass resolves its own markers and leaves everything else untouched.
 
-This is written in ES6 for Node and modern tools like Webpack.  The code is so small and simple, feel free to refactor it for the browser or back to ES5 for IE11 / etc.
+This gives you layered abstraction:
 
-Pull requests are always welcome.
+```
+Pass 1  ${}   Raw data         →  ${user.name}  →  "Jane"
+Pass 2  #{}   Functions        →  #{avatar:jane.png}  →  "<img src='jane.png' />"
+Pass 3  @{}   User references  →  @{42}  →  "Jane Doe, Admin"
+Pass N  ~{}   Whatever you need next
+```
 
+Each pass's output can contain markers for subsequent passes, but never for prior ones. That's a directed pipeline — easy to reason about, easy to debug (inspect the string between passes), and it costs almost nothing to add another pass.
 
-## Install:
+**This is the core idea.** The package is small because it's finished, not because it's trivial.
 
-NPM
-```
-npm install nano-var-template
-```
+## Install
 
-Yarn
 ```
-yarn add nano-var-template
+npm install nano-var-template
 ```
 
-## Usage:
+## Quick start
 
-### Basic
-```
+```js
 const tpl = require('nano-var-template')()
-console.log(tpl("Hello {{user}}!", {user: "Jane Doe"}))
-```
 
-```
-Output: Hello Jane Doe!
+tpl("Hello ${name}!", { name: "Jane" })
+// → "Hello Jane!"
 ```
 
-### More practical
-```
+## Variable substitution
+
+Supports full nested paths:
+
+```js
 const tpl = require('nano-var-template')()
 
-let template = "Welcome to {{app}}. You are {{person.name.first}} {{person.name.last}}!"
-
-let data = {
-        app: "Super App",
-        person: {
-            name: {
-              first: "Jane",
-              last: "Doe"
-            }
-        }
-    }
-    
-console.log(tpl(template, data))
-```
+const template = "Welcome to ${app}. You are ${person.name.first} ${person.name.last}!"
+
+const data = {
+  app: "Super App",
+  person: {
+    name: { first: "Jane", last: "Doe" }
+  }
+}
 
+tpl(template, data)
+// → "Welcome to Super App. You are Jane Doe!"
 ```
-Output: Welcome to Super App. You are Jane Doe!
+
+## Custom delimiters
+
+```js
+// Vue/Angular style
+const tpl = require('nano-var-template')({ start: '{{', end: '}}' })
+tpl("Hello {{name}}!", { name: "Jane" })
+// → "Hello Jane!"
+
+// Anything you want
+const tpl2 = require('nano-var-template')({ start: '@#[', end: ']#' })
+tpl2("Hello @#[name]#!", { name: "Jane" })
+// → "Hello Jane!"
 ```
 
-### Change defaults to make it feel like ES6
+## Functions (plugins)
+
+Enable function mode to call named functions from templates. Everything after `:` is passed as the argument string:
+
+```js
+const tpl = require('nano-var-template')({ functions: true })
+
+const plugins = {
+  upper: s => s.toUpperCase(),
+  greet: name => `Welcome, ${name}!`,
+  badge: type => `<span class="badge badge-${type}">${type}</span>`
+}
+
+tpl("#{upper:hello}", plugins)
+// → "HELLO"
+
+tpl("#{greet:Jane}", plugins)
+// → "Welcome, Jane!"
+
+tpl("#{badge:admin}", plugins)
+// → '<span class="badge badge-admin">admin</span>'
 ```
-const tpl = require('nano-var-template')( {start: '${', end: '}'} )
-console.log(tpl("Hello ${user}!", {user: "Jane Doe"}))
+
+Functions can be as complex as you need — any JavaScript function works. Split multiple arguments yourself:
+
+```js
+const plugins = {
+  link: args => {
+    const [url, text] = args.split(',')
+    return `<a href="${url.trim()}">${text.trim()}</a>`
+  }
+}
+tpl("#{link:https://example.com, Click here}", plugins)
+// → '<a href="https://example.com">Click here</a>'
 ```
 
+## N-pass composition
+
+This is the architectural pattern that makes nano-var-template more than a string replacer. Create multiple instances with different delimiters and pipe them together:
+
+### Two-pass: variables then functions
+
+```js
+const Tpl = require('nano-var-template')
+const varTpl = Tpl()
+const fnTpl = Tpl({ functions: true })
+
+const template = "Hello #{greet:${name}}!"
+const data = { name: "Jane" }
+const plugins = { greet: name => `Welcome, ${name}` }
+
+// Pass 1: resolve ${} variables
+const pass1 = varTpl(template, data)
+// → "Hello #{greet:Jane}!"
+
+// Pass 2: resolve #{} functions (now with resolved data)
+const pass2 = fnTpl(pass1, plugins)
+// → "Hello Welcome, Jane!"
 ```
-Output: Hello Jane Doe!
+
+### Three-pass: variables, functions, and user references
+
+```js
+const Tpl = require('nano-var-template')
+const varTpl = Tpl()
+const fnTpl = Tpl({ functions: true })
+const userTpl = Tpl({ start: '@{', end: '}' })
+
+const template = "Hi @{${user.id}}! Avatar: #{avatar:${user.avatar}}"
+
+const data = { user: { id: '42', avatar: 'cat.png' } }
+const users = { 42: 'Jane Doe' }
+const plugins = { avatar: src => `<img src="${src}" />` }
+
+const result = userTpl(fnTpl(varTpl(template, data), plugins), users)
+// → 'Hi Jane Doe! Avatar: <img src="cat.png" />'
 ```
 
-### Make a mistake and get easy to understand debug errors
+### N-pass: as many layers as you need
+
+Each pass is the same ~10-line function with a different delimiter. Adding a 4th, 5th, or Nth pass costs essentially nothing. The only rule: **choose delimiters for each pass so that output from one pass doesn't accidentally contain markers for a later pass.** For example, if a function produces output containing `}`, use `]` or `)` as the closing delimiter for subsequent passes.
+
+```js
+const Tpl = require('nano-var-template')
+const dataTpl = Tpl()                                            // ${}
+const tagTpl = Tpl({ functions: true })                          // #{}
+const wrapTpl = Tpl({ start: '@{', end: '}', functions: true })  // @{}
+const frameTpl = Tpl({ start: '~(', end: ')' })                  // ~()
+
+const template = "~(before)@{wrap:#{tag:${word}}}~(after)"
+
+let result = template
+result = dataTpl(result, { word: "hello" })       // → "~(before)@{wrap:#{tag:hello}}~(after)"
+result = tagTpl(result, { tag: w => w.toUpperCase() }) // → "~(before)@{wrap:HELLO}~(after)"
+result = wrapTpl(result, { wrap: s => `[${s}]` })      // → "~(before)[HELLO]~(after)"
+result = frameTpl(result, { before: ">>>", after: "<<<" }) // → ">>>[HELLO]<<<"
 ```
+
+## Error handling
+
+By default, missing variables throw descriptive errors:
+
+```js
 const tpl = require('nano-var-template')()
-console.log(tpl("Hello ${user.name}!", {user: "Jane Doe"}))
+
+tpl("Hello ${user.name}!", { user: {} })
+// throws: "nano-var-template: 'name' missing in ${user.name}"
 ```
 
+Set `warn: false` to silently leave unresolved tokens in place:
+
+```js
+const tpl = require('nano-var-template')({ warn: false })
+
+tpl("Hello ${name}!", {})
+// → "Hello ${name}!"
 ```
-Output: Error: nano-var-template: 'name' missing in ${user.name}
+
+## Options
+
+```js
+const tpl = require('nano-var-template')({
+  start: '${',    // Opening delimiter (any string)
+  end: '}',       // Closing delimiter (any string)
+  functions: false, // true = function mode (data object contains functions, not values)
+  path: '[a-z0-9_$][\\.a-z0-9_]*',  // Regex for allowed variable paths
+  warn: true       // true = throw on missing variables, false = leave token unchanged
+})
 ```
+
+## Design notes
+
+**Why is this package so small?** Because it's a single, well-defined operation: regex match → path lookup → replace. There's nothing to add. The power comes from composing multiple instances, not from framework complexity.
+
+**Why N-pass instead of one big template engine?** Single-pass engines need to eagerly compute every possible variable upfront. N-pass composition is lazy — each pass only evaluates what the template actually uses. New functions don't bloat existing templates. Template authors compose building blocks without understanding the internals.
+
+**Is this the same idea as Unix pipes?** Yes. Each pass is a filter that transforms the string and passes it along. Same principle as compiler passes, middleware chains, and stream pipelines. The difference is that each filter ignores delimiters it doesn't own.
+
+**Delimiter design:** When piping passes together, choose delimiters so that output from one pass can't accidentally contain markers for a later pass. For example, if your functions produce HTML containing `}`, don't use `}` as the closing delimiter for subsequent passes — use `]`, `)`, or a multi-character sequence like `]]` instead.
+
+## License
+
+MIT

package/index.js

@@ -1,17 +1,54 @@
-// You can pass options to replace allowed variables, and the start and end brackets...
-module.exports = (options = { start: "{{", end: "}}", path: "[a-z0-9_$][\\.a-z0-9_]*", warn: true}) => {
-  const match = new RegExp(options.start + "\\s*(" + options.path + ")\\s*" + options.end, "gi")
+const escapeRegex = s => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+const Tpl = options => {
+  // You can pass options to overide defaults...
+  options = Object.assign(
+    {
+      start: options && options.functions
+      ? "#{"
+      : "${",
+      end: "}",
+      path:
+        options && options.functions
+          ? "[a-z0-9_$][: ,\\.a-z0-9_]*"
+          : "[a-z0-9_$][\\.a-z0-9_]*",
+      warn: true,
+      functions: false
+    },
+    options
+  )
+  const match = new RegExp(
+    escapeRegex(options.start) + "\\s*(" + options.path + ")\\s*" + escapeRegex(options.end),
+    "gi"
+  )
   return (template, data) => {
-    // Merge the passed data into the template strings...
+    // Merge the passed data into the template string we're sending back...
     return template.replace(match, (tag, token) => {
-      let path = token.split("."), lookup = data
+      var delim = options.functions ? ":" : "."
+      var path = token.split(delim),
+        lookup = data
+      if (options.functions) {
+        if (typeof data[path[0]] !== "function") {
+          if (options.warn) throw `nano-var-template: Missing function ${path}`
+          return tag
+        }
+        return data[path[0]](path[1])
+      }
       for (let i = 0; i < path.length; i++) {
+        if (lookup == null) {
+          if (options.warn) throw `nano-var-template: '${path[i]}' missing in ${tag}`
+          return tag
+        }
         lookup = lookup[path[i]]
         // Property not found
-        if (lookup === undefined && options.warn) throw "nano-var-template: '" + path[i] + "' missing in " + tag
+        if (lookup === undefined) {
+          if (options.warn) throw `nano-var-template: '${path[i]}' missing in ${tag}`
+          return tag
+        }
         // Return the required value
         if (i === path.length - 1) return lookup
       }
     })
   }
-} 
+}
+module.exports = Tpl

package/package.json

@@ -1,30 +1,36 @@
-{
-  "name": "nano-var-template",
-  "version": "1.0.0",
-  "description": "The smallest *safe* variable template engine for Javascript",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/onexdata/nano-var-template.git"
-  },
-  "keywords": [
-    "template",
-    "engine",
-    "variable",
-    "ES6",
-    "backticks",
-    "injection",
-    "inject",
-    "vars",
-    "variables"
-  ],
-  "author": "NIck Steele <njsteele@gmail.com>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/onexdata/nano-var-template/issues"
-  },
-  "homepage": "https://github.com/onexdata/nano-var-template#readme"
-}
+{
+  "name": "nano-var-template",
+  "version": "2.0.1",
+  "description": "The smallest and most robust *safe* variable template engine for Javascript",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onexdata/nano-var-template.git"
+  },
+  "keywords": [
+    "template",
+    "engine",
+    "variable",
+    "ES6",
+    "backticks",
+    "injection",
+    "inject",
+    "vars",
+    "variables",
+    "functions",
+    "userland",
+    "safe",
+    "scrubbed",
+    "XSS",
+    "strategy"
+  ],
+  "author": "NIck Steele <njsteele@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/onexdata/nano-var-template/issues"
+  },
+  "homepage": "https://github.com/onexdata/nano-var-template#readme"
+}

package/test/index.test.js

@@ -0,0 +1,438 @@
+const { describe, it } = require("node:test")
+const assert = require("node:assert/strict")
+const Tpl = require("../index")
+
+// ─── Basic variable substitution ────────────────────────────────────────────
+
+describe("basic variable substitution", () => {
+  const tpl = Tpl()
+
+  it("replaces a single variable", () => {
+    assert.equal(tpl("Hello ${name}!", { name: "Jane" }), "Hello Jane!")
+  })
+
+  it("replaces multiple variables", () => {
+    assert.equal(
+      tpl("${greeting} ${name}!", { greeting: "Hi", name: "Jane" }),
+      "Hi Jane!"
+    )
+  })
+
+  it("replaces the same variable used multiple times", () => {
+    assert.equal(
+      tpl("${x} and ${x}", { x: "ok" }),
+      "ok and ok"
+    )
+  })
+
+  it("leaves non-matching text untouched", () => {
+    assert.equal(tpl("no vars here", {}), "no vars here")
+  })
+
+  it("handles empty template string", () => {
+    assert.equal(tpl("", { x: 1 }), "")
+  })
+
+  it("handles template with no matching vars in data", () => {
+    // warn defaults to true, so missing var throws
+    assert.throws(() => tpl("${missing}", {}), /missing/)
+  })
+})
+
+// ─── Nested path access ────────────────────────────────────────────────────
+
+describe("nested path access", () => {
+  const tpl = Tpl()
+
+  it("resolves a two-level path", () => {
+    assert.equal(
+      tpl("${user.name}", { user: { name: "Jane" } }),
+      "Jane"
+    )
+  })
+
+  it("resolves a deep path", () => {
+    const data = { a: { b: { c: { d: "deep" } } } }
+    assert.equal(tpl("${a.b.c.d}", data), "deep")
+  })
+
+  it("throws on missing intermediate property (warn: true)", () => {
+    assert.throws(
+      () => tpl("${user.name}", { user: {} }),
+      /name.*missing/
+    )
+  })
+
+  it("throws when traversing through a non-object (warn: true)", () => {
+    assert.throws(
+      () => tpl("${user.name.first}", { user: { name: "Jane" } }),
+      /first.*missing/
+    )
+  })
+})
+
+// ─── Falsy but valid values ─────────────────────────────────────────────────
+
+describe("falsy but valid values", () => {
+  const tpl = Tpl()
+
+  it("resolves 0", () => {
+    assert.equal(tpl("${count}", { count: 0 }), "0")
+  })
+
+  it("resolves false", () => {
+    assert.equal(tpl("${flag}", { flag: false }), "false")
+  })
+
+  it("resolves empty string", () => {
+    assert.equal(tpl("${empty}", { empty: "" }), "")
+  })
+
+  it("resolves null (returns 'null' as string)", () => {
+    // null is a valid value — String.replace coerces to "null"
+    assert.equal(tpl("${val}", { val: null }), "null")
+  })
+})
+
+// ─── warn: false (silent mode) ─────────────────────────────────────────────
+
+describe("warn: false (silent mode)", () => {
+  const tpl = Tpl({ warn: false })
+
+  it("returns original tag for missing top-level variable", () => {
+    assert.equal(tpl("Hello ${name}!", {}), "Hello ${name}!")
+  })
+
+  it("returns original tag for missing nested property", () => {
+    assert.equal(
+      tpl("${user.name}", { user: {} }),
+      "${user.name}"
+    )
+  })
+
+  it("returns original tag when traversing through null", () => {
+    assert.equal(
+      tpl("${a.b.c}", { a: { b: null } }),
+      "${a.b.c}"
+    )
+  })
+
+  it("returns original tag when traversing through a primitive", () => {
+    assert.equal(
+      tpl("${user.name.first}", { user: { name: "Jane" } }),
+      "${user.name.first}"
+    )
+  })
+
+  it("still resolves variables that do exist", () => {
+    assert.equal(
+      tpl("${found} ${missing}", { found: "yes" }),
+      "yes ${missing}"
+    )
+  })
+})
+
+// ─── Custom delimiters ─────────────────────────────────────────────────────
+
+describe("custom delimiters", () => {
+  it("supports {{ }} (Vue/Angular style)", () => {
+    const tpl = Tpl({ start: "{{", end: "}}" })
+    assert.equal(tpl("Hello {{name}}!", { name: "Jane" }), "Hello Jane!")
+  })
+
+  it("supports @#[ ]# (arbitrary custom)", () => {
+    const tpl = Tpl({ start: "@#[", end: "]#" })
+    assert.equal(tpl("Hello @#[name]#!", { name: "Jane" }), "Hello Jane!")
+  })
+
+  it("supports delimiters with regex special characters", () => {
+    const tpl = Tpl({ start: "$(", end: ")" })
+    assert.equal(tpl("Hello $(name)!", { name: "Jane" }), "Hello Jane!")
+  })
+
+  it("supports [ ] delimiters", () => {
+    const tpl = Tpl({ start: "[", end: "]" })
+    assert.equal(tpl("Hello [name]!", { name: "Jane" }), "Hello Jane!")
+  })
+
+  it("supports single-char delimiters", () => {
+    const tpl = Tpl({ start: "%", end: "%" })
+    assert.equal(tpl("Hello %name%!", { name: "Jane" }), "Hello Jane!")
+  })
+})
+
+// ─── Whitespace handling ────────────────────────────────────────────────────
+
+describe("whitespace in tokens", () => {
+  const tpl = Tpl()
+
+  it("handles leading whitespace inside delimiters", () => {
+    assert.equal(tpl("Hello ${ name}!", { name: "Jane" }), "Hello Jane!")
+  })
+
+  it("handles trailing whitespace inside delimiters", () => {
+    assert.equal(tpl("Hello ${name }!", { name: "Jane" }), "Hello Jane!")
+  })
+
+  it("handles whitespace on both sides", () => {
+    assert.equal(tpl("Hello ${ name }!", { name: "Jane" }), "Hello Jane!")
+  })
+})
+
+// ─── Case sensitivity ───────────────────────────────────────────────────────
+
+describe("case sensitivity", () => {
+  const tpl = Tpl()
+
+  it("matches variable names case-insensitively in the template", () => {
+    // regex has 'i' flag so ${NAME} matches, but token preserves original case
+    // for data lookup — so data key must match the template's case
+    assert.equal(tpl("${Name}", { Name: "Jane" }), "Jane")
+  })
+
+  it("data key case must match template token case", () => {
+    // ${NAME} looks up data["NAME"], not data["name"]
+    assert.throws(() => tpl("${NAME}", { name: "Jane" }))
+  })
+})
+
+// ─── Function / plugin mode ────────────────────────────────────────────────
+
+describe("function mode", () => {
+  const tpl = Tpl({ functions: true })
+
+  it("calls a function with no arguments", () => {
+    const plugins = { greet: () => "Hello!" }
+    assert.equal(tpl("#{greet}", plugins), "Hello!")
+  })
+
+  it("calls a function with a string argument", () => {
+    const plugins = { upper: s => s.toUpperCase() }
+    assert.equal(tpl("#{upper:hello}", plugins), "HELLO")
+  })
+
+  it("passes everything after : as the argument string", () => {
+    const plugins = { echo: s => s }
+    assert.equal(
+      tpl("#{echo:a, b, c}", plugins),
+      "a, b, c"
+    )
+  })
+
+  it("function receives undefined when no argument given", () => {
+    const plugins = {
+      check: arg => (arg === undefined ? "none" : arg)
+    }
+    assert.equal(tpl("#{check}", plugins), "none")
+  })
+
+  it("throws on missing function (warn: true)", () => {
+    assert.throws(() => tpl("#{nope}", {}), /Missing function/)
+  })
+
+  it("returns original tag on missing function (warn: false)", () => {
+    const quietTpl = Tpl({ functions: true, warn: false })
+    assert.equal(quietTpl("#{nope}", {}), "#{nope}")
+  })
+
+  it("returns original tag when value is not a function (warn: false)", () => {
+    const quietTpl = Tpl({ functions: true, warn: false })
+    assert.equal(quietTpl("#{notfn}", { notfn: "string" }), "#{notfn}")
+  })
+
+  it("supports custom function delimiters", () => {
+    const tpl2 = Tpl({ functions: true, start: "@{", end: "}" })
+    const plugins = { greet: () => "Hi" }
+    assert.equal(tpl2("@{greet}", plugins), "Hi")
+  })
+})
+
+// ─── Multi-pass composition (the core architectural pattern) ────────────────
+
+describe("multi-pass composition", () => {
+  it("two-pass: variables then functions", () => {
+    const varTpl = Tpl()
+    const fnTpl = Tpl({ functions: true })
+
+    const template = "Hello #{greet:${name}}!"
+    const data = { name: "Jane" }
+    const plugins = { greet: name => `Welcome, ${name}` }
+
+    // Pass 1: resolve ${} variables
+    const pass1 = varTpl(template, data)
+    assert.equal(pass1, "Hello #{greet:Jane}!")
+
+    // Pass 2: resolve #{} functions
+    const pass2 = fnTpl(pass1, plugins)
+    assert.equal(pass2, "Hello Welcome, Jane!")
+  })
+
+  it("three-pass: variables, then functions, then user references", () => {
+    const varTpl = Tpl()
+    const fnTpl = Tpl({ functions: true })
+    const userTpl = Tpl({ start: "@{", end: "}" })
+
+    const template = "Hi @{${user.id}}! Avatar: #{avatar:${user.avatar}}"
+    const data = { user: { id: "42", avatar: "cat.png" } }
+    const users = { 42: "Jane Doe" }
+    const plugins = { avatar: src => `<img src="${src}" />` }
+
+    // Pass 1: resolve ${} variables
+    const pass1 = varTpl(template, data)
+    assert.equal(pass1, 'Hi @{42}! Avatar: #{avatar:cat.png}')
+
+    // Pass 2: resolve #{} functions
+    const pass2 = fnTpl(pass1, plugins)
+    assert.equal(pass2, 'Hi @{42}! Avatar: <img src="cat.png" />')
+
+    // Pass 3: resolve @{} user references
+    const pass3 = userTpl(pass2, users)
+    assert.equal(pass3, 'Hi Jane Doe! Avatar: <img src="cat.png" />')
+  })
+
+  it("four-pass: data → components → layout → final", () => {
+    // Four passes with simple string values to demonstrate N-pass depth.
+    // Note: function arguments are constrained by the path regex, so each
+    // pass that uses functions should receive simple alphanumeric args.
+    // The final assembly into complex output (HTML etc.) happens at the
+    // last function pass, or via variable passes which have no such limit.
+    const dataTpl = Tpl()                                          // pass 1: ${}
+    const tagTpl = Tpl({ functions: true })                        // pass 2: #{}
+    const wrapTpl = Tpl({ start: "@{", end: "}", functions: true })// pass 3: @{}
+    const frameTpl = Tpl({ start: "~(", end: ")" })                // pass 4: ~()
+
+    const template = "~(before)@{wrap:#{tag:${word}}}~(after)"
+
+    // Pass 1: resolve ${} — inject raw data
+    const p1 = dataTpl(template, { word: "hello" })
+    assert.equal(p1, "~(before)@{wrap:#{tag:hello}}~(after)")
+
+    // Pass 2: resolve #{} — tag function transforms the word
+    const p2 = tagTpl(p1, { tag: w => w.toUpperCase() })
+    assert.equal(p2, "~(before)@{wrap:HELLO}~(after)")
+
+    // Pass 3: resolve @{} — wrap function adds decoration
+    const p3 = wrapTpl(p2, { wrap: s => `[${s}]` })
+    assert.equal(p3, "~(before)[HELLO]~(after)")
+
+    // Pass 4: resolve ~() — inject frame variables
+    const p4 = frameTpl(p3, { before: ">>>", after: "<<<" })
+    assert.equal(p4, ">>>[HELLO]<<<")
+  })
+
+  it("passes are order-independent — later delimiters survive earlier passes", () => {
+    const pass1 = Tpl()
+    const pass2 = Tpl({ functions: true })
+
+    // #{} tokens survive pass 1 because pass 1 only matches ${}
+    const template = "#{fn:${val}}"
+    const result1 = pass1(template, { val: "x" })
+    assert.equal(result1, "#{fn:x}")
+
+    // ${} tokens would NOT survive pass 2 if any remained — but they don't
+    const result2 = pass2(result1, { fn: v => v.toUpperCase() })
+    assert.equal(result2, "X")
+  })
+})
+
+// ─── Edge cases ─────────────────────────────────────────────────────────────
+
+describe("edge cases", () => {
+  const tpl = Tpl()
+
+  it("handles variables at start of string", () => {
+    assert.equal(tpl("${x}!", { x: "hi" }), "hi!")
+  })
+
+  it("handles variables at end of string", () => {
+    assert.equal(tpl("say ${x}", { x: "hi" }), "say hi")
+  })
+
+  it("handles adjacent variables with no separator", () => {
+    assert.equal(tpl("${a}${b}", { a: "1", b: "2" }), "12")
+  })
+
+  it("handles numeric values", () => {
+    assert.equal(tpl("count: ${n}", { n: 42 }), "count: 42")
+  })
+
+  it("handles boolean values", () => {
+    assert.equal(tpl("${a} ${b}", { a: true, b: false }), "true false")
+  })
+
+  it("handles underscore and $ in variable names", () => {
+    assert.equal(tpl("${_private}", { _private: "yes" }), "yes")
+    assert.equal(tpl("${$special}", { $special: "yes" }), "yes")
+  })
+
+  it("does not match empty delimiters", () => {
+    // ${} has no valid path inside — regex requires at least one char
+    assert.equal(tpl("${}", {}), "${}")
+  })
+})
+
+// ─── Regex escaping in delimiters ───────────────────────────────────────────
+
+describe("regex-safe delimiters", () => {
+  it("handles $( ) which contains regex special chars", () => {
+    const tpl = Tpl({ start: "$(", end: ")" })
+    assert.equal(tpl("$(name)", { name: "Jane" }), "Jane")
+  })
+
+  it("handles [ ] which are regex character class markers", () => {
+    const tpl = Tpl({ start: "[", end: "]" })
+    assert.equal(tpl("[name]", { name: "Jane" }), "Jane")
+  })
+
+  it("handles pipes | which are regex alternation", () => {
+    const tpl = Tpl({ start: "|", end: "|" })
+    assert.equal(tpl("|name|", { name: "Jane" }), "Jane")
+  })
+
+  it("handles ${{ }} (double-brace like GitHub Actions)", () => {
+    const tpl = Tpl({ start: "${{", end: "}}" })
+    assert.equal(tpl("Hello ${{ name }}!", { name: "Jane" }), "Hello Jane!")
+  })
+})
+
+// ─── Independent instance isolation ─────────────────────────────────────────
+
+describe("instance isolation", () => {
+  it("two instances with different delimiters don't interfere", () => {
+    const tplA = Tpl({ start: "${", end: "}" })
+    const tplB = Tpl({ start: "{{", end: "}}" })
+
+    assert.equal(tplA("${x} and {{y}}", { x: "A" }), "A and {{y}}")
+    assert.equal(tplB("${x} and {{y}}", { y: "B" }), "${x} and B")
+  })
+
+  it("variable and function instances are independent", () => {
+    const varTpl = Tpl()
+    const fnTpl = Tpl({ functions: true })
+
+    // varTpl ignores #{} and fnTpl ignores ${}
+    assert.equal(varTpl("${x} #{fn}", { x: "hi" }), "hi #{fn}")
+    assert.equal(fnTpl("${x} #{fn}", { fn: () => "called" }), "${x} called")
+  })
+})
+
+// ─── Error messages ─────────────────────────────────────────────────────────
+
+describe("error messages", () => {
+  const tpl = Tpl()
+
+  it("includes the variable path in the error", () => {
+    assert.throws(
+      () => tpl("${user.name}", { user: {} }),
+      err => err.includes("name") && err.includes("${user.name}")
+    )
+  })
+
+  it("includes 'Missing function' for function mode errors", () => {
+    const fnTpl = Tpl({ functions: true })
+    assert.throws(
+      () => fnTpl("#{nope}", {}),
+      err => err.includes("Missing function")
+    )
+  })
+})