jtlt 0.13.0 → 0.15.0

package/dist/indexedDB.d.ts

@@ -0,0 +1,107 @@
+export type OpenDBFunction = typeof import("idb").openDB;
+export type IndexedDBResultType = 'value' | 'key' | 'primaryKey' | 'all';
+export type QueryOptions = {
+    index?: string;
+    range?: {
+        lower?: IDBValidKey;
+        upper?: IDBValidKey;
+        lowerOpen?: boolean;
+        upperOpen?: boolean;
+    };
+    query?: NonNullable<object | string | number>;
+    direction?: 'next' | 'nextunique' | 'prev' | 'prevunique';
+    count?: number;
+    resultType?: IndexedDBResultType;
+};
+export type IdbCursorLike = {
+    key: IDBValidKey;
+    primaryKey: IDBValidKey;
+    value: unknown;
+    continue: () => Promise<IdbCursorLike | null>;
+};
+export type IdbRecord = {
+    key: IDBValidKey;
+    primaryKey: IDBValidKey;
+    value: unknown;
+};
+export type IdbQueryTarget = {
+    openCursor: (range?: IDBKeyRange | null, direction?: IDBCursorDirection) => Promise<IdbCursorLike | null>;
+    openKeyCursor: (range?: IDBKeyRange | null, direction?: IDBCursorDirection) => Promise<IdbCursorLike | null>;
+    getAll: (range?: IDBKeyRange | null, count?: number) => Promise<unknown[]>;
+    getAllKeys: (range?: IDBKeyRange | null, count?: number) => Promise<IDBValidKey[]>;
+    getAllRecords?: ((options?: {
+        query?: IDBKeyRange | null;
+        count?: number;
+        direction?: IDBCursorDirection;
+    }) => Promise<IdbRecord[]>);
+};
+export declare function queryIndexedDB(dbName: string, storeName: string, options: QueryOptions & {
+    resultType: 'all';
+}): Promise<IdbRecord[]>;
+export declare function queryIndexedDB(dbName: string, storeName: string, options: QueryOptions & {
+    resultType: 'key' | 'primaryKey';
+}): Promise<IDBValidKey[]>;
+export declare function queryIndexedDB(dbName: string, storeName: string, options?: QueryOptions): Promise<unknown[]>;
+export type ParsedIndexedDBExpression = {
+    dbName: string;
+    storeName: string;
+    options: QueryOptions | undefined;
+    /**
+     * - A JSONPath segment applied to the fetched
+     * records (e.g. `.*.name` or `[0].name`), with surrounding whitespace
+     * trimmed. Used by the JSONPath engine only; the XPath engine exposes
+     * `indexedDB()` as a registered XPath function instead (see
+     * {@link evaluateXPathWithIndexedDB}).
+     */
+    trailing: string;
+};
+/**
+ * @typedef {object} ParsedIndexedDBExpression
+ * @property {string} dbName
+ * @property {string} storeName
+ * @property {QueryOptions|undefined} options
+ * @property {string} trailing - A JSONPath segment applied to the fetched
+ *   records (e.g. `.*.name` or `[0].name`), with surrounding whitespace
+ *   trimmed. Used by the JSONPath engine only; the XPath engine exposes
+ *   `indexedDB()` as a registered XPath function instead (see
+ *   {@link evaluateXPathWithIndexedDB}).
+ */
+/**
+ * Detect and parse an `indexedDB(...)` call at the start of a selector string.
+ * @param {string} expr
+ * @returns {ParsedIndexedDBExpression|null} `null` when `expr` is not an
+ *   `indexedDB(...)` expression.
+ */
+export declare function parseIndexedDBExpression(expr: string): ParsedIndexedDBExpression | null;
+/**
+ * Fetch the records for a parsed `indexedDB(...)` expression and, when a
+ * trailing JSONPath segment is present (e.g. `.*.name`), evaluate it against
+ * the fetched records. Shared by the JSONPath and XPath engines.
+ * @param {ParsedIndexedDBExpression} parsed
+ * @param {{preventEval?: boolean}} [options]
+ * @returns {Promise<unknown>}
+ */
+export declare function resolveIndexedDBQuery(parsed: ParsedIndexedDBExpression, { preventEval }?: {
+    preventEval?: boolean;
+}): Promise<unknown>;
+/**
+ * Namespace URI backing the predefined `jtlt` prefix under which the XPath
+ * `indexedDB()` function is registered.
+ */
+export declare const JTLT_XPATH_NAMESPACE = "urn:jtlt";
+/**
+ * @param {unknown} expr
+ * @returns {boolean} Whether `expr` calls the `indexedDB()` XPath function
+ */
+export declare function xpathExpressionUsesIndexedDB(expr: unknown): boolean;
+/**
+ * Evaluate an XPath 3.1 expression that may call `jtlt:indexedDB(...)`,
+ * to a string. Because fontoxpath is synchronous, this first evaluates the
+ * expression in "collect" mode to discover every `indexedDB()` call, awaits
+ * those queries, then evaluates again with the records available.
+ * @param {string} selectStr
+ * @param {Node} contextNode
+ * @returns {Promise<string>}
+ */
+export declare function evaluateXPathWithIndexedDB(selectStr: string, contextNode: Node): Promise<string>;
+//# sourceMappingURL=indexedDB.d.ts.map

package/dist/indexedDB.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexedDB.d.ts","sourceRoot":"","sources":["../src/indexedDB.js"],"names":[],"mappings":"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"}

package/dist/maybeAsync.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Iterate over an array, staying fully synchronous while `body` returns
+ * synchronously and only chaining Promises once `body` returns a thenable.
+ *
+ * This lets a nested asynchronous operation (e.g. an
+ * `await this.indexedDB(...)` fetch inside a template) suspend the loop,
+ * without forcing the common synchronous case through microtasks or
+ * breaking DOM-bound consumers.
+ * @template T
+ * @param {T[]} array
+ * @param {(item: T, index: number, arr: T[]) => any} body
+ * @returns {Promise<void>|void}
+ */
+export declare function maybeAsyncLoop<T>(array: T[], body: (item: T, index: number, arr: T[]) => any): Promise<void> | void;
+//# sourceMappingURL=maybeAsync.d.ts.map

package/dist/maybeAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maybeAsync.d.ts","sourceRoot":"","sources":["../src/maybeAsync.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CALjB,CAAC,EAKkB,KAAK,EAJ1B,CAAC,EAIyB,EAAE,IAAI,EAHhC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,GAGN,GAF9B,OAAO,CAAC,IAAI,CAAC,GAAC,IAAI,CAgC9B"}

package/docs/API.expanded.md

@@ -4,14 +4,18 @@ This document describes the public API surface of JTLT (JavaScript Template Lang
 
 > Early alpha: APIs may evolve; experimental sections (XPath) can change without major version bumps.
 
-## Core façade: `JTLT`
+## Entry points: `jtlt()` and `JTLT`
 
-High-level entry point for running a transform over JSON data using JSONPath.
+### `jtlt(config)` — recommended
+
+Runs a transform and returns a `Promise` resolving to the result. It takes
+every option below **except `success`**, and does not accept `autostart`
+meaningfully (it always runs).
 
 ```js
-import JTLT from 'jtlt';
+import {jtlt} from 'jtlt';
 
-const out = JTLT.create({
+const out = await jtlt({
   data: {title: 'Hello'},
   outputType: 'string',
   templates: [
@@ -22,31 +26,56 @@ const out = JTLT.create({
         this.string('</h1>');
       }
     }
-  ],
+  ]
+});
+```
+
+### `JTLT` class — lower level
+
+`JTLT.create(config)` (or `new JTLT(config)`) returns a `JTLT` instance. The
+result is delivered through the **required `success` callback**, which is
+also the return value of `.transform(mode?)`:
+
+```js
+import JTLT from 'jtlt';
+
+const inst = JTLT.create({
+  data: {title: 'Hello'},
+  outputType: 'string',
+  templates: [/* … */],
   success: (res) => res
-}).transform('');
+});
+const out = inst.transform('');
 ```
 
-### `new JTLT(config)` or `JTLT.create(config)` options
+By default the constructor runs the transform immediately; pass
+`autostart: false` to defer it to your own `.transform()` call.
+
+### Options
+
+Common to both entry points unless noted.
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
-| `data` | any | Root JSON/JS object. Required unless `ajaxData` provided. |
+| `data` | object \| primitive | Root JSON/JS value (or DOM `Document`/`Element` for the XPath engine). Required unless `ajaxData` provided. |
 | `ajaxData` | string | URL to fetch JSON (async start). |
-| `templates` | Array<TemplateObject> | Template declarations; see below. |
+| `templates` | Array&lt;TemplateObject&gt; | Template declarations; see below. |
 | `template` | Function \| TemplateObject | Single root template convenience. |
 | `query` | Function | Root template convenience (wrapped as `path: '$'`). |
 | `forQuery` | [select, cb] | One-off query (like FLWOR `for`). Auto-wrapped as root template. |
-| `success` | Function(result) | Required callback; also receives transform return. |
+| `success` | Function(result) | **`JTLT` only** — required callback; also the return of `.transform()`. Not accepted by `jtlt()`. |
 | `mode` | string | Starting mode for template matching. |
-| `outputType` | 'string' \| 'dom' \| 'json' | Chooses joiner. Default 'string'. |
-| `joiningTransformer` | Joiner instance | Custom joiner; skip auto creation. |
+| `outputType` | 'string' \| 'dom' \| 'json' | Chooses joiner. Default `'string'`. |
+| `engineType` | 'jsonpath' \| 'xpath' | Engine to use. Default `'jsonpath'`. |
+| `xpathVersion` | 1 \| 2 \| 3.1 | XPath engine only. `1` native, `2` xpath2.js, `3.1` fontoxpath. Default `1`. |
+| `sync` | boolean | Off by default (async templates are awaited). When `true`, a template that returns a Promise throws; disables `indexedDB()`. |
+| `joiningTransformer` | Joiner | Custom joiner; skip auto creation. Needs `append` and `get` (see `JoiningTransformerContract`). |
 | `joiningConfig` | object | Passed to joiner (e.g., `{xmlElements:true}`). |
 | `unwrapSingleResult` | boolean | For JSON joiner: unwrap single-item root array. |
 | `errorOnEqualPriority` | boolean | Throw when multiple templates share priority on a node. |
-| `specificityPriorityResolver` | fn(path)=>number | Custom resolver for relative priorities. Defaults to XSLT-like JSONPath resolver. |
-| `engine` | fn(config)=>any | Override transform engine (defaults to JSONPathTransformer). |
-| `autostart` | boolean | If `false`, don’t auto-call `transform()` in constructor. |
+| `specificityPriorityResolver` | fn(path)=&gt;number | Custom resolver for relative priorities. Defaults to XSLT-like JSONPath resolver. |
+| `engine` | fn(config)=&gt;result | Override transform engine (defaults to JSONPathTransformer). |
+| `autostart` | boolean | **`JTLT` only** — if `false`, don't auto-call `transform()` in constructor. |
 | `preventEval` | boolean | Disable parenthetical eval portions of JSONPath (security). |
 
 ## Template objects
@@ -123,9 +152,10 @@ const out = engine.transform('');
 ```
 
 Limitations:
-- Versions 2 and 3 (`xpath2.js` and `fontoxpath`) may lack some XPath functions;
-  stick to basic location paths and simple predicates.
-- Namespace resolution not yet exposed (future `namespaceResolver` option).
+- Versions 2 and 3.1 (`xpath2.js` and `fontoxpath`) may lack some XPath
+  functions; stick to basic location paths and simple predicates.
+- A user `namespaceResolver` option is not yet exposed (the XPath 3.1
+  `jtlt:` prefix used by `indexedDB()` is wired in internally).
 
 ## Contexts
 
@@ -144,6 +174,13 @@ Methods (subset):
 - `variable(name, select)` – stores value/array from JSONPath.
 - `callTemplate(name, withParam?)`
 - `key(name, match, use)` / `getKey(name, value)`
+- `indexedDB(dbName, storeName, options?)` – returns a `Promise` of matching
+  IndexedDB records. `options` mirror `jsonpath-plus`'s `resultType`
+  (`'value'` default, `'key'`, `'primaryKey'`, `'all'`) plus `index`,
+  `range`, `query`, `direction`, `count`. A template using it must be
+  `async` (or return the Promise). Throws under `sync: true`. A selector of
+  the form `indexedDB('db', 'store').*.name` in `valueOf()` is intercepted
+  and resolved the same way.
 - Joiner passthrough: `string()`, `text()`, `element()`, `object()`, `array()`, `number()`, `boolean()`, etc.
 \- Cloning helpers:
   - `copy(propertySets?)` — Shallow clone of current context value (object/array). Nested references are preserved. Optional `propertySets` (array of registered names) merge into the top-level clone when object-like.
@@ -163,6 +200,14 @@ Parallels JSONPath context with XPath evaluation:
   current context node; absolute paths (`/`, `//`) target the document root.
 - `variable(name, select)` – always stores node arrays for XPath.
 - `key(name, match, use)` – index by attribute value; `getKey` returns matching Element or context sentinel (`this`).
+- `indexedDB(dbName, storeName, options?)` – same direct helper as the
+  JSONPath context. Additionally, `jtlt:indexedDB('db', 'store')` is
+  registered as an XPath 3.1 function (predefined `jtlt` prefix,
+  `urn:jtlt`), so `valueOf()` selectors such as
+  `string-join(jtlt:indexedDB('db', 'store') ! ?name, ',')` work; options
+  are passed as an XPath map. Since fontoxpath is synchronous, the
+  expression is evaluated in a collect pass, the queries are awaited, then
+  it is re-evaluated with the records. Throws under `sync: true`.
 - Default template rules: root traverses `.`, element traverses `*`, text nodes emit `nodeValue`, scalars emit `valueOf('.')`.
 \- Cloning helpers:
   - `copy()` — Shallow clone of the current context node (`cloneNode(false)`) appended to the joiner.
@@ -456,9 +501,14 @@ See `README.md` for FLWOR-style and join patterns.
 ## Roadmap (selected)
 
 - Namespace support for XPath.
-- Copy helpers (deep/shallow) parity with XSLT.
-- Streaming / async query execution.
 - Schema-aware template targeting.
+- Broader async data sources (async templates and IndexedDB access via
+  `this.indexedDB(...)` already land).
+- Closing remaining `xsl:copy` / `xsl:copy-of` parity gaps: a sequence
+  constructor for `copy()` (shallow-copy the node, then build its content in
+  the same call), `use-attribute-sets` on the XPath `copy()` (the JSONPath
+  one already takes `propertySets`), and `copy-namespaces` /
+  `inherit-namespaces` control over which namespace nodes are carried.
 
 ## Versioning
 

package/docs/API.md

@@ -3,11 +3,15 @@
 For the full reference (engines, contexts, joiners, sorting, keys, variables,
 property sets, defaults, roadmap), see `docs/API.expanded.md`.
 
-## Facade: JTLT
+## Entry points: `jtlt()` and `JTLT`
+
+**`jtlt(config)`** is the recommended entry point. It runs the transform and
+returns a `Promise` that resolves to the result — no `success` callback:
 
 ```js
-import JTLT from 'jtlt';
-JTLT.create({
+import {jtlt} from 'jtlt';
+
+const out = await jtlt({
   data: {title: 'Hi'},
   templates: [
     {path: '$.title', template (v) {
@@ -15,11 +19,32 @@ JTLT.create({
       this.string('</h1>');
     }}
   ],
+  outputType: 'string'
+});
+```
+
+Async templates (e.g. `await this.indexedDB(...)`) are awaited automatically;
+pass `sync: true` to forbid them (a template that returns a Promise then
+throws).
+
+The lower-level **`JTLT`** class (`JTLT.create(config)` / `new JTLT(config)`)
+is for when you need the instance itself, `autostart: false`, or to call
+`.transform(mode)` yourself. It delivers the result through a **required
+`success` callback** (also returned from `.transform()`):
+
+```js
+import JTLT from 'jtlt';
+
+const out = JTLT.create({
+  data: {title: 'Hi'},
+  templates: [/* … */],
   outputType: 'string',
-  success: (out) => out
+  success: (result) => result
 }).transform('');
 ```
 
+`jtlt()` accepts every `JTLT` option except `success`.
+
 ## Engines
 
 - JSONPathTransformer: on JSON with JSONPath selectors; resolves
@@ -33,6 +58,11 @@ JTLT.create({
 `variable(name, select)`, `key(name, match, use)`, `getKey(name, value)`.
 JSONPath variables store values; XPath variables store arrays of nodes.
 
+Async: a template may be `async` and `await` inside it. `this.indexedDB(db,
+store, options?)` resolves to matching IndexedDB records (see
+`docs/API.expanded.md`). Unavailable when JTLT is configured with
+`sync: true`.
+
 Cloning:
 `copy()` (shallow clone current JSON value or DOM node) and
 `copyOf(select?)` (deep clone; optional selector overrides target; scalar

package/docs/TO-DO.md

@@ -76,7 +76,7 @@
     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
+    iterating or retrieving `localStorage` and cookies
     (names, keys and values).
 
 6. Add `outputType` which uses a DOM joiner but allows specialized
@@ -86,9 +86,23 @@
 
 7. See code for other possible to-dos
 
-8. Promise-based templates; jtlt as templating engine (including zodexy-aware path expressions like @blob() for jsonpath-plus with `copyOf`/`valueOf` `document(...url...)` or our own indexeddb path db/store/key equivalent); work on **schema-driven** search forms too
+8. jtlt as templating engine (including zodexy-aware path expressions like @blob() for jsonpath-plus with `copyOf`/`valueOf` `document(...url...)`; work on **schema-driven** search forms too
 
-9. Consider implementing the following elements from <https://www.w3.org/TR/xslt-30/>
+9. Note that while we could allow `template` to act as a sync function with sync calls to `this.valueOf` even when indexedDB was used within that latter call, the problem is that with the easy solution, it would require adding content to output after subsequent synchronous calls within the function did so.
+
+```js
+const args = {
+  template () {
+    this.valueOf({select: "indexedDB('db','store').*.name"}); // resolves later
+    this.string('!'); // appends NOW
+  }
+};
+// -> "!Alice,Bob,Charlie"   (not "Alice,Bob,Charlie!")
+```
+
+We'd otherwise have to refactor a great deal to maintain a buffer.
+
+10. Consider implementing the following elements from <https://www.w3.org/TR/xslt-30/>
     which are not yet implemented.
 
   xsl:accept

package/eslint.config.js

@@ -9,6 +9,14 @@ export default [
       'demo/codemirror.esm.js'
     ]
   },
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      globals: {
+        IDBKeyRange: 'readonly'
+      }
+    }
+  },
   ...ashNazg(['sauron']),
   {
     rules: {
@@ -19,9 +27,6 @@ export default [
       'unicorn/prefer-private-class-fields': 0,
       'unicorn/no-undeclared-class-members': 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,
 
@@ -42,6 +47,9 @@ export default [
   {
     files: ['test/**/*.js', 'test.js'],
     rules: {
+      // Reapply rule to testing file as it demonstrates the API
+      'jsdoc/reject-any-type': ['error'],
+
       'unicorn/prefer-https': 0, // Old namespaces
       // Too many are JSON properties called "children"
       'unicorn/better-dom-traversing': 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jtlt",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "author": "Brett Zamir",
   "contributors": [],
@@ -8,12 +8,17 @@
   "types": "./dist/index.d.ts",
   "main": "src/index-node.js",
   "exports": {
-    "types": "./dist/index.d.ts",
-    "browser": {
-      "import": "./src/index-browser.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": {
+        "import": "./src/index-browser.js"
+      },
+      "node": {
+        "import": "./src/index-node.js"
+      }
     },
-    "node": {
-      "import": "./src/index-node.js"
+    "./context-extensions": {
+      "types": "./dist/context-extensions.d.ts"
     }
   },
   "engines": {
@@ -29,11 +34,12 @@
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/lang-xml": "^6.1.0",
     "@codemirror/language": "^6.12.4",
-    "@codemirror/state": "^6.7.1",
+    "@codemirror/state": "^6.7.4",
     "@lezer/highlight": "^1.2.3",
     "codemirror": "^6.0.2",
     "fontoxpath": "^3.34.0",
-    "jamilih": "0.69.0",
+    "idb": "^8.0.3",
+    "jamilih": "0.69.1",
     "jhtml": "0.7.3",
     "jsdom": "30.0.1",
     "jsonpath-plus": "10.4.0",
@@ -50,14 +56,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.21",
     "c8": "^12.0.0",
     "chai": "^6.2.2",
-    "eslint": "^10.9.1",
-    "eslint-config-ash-nazg": "^42.6.0",
-    "mocha": "^11.8.0",
-    "open": "^11.0.1",
-    "rollup": "^4.63.0",
+    "eslint": "^10.10.0",
+    "eslint-config-ash-nazg": "^43.1.7",
+    "indexeddbshim": "^19.0.1",
+    "mocha": "^12.0.0",
+    "open": "^11.0.2",
+    "rollup": "^4.63.1",
     "typescript": "^7.0.2"
   },
   "bugs": "https://github.com/brettz9/jtlt/issues",
@@ -72,7 +79,7 @@
     "start": "open http://localhost:8021/demo/ && static -p 8021",
     "attw": "attw --pack . --profile esm-only",
     "tsc": "tsc",
-    "build": "tsc -p tsconfig-prod.json && npm run rollup",
+    "build": "tsc -p tsconfig-prod.json && cp src/context-extensions.d.ts dist/context-extensions.d.ts && npm run rollup",
     "rollup": "rollup -c",
     "copy-simple-get-json": "cp -r node_modules/simple-get-json/dist/index-es.js demo/vendor/simple-get-json/dist/index-es.js",
     "copy-jhtml": "cp -Rf node_modules/jhtml/src demo/vendor/jhtml",

package/pnpm-workspace.yaml

@@ -1,4 +1,6 @@
 allowBuilds:
+  better-sqlite3: true
+  canvas: true
   is-hidden-file: true
   libxmljs: true
   unrs-resolver: true
@@ -30,3 +32,10 @@ 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 || 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
+  - open@11.0.2
+  - powershell-utils@0.2.1
+  - websql-configurable@4.0.0

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,48 @@ 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});
+      // `this` carries runtime `extensions`; a consumer's `ContextExtensions`
+      // augmentation would otherwise reject the bare context here.
+    ).template.call(/** @type {any} */ (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>