jtlt 0.18.0 → 0.20.0

package/src/index.js

@@ -40,7 +40,16 @@ export const setWindow = (win) => {
  * @property {string} [name] - Optional name for calling via callTemplate
  * @property {string} [mode] - Optional mode for template matching
  * @property {number} [priority] - Priority for template selection
- * @property {TemplateFunction<T, U, TCtx>} template - Template function
+ * @property {'json'|'javascript'} [format] - For an Array `template` only:
+ *   the jamilih validation strictness `compileJSONTemplate` applies
+ *   (`isValidJamilih`'s own `format` option) — `'json'` (default) rejects
+ *   live values (functions, DOM nodes, …) embedded in the structure,
+ *   `'javascript'` allows them. Ignored for a function `template`. Falls
+ *   back to `config.defaultTemplateFormat`, then `'json'`, when omitted.
+ * @property {TemplateFunction<T, U, TCtx> | JSONTemplateNode[]} template -
+ *   Template function, or a declarative (jamilih-shaped) node array
+ *   compiled via `compileJSONTemplate` — detected by `Array.isArray`, since
+ *   a `TemplateFunction` is never an array.
  */
 
 /**
@@ -80,7 +89,78 @@ export const setWindow = (win) => {
  * @template {"json"|"string"|"dom"} T
  * @typedef {JSONPathTemplateObject<T> | [string, TemplateFunction<T, "json",
  *   import('./JSONPathTransformerContext.js').default
- * >]} JSONPathTemplateArray
+ * > | JSONTemplateNode[]]} JSONPathTemplateArray
+ */
+
+/**
+ * A jamilih-shaped element node — see
+ * `~/idb-manager/ROUTE-OVERRIDES-PLAN.md` §3.1. An attributes object may be
+ * omitted when there are no attributes, in which case the second item is
+ * the children array directly. Attribute *values* are left `unknown` rather
+ * than modeled precisely: they range from HTML-attribute primitives to
+ * jamilih's own richer magic-key values (`$on` handler arrays, etc.), and
+ * that shape is validated at runtime by `isValidJamilih`/`validateJamilih`,
+ * not statically here.
+ * @typedef {[string] |
+ *   [string, Record<string, unknown>] |
+ *   [string, JSONTemplateNode[]] |
+ *   [string, Record<string, unknown>, JSONTemplateNode[]]
+ * } JSONElementNode
+ */
+
+/**
+ * The declarative operation vocabulary (see
+ * `~/idb-manager/ROUTE-OVERRIDES-PLAN.md` §3.2). Every key on the leading
+ * object is `$`-prefixed — jamilih's own validator requires this of any
+ * first-position plain object. Most keys use a bare `$`-prefix. `$jtltMode`
+ * is namespaced unconditionally: jamilih hard-rejects `$mode` even bare
+ * (`RESERVED_OPTION`). `$text` / `$jtltText` are the general form and a
+ * jamilih-native-compatible shorthand for the same thing, not two distinct
+ * operations: `$jtltText` (never seen by jamilih's own `$text` handling, so
+ * an unrecognized `$select` alongside it is just ordinary dialect data) is
+ * the canonical form and works with or without `$select`; a **bare**
+ * `{$text: value}` (literal only, no `$select`) is jamilih's own native
+ * text-node form, equivalent to `{$jtltText: value}`, and validates as-is —
+ * but `{$text: value, $select}` does not, because jamilih rejects the
+ * unrecognized `$select` sitting next to its own reserved `$text`
+ * (`UNKNOWN_MAGIC_PROPERTY`); that combined form needs `$jtltText` instead.
+ * See §3.5. `$indexedDB`'s children are optional (unlike `$if`/`$forEach`,
+ * which both require theirs): a bare prefetch — binding via `$as` for later
+ * use, or simply discarding the rows — is a legitimate leaf use.
+ * @typedef {[{$text: unknown}] |
+ *   [{$jtltText: unknown, $select?: string}] |
+ *   [{$string: unknown, $select?: string}] |
+ *   [{$valueOf: string}] |
+ *   [{$applyTemplates: string, $jtltMode?: string, $sort?: unknown}] |
+ *   [{$if: string}, JSONTemplateNode[]] |
+ *   [{$if: string}, JSONTemplateNode[], JSONTemplateNode[]] |
+ *   [{$forEach: string, $sort?: unknown}, JSONTemplateNode[]] |
+ *   [{$variable: string, $select: string}] |
+ *   [{
+ *     $indexedDB: {
+ *       db: string, store: string,
+ *       options?: import('./indexedDB.js').QueryOptions
+ *     },
+ *     $as?: string
+ *   }] |
+ *   [{
+ *     $indexedDB: {
+ *       db: string, store: string,
+ *       options?: import('./indexedDB.js').QueryOptions
+ *     },
+ *     $as?: string
+ *   }, JSONTemplateNode[]] |
+ *   [{$renderDefault: true}]
+ * } JSONOperationNode
+ */
+
+/**
+ * A declarative (jamilih-shaped) template node: a text string, an element
+ * node, or an operation node. Passed as a `TemplateObject.template` (or a
+ * `[path, JSONTemplateNode[]]` tuple's second slot) wherever a
+ * `TemplateFunction` is otherwise accepted, compiled via
+ * `compileJSONTemplate` — see `~/idb-manager/JTLT-JSON-TEMPLATES-PROPOSAL.md`.
+ * @typedef {string | JSONElementNode | JSONOperationNode} JSONTemplateNode
  */
 
 /**
@@ -223,6 +303,10 @@ export const setWindow = (win) => {
  *   A `this.param(name, default)` declaration whose name appears here resolves
  *   to this value instead of its default, and `$name` references such a
  *   parameter from any template.
+ * @property {'json'|'javascript'} [defaultTemplateFormat] Config-wide
+ *   default for an Array `template`'s jamilih validation strictness (see
+ *   `TemplateObject.format`), used for any entry that doesn't specify its
+ *   own `format`. Defaults to `'json'` when omitted here too.
  */
 
 /**
@@ -230,7 +314,7 @@ export const setWindow = (win) => {
  * @template {"json"|"string"|"dom"} [T = "json"]
  * @template {boolean|undefined} [E=false]
  * @typedef {BaseJTLTOptions<T, E> & {
- *   templates?: JSONPathTemplateArray<T>[] |
+ *   templates?: JSONPathTemplateArray<T>[] | JSONPathTemplateArray<T> |
  *     TemplateFunction<T, "json",
  *     import('./JSONPathTransformerContext.js').default<T>>,
  *   template?: JSONPathTemplateObject<T> | TemplateFunction<T, "json",
@@ -288,6 +372,29 @@ export const setWindow = (win) => {
  *   XPathJTLTOptions<"dom", E>} JTLTOptions
  */
 
+/**
+ * `config.templates` (and, for symmetry, `config.template`) may be given as
+ * a bare single entry — a `TemplateObject` (`{path, template}`) or a
+ * `[path, template]` tuple — rather than always wrapped in an outer array.
+ * A bare tuple is distinguished from a list of entries by its own first
+ * item being a string: no valid entry (a plain object, or itself a tuple
+ * whose own first item is a path string) is ever a bare string, so this
+ * can't collide with a real list.
+ * @param {unknown} templates
+ * @returns {unknown[]|undefined}
+ */
+function normalizeBareTemplatesShape (templates) {
+  if (!templates) {
+    return undefined;
+  }
+  if (Array.isArray(templates)) {
+    return typeof templates[0] === 'string' ? [templates] : templates;
+  }
+  // A bare `TemplateObject` (a plain object, not a function — functions are
+  // already routed through the `query` branch above this call).
+  return [templates];
+}
+
 /**
  * High-level façade for running a JTLT transform.
  *
@@ -519,7 +626,8 @@ class JTLT {
         ])
       // eslint-disable-next-line @stylistic/max-len -- Long
       : /** @type {JSONPathTemplateObject<joiningTypes>[]|XPathTemplateObject<joiningTypes>[]} */ (
-        cfg.templates || [cfg.template]
+        normalizeBareTemplatesShape(cfg.templates) ||
+          normalizeBareTemplatesShape(cfg.template)
       );
     this.config.errorOnEqualPriority = cfg.errorOnEqualPriority || false;
     this.config.engine ||=
@@ -859,5 +967,9 @@ export {
 export {
   default as XPathTransformer
 } from './XPathTransformer.js';
+export {
+  compileJSONTemplate, extractReads, isJSONTemplateNodeArray,
+  validateJSONTemplate
+} from './jsonTemplate.js';
 
 export default JTLT;

package/src/jsonTemplate.js

@@ -0,0 +1,527 @@
+import {isValidJamilih} from 'jamilih';
+
+/**
+ * Compiles and runs the declarative (jamilih-shaped) node format used by
+ * idb-manager route overrides — see `~/idb-manager/ROUTE-OVERRIDES-PLAN.md`
+ * §3 and `~/idb-manager/JTLT-JSON-TEMPLATES-PROPOSAL.md`.
+ *
+ * A node is one of:
+ * - a string — a text node;
+ * - `[name, attrs?, children?]` — a jamilih-shaped element node (`attrs` is
+ *   omitted when there are no attributes, in which case the second item is
+ *   the children array directly);
+ * - `[{$op: ...}, ...]` — an operation node (an object as the first item).
+ *
+ * Every operation-node key is `$`-prefixed (jamilih's own validator requires
+ * this of any first-position plain object). See the vocabulary table in
+ * ROUTE-OVERRIDES-PLAN.md §3.2 for the full mapping to jtlt context calls,
+ * including the `$text`/`$jtltText` and `$mode`/`$jtltMode` namespacing
+ * rules and `$indexedDB`'s optional `$as`.
+ *
+ * `$indexedDB`/`$renderDefault` (the only async operations) may appear
+ * anywhere a node is allowed — nested inside an element's children, or a
+ * `$if`/`$forEach` body, included — because every node here is run through
+ * an `async` callback, and `element()`/`if()`/`choose()`/`forEach()` (in
+ * every joining transformer and `JSONPathTransformerContext`) duck-type
+ * their callback's return value: a synchronous callback keeps them
+ * synchronous, but one returning a `Promise` (an async function that
+ * awaited something) makes the call itself return a `Promise` that settles
+ * once the callback's work is done, keeping output correctly ordered
+ * either way.
+ */
+
+/**
+ * @param {unknown} x
+ * @returns {x is Record<string, unknown>}
+ */
+function isPlainObject (x) {
+  return Boolean(x) && typeof x === 'object' && !Array.isArray(x);
+}
+
+/**
+ * @typedef {'text'|'element'|'operation'} NodeKind
+ */
+
+/**
+ * @param {unknown} node
+ * @returns {NodeKind|null} `null` for a structurally unrecognizable node.
+ */
+function classify (node) {
+  if (typeof node === 'string') {
+    return 'text';
+  }
+  if (!Array.isArray(node) || node.length === 0) {
+    return null;
+  }
+  const head = node[0];
+  if (typeof head === 'string') {
+    return 'element';
+  }
+  if (isPlainObject(head)) {
+    return 'operation';
+  }
+  return null;
+}
+
+/**
+ * Split an element node's trailing items into `{atts, children}`. The
+ * second item is an attributes object, or (when there are no attributes)
+ * the children array directly; the optional third item is the children
+ * array when the second was attributes.
+ * @param {unknown[]} rest - Everything after the element name
+ * @returns {{atts: Record<string, unknown>, children: unknown[]}}
+ */
+function splitElementRest (rest) {
+  const [second, third] = rest;
+  if (Array.isArray(second)) {
+    return {atts: {}, children: second};
+  }
+  if (isPlainObject(second)) {
+    return {atts: second, children: Array.isArray(third) ? third : []};
+  }
+  return {atts: {}, children: []};
+}
+
+/**
+ * Operation keys recognized on an operation node's leading object. `$mode`
+ * is never valid bare (jamilih hard-reserves it); `$text` is valid bare
+ * (jamilih's own text-node form) but not combined with `$select` (jamilih
+ * rejects the unrecognized companion) — that combination needs `$jtltText`.
+ * @type {ReadonlySet<string>}
+ */
+const RECOGNIZED_OP_KEYS = new Set([
+  '$text', '$jtltText', '$string', '$valueOf', '$applyTemplates', '$if',
+  '$forEach', '$variable', '$indexedDB', '$renderDefault'
+]);
+
+/**
+ * Validate one operation node's leading object against the vocabulary
+ * rules that don't require a live jtlt context (safe to run non-executing).
+ * @param {Record<string, unknown>} head
+ * @returns {string|null} An error message, or `null` if valid.
+ */
+function validateOperationHead (head) {
+  const keys = Object.keys(head);
+  if (Object.hasOwn(head, '$mode')) {
+    return '`$mode` is reserved by jamilih and is never valid here; use ' +
+      '`$jtltMode` instead.';
+  }
+  const opKeys = keys.filter((k) => RECOGNIZED_OP_KEYS.has(k));
+  if (opKeys.length === 0) {
+    const badKey = keys.find((k) => !k.startsWith('$')) ?? keys[0];
+    return `Unrecognized operation-node key \`${badKey}\`.`;
+  }
+  if (Object.hasOwn(head, '$text') && keys.length > 1) {
+    return '`$text` combined with any other key (e.g. `$select`) is not ' +
+      'valid jamilih (jamilih rejects the unrecognized companion alongside ' +
+      'its own reserved `$text`); use `$jtltText` for the combined form.';
+  }
+  return null;
+}
+
+/**
+ * Recursively validate a node (and its descendants), collecting every
+ * problem found rather than stopping at the first.
+ * @param {unknown} node
+ * @param {'json'|'javascript'} format
+ * @param {string[]} errors - Populated in place
+ * @returns {void}
+ */
+function validateNode (node, format, errors) {
+  const kind = classify(node);
+  if (kind === 'text') {
+    return;
+  }
+  if (kind === null) {
+    errors.push(`Not a valid declarative node: ${JSON.stringify(node)}`);
+    return;
+  }
+  const arr = /** @type {unknown[]} */ (node);
+  if (kind === 'element') {
+    // Only the element's own name+attributes are checked against jamilih:
+    // jamilih validates a structure's *whole* nested tree at once, and its
+    // tolerance for unrecognized `$`-prefixed keys (branch 4 of its own
+    // `struct[0]`-is-a-plain-object rule) applies only to a structure
+    // passed to it as a complete top-level call — not to something nested
+    // inside real children — so an operation node (which uses jtlt-only
+    // keys jamilih doesn't recognize) would wrongly fail jamilih's own
+    // validation if it were included here. Children are validated by our
+    // own node-kind dispatch below instead, recursively, each as its own
+    // notional top level.
+    const [name, ...rest] = /** @type {[string, ...unknown[]]} */ (arr);
+    const {atts, children} = splitElementRest(rest);
+    if (!isValidJamilih([name, atts], {format})) {
+      errors.push(
+        `Not valid jamilih (format: "${format}"): ` +
+        JSON.stringify([name, atts])
+      );
+      return;
+    }
+    for (const child of children) {
+      validateNode(child, format, errors);
+    }
+    return;
+  }
+  // kind === 'operation'
+  const head = /** @type {Record<string, unknown>} */ (arr[0]);
+  const headError = validateOperationHead(head);
+  if (headError) {
+    errors.push(headError);
+    return;
+  }
+  if (Object.hasOwn(head, '$if')) {
+    const [, thenNodes, elseNodes] = arr;
+    if (!Array.isArray(thenNodes)) {
+      errors.push(
+        '`$if` requires a then-branch node array as its second item.'
+      );
+      return;
+    }
+    for (const child of thenNodes) {
+      validateNode(child, format, errors);
+    }
+    if (elseNodes !== undefined) {
+      if (!Array.isArray(elseNodes)) {
+        errors.push(
+          "`$if`'s else-branch, when given, must be a node array."
+        );
+        return;
+      }
+      for (const child of elseNodes) {
+        validateNode(child, format, errors);
+      }
+    }
+    return;
+  }
+  if (Object.hasOwn(head, '$forEach')) {
+    const [, childNodes] = arr;
+    if (!Array.isArray(childNodes)) {
+      errors.push(
+        '`$forEach` requires a children node array as its second item.'
+      );
+      return;
+    }
+    for (const child of childNodes) {
+      validateNode(child, format, errors);
+    }
+    return;
+  }
+  if (Object.hasOwn(head, '$indexedDB')) {
+    // Unlike `$if`/`$forEach`, `$indexedDB`'s children are optional — a
+    // bare prefetch (binding via `$as` for later use, or discarding the
+    // rows entirely) with no immediate consumer is a legitimate leaf use.
+    const [, childNodes] = arr;
+    if (childNodes !== undefined && !Array.isArray(childNodes)) {
+      errors.push(
+        "`$indexedDB`'s children, when given, must be a node array."
+      );
+      return;
+    }
+    const idbChildren = childNodes || [];
+    for (const child of idbChildren) {
+      validateNode(child, format, errors);
+    }
+  }
+}
+
+/**
+ * @typedef {{db: string, store: string}} ReadTarget
+ */
+
+/**
+ * Recursively collect the `{db, store}` targets under one node's
+ * `$indexedDB` operations (if any), walking every position a node can
+ * appear — element children, `$if` then/else, `$forEach` children, and
+ * another `$indexedDB` node's own children — not just the top level. Uses
+ * `classify()` defensively, so a structurally-invalid node (already
+ * reported by `validateNode`) simply contributes nothing here rather than
+ * throwing a second time.
+ * @param {unknown} node
+ * @param {ReadTarget[]} targets - Populated in place
+ * @param {string[]} errors - Populated in place
+ * @returns {void}
+ */
+function collectReads (node, targets, errors) {
+  const kind = classify(node);
+  if (kind !== 'element' && kind !== 'operation') {
+    return;
+  }
+  const arr = /** @type {unknown[]} */ (node);
+  if (kind === 'element') {
+    const [, ...rest] = /** @type {[string, ...unknown[]]} */ (arr);
+    const {children} = splitElementRest(rest);
+    for (const child of children) {
+      collectReads(child, targets, errors);
+    }
+    return;
+  }
+  // kind === 'operation'
+  const head = /** @type {Record<string, unknown>} */ (arr[0]);
+  if (Object.hasOwn(head, '$if')) {
+    const [, thenNodes, elseNodes] = arr;
+    const thenChildren = /** @type {unknown[]} */ (thenNodes ?? []);
+    for (const child of thenChildren) {
+      collectReads(child, targets, errors);
+    }
+    const elseChildren = /** @type {unknown[]} */ (elseNodes ?? []);
+    for (const child of elseChildren) {
+      collectReads(child, targets, errors);
+    }
+    return;
+  }
+  if (Object.hasOwn(head, '$forEach')) {
+    const [, childNodes] = arr;
+    const forEachChildren = /** @type {unknown[]} */ (childNodes ?? []);
+    for (const child of forEachChildren) {
+      collectReads(child, targets, errors);
+    }
+    return;
+  }
+  if (Object.hasOwn(head, '$indexedDB')) {
+    const spec = /** @type {any} */ (head.$indexedDB);
+    if (
+      !isPlainObject(spec) ||
+      typeof spec.db !== 'string' || spec.db.length === 0 ||
+      typeof spec.store !== 'string' || spec.store.length === 0
+    ) {
+      errors.push(
+        '`$indexedDB` target could not be resolved statically — `db` and ' +
+        '`store` must both be non-empty string literals: ' +
+        JSON.stringify(head)
+      );
+    } else {
+      targets.push({db: spec.db, store: spec.store});
+    }
+    const [, childNodes] = arr;
+    const idbChildren = /** @type {unknown[]} */ (childNodes ?? []);
+    for (const child of idbChildren) {
+      collectReads(child, targets, errors);
+    }
+  }
+}
+
+/**
+ * Statically derive the `{db, store}` targets a declarative template's
+ * `$indexedDB` nodes touch (ROUTE-OVERRIDES-PLAN.md §3.4, §13 decision 4)
+ * — for a route override's data-access checks and its `reads` field. Total:
+ * an `$indexedDB` node whose `db`/`store` isn't a literal string is
+ * reported as an error rather than silently omitted from `reads` — the
+ * whole point is to drive a data-access allowlist, so an unresolvable
+ * target must never be mistaken for "no read happens here". Duplicate
+ * targets are deduplicated.
+ * @param {unknown[]} nodes
+ * @returns {{reads: ReadTarget[], errors: string[]}}
+ */
+export function extractReads (nodes) {
+  if (!Array.isArray(nodes)) {
+    return {
+      reads: [],
+      errors: ['A declarative template must be an array of nodes.']
+    };
+  }
+  /** @type {ReadTarget[]} */
+  const targets = [];
+  /** @type {string[]} */
+  const errors = [];
+  for (const node of nodes) {
+    collectReads(node, targets, errors);
+  }
+  const seen = new Set();
+  const reads = targets.filter(({db, store}) => {
+    const key = `${db}${store}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+  return {reads, errors};
+}
+
+/**
+ * Non-executing structural check for a declarative template. Unlike
+ * `compileJSONTemplate`, this never throws — it reports every problem it
+ * finds, for a "validate before save" editor workflow. Includes the
+ * `extractReads()` check (an unresolvable `$indexedDB` target is a
+ * validation error, not just a `reads` omission).
+ * @param {unknown[]} nodes
+ * @param {{format?: 'json'|'javascript'}} [options]
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateJSONTemplate (nodes, {format = 'json'} = {}) {
+  if (!Array.isArray(nodes)) {
+    return {
+      valid: false,
+      errors: ['A declarative template must be an array of nodes.']
+    };
+  }
+  /** @type {string[]} */
+  const errors = [];
+  for (const node of nodes) {
+    validateNode(node, format, errors);
+  }
+  errors.push(...extractReads(nodes).errors);
+  return {valid: errors.length === 0, errors};
+}
+
+/**
+ * @param {unknown} x
+ * @returns {x is unknown[]}
+ */
+export function isJSONTemplateNodeArray (x) {
+  return Array.isArray(x);
+}
+
+/**
+ * Run one node against a live jtlt context.
+ * @param {unknown} node
+ * @param {any} ctx - The bound `this` inside the compiled template
+ * @returns {Promise<void>}
+ */
+async function runNode (node, ctx) {
+  const kind = classify(node);
+  if (kind === 'text') {
+    ctx.text(node);
+    return;
+  }
+  const arr = /** @type {unknown[]} */ (node);
+  if (kind === 'element') {
+    const [name, ...rest] = /** @type {[string, ...unknown[]]} */ (arr);
+    const {atts, children} = splitElementRest(rest);
+    await ctx.element(name, atts, [], async () => {
+      await runNodes(children, ctx);
+    });
+    return;
+  }
+  const head = /** @type {Record<string, unknown>} */ (arr[0]);
+  await runOperation(head, arr.slice(1), ctx);
+}
+
+/**
+ * @param {unknown[]} nodes
+ * @param {any} ctx
+ * @returns {Promise<void>}
+ */
+async function runNodes (nodes, ctx) {
+  for (const node of nodes) {
+    // eslint-disable-next-line no-await-in-loop -- Sequential output order
+    await runNode(node, ctx);
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} head
+ * @param {unknown[]} rest
+ * @param {any} ctx
+ * @returns {Promise<void>}
+ */
+async function runOperation (head, rest, ctx) {
+  if (Object.hasOwn(head, '$text')) {
+    ctx.text(head.$text);
+    return;
+  }
+  if (Object.hasOwn(head, '$jtltText')) {
+    if (Object.hasOwn(head, '$select')) {
+      ctx.valueOf(/** @type {string} */ (head.$select));
+    } else {
+      ctx.text(head.$jtltText);
+    }
+    return;
+  }
+  if (Object.hasOwn(head, '$string')) {
+    if (Object.hasOwn(head, '$select')) {
+      ctx.string(String(ctx.get(head.$select, false)));
+    } else {
+      ctx.string(head.$string);
+    }
+    return;
+  }
+  if (Object.hasOwn(head, '$valueOf')) {
+    ctx.valueOf(head.$valueOf);
+    return;
+  }
+  if (Object.hasOwn(head, '$applyTemplates')) {
+    await ctx.applyTemplates(head.$applyTemplates, head.$jtltMode, head.$sort);
+    return;
+  }
+  if (Object.hasOwn(head, '$variable')) {
+    ctx.variable(head.$variable, {select: head.$select});
+    return;
+  }
+  if (Object.hasOwn(head, '$if')) {
+    const [thenNodes, elseNodes] = rest;
+    if (elseNodes) {
+      await ctx.choose(
+        head.$if,
+        async () => {
+          await runNodes(/** @type {unknown[]} */ (thenNodes), ctx);
+        },
+        async () => {
+          await runNodes(/** @type {unknown[]} */ (elseNodes), ctx);
+        }
+      );
+    } else {
+      await ctx.if(head.$if, async () => {
+        await runNodes(/** @type {unknown[]} */ (thenNodes), ctx);
+      });
+    }
+    return;
+  }
+  if (Object.hasOwn(head, '$forEach')) {
+    const [childNodes] = rest;
+    await ctx.forEach(
+      head.$forEach,
+      async () => {
+        await runNodes(/** @type {unknown[]} */ (childNodes), ctx);
+      },
+      head.$sort
+    );
+    return;
+  }
+  if (Object.hasOwn(head, '$renderDefault')) {
+    await ctx.renderDefault();
+    return;
+  }
+  // Only $indexedDB is left (validateOperationHead already rejects
+  // anything else, and every other recognized key returned above).
+  const idb = /** @type {{db: string, store: string, options?: unknown}} */
+    (head.$indexedDB);
+  const rows = await ctx.indexedDB(idb.db, idb.store, idb.options);
+  // Validation already confirmed this is an array, when given at all.
+  const childNodes = /** @type {unknown[]} */ (rest[0] ?? []);
+  if (Object.hasOwn(head, '$as')) {
+    ctx.variable(head.$as, {value: rows});
+    await runNodes(childNodes, ctx);
+  } else {
+    const prevContext = ctx._contextObj;
+    ctx._contextObj = rows;
+    try {
+      await runNodes(childNodes, ctx);
+    } finally {
+      ctx._contextObj = prevContext;
+    }
+  }
+}
+
+/**
+ * Compile a declarative (jamilih-shaped) node array into a jtlt
+ * `TemplateFunction`. Validates the whole tree up front (see
+ * `validateJSONTemplate`) and throws on the first problem, rather than
+ * failing partway through execution.
+ * @param {unknown[]} nodes
+ * @param {{format?: 'json'|'javascript'}} [options]
+ * @returns {(
+ *   this: any, value: unknown, cfg?: {mode?: string}
+ * ) => Promise<void>}
+ */
+export function compileJSONTemplate (nodes, {format = 'json'} = {}) {
+  const {valid, errors} = validateJSONTemplate(nodes, {format});
+  if (!valid) {
+    throw new TypeError(
+      `Invalid declarative template:\n${errors.join('\n')}`
+    );
+  }
+  return async function () {
+    await runNodes(nodes, this);
+  };
+}