jtlt 0.13.0 → 0.14.0

package/src/XPathTransformerContext.js

@@ -2,6 +2,12 @@ import xpath2 from 'xpath2.js'; // Runtime JS import; ambient types declared
 // eslint-disable-next-line @stylistic/max-len -- Long
 // xpathVersion: 1 => browser/native XPathEvaluator API; 2 => xpath2.js, 3 => fontoxpath
 import fontoxpath from 'fontoxpath';
+import {maybeAsyncLoop} from './maybeAsync.js';
+import {
+  queryIndexedDB,
+  xpathExpressionUsesIndexedDB,
+  evaluateXPathWithIndexedDB
+} from './indexedDB.js';
 // import xsdValidator from 'xsd-validator';
 
 /**
@@ -19,6 +25,10 @@ const escapeRegexReplacement = (string) => {
  * @property {import('./index.js').
  *   JoiningTransformer} joiningTransformer Joiner
  * @property {boolean} [errorOnEqualPriority]
+ * @property {boolean} [sync] - When true, throw if a template returns a
+ *   Promise instead of awaiting it (disables `indexedDB()`)
+ * @property {boolean} [preventEval] - Whether to prevent eval in the JSONPath
+ *   trailing segment of an `indexedDB(...)` expression
  * @property {(path: string) => number} [specificityPriorityResolver]
  */
 
@@ -126,9 +136,14 @@ class XPathTransformerContext {
     this._stripSpaceElements = [];
   }
 
-  /** @returns {import('./index.js').JoiningTransformer} */
+  /** @returns {import('./index.js').BuiltinJoiningTransformer} */
   _getJoiningTransformer () {
-    return this._config.joiningTransformer;
+    // Engine internals only ever run against a built-in joiner (they touch
+    // concrete members such as `_modeConfig`); a custom stub is the caller's
+    // responsibility.
+    return /** @type {import('./index.js').BuiltinJoiningTransformer} */ (
+      this._config.joiningTransformer
+    );
   }
 
   /**
@@ -398,9 +413,13 @@ class XPathTransformerContext {
     });
 
     const preApplyContext = this._contextNode;
+    const isSync = Boolean(/** @type {any} */ (this._config).sync);
 
-    // Process each node
-    for (const node of nodes) {
+    // Process each node. `maybeAsyncLoop` keeps this a plain synchronous
+    // loop unless a template returns a Promise (e.g. via
+    // `await this.indexedDB(...)`), in which case it chains and the whole
+    // call becomes asynchronous.
+    const loopResult = maybeAsyncLoop(nodes, (node) => {
     // Path resolution simplified (could track full XPath if needed)
       const pathMatchedTemplates = modeMatched.filter((t) => {
         // Basic matching: template.path is XPath tested for existence
@@ -438,7 +457,7 @@ class XPathTransformerContext {
           }
           if (onNoMatch === 'deep-skip') {
             // Skip this node entirely
-            continue;
+            return undefined;
           }
           if (onNoMatch === 'shallow-copy') {
             // Output the node without processing children
@@ -451,7 +470,7 @@ class XPathTransformerContext {
             } else if (node.nodeType === 3 && node.nodeValue) { // Text
               joiner.text(node.nodeValue);
             }
-            continue;
+            return undefined;
           }
           if (onNoMatch === 'deep-copy') {
             // Output the node and all descendants
@@ -462,7 +481,7 @@ class XPathTransformerContext {
             } else if (node.nodeType === 3 && node.nodeValue) { // Text
               joiner.text(node.nodeValue);
             }
-            continue;
+            return undefined;
           }
           if (onNoMatch === 'text-only-copy') {
             // Output only text content
@@ -474,7 +493,7 @@ class XPathTransformerContext {
                 joiner.text(textContent);
               }
             }
-            continue;
+            return undefined;
           }
           // 'apply-templates', 'shallow-skip', or other:
           // use default template rules
@@ -569,11 +588,45 @@ class XPathTransformerContext {
       const prevTemplateParams = this._params;
       this._params = {0: node};
 
+      /**
+       * 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(this, node, {mode});
 
       // Restore previous parameter context
       this._params = prevTemplateParams;
 
+      if (ret !== null && typeof ret !== 'undefined' &&
+          typeof ret.then === 'function') {
+        if (isSync) {
+          throw new Error(
+            'A template returned a Promise but JTLT is configured with ' +
+            '`sync: true`.'
+          );
+        }
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        // eslint-disable-next-line promise/prefer-await-to-then -- intentional dynamic sync/async
+        return ret.then((/** @type {any} */ resolvedRet) => {
+          if (typeof resolvedRet !== 'undefined') {
+            const joiner = this._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);
+          }
+          this._contextNode = node;
+          return undefined;
+        });
+      }
+
       if (typeof ret !== 'undefined') {
         const joiner = this._getJoiningTransformer();
         // Close any open tag before appending template return value
@@ -586,6 +639,18 @@ class XPathTransformerContext {
         joiner.append(ret);
       }
       this._contextNode = node; // Restore (placeholder for more complex state)
+      return undefined;
+    });
+
+    if (typeof loopResult?.then === 'function') {
+      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._contextNode = preApplyContext;
+          return this;
+        })
+      );
     }
 
     this._contextNode = preApplyContext;
@@ -691,7 +756,10 @@ class XPathTransformerContext {
    * @param {string} [options.groupEndingWith] - Ends group when expression
    *   matches
    * @param {(
-   *   this: XPathTransformerContext, key: any, items: Node[], ctx: any
+   *   this: XPathTransformerContext,
+   *   key: unknown,
+   *   items: Node[],
+   *   ctx: XPathTransformerContext
    * ) => void} cb - Callback receives (groupingKey, groupItems, context)
    * @returns {this}
    */
@@ -919,25 +987,77 @@ class XPathTransformerContext {
 
   /**
    * 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 (/** @type {any} */ (this._config).sync) {
+      throw new Error(
+        'The `indexedDB()` API is unavailable when JTLT is configured with ' +
+        '`sync: true`.'
+      );
+    }
+    return queryIndexedDB(dbName, storeName, options);
+  }
+
+  /**
+   * Evaluate an XPath selector that calls the `jtlt:indexedDB(...)` function,
+   * awaiting the underlying IndexedDB reads, then append the string result.
+   * Used by {@link valueOf}. Callers reject `config.sync`.
+   * @param {string} selectStr
+   * @returns {Promise<XPathTransformerContext>}
+   */
+  async _appendIndexedDBValue (selectStr) {
+    const value = await evaluateXPathWithIndexedDB(
+      selectStr, this._contextNode
+    );
+    this._getJoiningTransformer().text(value);
+    return this;
+  }
+
   /**
    * Append the value from an XPath expression or the context node text.
    * @param {string|object} [select]
    * @returns {XPathTransformerContext}
    */
   valueOf (select) {
-    const jt = this._getJoiningTransformer();
-    let val;
-
     const selectStr = typeof select === 'object'
       ? /** @type {{select?: string}} */ (select).select
       : select;
 
+    // `jtlt:indexedDB(...)` is a registered XPath function backed by async
+    // IndexedDB reads. When it appears in the selector, evaluate the whole
+    // expression asynchronously (fontoxpath itself stays synchronous) and
+    // return a Promise so templates can `await this.valueOf(...)`.
+    if (xpathExpressionUsesIndexedDB(selectStr)) {
+      if (/** @type {any} */ (this._config).sync) {
+        throw new Error(
+          'The `indexedDB()` XPath function is unavailable when JTLT is ' +
+          'configured with `sync: true`.'
+        );
+      }
+      return /** @type {any} */ (
+        this._appendIndexedDBValue(/** @type {string} */ (selectStr))
+      );
+    }
+
+    const jt = this._getJoiningTransformer();
+    let val;
+
     // Check if select is a custom function call: prefix:name(...)
     // Try to parse and invoke registered function
     if (selectStr && (/^[^:]+:[^\(]+\(/v).test(selectStr)) {
@@ -1039,7 +1159,7 @@ class XPathTransformerContext {
           const resultToAppend = Array.isArray(result)
             ? result.join(' ')
             : result;
-          jt.append(resultToAppend);
+          jt.append(/** @type {string | Node} */ (resultToAppend));
           return this;
         }
       /* c8 ignore start -- Error handler for malformed function calls */
@@ -2002,8 +2122,8 @@ class XPathTransformerContext {
   /**
    * 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);

package/src/index.js

@@ -51,7 +51,7 @@ export const setWindow = (win) => {
  * @typedef {(this: TCtx,
  *   value: ResultType<U>,
  *   cfg?: {mode?: string}
- * ) => ResultType<T>|void} TemplateFunction
+ * ) => ResultType<T>|void|Promise<ResultType<T>|void>} TemplateFunction
  */
 
 /**
@@ -80,11 +80,71 @@ export const setWindow = (win) => {
  */
 
 /**
+ * The output-sink surface a custom `joiningTransformer` may provide. Only
+ * `append` and `get` are required; the rest are optional because the engine
+ * guards each call. The built-in joiners' `append`/`string`/… signatures
+ * diverge (e.g. the DOM joiner also accepts `Node`), so under
+ * `strictFunctionTypes` no single structural type is a supertype of all
+ * three; this contract lists the surface with `unknown` parameters, and
+ * {@link JoiningTransformer} unions it with the concrete classes so real
+ * joiners still type precisely.
+ * @typedef {object} JoiningTransformerContract
+ * @property {(item: unknown) => unknown} append
+ * @property {() => unknown} get
+ * @property {(txt: string) => unknown} [text]
+ * @property {(str: unknown, cb?: () => void) => unknown} [string]
+ * @property {(num: unknown) => unknown} [number]
+ * @property {(
+ *   obj: unknown, cb?: unknown, usePropertySets?: unknown, propSets?: unknown
+ * ) => unknown} [object]
+ * @property {(arr: unknown, cb?: unknown) => unknown} [array]
+ * @property {(
+ *   name: string, atts?: unknown, children?: unknown,
+ *   cb?: unknown, useAttributeSets?: unknown
+ * ) => unknown} [element]
+ * @property {(
+ *   name: string, val: unknown, avoidAttEscape?: unknown
+ * ) => unknown} [attribute]
+ * @property {(text: string) => unknown} [comment]
+ * @property {(
+ *   target: string, data: string
+ * ) => unknown} [processingInstruction]
+ * @property {(str: unknown) => unknown} [plainText]
+ * @property {(prop: unknown, val: unknown) => unknown} [propValue]
+ * @property {(item: unknown) => unknown} [rawAppend]
+ * @property {(prefix: string, namespaceURI: string) => unknown} [namespace]
+ * @property {(context: unknown) => unknown} [setContext]
+ * @property {(cfg: unknown) => unknown} [output]
+ * @property {(cfg: unknown) => unknown} [mode]
+ * @property {(cfg: unknown) => unknown} [stylesheet]
+ * @property {(cfg: unknown) => unknown} [function]
+ * @property {(
+ *   name: string, args?: unknown[]
+ * ) => unknown} [invokeFunctionByArity]
+ * @property {(
+ *   name: string, outputCharacters: unknown
+ * ) => unknown} [characterMap]
+ * @property {(name: string, attributes: unknown) => unknown} [attributeSet]
+ * @property {(
+ *   stylesheetPrefix: string, resultPrefix: string
+ * ) => unknown} [namespaceAlias]
+ */
+
+/**
+ * One of the three built-in joiners. Used where engine internals rely on
+ * concrete members (e.g. `_modeConfig`).
  * @typedef {(
  *   StringJoiningTransformer|
  *   DOMJoiningTransformer|
  *   JSONJoiningTransformer
- * )} JoiningTransformer
+ * )} BuiltinJoiningTransformer
+ */
+
+/**
+ * The type accepted for a config `joiningTransformer`: a built-in joiner or
+ * any object implementing {@link JoiningTransformerContract}.
+ * @typedef {BuiltinJoiningTransformer | JoiningTransformerContract
+ * } JoiningTransformer
  */
 
 /**
@@ -95,7 +155,7 @@ export const setWindow = (win) => {
  * @template T
  * @template {boolean|undefined} [E=false]
  * @typedef {T extends "json" ?
- *   (E extends true ? any[] : unknown) :
+ *   (E extends true ? unknown[] : unknown) :
  *   T extends "string" ?
  *   (E extends true ? string[] : string) :
  *   (E extends true ? XMLDocument[] :
@@ -107,9 +167,12 @@ export const setWindow = (win) => {
  * @template T
  * @template {boolean|undefined} [E=false]
  * @typedef {object} BaseJTLTOptions
+ * @property {boolean} [sync] Off by default: the engine awaits any Promise a
+ *   template returns (e.g. from `await this.indexedDB(...)`). Set `true` to
+ *   forbid asynchrony — a template that returns a Promise then throws.
  * @property {(
  *   result: ResultType<T, E>
- * ) => ResultType<T, E>|void} success A callback supplied
+ * ) => ResultType<T, E>|void} [success] A callback supplied
  *   with a single argument that is the result of this instance's
  *   transform() method. When used in TypeScript, this can be made
  *   generic as `success<T>(result: T): void`.
@@ -199,7 +262,7 @@ export const setWindow = (win) => {
  */
 
 /**
- * @template {boolean|undefined} [E=any]
+ * @template {boolean|undefined} [E=boolean|undefined]
  * @typedef {JSONPathJTLTOptions<"json", E> |
  *   JSONPathJTLTOptions<"string", E> |
  *   JSONPathJTLTOptions<"dom", E> |
@@ -556,7 +619,8 @@ class JTLT {
       }
       throw new Error('You must wait until the ajax file is retrieved');
     }
-    if (typeof this.config.success !== 'function') {
+    const {success} = this.config;
+    if (typeof success !== 'function') {
       throw new TypeError("You must supply a 'success' callback");
     }
 
@@ -585,7 +649,20 @@ class JTLT {
     );
     // The engine returns ResultType<T>. We cast through never to bypass
     // the impossible intersection type that TypeScript infers for the union.
-    const ret = this.config.success(
+    // The engine returns a Promise instead when a template ran asynchronously
+    // (e.g. it performed an `await this.indexedDB(...)` fetch); under
+    // `config.sync` the engine throws rather than returning one.
+    const maybePromise = /** @type {{then?: unknown}} */ (result);
+    if (maybePromise && typeof maybePromise.then === 'function') {
+      return /** @type {any} */ (
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        // eslint-disable-next-line promise/prefer-await-to-then -- intentional dynamic sync/async
+        /** @type {Promise<never>} */ (result).then((res) => {
+          return /** @type {any} */ (success(res));
+        })
+      );
+    }
+    const ret = success(
       /** @type {never} */ (result)
     );
     return /** @type {any} */ (ret);
@@ -657,7 +734,7 @@ class JTLT {
  */
 /**
  * @param {Omit<JTLTOptions, "success">} cfg Options
- * @returns {Promise<any>}
+ * @returns {Promise<unknown>}
  */
 export function jtlt (cfg) {
   // eslint-disable-next-line promise/avoid-new -- Own API