jtlt 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jtlt",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "author": "Brett Zamir",
   "contributors": [],
@@ -39,7 +39,7 @@
     "codemirror": "^6.0.2",
     "fontoxpath": "^3.34.0",
     "idb": "^8.0.3",
-    "jamilih": "0.69.1",
+    "jamilih": "0.70.0",
     "jhtml": "0.7.3",
     "jsdom": "30.0.1",
     "jsonpath-plus": "10.4.0",
@@ -51,17 +51,17 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@node-static/node-static": "^0.9.1",
+    "@node-static/node-static": "^0.9.2",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@types/chai": "^5.2.3",
     "@types/jsdom": "^30.0.0",
     "@types/mocha": "^10.0.10",
-    "baseline-browser-mapping": "^2.11.21",
+    "baseline-browser-mapping": "^2.11.22",
     "c8": "^12.0.0",
     "chai": "^6.2.2",
     "eslint": "^10.10.0",
-    "eslint-config-ash-nazg": "^43.1.7",
-    "indexeddbshim": "^19.0.1",
+    "eslint-config-ash-nazg": "^43.1.8",
+    "indexeddbshim": "^19.0.2",
     "mocha": "^12.0.0",
     "open": "^11.0.2",
     "rollup": "^4.63.1",

package/pnpm-workspace.yaml

@@ -35,7 +35,10 @@ minimumReleaseAgeExclude:
   - eslint-config-ash-nazg@43.1.0 || 43.1.6
   - eslint-plugin-escompat@3.12.0
   - eslint-plugin-jsdoc@64.3.0 || 64.3.3
-  - indexeddbshim@17.4.1 || 17.4.2 || 17.4.3 || 17.5.0 || 17.6.0
+  - indexeddbshim@17.4.1 || 17.4.2 || 17.4.3 || 17.5.0 || 17.6.0 || 19.0.2
   - open@11.0.2
   - powershell-utils@0.2.1
   - websql-configurable@4.0.0
+  - '@node-static/node-static@0.9.2'
+  - baseline-browser-mapping@2.11.22
+  - jamilih@0.70.0

package/src/DOMJoiningTransformer.js

@@ -300,7 +300,7 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
    * @overload
    * @param {Element|string} elName
    * @param {(this: DOMJoiningTransformer) => void} cb
-   * @returns {DOMJoiningTransformer}
+   * @returns {DOMJoiningTransformer|Promise<DOMJoiningTransformer>}
    */
   /**
    * @overload
@@ -314,9 +314,15 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
    *   childNodes, or callback
    * @param {(Node|string)[]|((this: DOMJoiningTransformer) => void)
    *   } [childNodes] - Child nodes or callback
-   * @param {(this: DOMJoiningTransformer) => void} [cb] - Callback
+   * @param {(this: DOMJoiningTransformer) => void} [cb] -
+   *   Callback; may be async (e.g. to `await` a `$indexedDB` fetch), in
+   *   which case `element()` itself returns a `Promise` instead of `this`.
+   *   (Typed as returning plain `void`, not `void|Promise<void>` — a union
+   *   there would lose TypeScript's usual "a void-returning callback
+   *   parameter accepts any actual return value" leniency, which existing
+   *   callers rely on for e.g. `() => this.text(...)` concise arrows.)
    * @param {string[]} [useAttributeSets] - Attribute set names to apply
-   * @returns {DOMJoiningTransformer}
+   * @returns {DOMJoiningTransformer|Promise<DOMJoiningTransformer>}
    */
   element (elem, atts, childNodes, cb, useAttributeSets) {
     // Handle argument overloading like other transformers
@@ -440,12 +446,24 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
         }
       }
 
+      const finishRoot = () => {
+        this._dom = oldDOM;
+        return this;
+      };
       if (cb) {
-        cb.call(this._context || this);
+        // `cb`'s declared return type is plain `void` (see the parameter's
+        // JSDoc), preserving TypeScript's void-return leniency for
+        // callers — cast here to duck-type the real value.
+        const cbResult = /** @type {any} */ (cb.call(this._context || this));
+        // `cb` may be an async function (e.g. one that awaits a
+        // `$indexedDB` fetch); resume only once it settles, so `_dom` is
+        // restored in the right order.
+        if (cbResult && typeof cbResult.then === 'function') {
+          // eslint-disable-next-line promise/prefer-await-to-then -- Not async
+          return cbResult.then(() => finishRoot());
+        }
       }
-      this._dom = oldDOM;
-
-      return this;
+      return finishRoot();
     }
 
     // Non-root elements
@@ -494,12 +512,20 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
       }
     }
 
+    const finish = () => {
+      this._dom = oldDOM;
+      return this;
+    };
     if (cb) {
-      cb.call(this._context || this);
+      // `cb`'s declared return type is plain `void` — cast here to
+      // duck-type the real value; see the note above the other branch.
+      const cbResult = /** @type {any} */ (cb.call(this._context || this));
+      if (cbResult && typeof cbResult.then === 'function') {
+        // eslint-disable-next-line promise/prefer-await-to-then -- Not async
+        return cbResult.then(() => finish());
+      }
     }
-    this._dom = oldDOM;
-
-    return this;
+    return finish();
   }
 
   /**

package/src/JSONJoiningTransformer.js

@@ -30,6 +30,12 @@ function _makeDatasetAttribute (n0) {
  *   : import('./DOMJoiningTransformer.js').default}
  * @returns {void}
  */
+// Kept as plain `void` (not `void|Promise<void>`) rather than a union:
+// TypeScript's "a void-returning callback parameter accepts any actual
+// return value" leniency — relied on throughout the test suite for
+// concise-body arrows like `() => this.text(...)` — only applies to a
+// literal `void` return type, not a union. An async callback (returning
+// `Promise<void>`) is still assignable here for the same reason.
 
 /**
  * Attributes object for element() allowing standard string attributes
@@ -392,9 +398,11 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
    * @param {ElementAttributes|any[]|SimpleCallback} [atts]
    *   Attrs, children, or cb.
    * @param {any[]|SimpleCallback} [childNodes] Children or cb.
-   * @param {SimpleCallback} [cb] Builder callback.
+   * @param {SimpleCallback} [cb] Builder callback; may be async (e.g. to
+   *   `await` a `$indexedDB` fetch), in which case `element()` itself
+   *   returns a `Promise` instead of `this`.
    * @param {string[]} [useAttributeSets] - Attribute set names to apply
-   * @returns {JSONJoiningTransformer}
+   * @returns {JSONJoiningTransformer|Promise<JSONJoiningTransformer>}
    */
   element (elem, atts, childNodes, cb, useAttributeSets) {
     this._requireSameChildren('json', 'element');
@@ -485,77 +493,96 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
       }));
     }
 
-    // Callback-driven building (attribute/text/nested element mutate stack)
-    if (cb) {
-      // Push current state onto a stack
-      this._elementStack.push({attsObj, jmlChildren});
-      cb.call(this._context || this);
-      const state = /** @type {ElementInfo} */ (this._elementStack.pop());
-      ({attsObj} = state);
-      // Children may have been mutated by nested element()/text();
-      // already in jmlChildren
-    }
-
-    // Build Jamilih array
-    /** @type {any[]} */
-    const jmlEl = [elementName];
-    if (Object.keys(attsObj).length) {
-      jmlEl.push(attsObj, jmlChildren);
-    } else {
-      jmlEl.push(jmlChildren);
-    }
-
-    if (isRoot) {
-      // todo: indent, cdataSectionElements
-      const {
-        omitXmlDeclaration, bareDoctype, doctypePublic, doctypeSystem, method
-      } = this._outputConfig ?? {};
-
-      const dtd = bareDoctype !== false
-        ? [{$DOCTYPE: {
-          name: elementName,
-          publicId: doctypePublic ?? null, // Public ID (optional)
-          systemId: doctypeSystem ?? null // System ID (optional)
-        }}]
-        : [];
-
-      let xmlDeclaration;
-      /* c8 ignore start -- third OR condition short-circuits */
-      if (!omitXmlDeclaration && (
-        method === 'xml' || method === 'xhtml' || omitXmlDeclaration === false)
-      ) {
-        const {version, encoding, standalone} = this._outputConfig ?? {};
-
-        xmlDeclaration = {
-          version,
-          encoding,
-          standalone
-        };
+    // Everything from here on depends on `attsObj`/`jmlChildren` having
+    // been fully populated by `cb` (when given) — deferred into a
+    // continuation so an async `cb` (e.g. one that awaits a `$indexedDB`
+    // fetch) can be awaited first, keeping output correctly ordered.
+    const finishElement = () => {
+      // Build Jamilih array
+      /** @type {any[]} */
+      const jmlEl = [elementName];
+      if (Object.keys(attsObj).length) {
+        jmlEl.push(attsObj, jmlChildren);
+      } else {
+        jmlEl.push(jmlChildren);
       }
-      /* c8 ignore stop */
 
-      const doc = {$document: {
-        ...(xmlDeclaration ? {xmlDeclaration} : {}),
-        childNodes: [
-          ...(method === 'xml' || method === 'xhtml' ? dtd : []),
-          jmlEl
-        ]
-      }};
+      if (isRoot) {
+        // todo: indent, cdataSectionElements
+        const {
+          omitXmlDeclaration, bareDoctype, doctypePublic, doctypeSystem, method
+        } = this._outputConfig ?? {};
+
+        const dtd = bareDoctype !== false
+          ? [{$DOCTYPE: {
+            name: elementName,
+            publicId: doctypePublic ?? null, // Public ID (optional)
+            systemId: doctypeSystem ?? null // System ID (optional)
+          }}]
+          : [];
+
+        let xmlDeclaration;
+        /* c8 ignore start -- third OR condition short-circuits */
+        if (!omitXmlDeclaration && (
+          method === 'xml' || method === 'xhtml' ||
+          omitXmlDeclaration === false)
+        ) {
+          const {version, encoding, standalone} = this._outputConfig ?? {};
+
+          xmlDeclaration = {
+            version,
+            encoding,
+            standalone
+          };
+        }
+        /* c8 ignore stop */
+
+        const doc = {$document: {
+          ...(xmlDeclaration ? {xmlDeclaration} : {}),
+          childNodes: [
+            ...(method === 'xml' || method === 'xhtml' ? dtd : []),
+            jmlEl
+          ]
+        }};
+
+        // Removed this._doc; use this._docs only
+        if (this._cfg.exposeDocuments) {
+          this._docs.push(doc);
+        }
+      }
 
-      // Removed this._doc; use this._docs only
-      if (this._cfg.exposeDocuments) {
-        this._docs.push(doc);
+      // If inside a parent element, append as its child; otherwise
+      // append to root
+      if (this._elementStack.length) {
+        const top = /** @type {ElementInfo} */ (this._elementStack.at(-1));
+        top.jmlChildren.push(jmlEl);
+      } else {
+        this.append(jmlEl);
       }
-    }
+      return this;
+    };
 
-    // If inside a parent element, append as its child; otherwise append to root
-    if (this._elementStack.length) {
-      const top = /** @type {ElementInfo} */ (this._elementStack.at(-1));
-      top.jmlChildren.push(jmlEl);
-    } else {
-      this.append(jmlEl);
+    // Callback-driven building (attribute/text/nested element mutate stack)
+    if (cb) {
+      // Push current state onto a stack
+      this._elementStack.push({attsObj, jmlChildren});
+      // `cb`'s declared return type is plain `void` (see `SimpleCallback`)
+      // — cast here to duck-type the real value.
+      const cbResult = /** @type {any} */ (cb.call(this._context || this));
+      const finishWithStack = () => {
+        const state = /** @type {ElementInfo} */ (this._elementStack.pop());
+        ({attsObj} = state);
+        // Children may have been mutated by nested element()/text();
+        // already in jmlChildren
+        return finishElement();
+      };
+      if (cbResult && typeof cbResult.then === 'function') {
+        // eslint-disable-next-line promise/prefer-await-to-then -- Not async
+        return cbResult.then(() => finishWithStack());
+      }
+      return finishWithStack();
     }
-    return this;
+    return finishElement();
   }
 
   /**

package/src/JSONPathTransformer.js

@@ -1,4 +1,7 @@
 import JSONPathTransformerContext from './JSONPathTransformerContext.js';
+import {
+  compileJSONTemplate, isJSONTemplateNodeArray
+} from './jsonTemplate.js';
 
 /**
  * Applies named JSONPath-driven templates to JSON data.
@@ -106,18 +109,35 @@ class JSONPathTransformer {
       throw new TypeError('config.templates is required');
     }
     this.templates = config.templates.map(function (template) {
+      /** @type {import('./index.js').JSONPathTemplateObject<T>} */
+      let normalized;
       if (Array.isArray(template)) {
         // Todo: We could allow a third argument (at beginning or
         //    end?) to represent template name
-        return /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
-          {path: template[0], template: template[1]}
-        );
+        normalized = /**
+                      * @type {import('./index.js').
+          JSONPathTemplateObject<T>} */ (
+            {path: template[0], template: template[1]}
+          );
+      } else if (template.match && !template.path) {
+        // Normalize 'match' to 'path' for XSLT compatibility
+        normalized = {...template, path: template.match};
+      } else {
+        normalized = template;
       }
-      // Normalize 'match' to 'path' for XSLT compatibility
-      if (template.match && !template.path) {
-        return {...template, path: template.match};
+      // A declarative (jamilih-shaped) node array, as opposed to a
+      // `TemplateFunction` — compile it once, up front, so every later
+      // dispatch site (root, applyTemplates, callTemplate) only ever sees
+      // a plain function.
+      if (isJSONTemplateNodeArray(normalized.template)) {
+        const format = normalized.format || config.defaultTemplateFormat ||
+          'json';
+        normalized = {
+          ...normalized,
+          template: compileJSONTemplate(normalized.template, {format})
+        };
       }
-      return template;
+      return normalized;
     });
     this.templates.forEach((template, i, templates) => {
       // eslint-disable-next-line @stylistic/max-len -- Long
@@ -164,16 +184,26 @@ class JSONPathTransformer {
     }
     // Set up parameter context for valueOf() access in root template
     jte._params = {0: jte._contextObj};
+    // `template` is always a function here: a declarative (jamilih-shaped)
+    // Array is compiled to one up front, in the constructor.
+    const {template: rootTemplateFn} =
+      /**
+       * @type {import('./index.js').JSONPathTemplateObject<T> &
+       *   {template: import('./index.js').
+       *     TemplateFunction<T, "json", JSONPathTransformerContext<T>>}}
+       */ (
+        templateObj
+      );
     /**
      * The template may return a value synchronously or a Promise (e.g. from
      * `await this.indexedDB(...)`), which is awaited unless `config.sync`.
      * @type {any}
      */
-    const ret = /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
-      templateObj
+    const ret = (
       // `this` carries runtime `extensions`; a consumer's `ContextExtensions`
       // augmentation would otherwise reject the bare context here.
-    ).template.call(/** @type {any} */ (jte), undefined, {mode});
+      rootTemplateFn
+    ).call(/** @type {any} */ (jte), undefined, {mode});
 
     if (ret !== null && typeof ret !== 'undefined' &&
         typeof ret.then === 'function') {