jtlt 0.18.0 → 0.20.0

package/docs/API.expanded.md

@@ -59,8 +59,9 @@ Common to both entry points unless noted.
 | ------ | ---- | ----------- |
 | `data` | object \| primitive | Root JSON/JS value (or DOM `Document`/`Element` for the XPath engine). Required unless `ajaxData` provided. |
 | `ajaxData` | string | URL to fetch JSON (async start). |
-| `templates` | Array<TemplateObject> | Template declarations; see below. |
+| `templates` | Array<TemplateObject> \| TemplateObject \| [path, Function\|Array] | Template declarations; see below. A bare `TemplateObject` or `[path, template]` tuple (not wrapped in an outer array) is also accepted directly. |
 | `template` | Function \| TemplateObject | Single root template convenience. |
+| `defaultTemplateFormat` | 'json' \| 'javascript' | JSONPath engine only. Jamilih validation strictness applied to a declarative (`Array`) `template` when its own `format` isn't set. Default `'json'`. See "Declarative (jamilih-shaped) templates" below. |
 | `query` | Function | Root template convenience (wrapped as `path: '$'`). |
 | `forQuery` | [select, cb] | One-off query (like FLWOR `for`). Auto-wrapped as root template. |
 | `success` | Function(result) | **`JTLT` only** — required callback; also the return of `.transform()`. Not accepted by `jtlt()`. |
@@ -97,6 +98,91 @@ Edge cases:
 - For XPath: `//item`, `/root/item`, `//*[@id='x']`.
 - Root template: path `$` (JSONPath) or `/` (XPath).
 
+## Declarative (jamilih-shaped) templates
+
+JSONPath engine only. A `TemplateObject.template` may be an `Array` of
+declarative nodes — modeled on [jamilih](https://github.com/brettz9/jamilih)'s
+own JSON/JS-array HTML/XML construction syntax — instead of a `Function`.
+`compileJSONTemplate()` compiles it once, up front, into an ordinary
+`TemplateFunction`; every other API (`applyTemplates`, `callTemplate`, modes,
+priority, …) works the same regardless of which form a matched template uses.
+
+```js
+const out = await jtlt({
+  data: {name: 'Ada'},
+  outputType: 'string',
+  templates: {
+    path: '$',
+    template: [
+      ['h1', ['Hello']],
+      [{$valueOf: '$.name'}]
+    ]
+  }
+});
+// -> <h1>Hello</h1>Ada
+```
+
+A node is one of:
+
+| Node | Emits |
+| --- | --- |
+| `"text"` (a plain string) | a text node |
+| `[name, attrs?, children?]` | an element — `attrs` is omitted when there are none, in which case the second item is the children array directly |
+| `[{$text: value}]` | `this.text(value)` — jamilih's own native text-node form; bare only, no `$select` |
+| `[{$jtltText: value, $select?: sel}]` | `this.text(value)` (no `$select`) or `this.valueOf(sel)` (with `$select`) — the general/canonical form of `$text` |
+| `[{$string: value, $select?: sel}]` | `this.string(value)` or, with `$select`, the selected value stringified |
+| `[{$valueOf: sel}]` | `this.valueOf(sel)` |
+| `[{$applyTemplates: sel, $jtltMode?: mode, $sort?: sort}]` | `this.applyTemplates(sel, mode, sort)` |
+| `[{$if: sel}, thenNodes, elseNodes?]` | `this.if(sel, cb)` or, with an else, `this.choose(sel, whenCb, otherwiseCb)` |
+| `[{$forEach: sel, $sort?: sort}, childNodes]` | `this.forEach(sel, cb, sort)` |
+| `[{$variable: name, $select: sel}]` | `this.variable(name, sel)`, readable back later via a bare `$name` reference |
+| `[{$indexedDB: {db, store, options?}, $as?: name}, childNodes?]` | fetches rows; with `$as`, binds them via `this.variable(name, {value: rows})`; without it, swaps the data context (`$`) to the rows for `childNodes` |
+| `[{$renderDefault: true}]` | `this.appendOutput(await this.renderDefault())` (an `extensions.renderDefault` your config supplies) |
+
+Every operation node's leading object is entirely `$`-prefixed — jamilih's
+own validator requires this of any first-position plain object. `$jtltMode`/
+`$jtltText` are namespaced because jamilih itself reserves `$mode` outright
+and gives `$text` its own (bare-only) native meaning; see the README's
+["Differences between an exact equivalence with
+XSLT"](../README.md#differences-between-an-exact-equivalence-with-xslt)
+section for why `template`, an `$if`/`$forEach` body, and an operation
+node's own trailing arguments are each *arrays* — including the
+easy-to-miss case of a single node or a single sibling, which still needs
+its wrapping array.
+
+`$indexedDB`/`$renderDefault` may appear nested anywhere a node is
+allowed — inside an element's children, or a `$if`/`$forEach` body — not
+just at a template's top level; see the README section above for why.
+
+**Validation**: `format: 'json'` (the default) rejects an embedded live
+function/DOM node anywhere in the tree — the intent is a safely
+serializable structure (e.g. round-tripped through IndexedDB), not
+arbitrary JavaScript. Pass `format: 'javascript'` on the `TemplateObject`
+(or set `defaultTemplateFormat: 'javascript'` on the config to relax every
+entry lacking its own `format`) to allow one.
+
+**Exports** (from `'jtlt'`):
+- `compileJSONTemplate(nodes, {format?}) => TemplateFunction` — throws a
+  `TypeError` with every problem found if `nodes` is invalid.
+- `validateJSONTemplate(nodes, {format?}) => {valid, errors}` — the same
+  checks, non-executing and non-throwing; for a "validate before save"
+  editor workflow. Includes `extractReads()`'s errors, below — an
+  unresolvable `$indexedDB` target makes the whole template invalid, not
+  just a `reads` omission.
+- `extractReads(nodes) => {reads: {db, store}[], errors}` — statically
+  derives the `{db, store}` targets every `$indexedDB` node in the tree
+  touches (walking element children, `$if`/`$forEach` bodies, and another
+  `$indexedDB` node's own children — not just the top level), deduplicated.
+  Total: an `$indexedDB` node whose `db`/`store` isn't a literal,
+  non-empty string is reported as an error rather than silently omitted
+  from `reads` — the point is to drive a data-access allowlist, so an
+  unresolvable target must never read as "no read happens here." Useful on
+  its own (not just via `validateJSONTemplate`) for computing the actual
+  `reads` value to store alongside a saved template.
+- `isJSONTemplateNodeArray(x) => boolean` — `Array.isArray`, exported for
+  callers that need to detect the declarative form themselves (e.g. before
+  deciding whether to call `compileJSONTemplate`).
+
 ## Engines
 
 ### `JSONPathTransformer`

package/docs/API.md

@@ -181,6 +181,27 @@ this.applyTemplates('$.items[*]');
 
 This is useful for strict template matching where ambiguity should be an error rather than silently choosing a template, or for development where warnings help identify potential issues.
 
+## Declarative (jamilih-shaped) templates
+
+JSONPath engine only. `template` may be an `Array` of jamilih-shaped nodes
+instead of a `Function` — compiled once via `compileJSONTemplate()`
+(also exported, along with `validateJSONTemplate()` for non-executing
+validation, `extractReads()` for statically deriving the `{db, store}`
+targets its `$indexedDB` nodes touch, and `isJSONTemplateNodeArray()`):
+
+```js
+const templates = {path: '$', template: [
+  ['h1', ['Hello']],
+  [{$valueOf: '$.name'}]
+]};
+// -> <h1>Hello</h1>Ada
+```
+
+`format: 'json'` (default) rejects an embedded live function/DOM node
+anywhere in the tree; `format: 'javascript'` (per-entry, or
+`defaultTemplateFormat` on the config) allows one. See
+`docs/API.expanded.md` for the full node vocabulary.
+
 ## Sorting
 
 Path string (ascending text), comparator function, object spec

package/docs/TO-DO.md

@@ -4,10 +4,12 @@
 
 1. Document
 
+    1. Write a specification for declarative jamilih / jtlt?
+
     1.  Implement and demo equivalent to applying and calling templates, and
         root template
 
-    2.  Demo chaining of methods, including [equivalents](https://www.saxonica.com/papers/XTech2005/mhkpaper.html#S4.)
+    1.  Demo chaining of methods, including [equivalents](https://www.saxonica.com/papers/XTech2005/mhkpaper.html#S4.)
         to XQuery's FLWOR expressions (see also Promises to-do), perhaps
         even making aliases so that XQuery's friendlier terms can be used
         instead of XSLT's.
@@ -41,10 +43,12 @@
     through [HTTPQuery](https://github.com/brettz9/httpquery) (and also
     supply to JSONEditor, etc.). Utilize updating by reference.
 
-8. Demo narrowing to subset of JavaScript (as with `jsep`) to make
+## Possible to-dos
+
+1. Demo narrowing to subset of JavaScript (as with `jsep`) to make
     JTLT truly "declarative" as far as freedom from scripting
 
-## Possible to-dos
+1. Support XPath and Declarative Jamilih
 
 1. Make schema-aware so that templates could target types. Most reusable
     application may be having a type-driven view of a JSON Schema instance
@@ -112,6 +116,7 @@ We'd otherwise have to refactor a great deal to maintain a buffer.
   xsl:break
   xsl:catch
   xsl:context-item
+  ~~"xsl:document",~~ (not yet exposed)
   xsl:evaluate
   xsl:expose
   "xsl:fallback",
@@ -139,6 +144,8 @@ We'd otherwise have to refactor a great deal to maintain a buffer.
   xsl:use-package
   xsl:where-populated
 
+  // Todo: Some of these may be implemented but not yet exposed
+
   ~~"xsl:analyze-string",~~
   ~~"xsl:apply-templates",~~
   ~~xsl:assert~~
@@ -151,7 +158,6 @@ We'd otherwise have to refactor a great deal to maintain a buffer.
   ~~"xsl:copy",~~
   ~~"xsl:copy-of",~~
   ~~"xsl:decimal-format",~~
-  ~~"xsl:document",~~
   ~~"xsl:element",~~
   ~~"xsl:for-each",~~
   ~~"xsl:for-each-group",~~

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jtlt",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "author": "Brett Zamir",
   "contributors": [],
@@ -39,7 +39,7 @@
     "codemirror": "^6.0.2",
     "fontoxpath": "^3.34.0",
     "idb": "^8.0.3",
-    "jamilih": "0.69.1",
+    "jamilih": "0.70.0",
     "jhtml": "0.7.3",
     "jsdom": "30.0.1",
     "jsonpath-plus": "10.4.0",
@@ -51,17 +51,17 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@node-static/node-static": "^0.9.1",
+    "@node-static/node-static": "^0.9.2",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@types/chai": "^5.2.3",
     "@types/jsdom": "^30.0.0",
     "@types/mocha": "^10.0.10",
-    "baseline-browser-mapping": "^2.11.21",
+    "baseline-browser-mapping": "^2.11.22",
     "c8": "^12.0.0",
     "chai": "^6.2.2",
     "eslint": "^10.10.0",
-    "eslint-config-ash-nazg": "^43.1.7",
-    "indexeddbshim": "^19.0.1",
+    "eslint-config-ash-nazg": "^43.1.8",
+    "indexeddbshim": "^19.0.2",
     "mocha": "^12.0.0",
     "open": "^11.0.2",
     "rollup": "^4.63.1",

package/pnpm-workspace.yaml

@@ -35,7 +35,10 @@ minimumReleaseAgeExclude:
   - eslint-config-ash-nazg@43.1.0 || 43.1.6
   - eslint-plugin-escompat@3.12.0
   - eslint-plugin-jsdoc@64.3.0 || 64.3.3
-  - indexeddbshim@17.4.1 || 17.4.2 || 17.4.3 || 17.5.0 || 17.6.0
+  - indexeddbshim@17.4.1 || 17.4.2 || 17.4.3 || 17.5.0 || 17.6.0 || 19.0.2
   - open@11.0.2
   - powershell-utils@0.2.1
   - websql-configurable@4.0.0
+  - '@node-static/node-static@0.9.2'
+  - baseline-browser-mapping@2.11.22
+  - jamilih@0.70.0

package/src/DOMJoiningTransformer.js

@@ -2,9 +2,11 @@ import * as JHTML from 'jhtml';
 import AbstractJoiningTransformer from './AbstractJoiningTransformer.js';
 
 /**
- * @callback SimpleCallback
- * @this {DOMJoiningTransformer}
- * @returns {void}
+ * A `@callback` tag combined with `@this` mis-emits in `dist/*.d.ts` (the
+ * `@this` type lands as raw, unparsed JSDoc text) — see the equivalent note
+ * in `JSONJoiningTransformer.js`; this inline `@typedef {(this: ...) =>
+ * ...}` function-type form emits correctly instead.
+ * @typedef {(this: DOMJoiningTransformer) => void} SimpleCallback
  */
 
 /* eslint-disable @stylistic/max-len -- Long */
@@ -300,7 +302,7 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
    * @overload
    * @param {Element|string} elName
    * @param {(this: DOMJoiningTransformer) => void} cb
-   * @returns {DOMJoiningTransformer}
+   * @returns {DOMJoiningTransformer|Promise<DOMJoiningTransformer>}
    */
   /**
    * @overload
@@ -314,9 +316,15 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
    *   childNodes, or callback
    * @param {(Node|string)[]|((this: DOMJoiningTransformer) => void)
    *   } [childNodes] - Child nodes or callback
-   * @param {(this: DOMJoiningTransformer) => void} [cb] - Callback
+   * @param {(this: DOMJoiningTransformer) => void} [cb] -
+   *   Callback; may be async (e.g. to `await` a `$indexedDB` fetch), in
+   *   which case `element()` itself returns a `Promise` instead of `this`.
+   *   (Typed as returning plain `void`, not `void|Promise<void>` — a union
+   *   there would lose TypeScript's usual "a void-returning callback
+   *   parameter accepts any actual return value" leniency, which existing
+   *   callers rely on for e.g. `() => this.text(...)` concise arrows.)
    * @param {string[]} [useAttributeSets] - Attribute set names to apply
-   * @returns {DOMJoiningTransformer}
+   * @returns {DOMJoiningTransformer|Promise<DOMJoiningTransformer>}
    */
   element (elem, atts, childNodes, cb, useAttributeSets) {
     // Handle argument overloading like other transformers
@@ -440,12 +448,24 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
         }
       }
 
+      const finishRoot = () => {
+        this._dom = oldDOM;
+        return this;
+      };
       if (cb) {
-        cb.call(this._context || this);
+        // `cb`'s declared return type is plain `void` (see the parameter's
+        // JSDoc), preserving TypeScript's void-return leniency for
+        // callers — cast here to duck-type the real value.
+        const cbResult = /** @type {any} */ (cb.call(this._context || this));
+        // `cb` may be an async function (e.g. one that awaits a
+        // `$indexedDB` fetch); resume only once it settles, so `_dom` is
+        // restored in the right order.
+        if (cbResult && typeof cbResult.then === 'function') {
+          // eslint-disable-next-line promise/prefer-await-to-then -- Not async
+          return cbResult.then(() => finishRoot());
+        }
       }
-      this._dom = oldDOM;
-
-      return this;
+      return finishRoot();
     }
 
     // Non-root elements
@@ -494,12 +514,20 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
       }
     }
 
+    const finish = () => {
+      this._dom = oldDOM;
+      return this;
+    };
     if (cb) {
-      cb.call(this._context || this);
+      // `cb`'s declared return type is plain `void` — cast here to
+      // duck-type the real value; see the note above the other branch.
+      const cbResult = /** @type {any} */ (cb.call(this._context || this));
+      if (cbResult && typeof cbResult.then === 'function') {
+        // eslint-disable-next-line promise/prefer-await-to-then -- Not async
+        return cbResult.then(() => finish());
+      }
     }
-    this._dom = oldDOM;
-
-    return this;
+    return finish();
   }
 
   /**

package/src/JSONJoiningTransformer.js

@@ -11,25 +11,33 @@ function _makeDatasetAttribute (n0) {
 }
 
 /**
- * @callback ObjectCallback
- * @this {JSONJoiningTransformer}
- * @param {Record<string, unknown>} obj
- * @returns {void}
+ * A `@callback` tag combined with `@this` mis-emits in `dist/*.d.ts`
+ * (verified against `tsc`'s declaration output — the `@this` type lands as
+ * raw, unparsed JSDoc text rather than being converted to a proper `this:`
+ * function-type parameter); the equivalent inline `@typedef {(this: ...) =>
+ * ...}` function-type form (already used elsewhere, e.g. `TemplateFunction`
+ * in `index.js`) emits correctly, so these three use that form instead.
+ * @typedef {(
+ *   this: JSONJoiningTransformer, obj: Record<string, unknown>
+ * ) => void} ObjectCallback
  */
 /**
- * @callback ArrayCallback
- * @this {JSONJoiningTransformer}
- * @param {any[]} arr
- * @returns {void}
+ * @typedef {(this: JSONJoiningTransformer, arr: any[]) => void} ArrayCallback
  */
 /**
  * @template [T = "json"]
- * @callback SimpleCallback
- * @this {T extends "json" ? JSONJoiningTransformer :
- *   T extends "string" ? import('./StringJoiningTransformer.js').default
- *   : import('./DOMJoiningTransformer.js').default}
- * @returns {void}
+ * @typedef {(
+ *   this: T extends "json" ? JSONJoiningTransformer :
+ *     T extends "string" ? import('./StringJoiningTransformer.js').default
+ *     : import('./DOMJoiningTransformer.js').default
+ * ) => void} SimpleCallback
  */
+// Kept as plain `void` (not `void|Promise<void>`) rather than a union:
+// TypeScript's "a void-returning callback parameter accepts any actual
+// return value" leniency — relied on throughout the test suite for
+// concise-body arrows like `() => this.text(...)` — only applies to a
+// literal `void` return type, not a union. An async callback (returning
+// `Promise<void>`) is still assignable here for the same reason.
 
 /**
  * Attributes object for element() allowing standard string attributes
@@ -392,9 +400,11 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
    * @param {ElementAttributes|any[]|SimpleCallback} [atts]
    *   Attrs, children, or cb.
    * @param {any[]|SimpleCallback} [childNodes] Children or cb.
-   * @param {SimpleCallback} [cb] Builder callback.
+   * @param {SimpleCallback} [cb] Builder callback; may be async (e.g. to
+   *   `await` a `$indexedDB` fetch), in which case `element()` itself
+   *   returns a `Promise` instead of `this`.
    * @param {string[]} [useAttributeSets] - Attribute set names to apply
-   * @returns {JSONJoiningTransformer}
+   * @returns {JSONJoiningTransformer|Promise<JSONJoiningTransformer>}
    */
   element (elem, atts, childNodes, cb, useAttributeSets) {
     this._requireSameChildren('json', 'element');
@@ -485,77 +495,96 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
       }));
     }
 
-    // Callback-driven building (attribute/text/nested element mutate stack)
-    if (cb) {
-      // Push current state onto a stack
-      this._elementStack.push({attsObj, jmlChildren});
-      cb.call(this._context || this);
-      const state = /** @type {ElementInfo} */ (this._elementStack.pop());
-      ({attsObj} = state);
-      // Children may have been mutated by nested element()/text();
-      // already in jmlChildren
-    }
-
-    // Build Jamilih array
-    /** @type {any[]} */
-    const jmlEl = [elementName];
-    if (Object.keys(attsObj).length) {
-      jmlEl.push(attsObj, jmlChildren);
-    } else {
-      jmlEl.push(jmlChildren);
-    }
-
-    if (isRoot) {
-      // todo: indent, cdataSectionElements
-      const {
-        omitXmlDeclaration, bareDoctype, doctypePublic, doctypeSystem, method
-      } = this._outputConfig ?? {};
-
-      const dtd = bareDoctype !== false
-        ? [{$DOCTYPE: {
-          name: elementName,
-          publicId: doctypePublic ?? null, // Public ID (optional)
-          systemId: doctypeSystem ?? null // System ID (optional)
-        }}]
-        : [];
-
-      let xmlDeclaration;
-      /* c8 ignore start -- third OR condition short-circuits */
-      if (!omitXmlDeclaration && (
-        method === 'xml' || method === 'xhtml' || omitXmlDeclaration === false)
-      ) {
-        const {version, encoding, standalone} = this._outputConfig ?? {};
-
-        xmlDeclaration = {
-          version,
-          encoding,
-          standalone
-        };
+    // Everything from here on depends on `attsObj`/`jmlChildren` having
+    // been fully populated by `cb` (when given) — deferred into a
+    // continuation so an async `cb` (e.g. one that awaits a `$indexedDB`
+    // fetch) can be awaited first, keeping output correctly ordered.
+    const finishElement = () => {
+      // Build Jamilih array
+      /** @type {any[]} */
+      const jmlEl = [elementName];
+      if (Object.keys(attsObj).length) {
+        jmlEl.push(attsObj, jmlChildren);
+      } else {
+        jmlEl.push(jmlChildren);
       }
-      /* c8 ignore stop */
 
-      const doc = {$document: {
-        ...(xmlDeclaration ? {xmlDeclaration} : {}),
-        childNodes: [
-          ...(method === 'xml' || method === 'xhtml' ? dtd : []),
-          jmlEl
-        ]
-      }};
+      if (isRoot) {
+        // todo: indent, cdataSectionElements
+        const {
+          omitXmlDeclaration, bareDoctype, doctypePublic, doctypeSystem, method
+        } = this._outputConfig ?? {};
+
+        const dtd = bareDoctype !== false
+          ? [{$DOCTYPE: {
+            name: elementName,
+            publicId: doctypePublic ?? null, // Public ID (optional)
+            systemId: doctypeSystem ?? null // System ID (optional)
+          }}]
+          : [];
+
+        let xmlDeclaration;
+        /* c8 ignore start -- third OR condition short-circuits */
+        if (!omitXmlDeclaration && (
+          method === 'xml' || method === 'xhtml' ||
+          omitXmlDeclaration === false)
+        ) {
+          const {version, encoding, standalone} = this._outputConfig ?? {};
+
+          xmlDeclaration = {
+            version,
+            encoding,
+            standalone
+          };
+        }
+        /* c8 ignore stop */
+
+        const doc = {$document: {
+          ...(xmlDeclaration ? {xmlDeclaration} : {}),
+          childNodes: [
+            ...(method === 'xml' || method === 'xhtml' ? dtd : []),
+            jmlEl
+          ]
+        }};
+
+        // Removed this._doc; use this._docs only
+        if (this._cfg.exposeDocuments) {
+          this._docs.push(doc);
+        }
+      }
 
-      // Removed this._doc; use this._docs only
-      if (this._cfg.exposeDocuments) {
-        this._docs.push(doc);
+      // If inside a parent element, append as its child; otherwise
+      // append to root
+      if (this._elementStack.length) {
+        const top = /** @type {ElementInfo} */ (this._elementStack.at(-1));
+        top.jmlChildren.push(jmlEl);
+      } else {
+        this.append(jmlEl);
       }
-    }
+      return this;
+    };
 
-    // If inside a parent element, append as its child; otherwise append to root
-    if (this._elementStack.length) {
-      const top = /** @type {ElementInfo} */ (this._elementStack.at(-1));
-      top.jmlChildren.push(jmlEl);
-    } else {
-      this.append(jmlEl);
+    // Callback-driven building (attribute/text/nested element mutate stack)
+    if (cb) {
+      // Push current state onto a stack
+      this._elementStack.push({attsObj, jmlChildren});
+      // `cb`'s declared return type is plain `void` (see `SimpleCallback`)
+      // — cast here to duck-type the real value.
+      const cbResult = /** @type {any} */ (cb.call(this._context || this));
+      const finishWithStack = () => {
+        const state = /** @type {ElementInfo} */ (this._elementStack.pop());
+        ({attsObj} = state);
+        // Children may have been mutated by nested element()/text();
+        // already in jmlChildren
+        return finishElement();
+      };
+      if (cbResult && typeof cbResult.then === 'function') {
+        // eslint-disable-next-line promise/prefer-await-to-then -- Not async
+        return cbResult.then(() => finishWithStack());
+      }
+      return finishWithStack();
     }
-    return this;
+    return finishElement();
   }
 
   /**

package/src/JSONPathTransformer.js

@@ -1,4 +1,7 @@
 import JSONPathTransformerContext from './JSONPathTransformerContext.js';
+import {
+  compileJSONTemplate, isJSONTemplateNodeArray
+} from './jsonTemplate.js';
 
 /**
  * Applies named JSONPath-driven templates to JSON data.
@@ -106,18 +109,35 @@ class JSONPathTransformer {
       throw new TypeError('config.templates is required');
     }
     this.templates = config.templates.map(function (template) {
+      /** @type {import('./index.js').JSONPathTemplateObject<T>} */
+      let normalized;
       if (Array.isArray(template)) {
         // Todo: We could allow a third argument (at beginning or
         //    end?) to represent template name
-        return /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
-          {path: template[0], template: template[1]}
-        );
+        normalized = /**
+                      * @type {import('./index.js').
+          JSONPathTemplateObject<T>} */ (
+            {path: template[0], template: template[1]}
+          );
+      } else if (template.match && !template.path) {
+        // Normalize 'match' to 'path' for XSLT compatibility
+        normalized = {...template, path: template.match};
+      } else {
+        normalized = template;
       }
-      // Normalize 'match' to 'path' for XSLT compatibility
-      if (template.match && !template.path) {
-        return {...template, path: template.match};
+      // A declarative (jamilih-shaped) node array, as opposed to a
+      // `TemplateFunction` — compile it once, up front, so every later
+      // dispatch site (root, applyTemplates, callTemplate) only ever sees
+      // a plain function.
+      if (isJSONTemplateNodeArray(normalized.template)) {
+        const format = normalized.format || config.defaultTemplateFormat ||
+          'json';
+        normalized = {
+          ...normalized,
+          template: compileJSONTemplate(normalized.template, {format})
+        };
       }
-      return template;
+      return normalized;
     });
     this.templates.forEach((template, i, templates) => {
       // eslint-disable-next-line @stylistic/max-len -- Long
@@ -164,16 +184,26 @@ class JSONPathTransformer {
     }
     // Set up parameter context for valueOf() access in root template
     jte._params = {0: jte._contextObj};
+    // `template` is always a function here: a declarative (jamilih-shaped)
+    // Array is compiled to one up front, in the constructor.
+    const {template: rootTemplateFn} =
+      /**
+       * @type {import('./index.js').JSONPathTemplateObject<T> &
+       *   {template: import('./index.js').
+       *     TemplateFunction<T, "json", JSONPathTransformerContext<T>>}}
+       */ (
+        templateObj
+      );
     /**
      * The template may return a value synchronously or a Promise (e.g. from
      * `await this.indexedDB(...)`), which is awaited unless `config.sync`.
      * @type {any}
      */
-    const ret = /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
-      templateObj
+    const ret = (
       // `this` carries runtime `extensions`; a consumer's `ContextExtensions`
       // augmentation would otherwise reject the bare context here.
-    ).template.call(/** @type {any} */ (jte), undefined, {mode});
+      rootTemplateFn
+    ).call(/** @type {any} */ (jte), undefined, {mode});
 
     if (ret !== null && typeof ret !== 'undefined' &&
         typeof ret.then === 'function') {