xslt-processor 4.7.0 → 4.8.1

package/index.d.mts

@@ -278,6 +278,14 @@ declare class ExprContext {
      * Contains the key value of the current group being processed.
      */
     currentGroupingKey?: any;
+    /**
+     * User-defined XSLT functions from xsl:function declarations.
+     * Maps QName (namespace:localname) to function definition info.
+     */
+    userDefinedFunctions?: Map<string, {
+        functionDef: XNode;
+        executor: (context: ExprContext, functionDef: XNode, args: any[]) => any;
+    }>;
     /**
      * Constructor -- gets the node, its position, the node set it
      * belongs to, and a parent context as arguments. The parent context
@@ -790,6 +798,16 @@ declare class Xslt {
      * Keys are attribute set names, values are arrays of xsl:attribute nodes.
      */
     attributeSets: Map<string, XNode[]>;
+    /**
+     * Map of user-defined functions from xsl:function declarations.
+     * Keys are QNames (namespace:localname), values are the function definition nodes.
+     */
+    userDefinedFunctions: Map<string, XNode>;
+    /**
+     * Result documents created by xsl:result-document.
+     * Keys are the href URIs, values are the serialized output strings.
+     */
+    resultDocuments: Map<string, string>;
     /**
      * Stack of stylesheet metadata for tracking import hierarchy.
      * Used by apply-imports to find templates from imported stylesheets.
@@ -815,11 +833,21 @@ declare class Xslt {
      * Manages loaded packages and their components.
      */
     private packageRegistry;
+    /**
+     * Callback for loading external packages.
+     * Called when a package is not found in the registry.
+     */
+    private packageLoader?;
     /**
      * Current package being processed (for XSLT 3.0).
      * null if processing a non-package stylesheet.
      */
     private currentPackage;
+    /**
+     * Current override context (for XSLT 3.0 xsl:original).
+     * Tracks the original component when executing an override.
+     */
+    private currentOverrideContext;
     /**
      * Accumulator registry for XSLT 3.0 accumulators.
      * Stores accumulator definitions and current state during processing.
@@ -1082,6 +1110,15 @@ declare class Xslt {
      * @param output The output node.
      */
     protected xsltPackage(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Loads and registers an external package.
+     * Creates a temporary context and processes the package document.
+     *
+     * @param name The package name/URI.
+     * @param packageDoc The parsed package document.
+     * @param version Optional semantic version string.
+     */
+    protected loadAndRegisterPackage(name: string, packageDoc: XNode, version?: string): Promise<void>;
     /**
      * Implements `<xsl:use-package>` (XSLT 3.0 Section 3.7).
      * Imports another package and makes its public components available.
@@ -1097,6 +1134,14 @@ declare class Xslt {
      * @param template The xsl:expose element.
      */
     protected xsltExpose(context: ExprContext, template: XNode): void;
+    /**
+     * Find a component definition in the package root.
+     * @param packageRoot The package root element
+     * @param type The component type to find
+     * @param name The component name (null for all matching type)
+     * @returns Component information or null if not found
+     */
+    private findComponentInPackageRoot;
     /**
      * Implements `<xsl:accept>` (XSLT 3.0 Section 3.9).
      * Accepts and optionally overrides a component from a used package.
@@ -1104,6 +1149,55 @@ declare class Xslt {
      * @param template The xsl:accept element.
      */
     protected xsltAccept(context: ExprContext, template: XNode): void;
+    /**
+     * Implements <xsl:override> (XSLT 3.0 Section 3.7.2).
+     * Overrides components from a used package.
+     */
+    protected xsltOverride(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Find components in a package matching the given criteria.
+     * Used by xsl:accept to locate components from used packages.
+     *
+     * @param pkg The package to search in
+     * @param componentType The type of component to find
+     * @param namePatterns Array of name patterns ('*' for all, or specific names)
+     * @returns Array of matching components
+     */
+    private findComponentsInPackage;
+    /**
+     * Get the name to use when matching components.
+     * For named components (functions, variables, attribute-sets), returns the name.
+     * For templates, returns the name if present, otherwise returns null (match-based templates).
+     *
+     * @param component The component to get the name from
+     * @returns The component name for matching, or null if unnamed
+     */
+    private getComponentNameForMatching;
+    /**
+     * Implements <xsl:original> (XSLT 3.0 Section 3.7.2).
+     * Calls the original component from within an override.
+     */
+    protected xsltOriginal(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `<xsl:mode>` (XSLT 3.0 Section 3.5).
+     * Declares a mode with visibility and other properties.
+     * Only valid within an xsl:package.
+     */
+    protected xsltMode(context: ExprContext, template: XNode): void;
+    /**
+     * Get the effective component, checking for overrides first.
+     * If the component has been overridden in the current package, returns the override.
+     * Otherwise, returns the original component.
+     * @param component The original component
+     * @returns The effective component (override or original)
+     */
+    private getEffectiveComponent;
+    /**
+     * Collect templates from accepted components in used packages.
+     * @param mode The mode to match (null for default mode)
+     * @returns Array of template priority interfaces
+     */
+    private collectAcceptedTemplates;
     /**
      * Implements `<xsl:stream>` (XSLT 3.0 Section 16).
      * Enables streaming processing of large documents.
@@ -1343,6 +1437,100 @@ declare class Xslt {
      * Sets up the context with the current text and regex groups.
      */
     private processAnalyzeStringContent;
+    /**
+     * Implements `xsl:function` (XSLT 2.0).
+     *
+     * Declares a stylesheet function that can be called from XPath expressions.
+     * Functions are collected during stylesheet initialization and made available
+     * to the XPath evaluator.
+     *
+     * @param context The expression context.
+     * @param template The xsl:function element.
+     */
+    protected xsltFunction(context: ExprContext, template: XNode): void;
+    /**
+     * Coerce a NodeValue to a specific type based on the 'as' attribute.
+     *
+     * @param value The value to coerce.
+     * @param type The target type (e.g., "xs:integer", "xs:string", "xs:boolean").
+     * @returns The coerced value.
+     */
+    protected coerceToType(value: NodeValue, type: string): NodeValue;
+    /**
+     * Execute a user-defined xsl:function.
+     * Called when a function from userDefinedFunctions is invoked from XPath.
+     *
+     * @param context The expression context.
+     * @param functionDef The xsl:function node.
+     * @param args The evaluated arguments passed to the function.
+     * @returns The result of the function execution.
+     */
+    protected executeUserDefinedFunction(context: ExprContext, functionDef: XNode, args: any[]): Promise<any>;
+    /**
+     * Synchronously execute a user-defined xsl:function.
+     * This is used when functions are called from XPath expressions.
+     * Limited to functions that don't require async operations in their body.
+     *
+     * @param context The expression context.
+     * @param functionDef The xsl:function node.
+     * @param args The evaluated arguments passed to the function.
+     * @returns The result of the function execution.
+     */
+    executeUserDefinedFunctionSync(context: ExprContext, functionDef: XNode, args: any[]): any;
+    /**
+     * Implements `xsl:result-document` (XSLT 2.0).
+     *
+     * Creates a secondary output document. The output is stored in the
+     * resultDocuments map, accessible via getResultDocuments().
+     *
+     * @param context The expression context.
+     * @param template The xsl:result-document element.
+     */
+    protected xsltResultDocument(context: ExprContext, template: XNode): Promise<void>;
+    /**
+     * Get all result documents created by xsl:result-document.
+     * @returns A map of href URIs to serialized output strings.
+     */
+    getResultDocuments(): Map<string, string>;
+    /**
+     * Sets the package loader callback.
+     * The callback is called when a package is referenced via xsl:use-package
+     * but is not found in the registry.
+     *
+     * @param loader A function that loads package documents by URI and optional version.
+     *               Returns the parsed package document, or null if not found.
+     */
+    setPackageLoader(loader: (uri: string, version?: string) => Promise<XNode | null>): void;
+    /**
+     * Pre-registers a package for use in transformations.
+     * The package is parsed and stored in the internal registry.
+     *
+     * @param name The package name/URI.
+     * @param packageDoc The parsed package document.
+     * @param version Optional semantic version string.
+     */
+    registerPackage(name: string, packageDoc: XNode, version?: string): Promise<void>;
+    /**
+     * Implements `xsl:perform-sort` (XSLT 2.0).
+     *
+     * Sorts a sequence of items without iteration. The sorted sequence
+     * is available via xsl:sequence or other sequence-consuming instructions.
+     *
+     * @param context The expression context.
+     * @param template The xsl:perform-sort element.
+     * @param output The output node.
+     */
+    protected xsltPerformSort(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `xsl:namespace` (XSLT 2.0).
+     *
+     * Creates a namespace node in the result tree.
+     *
+     * @param context The expression context.
+     * @param template The xsl:namespace element.
+     * @param output The output node.
+     */
+    protected xsltNamespace(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Evaluates a variable or parameter and set it in the current input
      * context. Implements `xsl:variable`, `xsl:param`, and `xsl:with-param`.
@@ -1355,6 +1543,12 @@ declare class Xslt {
      * value. `xsl:variable` and `xsl:with-param` override; `xsl:param` doesn't.
      */
     protected xsltVariable(context: ExprContext, template: XNode, override: boolean): Promise<void>;
+    /**
+     * Register accepted variables from used packages into the context.
+     * Called after processing package use-package declarations.
+     * @param context The expression context.
+     */
+    private registerAcceptedVariables;
     /**
      * Traverses the template node tree. Calls the main processing
      * function with the current input context for every child node of the
@@ -1454,6 +1648,28 @@ declare class Xslt {
      * @param stylesheetElement The stylesheet or transform element.
      */
     private collectAttributeSets;
+    /**
+     * Collect all user-defined function definitions from the stylesheet.
+     * Called at stylesheet initialization time.
+     * @param stylesheetElement The stylesheet or transform element.
+     * @param context The expression context.
+     */
+    private collectUserDefinedFunctions;
+    /**
+     * Register user-defined functions in the expression context.
+     * This makes them available to XPath expressions.
+     * @param context The expression context.
+     */
+    private registerUserDefinedFunctionsInContext;
+    /**
+     * Check if there are any accepted functions in used packages.
+     */
+    private hasAcceptedFunctions;
+    /**
+     * Register accepted functions from used packages.
+     * @param functionsMap The map to register functions into.
+     */
+    private registerAcceptedFunctions;
     /**
      * Apply one or more attribute sets to an element.
      * Parses space-separated attribute set names and applies them.

package/index.d.ts

@@ -278,6 +278,14 @@ declare class ExprContext {
      * Contains the key value of the current group being processed.
      */
     currentGroupingKey?: any;
+    /**
+     * User-defined XSLT functions from xsl:function declarations.
+     * Maps QName (namespace:localname) to function definition info.
+     */
+    userDefinedFunctions?: Map<string, {
+        functionDef: XNode;
+        executor: (context: ExprContext, functionDef: XNode, args: any[]) => any;
+    }>;
     /**
      * Constructor -- gets the node, its position, the node set it
      * belongs to, and a parent context as arguments. The parent context
@@ -790,6 +798,16 @@ declare class Xslt {
      * Keys are attribute set names, values are arrays of xsl:attribute nodes.
      */
     attributeSets: Map<string, XNode[]>;
+    /**
+     * Map of user-defined functions from xsl:function declarations.
+     * Keys are QNames (namespace:localname), values are the function definition nodes.
+     */
+    userDefinedFunctions: Map<string, XNode>;
+    /**
+     * Result documents created by xsl:result-document.
+     * Keys are the href URIs, values are the serialized output strings.
+     */
+    resultDocuments: Map<string, string>;
     /**
      * Stack of stylesheet metadata for tracking import hierarchy.
      * Used by apply-imports to find templates from imported stylesheets.
@@ -815,11 +833,21 @@ declare class Xslt {
      * Manages loaded packages and their components.
      */
     private packageRegistry;
+    /**
+     * Callback for loading external packages.
+     * Called when a package is not found in the registry.
+     */
+    private packageLoader?;
     /**
      * Current package being processed (for XSLT 3.0).
      * null if processing a non-package stylesheet.
      */
     private currentPackage;
+    /**
+     * Current override context (for XSLT 3.0 xsl:original).
+     * Tracks the original component when executing an override.
+     */
+    private currentOverrideContext;
     /**
      * Accumulator registry for XSLT 3.0 accumulators.
      * Stores accumulator definitions and current state during processing.
@@ -1082,6 +1110,15 @@ declare class Xslt {
      * @param output The output node.
      */
     protected xsltPackage(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Loads and registers an external package.
+     * Creates a temporary context and processes the package document.
+     *
+     * @param name The package name/URI.
+     * @param packageDoc The parsed package document.
+     * @param version Optional semantic version string.
+     */
+    protected loadAndRegisterPackage(name: string, packageDoc: XNode, version?: string): Promise<void>;
     /**
      * Implements `<xsl:use-package>` (XSLT 3.0 Section 3.7).
      * Imports another package and makes its public components available.
@@ -1097,6 +1134,14 @@ declare class Xslt {
      * @param template The xsl:expose element.
      */
     protected xsltExpose(context: ExprContext, template: XNode): void;
+    /**
+     * Find a component definition in the package root.
+     * @param packageRoot The package root element
+     * @param type The component type to find
+     * @param name The component name (null for all matching type)
+     * @returns Component information or null if not found
+     */
+    private findComponentInPackageRoot;
     /**
      * Implements `<xsl:accept>` (XSLT 3.0 Section 3.9).
      * Accepts and optionally overrides a component from a used package.
@@ -1104,6 +1149,55 @@ declare class Xslt {
      * @param template The xsl:accept element.
      */
     protected xsltAccept(context: ExprContext, template: XNode): void;
+    /**
+     * Implements <xsl:override> (XSLT 3.0 Section 3.7.2).
+     * Overrides components from a used package.
+     */
+    protected xsltOverride(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Find components in a package matching the given criteria.
+     * Used by xsl:accept to locate components from used packages.
+     *
+     * @param pkg The package to search in
+     * @param componentType The type of component to find
+     * @param namePatterns Array of name patterns ('*' for all, or specific names)
+     * @returns Array of matching components
+     */
+    private findComponentsInPackage;
+    /**
+     * Get the name to use when matching components.
+     * For named components (functions, variables, attribute-sets), returns the name.
+     * For templates, returns the name if present, otherwise returns null (match-based templates).
+     *
+     * @param component The component to get the name from
+     * @returns The component name for matching, or null if unnamed
+     */
+    private getComponentNameForMatching;
+    /**
+     * Implements <xsl:original> (XSLT 3.0 Section 3.7.2).
+     * Calls the original component from within an override.
+     */
+    protected xsltOriginal(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `<xsl:mode>` (XSLT 3.0 Section 3.5).
+     * Declares a mode with visibility and other properties.
+     * Only valid within an xsl:package.
+     */
+    protected xsltMode(context: ExprContext, template: XNode): void;
+    /**
+     * Get the effective component, checking for overrides first.
+     * If the component has been overridden in the current package, returns the override.
+     * Otherwise, returns the original component.
+     * @param component The original component
+     * @returns The effective component (override or original)
+     */
+    private getEffectiveComponent;
+    /**
+     * Collect templates from accepted components in used packages.
+     * @param mode The mode to match (null for default mode)
+     * @returns Array of template priority interfaces
+     */
+    private collectAcceptedTemplates;
     /**
      * Implements `<xsl:stream>` (XSLT 3.0 Section 16).
      * Enables streaming processing of large documents.
@@ -1343,6 +1437,100 @@ declare class Xslt {
      * Sets up the context with the current text and regex groups.
      */
     private processAnalyzeStringContent;
+    /**
+     * Implements `xsl:function` (XSLT 2.0).
+     *
+     * Declares a stylesheet function that can be called from XPath expressions.
+     * Functions are collected during stylesheet initialization and made available
+     * to the XPath evaluator.
+     *
+     * @param context The expression context.
+     * @param template The xsl:function element.
+     */
+    protected xsltFunction(context: ExprContext, template: XNode): void;
+    /**
+     * Coerce a NodeValue to a specific type based on the 'as' attribute.
+     *
+     * @param value The value to coerce.
+     * @param type The target type (e.g., "xs:integer", "xs:string", "xs:boolean").
+     * @returns The coerced value.
+     */
+    protected coerceToType(value: NodeValue, type: string): NodeValue;
+    /**
+     * Execute a user-defined xsl:function.
+     * Called when a function from userDefinedFunctions is invoked from XPath.
+     *
+     * @param context The expression context.
+     * @param functionDef The xsl:function node.
+     * @param args The evaluated arguments passed to the function.
+     * @returns The result of the function execution.
+     */
+    protected executeUserDefinedFunction(context: ExprContext, functionDef: XNode, args: any[]): Promise<any>;
+    /**
+     * Synchronously execute a user-defined xsl:function.
+     * This is used when functions are called from XPath expressions.
+     * Limited to functions that don't require async operations in their body.
+     *
+     * @param context The expression context.
+     * @param functionDef The xsl:function node.
+     * @param args The evaluated arguments passed to the function.
+     * @returns The result of the function execution.
+     */
+    executeUserDefinedFunctionSync(context: ExprContext, functionDef: XNode, args: any[]): any;
+    /**
+     * Implements `xsl:result-document` (XSLT 2.0).
+     *
+     * Creates a secondary output document. The output is stored in the
+     * resultDocuments map, accessible via getResultDocuments().
+     *
+     * @param context The expression context.
+     * @param template The xsl:result-document element.
+     */
+    protected xsltResultDocument(context: ExprContext, template: XNode): Promise<void>;
+    /**
+     * Get all result documents created by xsl:result-document.
+     * @returns A map of href URIs to serialized output strings.
+     */
+    getResultDocuments(): Map<string, string>;
+    /**
+     * Sets the package loader callback.
+     * The callback is called when a package is referenced via xsl:use-package
+     * but is not found in the registry.
+     *
+     * @param loader A function that loads package documents by URI and optional version.
+     *               Returns the parsed package document, or null if not found.
+     */
+    setPackageLoader(loader: (uri: string, version?: string) => Promise<XNode | null>): void;
+    /**
+     * Pre-registers a package for use in transformations.
+     * The package is parsed and stored in the internal registry.
+     *
+     * @param name The package name/URI.
+     * @param packageDoc The parsed package document.
+     * @param version Optional semantic version string.
+     */
+    registerPackage(name: string, packageDoc: XNode, version?: string): Promise<void>;
+    /**
+     * Implements `xsl:perform-sort` (XSLT 2.0).
+     *
+     * Sorts a sequence of items without iteration. The sorted sequence
+     * is available via xsl:sequence or other sequence-consuming instructions.
+     *
+     * @param context The expression context.
+     * @param template The xsl:perform-sort element.
+     * @param output The output node.
+     */
+    protected xsltPerformSort(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Implements `xsl:namespace` (XSLT 2.0).
+     *
+     * Creates a namespace node in the result tree.
+     *
+     * @param context The expression context.
+     * @param template The xsl:namespace element.
+     * @param output The output node.
+     */
+    protected xsltNamespace(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Evaluates a variable or parameter and set it in the current input
      * context. Implements `xsl:variable`, `xsl:param`, and `xsl:with-param`.
@@ -1355,6 +1543,12 @@ declare class Xslt {
      * value. `xsl:variable` and `xsl:with-param` override; `xsl:param` doesn't.
      */
     protected xsltVariable(context: ExprContext, template: XNode, override: boolean): Promise<void>;
+    /**
+     * Register accepted variables from used packages into the context.
+     * Called after processing package use-package declarations.
+     * @param context The expression context.
+     */
+    private registerAcceptedVariables;
     /**
      * Traverses the template node tree. Calls the main processing
      * function with the current input context for every child node of the
@@ -1454,6 +1648,28 @@ declare class Xslt {
      * @param stylesheetElement The stylesheet or transform element.
      */
     private collectAttributeSets;
+    /**
+     * Collect all user-defined function definitions from the stylesheet.
+     * Called at stylesheet initialization time.
+     * @param stylesheetElement The stylesheet or transform element.
+     * @param context The expression context.
+     */
+    private collectUserDefinedFunctions;
+    /**
+     * Register user-defined functions in the expression context.
+     * This makes them available to XPath expressions.
+     * @param context The expression context.
+     */
+    private registerUserDefinedFunctionsInContext;
+    /**
+     * Check if there are any accepted functions in used packages.
+     */
+    private hasAcceptedFunctions;
+    /**
+     * Register accepted functions from used packages.
+     * @param functionsMap The map to register functions into.
+     */
+    private registerAcceptedFunctions;
     /**
      * Apply one or more attribute sets to an element.
      * Parses space-separated attribute set names and applies them.