jtlt 0.8.0 → 0.10.0

package/src/AbstractJoiningTransformer.js

@@ -77,6 +77,39 @@ class AbstractJoiningTransformer {
 
     /** @type {Map<string, string>} */
     this._namespaceAliases = new Map();
+
+    /**
+     * @type {{
+     *   onMultipleMatch?: "use-last"|"fail",
+     *   warningOnMultipleMatch?: boolean,
+     *   onNoMatch?: "shallow-copy"|"deep-copy"|"fail"|"apply-templates"|
+     *     "shallow-skip"|"deep-skip"|"text-only-copy",
+     *   warningOnNoMatch?: boolean
+     * }|undefined}
+     */
+    this._modeConfig = undefined;
+
+    /** @type {Set<string>} */
+    this._excludeResultPrefixes = new Set();
+
+    /** @type {Set<string>} */
+    this._usedNamespacePrefixes = new Set();
+
+    /**
+     * Pending namespace declarations that may be excluded.
+     * @type {Array<{
+     *   prefix: string,
+     *   namespaceURI: string,
+     *   callback: () => void
+     * }>}
+     */
+    this._pendingNamespaces = [];
+
+    /**
+     * Track which prefixes have pending namespace declarations.
+     * @type {Map<string, {prefix: string, namespaceURI: string}>}
+     */
+    this._pendingNamespaceMap = new Map();
   }
 
   /**
@@ -101,6 +134,52 @@ class AbstractJoiningTransformer {
     return this;
   }
 
+  /**
+   * Configure mode behavior (similar to xsl:mode).
+   * @param {{
+   *   onMultipleMatch?: "use-last"|"fail",
+   *   warningOnMultipleMatch?: boolean,
+   *   onNoMatch?: "shallow-copy"|"deep-copy"|"fail"|"apply-templates"|
+   *     "shallow-skip"|"deep-skip"|"text-only-copy",
+   *   warningOnNoMatch?: boolean
+   * }} cfg - Mode configuration
+   * @returns {this}
+   */
+  mode (cfg) {
+    this._modeConfig = cfg;
+    return this;
+  }
+
+  /**
+   * Configure stylesheet behavior (similar to xsl:stylesheet).
+   * Unlike xsl:stylesheet, this is a directive method and does not contain
+   * nested content.
+   * @param {{
+   *   excludeResultPrefixes?: string[]
+   * }} cfg - Stylesheet configuration
+   * @returns {this}
+   */
+  stylesheet (cfg) {
+    if (cfg.excludeResultPrefixes) {
+      for (const prefix of cfg.excludeResultPrefixes) {
+        // Normalize empty string to internal #default representation
+        this._excludeResultPrefixes.add(prefix === '' ? '#default' : prefix);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Alias for stylesheet() method (XSLT compatibility).
+   * @param {{
+   *   excludeResultPrefixes?: string[]
+   * }} cfg - Stylesheet configuration
+   * @returns {this}
+   */
+  transform (cfg) {
+    return this.stylesheet(cfg);
+  }
+
   /**
    * @param {string} name
    * @param {OutputCharacters} outputCharacters
@@ -171,6 +250,12 @@ class AbstractJoiningTransformer {
     const prefix = colonIdx === -1 ? '#default' : elemName.slice(0, colonIdx);
     const alias = this._getNamespaceAlias(prefix);
 
+    // Track that this prefix (after aliasing) is actually used
+    this._usedNamespacePrefixes.add(alias);
+
+    // If this prefix was buffered, output it now
+    this._flushPendingNamespace(alias);
+
     if (colonIdx === -1) {
       if (alias === '#default') {
         return elemName;
@@ -184,6 +269,34 @@ class AbstractJoiningTransformer {
     ) + elemName.slice(colonIdx + 1);
   }
 
+  /**
+   * Output a pending namespace declaration if it exists.
+   * This method should be overridden by subclasses.
+   * @param {string} _prefix
+   * @returns {void}
+   */
+  // eslint-disable-next-line class-methods-use-this -- Abstract
+  _flushPendingNamespace (_prefix) {
+    // Default implementation does nothing - subclasses override
+    // Using _prefix to indicate unused parameter
+  }
+
+  /**
+   * Track attribute name prefix usage.
+   * @param {string} attrName
+   * @returns {void}
+   */
+  _trackAttributePrefix (attrName) {
+    const colonIdx = attrName.indexOf(':');
+    if (colonIdx !== -1 && !attrName.startsWith('xmlns')) {
+      const prefix = attrName.slice(0, colonIdx);
+      this._usedNamespacePrefixes.add(prefix);
+
+      // If this prefix was buffered, output it now
+      this._flushPendingNamespace(prefix);
+    }
+  }
+
   /**
    * @param {string} str
    * @returns {string}

package/src/DOMJoiningTransformer.js

@@ -479,7 +479,24 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
    * @returns {DOMJoiningTransformer}
    */
   namespace (prefix, namespaceURI) {
-    const alias = this._getNamespaceAlias(prefix);
+    let alias = this._getNamespaceAlias(prefix);
+
+    // Normalize empty string or undefined/null to #default
+    if (!alias) {
+      alias = '#default';
+    }
+    const normalizedPrefix = alias;
+
+    // If this prefix is excluded, buffer it instead of outputting immediately
+    if (this._excludeResultPrefixes.has(normalizedPrefix)) {
+      this._pendingNamespaceMap.set(normalizedPrefix, {
+        prefix: alias,
+        namespaceURI
+      });
+      return this;
+    }
+
+    // Not excluded, output immediately
     /** @type {Element} */
     (this._dom).setAttributeNS(
       'http://www.w3.org/2000/xmlns/',
@@ -489,6 +506,23 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
     return this;
   }
 
+  /**
+   * @param {string} prefix
+   * @returns {void}
+   * @override
+   */
+  _flushPendingNamespace (prefix) {
+    const pending = this._pendingNamespaceMap.get(prefix);
+    if (pending) {
+      /** @type {Element} */
+      (this._dom).setAttributeNS(
+        'http://www.w3.org/2000/xmlns/',
+        pending.prefix === '#default' ? 'xmlns' : 'xmlns:' + pending.prefix,
+        this._replaceCharacterMaps(pending.namespaceURI)
+      );
+      this._pendingNamespaceMap.delete(prefix);
+    }
+  }
   /**
    * @param {string} name
    * @param {string} val
@@ -499,6 +533,10 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
         this._dom.nodeType !== 1) {
       throw new Error('You may only set an attribute on an element');
     }
+
+    // Track attribute prefix usage for namespace exclusion
+    this._trackAttributePrefix(name);
+
     (/** @type {Element} */ (this._dom)).setAttribute(
       this._replaceNamespaceAliasInNamespaceDeclaration(name),
       this._replaceCharacterMaps(val)

package/src/JSONJoiningTransformer.js

@@ -551,6 +551,25 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
       // No-op outside an element() callback (JSON joiner semantics)
       return this;
     }
+
+    let alias = this._getNamespaceAlias(prefix);
+
+    // Normalize empty string or undefined/null to #default
+    if (!alias) {
+      alias = '#default';
+    }
+    const normalizedPrefix = alias;
+
+    // If this prefix is excluded, buffer it instead of outputting immediately
+    if (this._excludeResultPrefixes.has(normalizedPrefix)) {
+      this._pendingNamespaceMap.set(normalizedPrefix, {
+        prefix: alias,
+        namespaceURI
+      });
+      return this;
+    }
+
+    // Not excluded, output immediately
     const top = /** @type {ElementInfo} */ (this._elementStack.at(-1));
     const {attsObj} = top;
 
@@ -558,7 +577,6 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
       attsObj.xmlns = {};
     }
 
-    const alias = this._getNamespaceAlias(prefix);
     /** @type {Record<string, string>} */
     (attsObj.xmlns)[alias === '#default' ? '' : alias] =
       this._replaceCharacterMaps(namespaceURI);
@@ -566,6 +584,32 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
     return this;
   }
 
+  /**
+   * @param {string} prefix
+   * @returns {void}
+   * @override
+   */
+  _flushPendingNamespace (prefix) {
+    if (!this._elementStack.length) {
+      return;
+    }
+
+    const pending = this._pendingNamespaceMap.get(prefix);
+    if (pending) {
+      const top = /** @type {ElementInfo} */ (this._elementStack.at(-1));
+      const {attsObj} = top;
+
+      if (!attsObj.xmlns) {
+        attsObj.xmlns = {};
+      }
+
+      /** @type {Record<string, string>} */
+      (attsObj.xmlns)[pending.prefix === '#default' ? '' : pending.prefix] =
+        this._replaceCharacterMaps(pending.namespaceURI);
+
+      this._pendingNamespaceMap.delete(prefix);
+    }
+  }
   /**
    * Adds/updates an attribute for the most recently open element built via
    * a callback-driven element(). When not in an element callback context,
@@ -599,11 +643,18 @@ class JSONJoiningTransformer extends AbstractJoiningTransformer {
     if (name === '$a' && Array.isArray(val)) {
       val.forEach((pair) => {
         if (Array.isArray(pair) && pair.length > 1) {
-          attsObj[String(pair[0])] = this._replaceCharacterMaps(pair[1]);
+          const attrName = String(pair[0]);
+          // Track each ordered attribute
+          this._trackAttributePrefix(attrName);
+          attsObj[attrName] = this._replaceCharacterMaps(pair[1]);
         }
       });
       return this;
     }
+
+    // Track attribute prefix usage for namespace exclusion
+    this._trackAttributePrefix(name);
+
     attsObj[this._replaceNamespaceAliasInNamespaceDeclaration(name)] =
       this._replaceCharacterMaps(/** @type {string} */ (val));
     return this;

package/src/JSONPathTransformer.js

@@ -30,6 +30,10 @@ class JSONPathTransformer {
           {path: template[0], template: template[1]}
         );
       }
+      // Normalize 'match' to 'path' for XSLT compatibility
+      if (template.match && !template.path) {
+        return {...template, path: template.match};
+      }
       return template;
     });
     this.templates.forEach((template, i, templates) => {

package/src/JSONPathTransformerContext.js

@@ -408,6 +408,48 @@ class JSONPathTransformerContext {
 
       let templateObj;
       if (!pathMatchedTemplates.length) {
+        // Check mode config for no-match behavior
+        const joiner = that._getJoiningTransformer();
+        const modeConfig = joiner._modeConfig;
+        if (modeConfig) {
+          const onNoMatch = modeConfig.onNoMatch ?? 'text-only-copy';
+          if (modeConfig.warningOnNoMatch) {
+            // eslint-disable-next-line no-console -- Warning as specified
+            console.warn(
+              'Warning: No template matches. ' +
+              'Mode is configured with warningOnNoMatch=true.'
+            );
+          }
+          if (onNoMatch === 'fail') {
+            throw new Error(
+              'No template matches. Mode is configured with onNoMatch="fail".'
+            );
+          }
+          if (onNoMatch === 'deep-skip') {
+            // Skip this node and its descendants entirely
+            continue;
+          }
+          if (onNoMatch === 'shallow-copy') {
+            // Output the value as-is without processing children
+            joiner.append(value);
+            continue;
+          }
+          if (onNoMatch === 'deep-copy') {
+            // Output the value and all descendants as-is
+            joiner.append(JSON.stringify(value));
+            continue;
+          }
+          if (onNoMatch === 'text-only-copy') {
+            // Output only text content (primitives)
+            if (typeof value === 'string' || typeof value === 'number' ||
+                typeof value === 'boolean') {
+              joiner.append(String(value));
+            }
+            continue;
+          }
+          // 'apply-templates', 'shallow-skip', or other:
+          // use default template rules
+        }
         const dtr = JSONPathTransformer.DefaultTemplateRules;
         if (propertyNamesMode) {
           templateObj = dtr.transformPropertyNames;
@@ -446,6 +488,49 @@ class JSONPathTransformerContext {
           return (aPriority > bPriority) ? -1 : 1;
         });
 
+        // Check for multiple matches with same priority when mode is configured
+        const joiner = that._getJoiningTransformer();
+        const modeConfig = joiner._modeConfig;
+        if (modeConfig && pathMatchedTemplates.length > 1) {
+          // Check if top two templates have equal priority
+          const topPriority =
+            typeof pathMatchedTemplates[0].priority === 'number'
+              ? pathMatchedTemplates[0].priority
+              : (that._config.specificityPriorityResolver &&
+                pathMatchedTemplates[0].path
+                ? that._config.specificityPriorityResolver(
+                  pathMatchedTemplates[0].path
+                )
+                /* c8 ignore next 2 -- defensive, templates without paths
+                   are already filtered at line 388 */
+                : 0);
+          const secondPriority =
+            typeof pathMatchedTemplates[1].priority === 'number'
+              ? pathMatchedTemplates[1].priority
+              : (that._config.specificityPriorityResolver &&
+                pathMatchedTemplates[1].path
+                ? that._config.specificityPriorityResolver(
+                  pathMatchedTemplates[1].path
+                )
+                /* c8 ignore next 2 -- defensive, templates without paths
+                   are already filtered at line 388 */
+                : 0);
+          if (topPriority === secondPriority) {
+            if (modeConfig.onMultipleMatch === 'fail') {
+              throw new Error(
+                'Multiple templates match with equal priority. ' +
+                'Mode is configured with onMultipleMatch="fail".'
+              );
+            } else if (modeConfig.warningOnMultipleMatch !== false) {
+              // eslint-disable-next-line no-console -- Warning as specified
+              console.warn(
+                'Warning: Multiple templates match with equal priority. ' +
+                'Mode is configured with warningOnMultipleMatch=true.'
+              );
+            }
+          }
+        }
+
         templateObj =
           /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
             pathMatchedTemplates.shift()
@@ -471,7 +556,18 @@ class JSONPathTransformerContext {
       that._params = prevTemplateParams;
       if (typeof ret !== 'undefined') {
         // After the undefined check, ret is ResultType<T>
-        that._getJoiningTransformer().append(
+        const joiner = that._getJoiningTransformer();
+        // Close any open tag before appending template return value
+        /* c8 ignore start -- _openTagState only on StringJoiningTransformer,
+           defensive check for string output mode */
+        // @ts-expect-error -- _openTagState only on StringJoiningTransformer
+        if (joiner._openTagState) {
+          joiner.append('>');
+          // @ts-expect-error -- _openTagState only on StringJoiningTransformer
+          joiner._openTagState = false;
+        }
+        /* c8 ignore stop */
+        joiner.append(
           /** @type {string|Node|*} */ (ret)
         );
       }
@@ -1757,6 +1853,22 @@ class JSONPathTransformerContext {
     return this;
   }
 
+  /**
+   * Configure mode behavior (similar to xsl:mode).
+   * @param {{
+   *   onMultipleMatch?: "use-last"|"fail",
+   *   warningOnMultipleMatch?: boolean,
+   *   onNoMatch?: "shallow-copy"|"deep-copy"|"fail"|"apply-templates"|
+   *     "shallow-skip"|"deep-skip"|"text-only-copy",
+   *   warningOnNoMatch?: boolean
+   * }} cfg - Mode configuration
+   * @returns {this}
+   */
+  mode (cfg) {
+    this._getJoiningTransformer().mode(cfg);
+    return this;
+  }
+
   /**
    * @param {string} name
    * @param {import('./AbstractJoiningTransformer.js').
@@ -1790,6 +1902,31 @@ class JSONPathTransformerContext {
     return this;
   }
 
+  /**
+   * Configure stylesheet behavior (similar to xsl:stylesheet).
+   * Unlike xsl:stylesheet, this is a directive method and does not contain
+   * nested content.
+   * @param {{
+   *   excludeResultPrefixes?: string[]
+   * }} cfg - Stylesheet configuration
+   * @returns {this}
+   */
+  stylesheet (cfg) {
+    this._getJoiningTransformer().stylesheet(cfg);
+    return this;
+  }
+
+  /**
+   * Alias for stylesheet() method (XSLT compatibility).
+   * @param {{
+   *   excludeResultPrefixes?: string[]
+   * }} cfg - Stylesheet configuration
+   * @returns {this}
+   */
+  transform (cfg) {
+    return this.stylesheet(cfg);
+  }
+
   /**
    * Create an element. Mirrors the joining transformer API so templates can
    * call `this.element()`.

package/src/StringJoiningTransformer.js

@@ -633,7 +633,24 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
    * @returns {StringJoiningTransformer}
    */
   namespace (prefix, namespaceURI) {
-    const alias = this._getNamespaceAlias(prefix);
+    let alias = this._getNamespaceAlias(prefix);
+
+    // Normalize empty string or undefined/null to #default
+    if (!alias) {
+      alias = '#default';
+    }
+    const normalizedPrefix = alias;
+
+    // If this prefix is excluded, buffer it instead of outputting immediately
+    if (this._excludeResultPrefixes.has(normalizedPrefix)) {
+      this._pendingNamespaceMap.set(normalizedPrefix, {
+        prefix: alias,
+        namespaceURI
+      });
+      return this;
+    }
+
+    // Not excluded, output immediately
     this.append(' ' + (
       alias === '#default' ? 'xmlns' : 'xmlns:' + alias
     ) + '="' +
@@ -641,6 +658,22 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     return this;
   }
 
+  /**
+   * @param {string} prefix
+   * @returns {void}
+   * @override
+   */
+  _flushPendingNamespace (prefix) {
+    const pending = this._pendingNamespaceMap.get(prefix);
+    if (pending) {
+      this.append(' ' + (
+        pending.prefix === '#default' ? 'xmlns' : 'xmlns:' + pending.prefix
+      ) + '="' +
+          this._replaceCharacterMaps(pending.namespaceURI) + '"');
+      this._pendingNamespaceMap.delete(prefix);
+    }
+  }
+
   /**
    * @param {string} name - Attribute name
    * @param {string|Record<string, unknown>|
@@ -703,6 +736,10 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     val = (this._cfg.preEscapedAttributes || avoidAttEscape)
       ? valStr
       : valStr.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+
+    // Track attribute prefix usage for namespace exclusion
+    this._trackAttributePrefix(name);
+
     this.append(
       ' ' + this._replaceNamespaceAliasInNamespaceDeclaration(name) + '="' +
       this._replaceCharacterMaps(val) + '"'

package/src/XPathTransformer.js

@@ -34,6 +34,10 @@ class XPathTransformer {
       if (Array.isArray(template)) {
         return {path: template[0], template: template[1]};
       }
+      // Normalize 'match' to 'path' for XSLT compatibility
+      if (template.match && !template.path) {
+        return {...template, path: template.match};
+      }
       return template;
     });
     this.templates.forEach((template) => {