jtlt 0.17.0 → 0.19.0

package/src/StringJoiningTransformer.js

@@ -391,6 +391,12 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     if (_oldStrTemp !== undefined) {
       this._strTemp = (this._strTemp || '') + str;
     } else {
+      // Close any open parent start tag before appending content, matching
+      // text()'s behavior — string() is content too, not an attribute value.
+      if (this._openTagState) {
+        this.append('>');
+        this._openTagState = false;
+      }
       // Append to the output (or current container via append()).
       this.append(tmpStr + str);
     }
@@ -497,9 +503,14 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
    * @param {string|Element} elem - Element name or element object
    * @param {ElementAttributes} [atts] - Element attributes
    * @param {any[]} [childNodes] - Child nodes
-   * @param {(this: StringJoiningTransformer) => void} [cb] - Callback function
+   * @param {(this: StringJoiningTransformer) => void} [cb] -
+   *   Callback function; may be async (e.g. to `await` a `$indexedDB`
+   *   fetch), in which case `element()` itself returns a `Promise` instead
+   *   of `this` — check for `.then` (or `await`) rather than assuming a
+   *   synchronous return. (Typed as plain `void`, not `void|Promise<void>`
+   *   — see the note on `SimpleCallback` in JSONJoiningTransformer.js.)
    * @param {string[]} [useAttributeSets] - Attribute set names to apply
-   * @returns {StringJoiningTransformer}
+   * @returns {StringJoiningTransformer|Promise<StringJoiningTransformer>}
    */
   element (elem, atts, childNodes, cb, useAttributeSets) {
     // If a parent element's start tag is still open, close it before
@@ -635,17 +646,32 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
         jml[method]({'#': childNodes})
       ));
     }
-    cb.call(this._context || this);
+    // `cb`'s declared return type is plain `void` (see the parameter's
+    // JSDoc) so the leniency that lets any actual return value through
+    // still applies to callers — cast here to duck-type the real value.
+    const cbResult = /** @type {any} */ (cb.call(this._context || this));
 
     // Todo: Depending on an this._cfg.xmlElements option, allow for
     //    XML self-closing when empty or as per the tag, HTML
     //    self-closing tags (or polyglot-friendly self-closing)
-    if (this._openTagState) {
-      this.append('>');
-    }
-    this.append('</' + elName + '>');
-    this._openTagState = oldTagState;
-    return this;
+    const finish = () => {
+      if (this._openTagState) {
+        this.append('>');
+      }
+      this.append('</' + elName + '>');
+      this._openTagState = oldTagState;
+      return this;
+    };
+    // `cb` may be an async function (e.g. one that awaits
+    // `this.indexedDB(...)`/`this.renderDefault()` before appending
+    // content) — mirroring how a root/matched/named template's own return
+    // value is already handled elsewhere, closing the tag only after that
+    // settles keeps output correctly ordered.
+    if (cbResult && typeof cbResult.then === 'function') {
+      // eslint-disable-next-line promise/prefer-await-to-then -- Not async
+      return cbResult.then(() => finish());
+    }
+    return finish();
   }
 
   /**

package/src/XPathTransformerContext.js

@@ -619,12 +619,36 @@ class XPathTransformerContext {
       const prevTemplateParams = this._params;
       this._params = {0: node, ...appliedParams};
 
+      const {template: xpathTemplateFn} = templateObj;
+      /* c8 ignore start -- Todo: compile via compileJSONTemplate() once it
+         exists (see ~/idb-manager/JTLT-JSON-TEMPLATES-PROPOSAL.md) instead
+         of rejecting; no matched template can reach here with an Array
+         `template` until that lands (and the declarative subset is
+         JSONPath-only per that plan, so this may stay unreachable longer
+         than the JSONPath-side guards). */
+      if (Array.isArray(xpathTemplateFn)) {
+        throw new TypeError(
+          'JSON (jamilih-shaped) Array templates are not yet supported by ' +
+          'the XPath engine; compile with compileJSONTemplate() first.'
+        );
+      }
+      /* c8 ignore stop */
       /**
        * The template may return synchronously or return a Promise (e.g. from
        * `await this.indexedDB(...)`), which is awaited unless `config.sync`.
        * @type {any}
        */
-      const ret = templateObj.template.call(this, node, {mode});
+      const ret = xpathTemplateFn.call(
+        // `this` carries runtime `extensions`; a consumer's
+        // `ContextExtensions` augmentation would otherwise reject it here
+        // (matching the cast already used at the other three call sites).
+        // `node` is cast too: `templateObj.template`'s static type is a
+        // union across a `dom`-typed `TemplateFunction` (expecting
+        // `DocumentFragment | Element`) and the mode-callback signature
+        // above (expecting plain `Node`) — the same node value satisfies
+        // whichever one actually runs.
+        /** @type {any} */ (this), /** @type {any} */ (node), {mode}
+      );
 
       // Restore previous parameter context
       this._params = prevTemplateParams;
@@ -2469,6 +2493,13 @@ class XPathTransformerContext {
    * supplied via `withParam()`, or provided at runtime as `config.params` —
    * rather than an XPath expression.
    *
+   * The test may also be a simple binary comparison of a `$name` parameter
+   * against a literal, evaluated without `eval`, e.g.
+   * `this.if('$name === "x"')` or `this.if('$count < 50')`. The operator is
+   * one of `===`, `!==`, `==`, `!=`, `<`, `<=`, `>`, `>=`; the right side is
+   * a string, number, boolean, `null`, or `undefined` literal. Anything else
+   * is left to the XPath engine.
+   *
    * Truthiness rules:
    * - Node set: length > 0 passes.
    * - Scalar: Boolean(value) must be true.
@@ -2514,13 +2545,20 @@ class XPathTransformerContext {
    */
   _passesIf (select) {
     if (typeof select === 'string') {
-      const paramRef = select.trim().match(/^\$(?<name>[\w\-]+)$/v);
+      const trimmed = select.trim();
+      const paramRef = trimmed.match(/^\$(?<name>[\w\-]+)$/v);
       if (paramRef && paramRef.groups) {
         const param = this._lookupParam(paramRef.groups.name);
         if (param.has) {
           return this._isTruthyResult(param.value);
         }
       }
+      const cmp = this._parseComparison(trimmed);
+      if (cmp) {
+        return this._compareValues(
+          this._resolveComparand(cmp.left), cmp.op, cmp.right
+        );
+      }
     }
     let passes = false;
     // Try scalar evaluation first (handles boolean/comparison expressions)
@@ -2567,6 +2605,106 @@ class XPathTransformerContext {
     return passes;
   }
 
+  /**
+   * Parse a simple `$name <op> <literal>` comparison test (no `eval`), such
+   * as `$name === "x"` or `$count < 50`. The left side must be a bare `$name`
+   * parameter reference; the right side a string, number, boolean, `null`,
+   * or `undefined` literal. Returns `null` when the string is not such a
+   * comparison, so richer XPath expressions fall through untouched.
+   * @param {string} str
+   * @returns {{left: string, op: string, right: unknown}|null}
+   * @private
+   */
+  _parseComparison (str) {
+    const m = str.match(
+      /^(?<left>\$[\w\-]+)\s*(?<op>===|!==|==|!=|<=|>=|<|>)\s*(?<right>.+)$/v
+    );
+    if (!m || !m.groups) {
+      return null;
+    }
+    const right = this._parseLiteral(m.groups.right.trim());
+    if (!right) {
+      return null;
+    }
+    return {left: m.groups.left, op: m.groups.op, right: right.value};
+  }
+
+  /**
+   * Parse a JSON-ish scalar literal: a double- or single-quoted string, a
+   * number, or `true` / `false` / `null` / `undefined`. Returns `null` when
+   * `str` is none of these.
+   * @param {string} str
+   * @returns {{value: unknown}|null}
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this -- pure helper
+  _parseLiteral (str) {
+    if ((/^"(?:[^"\\]|\\.)*"$/v).test(str)) {
+      return {value: JSON.parse(str)};
+    }
+    if ((/^'(?:[^'\\]|\\.)*'$/v).test(str)) {
+      return {value: str.slice(1, -1).replaceAll(/\\(?=['\\])/gv, '')};
+    }
+    if ((/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+\-]?\d+)?$/v).test(str)) {
+      return {value: Number(str)};
+    }
+    if (str === 'true') {
+      return {value: true};
+    }
+    if (str === 'false') {
+      return {value: false};
+    }
+    if (str === 'null') {
+      return {value: null};
+    }
+    if (str === 'undefined') {
+      return {value: undefined};
+    }
+    return null;
+  }
+
+  /**
+   * Resolve the left side of a simple comparison: a bare `$name` parameter
+   * reference (local, with-param, then runtime `config.params`).
+   * @param {string} ref
+   * @returns {unknown}
+   * @private
+   */
+  _resolveComparand (ref) {
+    const paramRef = ref.match(/^\$(?<name>[\w\-]+)$/v);
+    /* c8 ignore next 3 -- `_parseComparison` only yields a `$name` left side */
+    if (!paramRef || !paramRef.groups) {
+      return undefined;
+    }
+    return this._lookupParam(paramRef.groups.name).value;
+  }
+
+  /**
+   * Apply a comparison operator to two already-resolved values.
+   * @param {any} a - Left operand
+   * @param {string} op - One of `===`, `!==`, `==`, `!=`, `<`, `<=`, `>`, `>=`
+   * @param {any} b - Right operand
+   * @returns {boolean}
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this -- pure helper
+  _compareValues (a, op, b) {
+    /* eslint-disable eqeqeq -- `==`/`!=` are deliberately offered */
+    switch (op) {
+    case '===': return a === b;
+    case '!==': return a !== b;
+    case '==': return a == b;
+    case '!=': return a != b;
+    case '<': return a < b;
+    case '<=': return a <= b;
+    case '>': return a > b;
+    case '>=': return a >= b;
+    /* c8 ignore next -- the regex only yields the operators handled above */
+    default: return false;
+    }
+    /* eslint-enable eqeqeq -- restore */
+  }
+
   /**
    * Conditional with optional fallback (like choose/otherwise).
    * Truthiness same as `if()`.

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,8 @@ export {
 export {
   default as XPathTransformer
 } from './XPathTransformer.js';
+export {
+  compileJSONTemplate, isJSONTemplateNodeArray, validateJSONTemplate
+} from './jsonTemplate.js';
 
 export default JTLT;