jtlt 0.14.0 → 0.16.0

package/src/XPathTransformerContext.js

@@ -3,6 +3,7 @@ import xpath2 from 'xpath2.js'; // Runtime JS import; ambient types declared
 // xpathVersion: 1 => browser/native XPathEvaluator API; 2 => xpath2.js, 3 => fontoxpath
 import fontoxpath from 'fontoxpath';
 import {maybeAsyncLoop} from './maybeAsync.js';
+import applyExtensions from './extendContext.js';
 import {
   queryIndexedDB,
   xpathExpressionUsesIndexedDB,
@@ -30,6 +31,14 @@ const escapeRegexReplacement = (string) => {
  * @property {boolean} [preventEval] - Whether to prevent eval in the JSONPath
  *   trailing segment of an `indexedDB(...)` expression
  * @property {(path: string) => number} [specificityPriorityResolver]
+ * @property {Record<string, unknown>} [params] Runtime parameter values
+ *   (like an XSLT processor's stylesheet parameters); a `param()` with a
+ *   matching name uses this value instead of its declared default
+ * @property {Record<string, unknown> & ThisType<
+ *   import('./XPathTransformerContext.js').default &
+ *   import('./context-extensions.js').ContextExtensions
+ * >} [extensions] Extra methods/values
+ *   merged onto this context so templates can call `this.myHelper()`
  */
 
 /**
@@ -130,10 +139,26 @@ class XPathTransformerContext {
     this._currPath = undefined; // XPath string of current context
     /** @type {Record<string, any> | undefined} */
     this._params = undefined;
+    /**
+     * Parameter values supplied at runtime via `config.params`, mirroring the
+     * stylesheet parameters an XSLT processor is handed. A `param()` whose
+     * name appears here takes this value instead of its declared default.
+     * @type {Record<string, unknown>}
+     */
+    this._runtimeParams = /** @type {any} */ (config).params || {};
+    /**
+     * Parameters staged by `withParam()` and consumed (then cleared) by the
+     * next `callTemplate()` or `applyTemplates()` call.
+     * @type {{name: string, select?: string, value?: unknown}[] | undefined}
+     */
+    this._pendingParams = undefined;
     /** @type {string[]} */
     this._preserveSpaceElements = [];
     /** @type {string[]} */
     this._stripSpaceElements = [];
+    if (config.extensions) {
+      applyExtensions(this, config.extensions);
+    }
   }
 
   /** @returns {import('./index.js').BuiltinJoiningTransformer} */
@@ -402,6 +427,12 @@ class XPathTransformerContext {
     } else {
       select ||= '*';
     }
+    // Resolve params staged via `this.withParam()` in the calling context,
+    // once, before iterating; each matched template receives them
+    // (`xsl:apply-templates` / `xsl:with-param`).
+    /** @type {Record<string, unknown>} */
+    const appliedParams = {};
+    this._drainPendingParams(appliedParams);
     const nodesResult = this._evalXPath(select, true);
     const nodes = /** @type {Node[]} */ (nodesResult);
     const modeMatched = this._templates.filter((t) => {
@@ -586,7 +617,7 @@ class XPathTransformerContext {
 
       // Set up parameter context for valueOf() access in templates
       const prevTemplateParams = this._params;
-      this._params = {0: node};
+      this._params = {0: node, ...appliedParams};
 
       /**
        * The template may return synchronously or return a Promise (e.g. from
@@ -679,6 +710,10 @@ class XPathTransformerContext {
     const params = {};
     this._params = params;
 
+    // Params staged via `this.withParam()` seed the set; explicit `withParam`
+    // entries below override any of the same name (`xsl:with-param`).
+    this._drainPendingParams(params);
+
     withParams.forEach((withParam, index) => {
       const value = withParam.value !== undefined
         ? withParam.value
@@ -1143,9 +1178,8 @@ class XPathTransformerContext {
             // Parameter reference
             if (arg.startsWith('$')) {
               const paramName = arg.slice(1);
-              return this._params && Object.hasOwn(this._params, paramName)
-                ? this._params[paramName]
-                : undefined;
+              const {has, value} = this._lookupParam(paramName);
+              return has ? value : undefined;
             }
             // XPath expression - evaluate it
             return this._evalXPath(arg, false);
@@ -1184,9 +1218,8 @@ class XPathTransformerContext {
         if (valueExpr.trimStart().startsWith('$')) {
           // Parameter reference
           const paramName = valueExpr.trim().slice(1);
-          numValue = this._params && Object.hasOwn(this._params, paramName)
-            ? this._params[paramName]
-            : 0;
+          const {has, value} = this._lookupParam(paramName);
+          numValue = has ? value : 0;
         } else {
           // Try to parse as number or evaluate as XPath
           const trimmed = valueExpr.trim();
@@ -1212,8 +1245,9 @@ class XPathTransformerContext {
     // Check if this is a parameter reference (starts with $)
     if (selectStr && selectStr.startsWith('$')) {
       const paramName = selectStr.slice(1);
-      if (this._params && Object.hasOwn(this._params, paramName)) {
-        val = this._params[paramName];
+      const paramLookup = this._lookupParam(paramName);
+      if (paramLookup.has) {
+        val = paramLookup.value;
         // If val is a Node, extract its text content
         if (val && typeof val === 'object' && 'nodeType' in val) {
           if (val.nodeType === 3) {
@@ -1372,6 +1406,125 @@ class XPathTransformerContext {
     this.vars[name] = this.get(select, true);
     return this;
   }
+
+  /**
+   * Normalize a `param()`/`withParam()` default/value argument to `{select}`
+   * or `{value}`: a bare string is an XPath expression, `{value}` is a
+   * literal, and `{select}` (or an omitted argument) is an expression.
+   * @param {string|{select?: string, value?: unknown}|undefined} arg
+   * @returns {{select?: string, value?: unknown}}
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this -- pure helper
+  _paramSpec (arg) {
+    if (typeof arg === 'string') {
+      return {select: arg};
+    }
+    if (arg && 'value' in arg) {
+      return {value: arg.value};
+    }
+    // `{select}` object, or omitted (a default of `undefined`).
+    return {select: arg && arg.select};
+  }
+
+  /**
+   * Look up a parameter by name across the active with-param scope and the
+   * runtime `config.params`, so runtime-supplied params act like XSLT global
+   * parameters (visible to every template and expression).
+   * @param {string} name
+   * @returns {{has: boolean, value: any}}
+   * @private
+   */
+  _lookupParam (name) {
+    if (this._params && Object.hasOwn(this._params, name)) {
+      return {has: true, value: this._params[name]};
+    }
+    if (Object.hasOwn(this._runtimeParams, name)) {
+      return {has: true, value: this._runtimeParams[name]};
+    }
+    return {has: false, value: undefined};
+  }
+
+  /**
+   * Resolve a `{select}` or `{value}` parameter spec to its value in the
+   * current context. An XPath `select` is resolved to a first/atomic value
+   * (as `callTemplate`'s `withParam` already does), so `$name` references
+   * render as a string rather than a node object.
+   * @param {{select?: string, value?: unknown}} spec
+   * @returns {any}
+   * @private
+   */
+  _resolveParam (spec) {
+    if ('value' in spec) {
+      return spec.value;
+    }
+    if (spec.select === undefined) {
+      return undefined;
+    }
+    const resolved = this.get(spec.select, false);
+    // A node-set `select` yields an array; bind the first node so a `$name`
+    // reference renders as its string-value (XSLT behavior).
+    return Array.isArray(resolved) ? resolved[0] : resolved;
+  }
+
+  /**
+   * Resolve staged `withParam()` entries into `target` (in the calling
+   * context) and clear the staged set. Shared by `callTemplate()` and
+   * `applyTemplates()`.
+   * @param {Record<string, unknown>} target
+   * @returns {void}
+   * @private
+   */
+  _drainPendingParams (target) {
+    const pending = this._pendingParams;
+    this._pendingParams = undefined;
+    if (!pending) {
+      return;
+    }
+    for (const entry of pending) {
+      target[entry.name] = this._resolveParam(entry);
+    }
+  }
+
+  /**
+   * Declare a template parameter, equivalent to `xsl:param`. Binds `name` to
+   * the given default, unless a value was supplied by the caller (via
+   * `this.withParam()` or `callTemplate`'s `withParam`) or at runtime (via
+   * `config.params`), in which case the supplied value wins.
+   * @param {string} name - Parameter name
+   * @param {string|{select: string}|{value: unknown}} [select] - The default:
+   *   an XPath expression string, an explicit `{select}`, or a literal
+   *   `{value}`. Omitted means a default of `undefined`.
+   * @returns {XPathTransformerContext}
+   */
+  param (name, select) {
+    this._params ||= {};
+    const supplied = this._lookupParam(name);
+    // A caller's with-param or a `config.params` value overrides the default.
+    const resolved = supplied.has
+      ? supplied.value
+      : this._resolveParam(this._paramSpec(select));
+    this._params[name] = resolved;
+    this.vars[name] = resolved;
+    return this;
+  }
+
+  /**
+   * Stage a parameter for the next `callTemplate()` or `applyTemplates()`
+   * call, equivalent to `xsl:with-param`. The staged set is consumed and
+   * cleared by that call; entries are evaluated in the current (calling)
+   * context.
+   * @param {string} name - Parameter name
+   * @param {string|{select: string}|{value: unknown}} [select] - An XPath
+   *   expression string, an explicit `{select}`, or a literal `{value}`.
+   * @returns {XPathTransformerContext}
+   */
+  withParam (name, select) {
+    this._pendingParams ||= [];
+    this._pendingParams.push({name, ...this._paramSpec(select)});
+    return this;
+  }
+
   /**
    * Log a message (for debugging).
    * @param {unknown} json Any value

package/src/context-extensions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Consumer-augmentable registry of the helper methods/values added to a
+ * template context through the `extensions` option.
+ *
+ * `extensions` are merged onto the `this` seen inside templates at runtime,
+ * but TypeScript cannot see them unless they are declared here. Augment this
+ * interface with declaration merging so calls like `this.myHelper()` inside a
+ * template type-check without suppressions:
+ *
+ * @example
+ * ```ts
+ * declare module 'jtlt/context-extensions' {
+ *   interface ContextExtensions {
+ *     myHelper (): void;
+ *   }
+ * }
+ * ```
+ *
+ * Leaving it un-augmented keeps templates strict: an undeclared `this.foo()`
+ * is still a type error.
+ *
+ * Intentionally empty; consumers populate it via declaration merging.
+ */
+export interface ContextExtensions {}

package/src/extendContext.js

@@ -0,0 +1,21 @@
+/**
+ * Merges `extensions` onto a template context instance so templates can
+ * invoke them as `this.myHelper()`. Shared by JSONPathTransformerContext
+ * and XPathTransformerContext.
+ * @param {object} context - The context instance to extend
+ * @param {Record<string, unknown>} extensions - Extra methods/values
+ * @returns {void}
+ */
+export default function applyExtensions (context, extensions) {
+  for (const key of Object.keys(extensions)) {
+    // eslint-disable-next-line @stylistic/max-len -- Long
+    // eslint-disable-next-line unicorn/no-computed-property-existence-check -- Needed
+    if (key in context) {
+      throw new Error(
+        `Extension property "${key}" conflicts with an existing ` +
+        'context property.'
+      );
+    }
+  }
+  Object.assign(context, extensions);
+}

package/src/index.js

@@ -44,11 +44,15 @@ export const setWindow = (win) => {
  */
 
 /**
- * A callable template function with an engine-specific `this`.
+ * A callable template function with an engine-specific `this`. The `this`
+ * type is intersected with {@link ContextExtensions} so helpers registered
+ * through the `extensions` option are visible once a consumer augments that
+ * interface.
  * @template T
  * @template U
  * @template TCtx
- * @typedef {(this: TCtx,
+ * @typedef {(this: TCtx &
+ *     import('./context-extensions.js').ContextExtensions,
  *   value: ResultType<U>,
  *   cfg?: {mode?: string}
  * ) => ResultType<T>|void|Promise<ResultType<T>|void>} TemplateFunction
@@ -214,6 +218,11 @@ export const setWindow = (win) => {
  *   transformer.
  * @property {object} [parent] Parent object for context
  * @property {string} [parentProperty] Parent property name for context
+ * @property {Record<string, unknown>} [params] Parameter values supplied at
+ *   runtime, mirroring the stylesheet parameters an XSLT processor is handed.
+ *   A `this.param(name, default)` declaration whose name appears here resolves
+ *   to this value instead of its default, and `$name` references such a
+ *   parameter from any template.
  */
 
 /**
@@ -233,6 +242,10 @@ export const setWindow = (win) => {
  *   forQuery?: [string, TemplateFunction<T, "json",
  *     import('./XPathTransformerContext.js').default
  *   >],
+ *   extensions?: Record<string, unknown> & ThisType<
+ *     import('./JSONPathTransformerContext.js').default<T> &
+ *     import('./context-extensions.js').ContextExtensions
+ *   >,
  *   engineType?: 'jsonpath',
  *   outputType?: T
  * }} JSONPathJTLTOptions
@@ -255,6 +268,10 @@ export const setWindow = (win) => {
  *   forQuery?: [string, TemplateFunction<T, "dom",
  *     import('./JSONPathTransformerContext.js').default
  *   >],
+ *   extensions?: Record<string, unknown> & ThisType<
+ *     import('./XPathTransformerContext.js').default &
+ *     import('./context-extensions.js').ContextExtensions
+ *   >,
  *   engineType: 'xpath',
  *   xpathVersion?: 1|2|3.1,
  *   outputType?: T
@@ -476,7 +493,9 @@ class JTLT {
         // eslint-disable-next-line @stylistic/max-len -- Long
         // eslint-disable-next-line unicorn/no-array-method-this-argument -- Not array
         this.forEach(path, (arg) => {
-          const ret = fn.call(this, arg);
+          // `this` carries runtime `extensions`; a consumer's
+          // `ContextExtensions` augmentation would otherwise reject it here.
+          const ret = fn.call(/** @type {any} */ (this), arg);
           if (typeof ret !== 'undefined') {
             // @ts-expect-error Ok?
             this._getJoiningTransformer().append(ret);

package/tsconfig.json

@@ -11,8 +11,8 @@
     "types": ["mocha"]
   },
   "include": [
-    "*.js", "*.d.ts", "src/**/*.js", "demo/**/*.js", "test/**/*.js",
-    "typings/xpath2-js.d.ts"
+    "*.js", "*.d.ts", "src/**/*.js", "src/**/*.d.ts", "demo/**/*.js",
+    "test/**/*.js", "test/**/*.d.ts", "typings/xpath2-js.d.ts"
   ],
   "exclude": ["node_modules", "test.js", "./dist/**/*.js", "demo/codemirror.esm.js", "demo/vendor"]
 }