xslt-processor 4.5.0 → 4.6.1

package/index.d.mts

@@ -170,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.
  *
@@ -178,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 {
     /**
@@ -220,11 +236,96 @@ 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;
+}
+/**
+ * Represents an XPath 3.0 function item.
+ * This is a simplified interface to avoid circular dependencies.
+ */
+interface XPathFunctionItem {
+    __isFunctionItem: true;
+    implementation: (...args: any[]) => any;
+    arity: number;
+    name?: string;
+    namespace?: string;
 }
 /**
  * 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 | XPathFunctionItem;
 
 declare abstract class XPathExpression {
     abstract evaluate(context: XPathContext): XPathResult;
@@ -315,6 +416,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;
@@ -417,6 +537,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;
     /**
@@ -583,6 +705,15 @@ declare class Xslt {
     outputOmitXmlDeclaration: string;
     version: string;
     firstTemplateRan: boolean;
+    /**
+     * Forwards-compatible processing mode (XSLT 1.0 Section 2.5).
+     * When true, the processor is running a stylesheet with version > 1.0.
+     * In this mode:
+     * - Unknown top-level elements are silently ignored
+     * - Unknown XSLT instructions use xsl:fallback if available, otherwise are ignored
+     * - Unknown attributes on XSLT elements are ignored
+     */
+    forwardsCompatible: boolean;
     /**
      * List of element name patterns from xsl:strip-space declarations.
      * Whitespace-only text nodes inside matching elements will be stripped.
@@ -645,6 +776,21 @@ declare class Xslt {
      * @param output If set, the output where the transformation should occur.
      */
     protected xsltProcessContext(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Handle unknown XSLT instructions per XSLT 1.0 Section 2.5 (Forwards-Compatible Processing).
+     *
+     * In forwards-compatible mode (version > 1.0):
+     * - If the instruction has an xsl:fallback child, execute the fallback
+     * - Otherwise, the instruction is silently ignored
+     *
+     * In strict mode (version = 1.0):
+     * - Unknown instructions are an error
+     *
+     * @param context The Expression Context
+     * @param template The unknown XSLT instruction element
+     * @param output The output node
+     */
+    protected xsltUnknownInstruction(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Implements `xsl:apply-templates`.
      * @param context The Expression Context.
@@ -798,29 +944,57 @@ declare class Xslt {
      * @param context The Expression Context.
      * @param level The counting level: 'single', 'multiple', or 'any'.
      * @param count Pattern to match nodes to count.
-     * @param from Pattern to start counting from.
-     * @returns The count value.
+     * @param from Pattern to define counting boundary.
+     * @returns Array of count values (single element for 'single'/'any', multiple for 'multiple').
      */
-    protected xsltNumberCount(context: ExprContext, level: string, count: string | null, from: string | null): number;
+    protected xsltNumberCount(context: ExprContext, level: string, count: string | null, from: string | null): number[];
     /**
-     * Checks if a node matches a simple name pattern.
+     * Checks if a node matches a pattern (supports simple names and union patterns).
      * @param node The node to check.
-     * @param pattern The pattern (node name) to match.
+     * @param pattern The pattern (node name, wildcard, or union like "a|b|c").
      * @returns True if the node matches.
      */
     protected nodeMatchesPattern(node: XNode, pattern: string): boolean;
+    /**
+     * Checks if a node matches a single (non-union) pattern.
+     * @param node The node to check.
+     * @param pattern The pattern (node name or wildcard).
+     * @returns True if the node matches.
+     */
+    protected nodeMatchesSinglePattern(node: XNode, pattern: string): boolean;
     /**
      * Gets all nodes preceding the given node in document order.
      * @param node The reference node.
+     * @param fromPattern Optional pattern to define counting boundary.
      * @returns Array of preceding nodes.
      */
-    protected getAllPrecedingNodes(node: XNode): XNode[];
+    protected getAllPrecedingNodes(node: XNode, fromPattern?: string | null): XNode[];
     /**
      * Collects all descendant nodes of a given node.
      * @param node The parent node.
      * @param result The array to collect into.
      */
     protected collectDescendants(node: XNode, result: XNode[]): void;
+    /**
+     * Formats an array of numbers according to the format string.
+     * For level="multiple", numbers like [1, 2, 3] with format "1.1.1" produce "1.2.3".
+     * @param numbers The numbers to format.
+     * @param format The format string (e.g., "1", "1.1", "1.a.i").
+     * @param groupingSeparator Optional grouping separator.
+     * @param groupingSize Optional grouping size.
+     * @returns The formatted number string.
+     */
+    protected xsltFormatNumbers(numbers: number[], format: string, groupingSeparator: string | null, groupingSize: string | null): string;
+    /**
+     * Parses a format string into tokens and separators.
+     * E.g., "1.a.i" -> tokens: ["1", "a", "i"], separators: [".", "."]
+     * @param format The format string.
+     * @returns Object with tokens and separators arrays.
+     */
+    protected parseFormatString(format: string): {
+        tokens: string[];
+        separators: string[];
+    };
     /**
      * Formats a number according to the format string.
      * @param number The number to format.

package/index.d.ts

@@ -170,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.
  *
@@ -178,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 {
     /**
@@ -220,11 +236,96 @@ 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;
+}
+/**
+ * Represents an XPath 3.0 function item.
+ * This is a simplified interface to avoid circular dependencies.
+ */
+interface XPathFunctionItem {
+    __isFunctionItem: true;
+    implementation: (...args: any[]) => any;
+    arity: number;
+    name?: string;
+    namespace?: string;
 }
 /**
  * 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 | XPathFunctionItem;
 
 declare abstract class XPathExpression {
     abstract evaluate(context: XPathContext): XPathResult;
@@ -315,6 +416,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;
@@ -417,6 +537,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;
     /**
@@ -583,6 +705,15 @@ declare class Xslt {
     outputOmitXmlDeclaration: string;
     version: string;
     firstTemplateRan: boolean;
+    /**
+     * Forwards-compatible processing mode (XSLT 1.0 Section 2.5).
+     * When true, the processor is running a stylesheet with version > 1.0.
+     * In this mode:
+     * - Unknown top-level elements are silently ignored
+     * - Unknown XSLT instructions use xsl:fallback if available, otherwise are ignored
+     * - Unknown attributes on XSLT elements are ignored
+     */
+    forwardsCompatible: boolean;
     /**
      * List of element name patterns from xsl:strip-space declarations.
      * Whitespace-only text nodes inside matching elements will be stripped.
@@ -645,6 +776,21 @@ declare class Xslt {
      * @param output If set, the output where the transformation should occur.
      */
     protected xsltProcessContext(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
+    /**
+     * Handle unknown XSLT instructions per XSLT 1.0 Section 2.5 (Forwards-Compatible Processing).
+     *
+     * In forwards-compatible mode (version > 1.0):
+     * - If the instruction has an xsl:fallback child, execute the fallback
+     * - Otherwise, the instruction is silently ignored
+     *
+     * In strict mode (version = 1.0):
+     * - Unknown instructions are an error
+     *
+     * @param context The Expression Context
+     * @param template The unknown XSLT instruction element
+     * @param output The output node
+     */
+    protected xsltUnknownInstruction(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     /**
      * Implements `xsl:apply-templates`.
      * @param context The Expression Context.
@@ -798,29 +944,57 @@ declare class Xslt {
      * @param context The Expression Context.
      * @param level The counting level: 'single', 'multiple', or 'any'.
      * @param count Pattern to match nodes to count.
-     * @param from Pattern to start counting from.
-     * @returns The count value.
+     * @param from Pattern to define counting boundary.
+     * @returns Array of count values (single element for 'single'/'any', multiple for 'multiple').
      */
-    protected xsltNumberCount(context: ExprContext, level: string, count: string | null, from: string | null): number;
+    protected xsltNumberCount(context: ExprContext, level: string, count: string | null, from: string | null): number[];
     /**
-     * Checks if a node matches a simple name pattern.
+     * Checks if a node matches a pattern (supports simple names and union patterns).
      * @param node The node to check.
-     * @param pattern The pattern (node name) to match.
+     * @param pattern The pattern (node name, wildcard, or union like "a|b|c").
      * @returns True if the node matches.
      */
     protected nodeMatchesPattern(node: XNode, pattern: string): boolean;
+    /**
+     * Checks if a node matches a single (non-union) pattern.
+     * @param node The node to check.
+     * @param pattern The pattern (node name or wildcard).
+     * @returns True if the node matches.
+     */
+    protected nodeMatchesSinglePattern(node: XNode, pattern: string): boolean;
     /**
      * Gets all nodes preceding the given node in document order.
      * @param node The reference node.
+     * @param fromPattern Optional pattern to define counting boundary.
      * @returns Array of preceding nodes.
      */
-    protected getAllPrecedingNodes(node: XNode): XNode[];
+    protected getAllPrecedingNodes(node: XNode, fromPattern?: string | null): XNode[];
     /**
      * Collects all descendant nodes of a given node.
      * @param node The parent node.
      * @param result The array to collect into.
      */
     protected collectDescendants(node: XNode, result: XNode[]): void;
+    /**
+     * Formats an array of numbers according to the format string.
+     * For level="multiple", numbers like [1, 2, 3] with format "1.1.1" produce "1.2.3".
+     * @param numbers The numbers to format.
+     * @param format The format string (e.g., "1", "1.1", "1.a.i").
+     * @param groupingSeparator Optional grouping separator.
+     * @param groupingSize Optional grouping size.
+     * @returns The formatted number string.
+     */
+    protected xsltFormatNumbers(numbers: number[], format: string, groupingSeparator: string | null, groupingSize: string | null): string;
+    /**
+     * Parses a format string into tokens and separators.
+     * E.g., "1.a.i" -> tokens: ["1", "a", "i"], separators: [".", "."]
+     * @param format The format string.
+     * @returns Object with tokens and separators arrays.
+     */
+    protected parseFormatString(format: string): {
+        tokens: string[];
+        separators: string[];
+    };
     /**
      * Formats a number according to the format string.
      * @param number The number to format.