jtlt 0.17.0 → 0.19.0

package/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+coverage
+.idea

package/.npmignore

@@ -0,0 +1,3 @@
+test
+coverage
+.idea

package/CHANGES.md

@@ -1,5 +1,19 @@
 # jtlt CHANGES
 
+## 0.19.0
+
+- feat: declarative jamilih node format
+
+## 0.18.0
+
+- feat: `this.if()` / `choose()` / `assert()` accept a simple, non-`eval`
+  binary comparison as their test, e.g. `this.if('$name === "x"')` or
+  `this.if('$count < 50')` — a bare `$name` parameter (or, for the JSONPath
+  engine, a plain dotted/indexed `$...` path) on the left, one of
+  `===` / `!==` / `==` / `!=` / `<` / `<=` / `>` / `>=`, and a string,
+  number, boolean, `null`, or `undefined` literal on the right; anything
+  more complex is left to the JSONPath/XPath engine
+
 ## 0.17.0
 
 - feat: `this.if('$name', ...)` (and `choose()`/`assert()`) test a parameter

package/README.md

@@ -419,6 +419,7 @@ Advantages (strong parallels with XSLT):
 - Built‑in default rules: when no template matches, defaults traverse and render objects, arrays, scalars, property names, and functions, similar to XSLT’s built‑in templates.
 - applyTemplates/forEach and sorting: `applyTemplates(select, mode, sort)` and `forEach(select, cb, sort)` mirror `xsl:apply-templates`/`xsl:for-each` and `xsl:sort`.
 - Named templates and parameters: `callTemplate(name, withParam)` reflects `xsl:call-template` + `xsl:with-param`. `this.param(name, default)` mirrors `xsl:param` — the declared default is used unless the caller supplied a value (via `this.withParam(name, value)` before the call, or `callTemplate`'s `withParam` array) or a runtime value was passed as `config.params` (like an XSLT processor's stylesheet parameters). `this.withParam(name, value)` stages a parameter for the next `callTemplate()`/`applyTemplates()`, which consumes and clears the staged set. `config.params` values are also readable as `$name` from any template. In each of `param()`/`withParam()`, the value argument is a selector expression string (or `{select}`), or a literal `{value}`.
+- Conditionals: `this.if(test, cb)`, `this.choose(test, whenCb, otherwiseCb)`, and `this.assert(test, message)` mirror `xsl:if`, `xsl:choose`, and `xsl:assert`. `test` is a JSONPath/XPath expression (a non-empty result set is truthy), a bare `$name` parameter reference, or a simple non-`eval` comparison such as `'$name === "x"'` or `'$count < 50'` — a `$name` parameter (or, for the JSONPath engine, a plain dotted/indexed `$...` path) on the left, one of `===` / `!==` / `==` / `!=` / `<` / `<=` / `>` / `>=`, and a string, number, boolean, `null`, or `undefined` literal on the right.
 - Keys and lookups: `key(name, match, use)` + `getKey(name, value)` provide `xsl:key`-style indexing for joins and fast lookups.
 - Multiple output forms: string, DOM, and JSON builders ("joiners") allow emitting different result trees like XSLT’s result tree model.
 
@@ -442,6 +443,81 @@ from XSLT):
 
 1. The method `this.stylesheet()` (or `this.transform()`) is used similarly to XSLT for configuration, but it does not call for including the templates within it as nested content.
 2. JTLT adds `path` as an alias for `match` on templates.
+3. **No single-root-node restriction.** XSLT's content model has, at root,
+   a single node per template (not counting processing instructions) —
+   `xsl:output` is a separate top-level stylesheet declaration, and
+   `xsl:template`'s own content is one nested tree. JTLT has no equivalent
+   of that single `xsl:stylesheet`/`xsl:transform` wrapper to enforce it:
+   - A **function template** is a plain JavaScript function body, so it can
+     make any number of top-level calls in sequence — there is nothing
+     that limits it to producing (or delegating to) one node:
+    ```js
+    const templateObj = {path: '$', template () {
+      // Two independent things at the root, not one nested tree:
+      this.output({method: 'html'}); // configure output
+      this.applyTemplates('$.items[*]'); // then produce content
+    }};
+    ```
+   - A **declarative (jamilih-shaped) template** — the `Array`-of-nodes
+     form compiled by `compileJSONTemplate()` — is likewise an array of
+     *sibling* top-level nodes, not one node:
+    ```js
+    const templateObj = {
+      template: [
+        ['h1', ['Custom heading']], // a literal element, then
+        [{$applyTemplates: '$.items[*]'}] // an operation node
+      ]
+      // -> <h1>Custom heading</h1><li>...</li>...
+    };
+    ```
+     jamilih's own `#` fragment node offers a similar grouping when only
+     one node is structurally expected, but the top level here never
+     requires it — an array of nodes is already accepted directly.
+
+     This is also why a template holding just *one* operation node, with
+     no other siblings, still needs two levels of array, not one:
+
+    ```js
+    // Rejected: a bare `{$applyTemplates}` object is not itself a node —
+    // every node (elements included) is array-shaped, `[head, ...args]`.
+    const rejected = {template: [{$applyTemplates: '$.items[*]'}]};
+
+    // Accepted: the outer array is the sibling-node list (point 3, above);
+    // the inner array is this one operation node's own `[head, ...args]`
+    // shape — `$applyTemplates` just happens to need no further `args`.
+    const accepted = {template: [[{$applyTemplates: '$.items[*]'}]]};
+    ```
+
+     The inner array isn't there *for* `$applyTemplates` specifically — it's
+     the same shape every operation node uses, whether or not that
+     operation happens to need trailing arguments: `$if` and `$forEach`
+     both use later array items for their bodies (`[{$if}, thenNodes,
+     elseNodes?]`, `[{$forEach}, childNodes]`), so the node model treats
+     `[head, ...args]` as the one uniform shape rather than special-casing
+     the argument-less operations to a bare head object.
+
+     `$if`'s then/else and `$forEach`'s children are, in turn, each a
+     `thenNodes`/`elseNodes`/`childNodes` **array of sibling nodes** — the
+     exact same shape as `template` itself (point 3, above) — not a single
+     unwrapped node, even when the body happens to hold just one:
+
+    ```js
+    // Not this — a single node, unwrapped:
+    const unwrapped = [[{$if: '$flag'}, ['p', ['yes']]]];
+
+    // This — an array of (one) sibling node(s):
+    const wrapped = [[{$if: '$flag'}, [['p', ['yes']]]]];
+    ```
+
+     Requiring the wrapper isn't just consistency for its own sake — an
+     *unwrapped* single node would be genuinely ambiguous, silently so:
+     an element node is itself an array, `[name, attrs?, children?]`, so
+     `['p', ['yes']]` is indistinguishable, at the array level, from a
+     two-node *list*: a bare string `'p'` (a text node) followed by an
+     element node `['yes']` (an empty `<yes>` tag). That is exactly what
+     `unwrapped` above produces — `p<yes></yes>`, not `<p>yes</p>` — with
+     no error, since both readings are structurally valid nodes on their
+     own; only the wrapped array-of-nodes form is unambiguous.
 
 ## To-dos