jtlt 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jtlt",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "author": "Brett Zamir",
   "contributors": [],
@@ -33,6 +33,7 @@
     "@lezer/highlight": "^1.2.3",
     "codemirror": "^6.0.2",
     "fontoxpath": "^3.34.0",
+    "idb": "^8.0.3",
     "jamilih": "0.69.0",
     "jhtml": "0.7.3",
     "jsdom": "30.0.1",
@@ -50,14 +51,15 @@
     "@types/chai": "^5.2.3",
     "@types/jsdom": "^30.0.0",
     "@types/mocha": "^10.0.10",
-    "baseline-browser-mapping": "^2.11.19",
+    "baseline-browser-mapping": "^2.11.20",
     "c8": "^12.0.0",
     "chai": "^6.2.2",
     "eslint": "^10.9.1",
-    "eslint-config-ash-nazg": "^42.6.0",
+    "eslint-config-ash-nazg": "^43.1.0",
+    "indexeddbshim": "^17.4.3",
     "mocha": "^11.8.0",
-    "open": "^11.0.1",
-    "rollup": "^4.63.0",
+    "open": "^11.0.2",
+    "rollup": "^4.63.1",
     "typescript": "^7.0.2"
   },
   "bugs": "https://github.com/brettz9/jtlt/issues",

package/pnpm-workspace.yaml

@@ -1,6 +1,9 @@
 allowBuilds:
+  better-sqlite3: true
+  canvas: true
   is-hidden-file: true
   libxmljs: true
+  sqlite3: true
   unrs-resolver: true
 minimumReleaseAgeExclude:
   - '@rollup/rollup-android-arm-eabi@4.63.0'
@@ -30,3 +33,9 @@ minimumReleaseAgeExclude:
   - '@rollup/rollup-win32-x64-msvc@4.63.0'
   - rollup@4.63.0
   - jhtml@0.7.2 || 0.7.3
+  - eslint-config-ash-nazg@43.1.0
+  - eslint-plugin-escompat@3.12.0
+  - eslint-plugin-jsdoc@64.3.0
+  - indexeddbshim@17.4.1 || 17.4.2 || 17.4.3
+  - open@11.0.2
+  - powershell-utils@0.2.1

package/src/AbstractJoiningTransformer.js

@@ -258,8 +258,8 @@ class AbstractJoiningTransformer {
   /**
    * Invoke a registered stylesheet function with positional arguments.
    * @param {string} name - Function name (with namespace)
-   * @param {any[]} args - Positional arguments
-   * @returns {any} Function return value
+   * @param {unknown[]} args - Positional arguments
+   * @returns {unknown} Function return value
    */
   invokeFunctionByArity (name, args = []) {
     const arity = args.length;
@@ -436,7 +436,7 @@ class AbstractJoiningTransformer {
 
   /**
    * @param {string} prop - Configuration property name
-   * @param {any} val - Configuration property value
+   * @param {unknown} val - Configuration property value
    * @param {(this: AbstractJoiningTransformer<T>) => void} [cb]
    *   Optional callback invoked with this instance
    * @returns {void}

package/src/JSONPathTransformer.js

@@ -16,7 +16,7 @@ class JSONPathTransformer {
       /**
        * @template {"json"|"string"|"dom"} U
        * @this {JSONPathTransformerContext<U>}
-       * @param {any} value - Value
+       * @param {unknown} value - Value
        * @param {{mode?: string}} cfg - Configuration
        * @returns {void}
        */
@@ -26,8 +26,8 @@ class JSONPathTransformer {
     },
     transformPropertyNames: {
       /**
-       * @param {any} value - Current context value
-       * @returns {any}
+       * @param {unknown} value - Current context value
+       * @returns {unknown}
        */
       template (value) {
         // Emit property names for the current object context
@@ -40,7 +40,7 @@ class JSONPathTransformer {
     transformObjects: {
       /**
        * @this {JSONPathTransformerContext}
-       * @param {any} value - Value
+       * @param {unknown} value - Value
        * @param {{mode?: string}} cfg - Configuration
        * @returns {void}
        */
@@ -51,7 +51,7 @@ class JSONPathTransformer {
     transformArrays: {
       /**
        * @this {JSONPathTransformerContext}
-       * @param {any} value - Value
+       * @param {unknown} value - Value
        * @param {{mode?: string}} cfg - Configuration
        * @returns {void}
        */
@@ -70,8 +70,9 @@ class JSONPathTransformer {
     },
     transformFunctions: {
       /**
-       * @param {( ...args: any[]) => any} value - Function at current context
-       * @returns {any}
+       * @param {(...args: unknown[]) => unknown} value - Function at current
+       *   context
+       * @returns {unknown}
        */
       template (value) {
         // Call the function and return its result
@@ -163,9 +164,46 @@ class JSONPathTransformer {
     }
     // Set up parameter context for valueOf() access in root template
     jte._params = {0: jte._contextObj};
+    /**
+     * 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
     ).template.call(jte, undefined, {mode});
+
+    if (ret !== null && typeof ret !== 'undefined' &&
+        typeof ret.then === 'function') {
+      if (this._config.sync) {
+        throw new Error(
+          'A template returned a Promise but JTLT is configured with ' +
+          '`sync: true`.'
+        );
+      }
+      return /** @type {any} */ (
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        // eslint-disable-next-line promise/prefer-await-to-then -- intentional dynamic sync/async
+        ret.then((/** @type {any} */ resolvedRet) => {
+          if (typeof resolvedRet !== 'undefined') {
+            const joiner = jte._getJoiningTransformer();
+            if (typeof resolvedRet === 'string' ||
+                (typeof resolvedRet === 'object' && resolvedRet !== null &&
+                 'nodeType' in resolvedRet)) {
+              joiner.append(/** @type {string|Node} */ (resolvedRet));
+            } else {
+              /** @type {import('./JSONJoiningTransformer.js').default} */ (
+                joiner
+              ).append(resolvedRet);
+            }
+          }
+          return /** @type {import('./index.js').ResultType<T>} */ (
+            jte.getOutput()
+          );
+        })
+      );
+    }
+
     if (typeof ret !== 'undefined') {
       // Will vary by jte._config.outputType
       // After the undefined check, ret is ResultType<T>

package/src/JSONPathTransformerContext.js

@@ -1,5 +1,9 @@
 import {JSONPath as jsonpath} from 'jsonpath-plus';
 import JSONPathTransformer from './JSONPathTransformer.js';
+import {maybeAsyncLoop} from './maybeAsync.js';
+import {
+  parseIndexedDBExpression, queryIndexedDB, resolveIndexedDBQuery
+} from './indexedDB.js';
 
 /**
  * @param {string} string
@@ -52,7 +56,7 @@ const escapeRegexReplacement = (string) => {
  *   ctx: JSONPathTransformerContext
  * ) => number} SortComparator
  * @typedef {string | SortObject | SortComparator |
- *   Array<string|SortObject>} SortSpec
+ *   Array<string|SortObject> | null} SortSpec
  */
 
 /**
@@ -88,6 +92,8 @@ const escapeRegexReplacement = (string) => {
  * @property {JoiningTransformerMap[T]} joiningTransformer - Joining transformer
  * @property {boolean} [preventEval] - Whether to prevent eval in
  *   JSONPath
+ * @property {boolean} [sync] - When true, throw if a template returns a
+ *   Promise instead of awaiting it (disables `indexedDB()`)
  * @property {(path: string) => number} [specificityPriorityResolver]
  *   Priority resolver function
  * @property {import('./index.js').JSONPathTemplateObject<T>[]|
@@ -195,7 +201,7 @@ class JSONPathTransformerContext {
 
   /**
    * Gets the current output.
-   * @returns {any} The output from the joining transformer
+   * @returns {unknown} The output from the joining transformer
    */
   getOutput () {
     return this._getJoiningTransformer().get();
@@ -221,7 +227,7 @@ class JSONPathTransformerContext {
   }
 
   /**
-   * @param {any} v - Value to set
+   * @param {unknown} v - Value to set
    * @returns {this}
    */
   set (v) {
@@ -403,7 +409,7 @@ class JSONPathTransformerContext {
     const prevCurrPath = that._currPath;
 
     // Process in (sorted) order
-    for (const o of matches) {
+    const loopResult = maybeAsyncLoop(matches, (o) => {
       const {value, parent, parentProperty, path} = o;
       const _oldPath = that._currPath;
       that._currPath += path.replace(/^\$/v, '');
@@ -454,17 +460,19 @@ class JSONPathTransformerContext {
           }
           if (onNoMatch === 'deep-skip') {
             // Skip this node and its descendants entirely
-            continue;
+            return;
           }
           if (onNoMatch === 'shallow-copy') {
             // Output the value as-is without processing children
             joiner.append(value);
-            continue;
+            that._currPath = _oldPath;
+            return;
           }
           if (onNoMatch === 'deep-copy') {
             // Output the value and all descendants as-is
             joiner.append(JSON.stringify(value));
-            continue;
+            that._currPath = _oldPath;
+            return;
           }
           if (onNoMatch === 'text-only-copy') {
             // Output only text content (primitives)
@@ -472,7 +480,8 @@ class JSONPathTransformerContext {
                 typeof value === 'boolean') {
               joiner.append(String(value));
             }
-            continue;
+            that._currPath = _oldPath;
+            return;
           }
           // 'apply-templates', 'shallow-skip', or other:
           // use default template rules
@@ -573,6 +582,11 @@ class JSONPathTransformerContext {
       const prevTemplateParams = that._params;
       that._params = {0: value};
 
+      /**
+       * 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 =
         /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
           templateObj
@@ -582,6 +596,42 @@ class JSONPathTransformerContext {
 
       // Restore previous parameter context
       that._params = prevTemplateParams;
+      if (ret !== null && typeof ret !== 'undefined' &&
+          typeof ret.then === 'function') {
+        if (that._config.sync) {
+          throw new Error(
+            'A template returned a Promise but JTLT is configured with ' +
+            '`sync: true`.'
+          );
+        }
+        // The loop body deliberately mixes value and no-value returns so
+        // `maybeAsyncLoop` can stay synchronous unless a template awaits.
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        // eslint-disable-next-line promise/prefer-await-to-then, consistent-return -- intentional dynamic sync/async
+        return ret.then((/** @type {any} */ resolvedRet) => {
+          that._params = prevTemplateParams;
+          if (typeof resolvedRet !== 'undefined') {
+            const joiner = that._getJoiningTransformer();
+            /* c8 ignore start -- _openTagState only on
+               StringJoiningTransformer; string-output defensive check */
+            // @ts-expect-error -- _openTagState: StringJoiningTransformer only
+            if (joiner._openTagState) {
+              joiner.append('>');
+              // @ts-expect-error -- _openTagState: StringJoiningTransformer
+              joiner._openTagState = false;
+            }
+            /* c8 ignore stop */
+            joiner.append(resolvedRet);
+          }
+          that._parent = parent;
+          // Matches reached here always carry a parentProperty; the sync
+          // path covers the root-node fallback.
+          /* c8 ignore next */
+          that._parentProperty = (parentProperty ?? that._parentProperty);
+          that._currPath = _oldPath;
+          return undefined;
+        });
+      }
       if (typeof ret !== 'undefined') {
         // After the undefined check, ret is ResultType<T>
         const joiner = that._getJoiningTransformer();
@@ -604,12 +654,27 @@ class JSONPathTransformerContext {
       that._parent = parent;
       that._parentProperty = (parentProperty ?? that._parentProperty);
       that._currPath = _oldPath;
+    });
+
+    if (typeof loopResult?.then === 'function') {
+      // Returns a Promise<this> when a nested template ran asynchronously.
+      return /** @type {any} */ (
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        // eslint-disable-next-line promise/prefer-await-to-then -- intentional dynamic sync/async
+        loopResult.then(() => {
+          this._contextObj = prevContext;
+          this._parent = prevParent;
+          this._parentProperty = prevParentProp;
+          this._currPath = prevCurrPath;
+          return this;
+        })
+      );
     }
-    // Restore outer context
-    that._contextObj = prevContext;
-    that._parent = prevParent;
-    that._parentProperty = prevParentProp;
-    that._currPath = prevCurrPath;
+
+    this._contextObj = prevContext;
+    this._parent = prevParent;
+    this._parentProperty = prevParentProp;
+    this._currPath = prevCurrPath;
     return this;
   }
 
@@ -819,9 +884,12 @@ class JSONPathTransformerContext {
    *   expression matches
    * @param {string} [options.groupEndingWith] - Ends group when expression
    *   matches
-   * @param {any} [options.sort] - Sort specification (same as forEach)
+   * @param {SortSpec<V>} [options.sort] - Sort specification (same as forEach)
    * @param {(
-   *   this: JSONPathTransformerContext<T>, key: any, items: any[], ctx: any
+   *   this: JSONPathTransformerContext<T>,
+   *   key: unknown,
+   *   items: unknown[],
+   *   ctx: JSONPathTransformerContext<T>
    * ) => void} cb - Callback receives (groupingKey, groupItems, context)
    * @returns {this}
    */
@@ -1135,7 +1203,7 @@ class JSONPathTransformerContext {
 
   /**
    * Returns the current group (for use within forEachGroup callback).
-   * @returns {any[]|undefined}
+   * @returns {unknown[]|undefined}
    */
   currentGroup () {
     return /** @type {any} */ (this)._currentGroup;
@@ -1143,12 +1211,48 @@ class JSONPathTransformerContext {
 
   /**
    * Returns the current grouping key (for use within forEachGroup callback).
-   * @returns {any}
+   * @returns {unknown}
    */
   currentGroupingKey () {
     return /** @type {any} */ (this)._currentGroupingKey;
   }
 
+  /**
+   * Directly query IndexedDB from within a template, e.g.
+   * `await this.indexedDB('myDB', 'myStore', {index: 'byAge'})`.
+   *
+   * Since IndexedDB access is asynchronous, this is unavailable when JTLT is
+   * configured with `sync: true`.
+   * @param {string} dbName - Database name
+   * @param {string} storeName - Object store name
+   * @param {import('./indexedDB.js').QueryOptions} [options] - Query options
+   * @returns {Promise<unknown[]>} The matching records
+   */
+  indexedDB (dbName, storeName, options) {
+    if (this._config.sync) {
+      throw new Error(
+        'The `indexedDB()` API is unavailable when JTLT is configured with ' +
+        '`sync: true`.'
+      );
+    }
+    return queryIndexedDB(dbName, storeName, options);
+  }
+
+  /**
+   * Await a parsed `indexedDB(...)` expression and append its (stringified)
+   * value to the output. Used by {@link valueOf}. Callers reject `config.sync`.
+   * @param {import('./indexedDB.js').ParsedIndexedDBExpression} parsed
+   * @param {any} results - The joining transformer
+   * @returns {Promise<this>}
+   */
+  async _appendIndexedDBValue (parsed, results) {
+    const value = await resolveIndexedDBQuery(parsed, {
+      preventEval: this._config.preventEval
+    });
+    results.text(String(value));
+    return this;
+  }
+
   /**
    * @param {string|object} [select] - JSONPath selector
    * @returns {this}
@@ -1159,6 +1263,26 @@ class JSONPathTransformerContext {
     const results = this._getJoiningTransformer();
     let result;
 
+    const selectString = select && typeof select === 'object'
+      ? /** @type {{select?: string}} */ (select).select
+      : select;
+
+    // Intercept `indexedDB('db', 'store')<trailing JSONPath>` expressions and
+    // resolve them asynchronously before appending. Returns a Promise so
+    // templates can `await this.valueOf(...)`.
+    if (typeof selectString === 'string') {
+      const parsed = parseIndexedDBExpression(selectString);
+      if (parsed) {
+        if (this._config.sync) {
+          throw new Error(
+            'The `indexedDB()` function is unavailable when JTLT is ' +
+            'configured with `sync: true`.'
+          );
+        }
+        return /** @type {any} */ (this._appendIndexedDBValue(parsed, results));
+      }
+    }
+
     if (select && typeof select === 'object' &&
     /** @type {{select?: string}} */ (select).select === '.') {
       result = this._contextObj;
@@ -2079,8 +2203,8 @@ class JSONPathTransformerContext {
   /**
    * Invoke a registered stylesheet function with positional arguments.
    * @param {string} name - Function name (with namespace)
-   * @param {any[]} args - Positional arguments
-   * @returns {any} Function return value
+   * @param {unknown[]} args - Positional arguments
+   * @returns {unknown} Function return value
    */
   invokeFunctionByArity (name, args = []) {
     return this._getJoiningTransformer().invokeFunctionByArity(name, args);
@@ -2233,12 +2357,23 @@ class JSONPathTransformerContext {
 
   /**
    * @param {string} name - Key name
-   * @param {any} value - Value to match
-   * @returns {any}
+   * @param {unknown} value - Value to match
+   * @returns {unknown}
    */
   getKey (name, value) {
     const key = this.keys[name];
-    const matches = this.get(key.match, true);
+    // Keys are document-global (like `xsl:key`): resolve `match` against the
+    // root, not the current context (which may be a `forEach`/`applyTemplates`
+    // item).
+    const matches = /** @type {any[]} */ (
+      (/** @type {any} */ (jsonpath))({
+        path: JSONPathTransformer.makeJSONPathAbsolute(key.match),
+        json: this._origObj,
+        preventEval: this._config.preventEval,
+        wrap: true,
+        returnType: 'value'
+      })
+    );
     for (const match of matches) { // For objects or arrays
       if (match && typeof match === 'object' &&
         match[key.use] === value) {

package/src/XPathTransformer.js

@@ -7,6 +7,8 @@ import XPathTransformerContext from './XPathTransformerContext.js';
  * @property {import('./index.js').
  *   XPathTemplateArray<T>} templates Template objects
  * @property {number} [xpathVersion] XPath version (1|2|3.1)
+ * @property {boolean} [sync] When true, throw if a template returns a Promise
+ *   instead of awaiting it (disables `indexedDB()` and other async features)
  */
 
 /**
@@ -21,7 +23,7 @@ class XPathTransformer {
   static DefaultTemplateRules = {
     transformRoot: {
       /**
-       * @param {any} node Node
+       * @param {unknown} node Node
        * @param {{mode:string}} cfg Config
        * @returns {void}
        */
@@ -106,7 +108,37 @@ class XPathTransformer {
     }
     // Set up parameter context for valueOf() access in root template
     xte._params = {0: xte._contextNode};
+    /**
+     * 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(xte, undefined, {mode});
+
+    if (ret !== null && typeof ret !== 'undefined' &&
+        typeof ret.then === 'function') {
+      if (this._config.sync) {
+        throw new Error(
+          'A template returned a Promise but JTLT is configured with ' +
+          '`sync: true`.'
+        );
+      }
+      return /** @type {any} */ (
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        // eslint-disable-next-line promise/prefer-await-to-then -- intentional dynamic sync/async
+        ret.then((/** @type {any} */ resolvedRet) => {
+          if (typeof resolvedRet !== 'undefined') {
+            /** @type {any} */ (xte)._getJoiningTransformer().append(
+              resolvedRet
+            );
+          }
+          return /** @type {import('./index.js').ResultType<T>} */ (
+            xte.getOutput()
+          );
+        })
+      );
+    }
+
     if (typeof ret !== 'undefined') {
       /** @type {any} */ (xte)._getJoiningTransformer().append(ret);
     }