jtlt 0.2.0 → 0.4.0

package/CHANGES.md

@@ -1,5 +1,32 @@
 # jtlt CHANGES
 
+## 0.4.0
+
+- feat: `number()` enhancements
+- feat: `analyzeString()`
+- feat: xpath 3.1
+- feat: demo
+- fix: set XPath default query to `//*`
+- fix(types): outputType
+
+## 0.3.0
+
+- feat: `if()`
+- feat: `choose()`
+- feat: propSets for DOM
+- feat: add `comment()` and `processingInstruction()`
+- feat: optional `path` may be omitted when `name` present (named-only templates)
+- feat: XPath `copy()` (shallow) and `copyOf(select?)` (deep cloning / scalar append)
+- feat: JSONPath cloning docs expanded (existing `copy`/`copyOf` clarified)
+- fix: avoid appending `undefined` from `callTemplate` when template returns nothing
+- fix: parameter fallback in `valueOf` for JSONPath param access
+- fix: scalar XPath `copyOf()` prevents DOM hierarchy errors when expression returns Document
+ - feat: add `exposeDocuments` option
+ - feat: callTemplate in XPath
+ - feat: add `document()` (XSLT `xsl:document`-like) and `resultDocument()` (XSLT `xsl:result-document`-like) to all joiners
+ - feat: support `output({method})` values `json` and `xhtml` across joiners
+ - change: JSON joiner `$document` wrapper includes DOCTYPE only when `method` is `xml` or `xhtml`; XML declaration emitted for `xml`/`xhtml` unless `omitXmlDeclaration`
+
 ## 0.2.0
 
 - fix: point to `types` and add `exports`

package/README.md

@@ -2,14 +2,16 @@
 
 JavaScript Template Language Transformations (JTLT, pronounced as
 "Jetlet")—a JavaScript equivalent of [XSLT](https://www.w3.org/Style/XSL/),
-for JSON/JavaScript object data sources.
+for JSON/JavaScript object or XML data sources.
 
 As with XSLT, allows for declarative, linear declaration of
 (recursive) templates and can be transformed into different
-formats (e.g., HTML strings, JSON, DOM objects, etc.).
+formats (e.g., strings, JSON, or DOM objects).
 
 ***Beta state!!!***
 
+See the [Demo](https://brettz9.github.io/jtlt/demo/).
+
 ## Credits
 
 Packaged with [JSONPath Plus](https://github.com/s3u/JSONPath).
@@ -19,11 +21,11 @@ The sample file is from <https://goessner.net/articles/JsonPath/>
 ## Installation
 
 ```shell
-npm install .
+npm install jtlt
 ```
 
 In the browser, you will also need to include the dependencies.
-See the [test file](test/test.html).
+See the [test file](./test/browser/index.html).
 
 ## Basic usage
 
@@ -44,9 +46,9 @@ JTLT has two layers:
     - JSONPathTransformerContext: The execution context passed to templates. It mirrors the joiner API (e.g., string(), object(), array()) so templates can emit results. It also provides helpers like applyTemplates(), callTemplate(), valueOf(), variable(), and forEach().
     - XPathTransformer (experimental): Applies templates to
       XML/HTML DOM by matching XPath selectors (and optional modes).
-      Supports two evaluation modes: version 1 (native
-      XPathEvaluator) and version 2 (via xpath2.js). Falls back to
-      built‑in default rules when no template matches.
+      Supports three evaluation modes: version 1 (native
+      XPathEvaluator), version 2 (via xpath2.js), and version 3 (via fontoxpath).
+      Falls back to built‑in default rules when no template matches.
     - XPathTransformerContext (experimental): Execution context for
       XPath. Offers get(), forEach(), valueOf(), variable(), key()
       and the same joiner helpers as the JSONPath context.
@@ -56,6 +58,15 @@ JTLT has two layers:
     - DOMJoiningTransformer: Builds a DocumentFragment/Element tree. element()/attribute()/text() add real nodes; primitives append as text nodes.
     - JSONJoiningTransformer: Builds real JS values (objects/arrays/primitives) without serialization.
 
+### Output formats and multi-document
+
+- Output formats supported via `output({method})`: `xml`, `html`, `text`, `xhtml`, and `json`.
+  - `xml`/`xhtml` behave like XML: XML declaration (unless omitted) and optional DOCTYPE.
+  - `html` is HTML‑centric; `text` is raw text; `json` is JSON‑centric (no XML declaration/DOCTYPE).
+- Multi-document APIs:
+  - `document(cb, cfg?)`: Create additional documents; when a joiner is configured with `{exposeDocuments: true}`, `get()` returns an array of documents.
+  - `resultDocument(href, cb, cfg?)`: Create additional documents with metadata (`href`, `format`, and `document`) accessible on `joiner._resultDocuments`.
+
 ### Common joiner methods
 
 - append(value): Central sink. Based on context, concatenates to string, pushes to array, or assigns to an object property.
@@ -84,55 +95,54 @@ Provide joiningConfig when constructing JTLT:
 - joiningConfig.xmlElements: Switch element() to XML serialization mode in the String joiner.
 - joiningConfig.preEscapedAttributes: Skip escaping attribute values in the String joiner.
 
-### XPath (experimental)
-
-You can run templates against XML/HTML using XPath instead of JSONPath.
-
-- Construct with `new XPathTransformer({data, templates,
-  joiningTransformer, xpathVersion})`.
-- `data` should be a Document or Element (e.g., from DOMParser with
-  `text/xml`).
-- `xpathVersion`: `1` uses native XPath (browser like). `2` uses
-  `xpath2.js` for XPath 2.0‑style evaluation.
-- In version 2, some functions may be missing; prefer simple path
-  expressions. Use version 1 for wide XPath 1.0 function support.
-
-Example (string output):
+## Quick start (JSON source)
 
 ```js
-import {JSDOM} from 'jsdom';
-import {StringJoiningTransformer, XPathTransformer} from 'jtlt';
+import {jtlt} from 'jtlt';
 
-const {window} = new JSDOM('<!doctype><html><body></body></html>');
-const parser = new window.DOMParser();
-const doc = parser.parseFromString(
-  '<root><item>a</item><item>b</item></root>', 'text/xml'
-);
+const data = {title: 'Hello', items: ['a', 'b']};
 
-const joiner = new StringJoiningTransformer('', {document: doc});
 const templates = [
-  {name: 'root', path: '/', template () {
-    this.applyTemplates('//item');
+  {path: '$', template () {
+    this.applyTemplates();
   }},
-  {name: 'item', path: '//item', template (node) {
-    this.element('li', {}, [], () => this.text(node.textContent));
+  {path: '$.title', template (v) {
+    this.string('<h1>', () => this.text(v));
+    this.string('</h1>');
+  }},
+  {path: '$.items[*]', template (v) {
+    this.element('li', {}, [], () => this.text(v));
   }}
 ];
 
-const out = new XPathTransformer({
-  data: doc,
-  templates,
-  joiningTransformer: joiner,
-  xpathVersion: 1 // or 2
-}).transform('');
-// -> <li>a</li><li>b</li>
+const out = await jtlt({data, templates, outputType: 'string'});
+
+console.log(out);
 ```
 
-Using the JTLT facade with XPath (no manual joiner needed):
+Notes:
+
+- Modes let you organize multiple passes or output targets.
+- You can also call templates by name via this.callTemplate('name').
+- For DOM output, use outputType: 'dom'. For JSON output, use 'json'.
+
+### Quick start (XML source with XPath)
+
+You can run templates against XML/HTML using XPath instead of JSONPath.
+
+- `data` should be a Document or Element (e.g., from `DOMParser` with
+  `text/xml`).
+- `xpathVersion`: `1` uses native XPath (browser like). `2` uses
+  `xpath2.js` for XPath 2.0‑style evaluation. and `3.1` uses `fontoxpath`
+  for XPath 3.1.
+- In version 2, some functions may be missing; prefer simple path
+  expressions. Use version 1 for standard XPath 1.0 function support.
+
+Example (string output) using the JTLT facade with XPath:
 
 ```js
 import {JSDOM} from 'jsdom';
-import JTLT from 'jtlt';
+import {jtlt} from 'jtlt';
 
 const {window} = new JSDOM('<!doctype><html><body></body></html>');
 const parser = new window.DOMParser();
@@ -156,49 +166,17 @@ const templates = [
   }
 ];
 
-const out = new JTLT({
+const out = await jtlt({
   data: doc,
   templates,
   outputType: 'string',
   engineType: 'xpath',
   xpathVersion: 1, // or 2
   success: (res) => res
-}).transform('');
+});
 // -> <li>a</li><li>b</li>
 ```
 
-## Quick start
-
-```js
-import JTLT from 'jtlt';
-
-const data = {title: 'Hello', items: ['a', 'b']};
-
-const templates = [
-  {path: '$', template () {
-    this.applyTemplates({mode: 'html'});
-  }},
-  {mode: 'html', path: '$.title', template (v) {
-    this.string('<h1>', () => this.text(v));
-    this.string('</h1>');
-  }},
-  {mode: 'html', path: '$.items[*]', template (v) {
-    this.element('li', {}, [], () => this.text(v));
-  }}
-];
-
-const out = new JTLT({data, templates, outputType: 'string'}).
-  transform('html');
-
-console.log(out);
-```
-
-Notes:
-
-- Modes let you organize multiple passes or output targets.
-- You can also call templates by name via this.callTemplate('name').
-- For DOM output, use outputType: 'dom'. For JSON output, use 'json'.
-
 ## One-off queries with forQuery (XQuery-like)
 
 If you just want to run a single, non-recursive query (similar to an XQuery "for … where … return …"), you can skip defining templates and use `forQuery` to seed a root function that iterates a JSONPath and emits results.
@@ -427,15 +405,18 @@ Advantages (strong parallels with XSLT):
 
 Differences / current limitations:
 
-- Expression language: XPath 2.0 implementation is not fully feature complete.
+- Expression language: XPath 2.0 implementation is not fully feature complete and the XPath 1.0 implementation from `jsdom` may not be either.
+- As the syntax is JavaScript, it is not feasible to recursively transform
+  JTLT syntax with itself (at least not easily) as one can do with XSLT.
+  However, one can use arbitrary JavaScript, or using such as `jsep`,
+  allow a particuluar subset of JavaScript.
 - Stylesheet composition/precedence: no `xsl:import`/`xsl:include` equivalents; only basic priority and modes.
 - Schema awareness: no type-aware processing (a major XSLT/XQuery feature).
 - Multi-output (`xsl:result-document`): not built-in; pick one output type per transform.
 
 ## Differences between an exact equivalence with XSLT
 
-JTLT, having the freedom to start a new pattern from XSLT, and though
-seeking to learn from it, deviates somewhat from making an exact
+JTLT deviates somewhat from making an exact
 equivalence with XSLT (to the extent JTLT and JSONPath implement
 what could possibly be transferred to JSON-based transformations
 from XSLT):
@@ -447,88 +428,4 @@ from XSLT):
 
 ## To-dos
 
-1.  Document and add test cases to cover current features! (Could adapt an XSLT/XQuery test suite)
-
-    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.)
-        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.
-
-2.  Support processing of JSON documents with `$jtlt-stylesheet` to let
-    documents define their own targeted stylesheets.
-
-3.  When sufficiently documented, add as example library/tool to
-    JSONPath wiki.
-
-4.  Allow alternative to `element()`, `array()`, etc. methods by just
-    detecting those types from return values (and generic of each
-    type like `dom()` and `json()`).
-
-5.  Allow, depending on mode, containers to contain containers of other
-    types (e.g., a JS container containing DOM objects, or temporary use
-    of a string container, etc.).
-
-    1.  Support XML and add [hXML](https://github.com/brettz9/hxml) methods.
-
-    2.  Support [JHTML](https://github.com/brettz9/jhtml).
-
-    3.  Support `appendJSON()`/`appendDOM()` and
-        `appendType('json', ...)` (allowing type extensions).
-
-6.  Add `appendResult(function () {return result})`.
-
-7.  Add JSON update functions (equivalent to Xquery Update Facility for
-    XML ([overview](http://www.xmlplease.com/xquery-update))) and create
-    JSON serialization (as with XSLT expressed itself in declarative XML)
-    so one can submit and evaluate
-    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 `jspe`) to make
-    JTLT truly "declarative" as far as freedom from scripting
-
-## Possible to-dos
-
-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
-    (e.g., dates could be shown inside a calendar widget). Perhaps this
-    schema-awareness could also drive a JSON editor (as with other existing
-    projects) (even using same API as JSONEditor?) (or type-aware filtered
-    search/raw queries). This would help not only for editors which edit a
-    JSON file in full, but also for providing schema paths or other identifiers
-    so that a transformed/queried subset of a file (or joining of multiple
-    files) could point the way for edited contents to be saved back to the
-    correct JSON file and position in the JSON file.
-
-2.  Add a [non-eval PR for JSONPath](https://github.com/s3u/JSONPath/pull/4).
-    The OR condition (outside of filters) is another important feature as
-    would be schema-aware path results.
-
-3.  Allow hybrid JSON/[Jamilih](https://github.com/brettz9/jamilih) or
-    JSON/(X)HTML/XML so that one can add
-    XPath or query into HTML in a relevant manner
-
-4.  Support pull parsing/streaming? Pass `done()` function to templates to
-    signal completion?
-
-5.  Support Promise API in addition to callbacks (reconcile with
-    current chaining; see also XQuery FLWOR to-do)
-
-6.  Add [XQuery Functions](https://code.google.com/p/jsxqueryparser/source/browse/trunk/jsxqueryparser/XQueryParser.js#1768)
-    (also supporting DOM and JSON where possible) as plug-in (also any
-    missing from XSLT/XQuery 3.0). Also add, if not present among these
-    functions (or in XQuery), add equivalents to XSLT's
-    `document()` and `unparsed-text()` for allowing non-JSON file
-    retrieval (as well as variables/parameters) and also methods for
-    iterating or retrieving IndexedDB, `localStorage`, and cookies
-    (names, keys and values).
-
-7.  Add `outputType` which uses a DOM joiner but allows specialized
-    serialized output (e.g., pretty-printed HTML) so the users
-    don't need to build it themselves (likewise with stringified
-    JSON output).
-
-8.  See code for other possible to-dos
+See [TO-DO](./docs/TO.DO.md).

package/demo/calltemplate-params-demo.js

@@ -0,0 +1,138 @@
+/**
+ * Demo: Using valueOf() to access parameters in callTemplate
+ *
+ * This demonstrates the new feature where parameters passed via callTemplate
+ * can be accessed within the template using valueOf({select: '$paramName'})
+ * instead of having to receive them as function parameters.
+ */
+
+/* eslint-disable no-console, no-new -- Demo file */
+
+import JTLT from '../src/index-node.js';
+
+console.log('=== Demo 1: Named parameters ===');
+new JTLT({
+  data: {
+    users: [
+      {name: 'Alice', role: 'Admin'},
+      {name: 'Bob', role: 'User'}
+    ]
+  },
+  outputType: 'string',
+  templates: [
+    {
+      path: '$',
+      template () {
+        this.forEach('$.users[*]', function (user) {
+          this.callTemplate({
+            name: 'formatUser',
+            withParam: [
+              {name: 'userName', value: user.name},
+              {name: 'userRole', value: user.role},
+              {name: 'prefix', value: '> '}
+            ]
+          });
+        });
+      }
+    },
+    {
+      name: 'formatUser',
+      template () {
+        // Access parameters using valueOf with $paramName
+        this.valueOf({select: '$prefix'});
+        this.valueOf({select: '$userName'});
+        this.string(' (');
+        this.valueOf({select: '$userRole'});
+        this.string(')\n');
+      }
+    }
+  ],
+  success (result) {
+    console.log(result);
+    console.log('\n');
+  }
+});
+
+console.log('=== Demo 2: Indexed parameters (no names) ===');
+new JTLT({
+  data: {value: 'Test'},
+  outputType: 'string',
+  templates: [
+    {
+      path: '$',
+      template () {
+        this.callTemplate({
+          name: 'format',
+          withParam: [
+            {value: 'First param'},
+            {value: 'Second param'},
+            {select: '$.value'}
+          ]
+        });
+      }
+    },
+    {
+      name: 'format',
+      template () {
+        // Access by index when name not provided
+        this.string('Param 0: ');
+        this.valueOf({select: '$0'});
+        this.string('\nParam 1: ');
+        this.valueOf({select: '$1'});
+        this.string('\nParam 2: ');
+        this.valueOf({select: '$2'});
+        this.string('\n');
+      }
+    }
+  ],
+  success (result) {
+    console.log(result);
+    console.log('\n');
+  }
+});
+
+console.log('=== Demo 3: Nested callTemplate ===');
+new JTLT({
+  data: {company: 'ACME Corp'},
+  outputType: 'string',
+  templates: [
+    {
+      path: '$',
+      template () {
+        this.callTemplate({
+          name: 'outer',
+          withParam: [
+            {name: 'company', select: '$.company'}
+          ]
+        });
+      }
+    },
+    {
+      name: 'outer',
+      template () {
+        this.string('Company: ');
+        this.valueOf({select: '$company'});
+        this.string('\n');
+
+        // Call another template from within
+        /** @type {any} */ (this).callTemplate({
+          name: 'inner',
+          withParam: [
+            {name: 'message', value: 'Nested template call'}
+          ]
+        });
+      }
+    },
+    {
+      name: 'inner',
+      template () {
+        this.string('  Message: ');
+        this.valueOf({select: '$message'});
+        this.string('\n');
+      }
+    }
+  ],
+  success (result) {
+    console.log(result);
+  }
+});