xslt-processor 4.4.1 → 4.6.0

package/index.d.mts

@@ -73,6 +73,7 @@ declare class XDocument extends XNode {
     createComment(data: any): XNode;
     createCDATASection(data: any): XNode;
     createDTDSection(data: any): XNode;
+    createProcessingInstruction(target: string, data: any): XNode;
 }
 
 /**
@@ -169,6 +170,21 @@ type XPathFunctions = Record<string, XPathFunction>;
  * Type for namespace bindings (prefix -> namespace URI).
  */
 type XPathNamespaces = Record<string, string>;
+/**
+ * Type for available documents mapping (URI -> root node).
+ * Used by fn:doc() and related functions (XPath 2.0+).
+ */
+type XPathDocuments = Record<string, XPathNode | null>;
+/**
+ * Type for available collections mapping (URI -> sequence of nodes).
+ * Used by fn:collection() function (XPath 2.0+).
+ */
+type XPathCollections = Record<string, XPathNode[]>;
+/**
+ * Type for function implementations registry.
+ * Maps function names (with optional namespace) to their implementations.
+ */
+type XPathFunctionRegistry = Record<string, XPathFunction>;
 /**
  * The evaluation context for XPath expressions.
  *
@@ -177,6 +193,7 @@ type XPathNamespaces = Record<string, string>;
  * - Position information for predicates
  * - Variable bindings
  * - Custom function definitions
+ * - Dynamic properties like current dateTime, available documents, etc.
  */
 interface XPathContext {
     /**
@@ -219,11 +236,85 @@ interface XPathContext {
      * Used by functions like json-to-xml() which are only available in XSLT 3.0+
      */
     xsltVersion?: string;
+    /**
+     * XPath specification version being used.
+     * Default: '1.0'
+     *
+     * This affects:
+     * - Function library available
+     * - Type system behavior
+     * - Sequence vs node-set handling
+     */
+    xpathVersion?: '1.0' | '2.0' | '3.0' | '3.1';
+    /**
+     * Enable XPath 1.0 backward compatibility mode (Phase 8.1).
+     * When true, XPath 2.0+ expressions follow XPath 1.0 type conversion rules.
+     * This enables:
+     * - XPath 1.0 boolean conversion semantics
+     * - XPath 1.0 numeric conversion (with NaN for empty sequences)
+     * - XPath 1.0 comparison rules (node-set to string conversion)
+     * - XPath 1.0 logical operator behavior (short-circuit, error suppression)
+     * Default: false (XPath 2.0 semantics)
+     */
+    xpath10CompatibilityMode?: boolean;
+    /**
+     * Default collation for string comparisons (XPath 2.0+).
+     * Default: Unicode codepoint collation
+     */
+    defaultCollation?: string;
+    /**
+     * Base URI for resolving relative URIs (XPath 2.0+).
+     */
+    baseUri?: string;
+    /**
+     * Implicit timezone as duration offset from UTC (XPath 2.0+).
+     * Example: '-PT5H' for US Eastern Time (UTC-5)
+     */
+    implicitTimezone?: string;
+    /**
+     * Extension data for XSLT or custom implementations.
+     * This allows attaching arbitrary data to the context without
+     * polluting the main interface.
+     */
+    extensions?: Record<string, any>;
+    /**
+     * Current dateTime in the dynamic context (XPath 2.0+).
+     * Returned by fn:current-dateTime().
+     * If not provided, defaults to system time when accessed.
+     */
+    currentDateTime?: Date;
+    /**
+     * Available documents mapping for fn:doc() function (XPath 2.0+).
+     * Maps document URIs to their root document nodes.
+     * Example: { "http://example.com/data.xml": rootNode }
+     */
+    availableDocuments?: XPathDocuments;
+    /**
+     * Available collections mapping for fn:collection() function (XPath 2.0+).
+     * Maps collection URIs to sequences of nodes.
+     * Example: { "http://example.com/collection": [node1, node2, ...] }
+     */
+    availableCollections?: XPathCollections;
+    /**
+     * Default collection URI when fn:collection() is called without arguments (XPath 2.0+).
+     * If provided, fn:collection() returns availableCollections[defaultCollection].
+     */
+    defaultCollection?: string;
+    /**
+     * Function implementations registry (XPath 2.0+).
+     * Maps QName function names to their implementations.
+     * Allows defining custom/XSLT functions at evaluation time.
+     * Format: "localName" or "prefix:localName"
+     */
+    functionRegistry?: XPathFunctionRegistry;
 }
 /**
  * Result types that can be returned from XPath evaluation.
+ *
+ * XPath 1.0: node-set, string, number, boolean
+ * XPath 2.0+: sequences (which subsume node-sets), atomic values, functions
  */
-type XPathResult = XPathNode[] | string | number | boolean;
+type XPathResult = XPathNode[] | string | number | boolean | any[] | Map<any, any> | null | Function;
 
 declare abstract class XPathExpression {
     abstract evaluate(context: XPathContext): XPathResult;
@@ -314,6 +405,25 @@ declare class ExprContext {
     knownNamespaces: {
         [alias: string]: string;
     };
+    /**
+     * Custom system properties for system-property() function.
+     * Overrides the default properties (xsl:version, xsl:vendor, xsl:vendor-url).
+     */
+    systemProperties?: {
+        [name: string]: string;
+    };
+    /**
+     * Document loader function for the document() function.
+     * Takes a URI and returns an XNode document, or null if loading fails.
+     */
+    documentLoader?: (uri: string) => XNode | null;
+    /**
+     * Unparsed entity URIs for the unparsed-entity-uri() function.
+     * Maps entity names to their URIs (from DTD declarations).
+     */
+    unparsedEntities?: {
+        [name: string]: string;
+    };
     caseInsensitive: any;
     ignoreAttributesWithoutValue: any;
     returnOnFirstMatch: any;
@@ -416,6 +526,8 @@ declare class NodeConverter {
     private convertVariables;
     /**
      * Create custom functions for XPath context (like key(), document(), etc.).
+     * Note: Custom functions receive the XPathContext as their first argument,
+     * followed by the evaluated function arguments.
      */
     private createCustomFunctions;
     /**
@@ -598,6 +710,37 @@ declare class Xslt {
      * Maps stylesheet namespace prefixes to result namespace prefixes.
      */
     namespaceAliases: Map<string, string>;
+    /**
+     * Set of supported extension element namespaces.
+     * Processors can register custom extension namespaces here.
+     * Currently only XSLT namespace is auto-registered.
+     */
+    supportedExtensions: Set<string>;
+    /**
+     * Map of attribute sets defined in the stylesheet.
+     * Keys are attribute set names, values are arrays of xsl:attribute nodes.
+     */
+    attributeSets: Map<string, XNode[]>;
+    /**
+     * Stack of stylesheet metadata for tracking import hierarchy.
+     * Used by apply-imports to find templates from imported stylesheets.
+     */
+    private styleSheetStack;
+    /**
+     * Map of imported stylesheet HREFs to their parsed XNodes.
+     * Prevents duplicate imports and allows precedence tracking.
+     */
+    private importedStylesheets;
+    /**
+     * Map templates to the stylesheet they came from.
+     * Enables apply-imports to find templates by import precedence.
+     */
+    private templateSourceMap;
+    /**
+     * Stack of currently executing templates with their metadata.
+     * Used by apply-imports to determine which template called it.
+     */
+    private currentTemplateStack;
     constructor(options?: Partial<XsltOptions>);
     /**
      * The exported entry point of the XSL-T processor.
@@ -621,6 +764,16 @@ declare class Xslt {
      * @protected
      */
     protected xsltApplyTemplates(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `xsl:apply-imports`.
+     * Applies templates from imported stylesheets with the same match pattern and mode.
+     * This enables template overriding where a template in an importing stylesheet
+     * can call the overridden template from the imported stylesheet.
+     * @param context The Expression Context.
+     * @param template The apply-imports template node.
+     * @param output The output node.
+     */
+    protected xsltApplyImports(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Implements `xsl:attribute`.
      * @param context The Expression Context.
@@ -658,6 +811,13 @@ declare class Xslt {
      * @param output The output. Only used if there's no corresponding output node already defined.
      */
     protected xsltComment(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `xsl:processing-instruction`.
+     * @param context The Expression Context.
+     * @param template The template.
+     * @param output The output. Only used if there's no corresponding output node already defined.
+     */
+    protected xsltProcessingInstruction(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Implements `xsl:copy-of` for node-set values of the select
      * expression. Recurses down the source node tree, which is part of
@@ -957,6 +1117,58 @@ declare class Xslt {
      * @param template The template node.
      */
     protected xsltWithParam(context: ExprContext, template: XNode): Promise<void>;
+    /**
+     * Recursively map all template nodes in a stylesheet to their metadata.
+     * Used to track which stylesheet each template comes from for apply-imports.
+     * @param stylesheetElement The stylesheet or transform element (or any parent element).
+     * @param metadata The metadata for this stylesheet.
+     */
+    private mapTemplatesFromStylesheet;
+    /**
+     * Collect all attribute set definitions from the stylesheet.
+     * Called at stylesheet initialization time.
+     * @param stylesheetElement The stylesheet or transform element.
+     */
+    private collectAttributeSets;
+    /**
+     * Apply one or more attribute sets to an element.
+     * Parses space-separated attribute set names and applies them.
+     * @param context The Expression Context.
+     * @param element The element to apply attributes to.
+     * @param setNames Space-separated attribute set names.
+     */
+    protected applyAttributeSets(context: ExprContext, element: XNode, setNames: string): Promise<void>;
+    /**
+     * Apply a single attribute set to an element.
+     * Handles recursive attribute sets with cycle detection.
+     * @param context The Expression Context.
+     * @param element The element to apply attributes to.
+     * @param setName The name of the attribute set to apply.
+     * @param processedSets Set of already-processed attribute set names (for cycle detection).
+     */
+    private applyAttributeSet;
+    /**
+     * Test if an element is a supported extension.
+     * Returns false for unrecognized elements in non-XSLT namespaces.
+     * @param node The element to test.
+     * @returns True if the element is supported, false if it's an unrecognized extension.
+     */
+    protected isExtensionElementSupported(node: XNode): boolean;
+    /**
+     * Get the fallback element from an extension element if it exists.
+     * Searches for the first direct xsl:fallback child.
+     * @param node The extension element.
+     * @returns The fallback element, or null if not found.
+     */
+    protected getFallbackElement(node: XNode): XNode | null;
+    /**
+     * Process an extension element with fallback support.
+     * If a fallback is defined, executes it; otherwise treats element as literal.
+     * @param context The Expression Context.
+     * @param element The extension element.
+     * @param output The output node.
+     */
+    protected xsltExtensionElement(context: ExprContext, element: XNode, output?: XNode): Promise<void>;
     /**
      * Test if the given element is an XSLT element, optionally the one with the given name.
      * @param {XNode} element The element.

package/index.d.ts

@@ -73,6 +73,7 @@ declare class XDocument extends XNode {
     createComment(data: any): XNode;
     createCDATASection(data: any): XNode;
     createDTDSection(data: any): XNode;
+    createProcessingInstruction(target: string, data: any): XNode;
 }
 
 /**
@@ -169,6 +170,21 @@ type XPathFunctions = Record<string, XPathFunction>;
  * Type for namespace bindings (prefix -> namespace URI).
  */
 type XPathNamespaces = Record<string, string>;
+/**
+ * Type for available documents mapping (URI -> root node).
+ * Used by fn:doc() and related functions (XPath 2.0+).
+ */
+type XPathDocuments = Record<string, XPathNode | null>;
+/**
+ * Type for available collections mapping (URI -> sequence of nodes).
+ * Used by fn:collection() function (XPath 2.0+).
+ */
+type XPathCollections = Record<string, XPathNode[]>;
+/**
+ * Type for function implementations registry.
+ * Maps function names (with optional namespace) to their implementations.
+ */
+type XPathFunctionRegistry = Record<string, XPathFunction>;
 /**
  * The evaluation context for XPath expressions.
  *
@@ -177,6 +193,7 @@ type XPathNamespaces = Record<string, string>;
  * - Position information for predicates
  * - Variable bindings
  * - Custom function definitions
+ * - Dynamic properties like current dateTime, available documents, etc.
  */
 interface XPathContext {
     /**
@@ -219,11 +236,85 @@ interface XPathContext {
      * Used by functions like json-to-xml() which are only available in XSLT 3.0+
      */
     xsltVersion?: string;
+    /**
+     * XPath specification version being used.
+     * Default: '1.0'
+     *
+     * This affects:
+     * - Function library available
+     * - Type system behavior
+     * - Sequence vs node-set handling
+     */
+    xpathVersion?: '1.0' | '2.0' | '3.0' | '3.1';
+    /**
+     * Enable XPath 1.0 backward compatibility mode (Phase 8.1).
+     * When true, XPath 2.0+ expressions follow XPath 1.0 type conversion rules.
+     * This enables:
+     * - XPath 1.0 boolean conversion semantics
+     * - XPath 1.0 numeric conversion (with NaN for empty sequences)
+     * - XPath 1.0 comparison rules (node-set to string conversion)
+     * - XPath 1.0 logical operator behavior (short-circuit, error suppression)
+     * Default: false (XPath 2.0 semantics)
+     */
+    xpath10CompatibilityMode?: boolean;
+    /**
+     * Default collation for string comparisons (XPath 2.0+).
+     * Default: Unicode codepoint collation
+     */
+    defaultCollation?: string;
+    /**
+     * Base URI for resolving relative URIs (XPath 2.0+).
+     */
+    baseUri?: string;
+    /**
+     * Implicit timezone as duration offset from UTC (XPath 2.0+).
+     * Example: '-PT5H' for US Eastern Time (UTC-5)
+     */
+    implicitTimezone?: string;
+    /**
+     * Extension data for XSLT or custom implementations.
+     * This allows attaching arbitrary data to the context without
+     * polluting the main interface.
+     */
+    extensions?: Record<string, any>;
+    /**
+     * Current dateTime in the dynamic context (XPath 2.0+).
+     * Returned by fn:current-dateTime().
+     * If not provided, defaults to system time when accessed.
+     */
+    currentDateTime?: Date;
+    /**
+     * Available documents mapping for fn:doc() function (XPath 2.0+).
+     * Maps document URIs to their root document nodes.
+     * Example: { "http://example.com/data.xml": rootNode }
+     */
+    availableDocuments?: XPathDocuments;
+    /**
+     * Available collections mapping for fn:collection() function (XPath 2.0+).
+     * Maps collection URIs to sequences of nodes.
+     * Example: { "http://example.com/collection": [node1, node2, ...] }
+     */
+    availableCollections?: XPathCollections;
+    /**
+     * Default collection URI when fn:collection() is called without arguments (XPath 2.0+).
+     * If provided, fn:collection() returns availableCollections[defaultCollection].
+     */
+    defaultCollection?: string;
+    /**
+     * Function implementations registry (XPath 2.0+).
+     * Maps QName function names to their implementations.
+     * Allows defining custom/XSLT functions at evaluation time.
+     * Format: "localName" or "prefix:localName"
+     */
+    functionRegistry?: XPathFunctionRegistry;
 }
 /**
  * Result types that can be returned from XPath evaluation.
+ *
+ * XPath 1.0: node-set, string, number, boolean
+ * XPath 2.0+: sequences (which subsume node-sets), atomic values, functions
  */
-type XPathResult = XPathNode[] | string | number | boolean;
+type XPathResult = XPathNode[] | string | number | boolean | any[] | Map<any, any> | null | Function;
 
 declare abstract class XPathExpression {
     abstract evaluate(context: XPathContext): XPathResult;
@@ -314,6 +405,25 @@ declare class ExprContext {
     knownNamespaces: {
         [alias: string]: string;
     };
+    /**
+     * Custom system properties for system-property() function.
+     * Overrides the default properties (xsl:version, xsl:vendor, xsl:vendor-url).
+     */
+    systemProperties?: {
+        [name: string]: string;
+    };
+    /**
+     * Document loader function for the document() function.
+     * Takes a URI and returns an XNode document, or null if loading fails.
+     */
+    documentLoader?: (uri: string) => XNode | null;
+    /**
+     * Unparsed entity URIs for the unparsed-entity-uri() function.
+     * Maps entity names to their URIs (from DTD declarations).
+     */
+    unparsedEntities?: {
+        [name: string]: string;
+    };
     caseInsensitive: any;
     ignoreAttributesWithoutValue: any;
     returnOnFirstMatch: any;
@@ -416,6 +526,8 @@ declare class NodeConverter {
     private convertVariables;
     /**
      * Create custom functions for XPath context (like key(), document(), etc.).
+     * Note: Custom functions receive the XPathContext as their first argument,
+     * followed by the evaluated function arguments.
      */
     private createCustomFunctions;
     /**
@@ -598,6 +710,37 @@ declare class Xslt {
      * Maps stylesheet namespace prefixes to result namespace prefixes.
      */
     namespaceAliases: Map<string, string>;
+    /**
+     * Set of supported extension element namespaces.
+     * Processors can register custom extension namespaces here.
+     * Currently only XSLT namespace is auto-registered.
+     */
+    supportedExtensions: Set<string>;
+    /**
+     * Map of attribute sets defined in the stylesheet.
+     * Keys are attribute set names, values are arrays of xsl:attribute nodes.
+     */
+    attributeSets: Map<string, XNode[]>;
+    /**
+     * Stack of stylesheet metadata for tracking import hierarchy.
+     * Used by apply-imports to find templates from imported stylesheets.
+     */
+    private styleSheetStack;
+    /**
+     * Map of imported stylesheet HREFs to their parsed XNodes.
+     * Prevents duplicate imports and allows precedence tracking.
+     */
+    private importedStylesheets;
+    /**
+     * Map templates to the stylesheet they came from.
+     * Enables apply-imports to find templates by import precedence.
+     */
+    private templateSourceMap;
+    /**
+     * Stack of currently executing templates with their metadata.
+     * Used by apply-imports to determine which template called it.
+     */
+    private currentTemplateStack;
     constructor(options?: Partial<XsltOptions>);
     /**
      * The exported entry point of the XSL-T processor.
@@ -621,6 +764,16 @@ declare class Xslt {
      * @protected
      */
     protected xsltApplyTemplates(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `xsl:apply-imports`.
+     * Applies templates from imported stylesheets with the same match pattern and mode.
+     * This enables template overriding where a template in an importing stylesheet
+     * can call the overridden template from the imported stylesheet.
+     * @param context The Expression Context.
+     * @param template The apply-imports template node.
+     * @param output The output node.
+     */
+    protected xsltApplyImports(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Implements `xsl:attribute`.
      * @param context The Expression Context.
@@ -658,6 +811,13 @@ declare class Xslt {
      * @param output The output. Only used if there's no corresponding output node already defined.
      */
     protected xsltComment(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `xsl:processing-instruction`.
+     * @param context The Expression Context.
+     * @param template The template.
+     * @param output The output. Only used if there's no corresponding output node already defined.
+     */
+    protected xsltProcessingInstruction(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Implements `xsl:copy-of` for node-set values of the select
      * expression. Recurses down the source node tree, which is part of
@@ -957,6 +1117,58 @@ declare class Xslt {
      * @param template The template node.
      */
     protected xsltWithParam(context: ExprContext, template: XNode): Promise<void>;
+    /**
+     * Recursively map all template nodes in a stylesheet to their metadata.
+     * Used to track which stylesheet each template comes from for apply-imports.
+     * @param stylesheetElement The stylesheet or transform element (or any parent element).
+     * @param metadata The metadata for this stylesheet.
+     */
+    private mapTemplatesFromStylesheet;
+    /**
+     * Collect all attribute set definitions from the stylesheet.
+     * Called at stylesheet initialization time.
+     * @param stylesheetElement The stylesheet or transform element.
+     */
+    private collectAttributeSets;
+    /**
+     * Apply one or more attribute sets to an element.
+     * Parses space-separated attribute set names and applies them.
+     * @param context The Expression Context.
+     * @param element The element to apply attributes to.
+     * @param setNames Space-separated attribute set names.
+     */
+    protected applyAttributeSets(context: ExprContext, element: XNode, setNames: string): Promise<void>;
+    /**
+     * Apply a single attribute set to an element.
+     * Handles recursive attribute sets with cycle detection.
+     * @param context The Expression Context.
+     * @param element The element to apply attributes to.
+     * @param setName The name of the attribute set to apply.
+     * @param processedSets Set of already-processed attribute set names (for cycle detection).
+     */
+    private applyAttributeSet;
+    /**
+     * Test if an element is a supported extension.
+     * Returns false for unrecognized elements in non-XSLT namespaces.
+     * @param node The element to test.
+     * @returns True if the element is supported, false if it's an unrecognized extension.
+     */
+    protected isExtensionElementSupported(node: XNode): boolean;
+    /**
+     * Get the fallback element from an extension element if it exists.
+     * Searches for the first direct xsl:fallback child.
+     * @param node The extension element.
+     * @returns The fallback element, or null if not found.
+     */
+    protected getFallbackElement(node: XNode): XNode | null;
+    /**
+     * Process an extension element with fallback support.
+     * If a fallback is defined, executes it; otherwise treats element as literal.
+     * @param context The Expression Context.
+     * @param element The extension element.
+     * @param output The output node.
+     */
+    protected xsltExtensionElement(context: ExprContext, element: XNode, output?: XNode): Promise<void>;
     /**
      * Test if the given element is an XSLT element, optionally the one with the given name.
      * @param {XNode} element The element.