jtlt 0.2.0 → 0.3.0

package/docs/calltemplate-params.md

@@ -0,0 +1,251 @@
+# callTemplate Parameter Access via `valueOf()`
+
+## Overview
+
+Parameters can be accessed within the template using `valueOf({select: '$paramName'})`:
+
+```javascript
+await jtlt({
+  templates: [{
+    name: 'myTemplate',
+    template () {
+      this.string('Value: ');
+      this.valueOf({select: '$paramName'});
+    }
+  }]
+});
+```
+
+Note: Named templates (those with a `name` property) that are only called via `callTemplate` do not need a `path` property.
+
+## Features
+
+### Named Parameters
+
+You can pass named parameters using the `name` property in `withParam`:
+
+```javascript
+await jtlt({
+  templates: [
+    {
+      path: '$',
+      template () {
+        this.callTemplate({
+          name: 'formatUser',
+          withParam: [
+            {name: 'userName', value: 'Alice'},
+            {name: 'userRole', select: '$.role'}
+          ]
+        });
+      }
+    }
+    // ...
+  ]
+});
+```
+
+Access them in the template:
+
+```js
+await jtlt({
+  templates: [
+    // ...
+    {
+      name: 'formatUser',
+      template () {
+        this.valueOf({select: '$userName'});
+        this.string(' - ');
+        this.valueOf({select: '$userRole'});
+      }
+    }
+  ]
+});
+```
+
+### Indexed Parameters
+
+When no `name` is provided, parameters are accessible by their index (0, 1, 2, etc.):
+
+```js
+await jtlt({
+  templates: [
+    {
+      path: '$',
+      template () {
+        this.callTemplate({
+          name: 'format',
+          withParam: [
+            {value: 'First'},
+            {value: 'Second'}
+          ]
+        });
+      }
+    }
+  ]
+});
+```
+
+Access by index:
+
+```js
+await jtlt({
+  templates: [
+    {
+      name: 'format',
+      template () {
+        this.valueOf({select: '$0'}); // First
+        this.valueOf({select: '$1'}); // Second
+      }
+    }
+  ]
+});
+```
+
+### Nested callTemplate Calls
+
+Parameters are scoped to the current template call. When nesting `callTemplate` calls, each template has access to its own parameters:
+
+```js
+await jtlt({
+  templates: [
+    {
+      name: 'outer',
+      template () {
+        this.valueOf({select: '$outerParam'}); // Accesses outer parameter
+        this.callTemplate({
+          name: 'inner',
+          withParam: [{name: 'innerParam', value: 'inner-value'}]
+        });
+      }
+    },
+    {
+      name: 'inner',
+      template () {
+        this.valueOf({select: '$innerParam'}); // Accesses inner parameter
+      }
+    }
+  ]
+});
+```
+
+## Implementation Details
+
+### How It Works
+
+1. When `callTemplate()` is called, it stores the parameters in a temporary `_params` object on the context
+2. Parameters are stored either by name (if provided) or by index
+3. When `valueOf()` is called with a selector starting with `$`, it checks `_params` first
+4. If the parameter is not found, it falls back to normal JSONPath/XPath evaluation
+5. After the template completes, the previous parameter context is restored
+
+### Parameter Priority
+
+1. **Named parameters**: If `withParam[i].name` is provided, the parameter is stored with that name
+2. **Indexed parameters**: If no name is provided, the parameter is stored with its index as a string
+
+### Backward Compatibility
+
+The old approach of receiving parameters as function arguments is no longer supported. Templates should be updated to use `valueOf()` for parameter access. This change was made to:
+
+- Provide a more consistent API with XSLT-style parameter access
+- Allow templates to use the fluent builder pattern throughout
+- Enable better parameter naming and documentation
+- Support both JSONPath and XPath contexts uniformly
+
+## Examples
+
+### Example 1: User Formatting
+
+```js
+await jtlt({
+  data: {users: [{name: 'Alice', role: 'Admin'}]},
+  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: 'formatUser',
+      template () {
+        this.string(' (');
+        this.valueOf({select: '$userRole'});
+        this.string(')\n');
+      }
+    }
+  ]
+});
+// Output: "Alice (Admin)\n"
+```
+
+### Example 2: Nested callTemplate
+
+```js
+await jtlt({
+  data: {company: 'ACME Corp', division: 'Engineering'},
+  outputType: 'string',
+  templates: [
+    {
+      path: '$',
+      template () {
+        this.callTemplate({
+          name: 'outer',
+          withParam: [
+            {name: 'companyName', select: '$.company'},
+            {name: 'divisionName', select: '$.division'}
+          ]
+        });
+      }
+    },
+    {
+      name: 'outer',
+      template () {
+        this.string('Company: ');
+        this.valueOf({select: '$companyName'});
+        this.string('\n');
+
+        this.callTemplate({
+          name: 'inner',
+          withParam: [
+            {name: 'division', select: '$divisionName'}
+          ]
+        });
+      }
+    },
+    {
+      name: 'inner',
+      template () {
+        this.string('  Division: ');
+        this.valueOf({select: '$division'});
+        this.string('\n');
+      }
+    }
+  ]
+});
+// Output: "Company: ACME Corp\n  Division: Engineering\n"
+```
+
+## Testing
+
+Run the test suite to verify the implementation:
+
+```bash
+pnpm test test/test.calltemplate-params.js
+```
+
+Run the demo to see examples in action:
+
+```bash
+node demo/calltemplate-params-demo.js
+```
+

package/eslint.config.js

@@ -3,18 +3,22 @@ import ashNazg from 'eslint-config-ash-nazg';
 export default [
   {
     ignores: [
-      'dist'
+      'dist',
+      'coverage'
     ]
   },
   ...ashNazg(['sauron']),
   {
     rules: {
-      // Temporary only:
-      'sonarjs/public-static-readonly': 'off', // Until ash-nazg disables
-      'jsdoc/check-types': 0,
       'jsdoc/reject-any-type': 0,
-      'jsdoc/reject-function-type': 0,
+
+      // Temporary only:
       'no-unused-vars': 0,
+
+      // AI was frequently making egregious mistakes here, so make fixable
+      'jsdoc/check-alignment': 'error',
+
+      // We frequently use callbacks for nested interactions
       'promise/prefer-await-to-callbacks': 0
     }
   },

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "jtlt",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "author": "Brett Zamir",
   "contributors": [],
   "license": "MIT",
   "types": "./dist/index.d.ts",
-  "main": "src/index.js",
+  "main": "src/index-node.js",
   "exports": {
     "types": "./dist/index.d.ts",
-    "import": "./src/index.js"
+    "browser": {
+      "import": "./src/index-browser.js"
+    },
+    "node": {
+      "import": "./src/index-node.js"
+    }
   },
   "engines": {
     "node": ">=22.16.0"
@@ -20,25 +25,25 @@
     "url": "https://github.com/brettz9/jtlt.git"
   },
   "dependencies": {
-    "jamilih": "0.61.4",
+    "jamilih": "0.62.1",
     "jhtml": "0.7.1",
     "jsdom": "27.1.0",
     "jsonpath-plus": "10.3.0",
-    "lodash": "^4.17.21",
-    "object-assign": "4.x",
     "simple-get-json": "10.0.0",
     "xpath2.js": "1.0.0-alpha-6"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
+    "@node-static/node-static": "^0.8.1",
     "@types/chai": "^5.2.3",
     "@types/jsdom": "^27.0.0",
     "@types/mocha": "^10.0.10",
     "c8": "^10.1.3",
     "chai": "^6.2.0",
     "eslint": "^9.39.1",
-    "eslint-config-ash-nazg": "^39.7.1",
+    "eslint-config-ash-nazg": "^39.8.0",
     "mocha": "^11.7.5",
+    "open": "^10.2.0",
     "typescript": "^5.9.3"
   },
   "bugs": "https://github.com/brettz9/jtlt/issues",
@@ -50,6 +55,7 @@
     "javascript"
   ],
   "scripts": {
+    "start": "open http://localhost:8020/demo/ && static -p 8020",
     "attw": "attw --pack",
     "tsc": "tsc",
     "build": "tsc -p tsconfig-prod.json",

package/pnpm-workspace.yaml

@@ -1,3 +1,4 @@
 onlyBuiltDependencies:
   - ejs
+  - is-hidden-file
   - unrs-resolver

package/src/AbstractJoiningTransformer.js

@@ -2,6 +2,47 @@
 //    mid-transformation (e.g., building strings with
 //    string transformer but adding as text node in a DOM transformer)
 
+/**
+ * @typedef {{
+ *   requireSameChildren?: boolean,
+ *   JHTMLForJSON?: boolean,
+ *   mode?: "JSON"|"JavaScript"
+ * }} BaseTransformerConfig
+ */
+
+/**
+ * @typedef {BaseTransformerConfig & {
+ *   document: Document,
+ *   exposeDocuments?: boolean
+ * }} DOMJoiningTransformerConfig
+ * When exposeDocuments is true, get() returns an array of XMLDocument
+ * objects (one per root element) instead of a DocumentFragment.
+ */
+/**
+ * @typedef {object} JSONJoiningTransformerConfig
+ * @property {boolean} [requireSameChildren]
+ * @property {boolean} [unwrapSingleResult]
+ * @property {boolean} [exposeDocuments] - When true, get() returns an array
+ * of document wrapper objects (one per root element) instead of the raw array.
+ * @property {"JSON"|"JavaScript"} [mode]
+ */
+/**
+ * @typedef {BaseTransformerConfig & {
+ *   xmlElements?: boolean,
+ *   preEscapedAttributes?: boolean,
+ *   exposeDocuments?: boolean
+ * }} StringJoiningTransformerConfig
+ * When exposeDocuments is true, get() returns an array of document
+ * strings (one per root element) instead of a single concatenated string.
+ */
+/**
+ * @template T
+ * @typedef {T extends "string" ? StringJoiningTransformerConfig :
+ *   T extends "dom" ? DOMJoiningTransformerConfig :
+ *   T extends "json" ? JSONJoiningTransformerConfig : never
+ * } JoiningTransformerConfig
+ */
+
 /**
  * Base class for joining transformers.
  *
@@ -16,18 +57,19 @@
  *   based on the current state.
  * - get(): returns the accumulated result.
  * - config(): temporarily tweak a config flag for the duration of a callback.
+ * @template T
  */
 class AbstractJoiningTransformer {
   /**
-   * @param {object} [cfg] - Configuration object
+   * @param {JoiningTransformerConfig<T>} [cfg] - Configuration object
    */
   constructor (cfg) {
     // Todo: Might set some reasonable defaults across all classes
-    this.setConfig(cfg);
+    this._cfg = cfg ?? /** @type {JoiningTransformerConfig<T>} */ ({});
   }
 
   /**
-   * @param {any} [cfg] - Configuration object
+   * @param {JoiningTransformerConfig<T>} cfg - Configuration object
    * @returns {void}
    */
   setConfig (cfg) {
@@ -40,8 +82,8 @@ class AbstractJoiningTransformer {
    * @returns {void}
    */
   _requireSameChildren (type, embedType) {
-    if (this._cfg && /** @type {any} */ (this._cfg)[type] &&
-    /** @type {any} */ (this._cfg)[type].requireSameChildren) {
+    const cfg = this._cfg;
+    if (cfg.requireSameChildren) {
       throw new Error(
         'Cannot embed ' + embedType + ' children for a ' + type +
           ' joining transformer.'
@@ -51,21 +93,18 @@ class AbstractJoiningTransformer {
 
   /**
    * @param {string} prop - Configuration property name
-   * @param {*} val - Configuration property value
-   * @param {Function} [cb] - Callback function
+   * @param {any} val - Configuration property value
+   * @param {(this: AbstractJoiningTransformer<T>) => void} [cb]
+   *   Optional callback invoked with this instance
    * @returns {void}
    */
   config (prop, val, cb) {
-    const oldCfgProp = this._cfg &&
-    /** @type {any} */ (this._cfg)[prop];
-    if (this._cfg) {
-      /** @type {any} */ (this._cfg)[prop] = val;
-    }
+    const cfg = /** @type {Record<string, unknown>} */ (this._cfg);
+    const oldCfgProp = cfg[prop];
+    cfg[prop] = val;
     if (cb) {
       cb.call(this);
-      if (this._cfg) {
-        /** @type {any} */ (this._cfg)[prop] = oldCfgProp;
-      }
+      cfg[prop] = oldCfgProp;
     }
   }
 }