@tradik/xslt-processor 1.0.2 → 1.1.1

package/dist/xslt-processor.d.cts

@@ -0,0 +1,299 @@
+/**
+ * @tradik/xslt-processor - TypeScript Declarations
+ */
+
+/**
+ * Loader used to resolve xsl:import and xsl:include references.
+ *
+ * The loader is synchronous: it must return the external stylesheet as a
+ * Document or as an XML string (which is parsed automatically).
+ *
+ * @param href - The resolved URI of the referenced stylesheet
+ * @param baseUri - The URI of the importing/including stylesheet, if known
+ */
+export type StylesheetLoader = (href: string, baseUri?: string) => Document | string;
+
+/**
+ * XSLTProcessor - Applies XSLT stylesheet transformations to XML documents.
+ */
+export class XSLTProcessor {
+  constructor();
+
+  /**
+   * The underlying XSLT engine (advanced usage).
+   * Null until a stylesheet has been imported.
+   */
+  readonly engine: XsltEngine | null;
+
+  /**
+   * Sets the loader used to resolve xsl:import and xsl:include references.
+   * Call it before importStylesheet() so the loader is available while the
+   * stylesheet is compiled; calling it afterwards updates the live engine.
+   * @param loader - The loader function, or null to remove it
+   * @returns This processor, to allow chaining
+   */
+  setStylesheetLoader(loader: StylesheetLoader | null): this;
+
+  /**
+   * Imports the XSLT stylesheet.
+   * @param style - The XSLT stylesheet to import (Document or Element)
+   * @param stylesheetUri - Optional base URI used to resolve relative
+   *   xsl:import/xsl:include hrefs
+   */
+  importStylesheet(style: Node, stylesheetUri?: string): void;
+
+  /**
+   * Transforms the node source and returns a document fragment.
+   * @param source - The XML document to transform
+   * @param output - The document that will own the generated fragment
+   * @returns The transformed result as a DocumentFragment
+   */
+  transformToFragment(source: Node, output: Document): DocumentFragment | null;
+
+  /**
+   * Transforms the node source and returns a full XML document.
+   * @param source - The XML document to transform
+   * @returns The transformed result as an XMLDocument
+   */
+  transformToDocument(source: Node): XMLDocument | null;
+
+  /**
+   * Transforms the node source and serializes the result to a string,
+   * honoring the stylesheet xsl:output settings (non-W3C convenience method).
+   * @param source - The XML document to transform
+   * @returns The serialized result, or null on a transformation error
+   */
+  transformToString(source: Node): string | null;
+
+  /**
+   * Sets a parameter in the XSLT stylesheet.
+   * @param namespaceURI - The namespace URI (use null for no namespace)
+   * @param localName - The local name of the parameter
+   * @param value - The value to set
+   */
+  setParameter(namespaceURI: string | null, localName: string, value: unknown): void;
+
+  /**
+   * Gets the value of a parameter from the XSLT stylesheet.
+   * @param namespaceURI - The namespace URI
+   * @param localName - The local name of the parameter
+   * @returns The parameter value, or empty string if not set
+   */
+  getParameter(namespaceURI: string | null, localName: string): unknown;
+
+  /**
+   * Removes a parameter from the XSLT processor.
+   * @param namespaceURI - The namespace URI
+   * @param localName - The local name of the parameter
+   */
+  removeParameter(namespaceURI: string | null, localName: string): void;
+
+  /**
+   * Removes all set parameters from the XSLTProcessor.
+   */
+  clearParameters(): void;
+
+  /**
+   * Removes all parameters and stylesheets from the XSLTProcessor.
+   * The stylesheet loader is configuration, not stylesheet state, and is preserved.
+   */
+  reset(): void;
+}
+
+/**
+ * Check if native XSLTProcessor is available and functional.
+ */
+export function isNativeXSLTSupported(): boolean;
+
+/**
+ * Install as global XSLTProcessor replacement if native is not functional.
+ * @param force - Force installation even if native is available
+ * @returns True if installed as global
+ */
+export function installGlobal(force?: boolean): boolean;
+
+/**
+ * XPath evaluation result types.
+ */
+export const XPathResultType: {
+  ANY_TYPE: 0;
+  NUMBER_TYPE: 1;
+  STRING_TYPE: 2;
+  BOOLEAN_TYPE: 3;
+  UNORDERED_NODE_ITERATOR_TYPE: 4;
+  ORDERED_NODE_ITERATOR_TYPE: 5;
+  UNORDERED_NODE_SNAPSHOT_TYPE: 6;
+  ORDERED_NODE_SNAPSHOT_TYPE: 7;
+  ANY_UNORDERED_NODE_TYPE: 8;
+  FIRST_ORDERED_NODE_TYPE: 9;
+};
+
+/**
+ * XPath evaluation context.
+ */
+export class XPathContext {
+  constructor(
+    node: Node,
+    position?: number,
+    size?: number,
+    variables?: Record<string, unknown>,
+    namespaces?: Record<string, string>
+  );
+
+  node: Node;
+  position: number;
+  size: number;
+  variables: Record<string, unknown>;
+  namespaces: Record<string, string>;
+
+  clone(overrides?: Partial<XPathContext>): XPathContext;
+}
+
+/**
+ * XPath evaluator.
+ */
+export class XPathEvaluator {
+  constructor();
+
+  evaluate(ast: unknown, context: XPathContext): unknown;
+  toBoolean(value: unknown): boolean;
+  toNumber(value: unknown): number;
+  toString(value: unknown): string;
+  getStringValue(node: Node): string;
+}
+
+/**
+ * Evaluate an XPath expression against a node.
+ */
+export function evaluateXPath(
+  expression: string,
+  contextNode: Node,
+  options?: { variables?: Record<string, unknown>; namespaces?: Record<string, string> }
+): unknown;
+
+/**
+ * Select nodes matching an XPath expression.
+ */
+export function selectXPath(
+  expression: string,
+  contextNode: Node,
+  options?: { variables?: Record<string, unknown>; namespaces?: Record<string, string> }
+): Node[];
+
+/**
+ * Select first node matching an XPath expression.
+ */
+export function selectFirstXPath(
+  expression: string,
+  contextNode: Node,
+  options?: { variables?: Record<string, unknown>; namespaces?: Record<string, string> }
+): Node | null;
+
+/**
+ * Parse an XPath expression into an AST.
+ */
+export function parseXPath(expression: string): unknown;
+
+/**
+ * XSLT processing context.
+ */
+export class XsltContext {
+  constructor(options?: {
+    currentNode?: Node;
+    currentNodeList?: Node[];
+    position?: number;
+    variables?: Record<string, unknown>;
+    parameters?: Record<string, unknown>;
+    outputDocument?: Document;
+    stylesheet?: Document;
+    namespaces?: Record<string, string>;
+    templates?: unknown[];
+    keys?: Record<string, unknown>;
+    decimalFormats?: Record<string, unknown>;
+    outputMethod?: string;
+    xpathEvaluator?: XPathEvaluator;
+  });
+
+  clone(overrides?: Partial<XsltContext>): XsltContext;
+  getVariable(name: string): unknown;
+  setVariable(name: string, value: unknown): void;
+}
+
+/**
+ * XSLT processing engine.
+ */
+export class XsltEngine {
+  constructor(options?: { stylesheetLoader?: StylesheetLoader | null; baseUri?: string });
+
+  setStylesheetLoader(loader: StylesheetLoader | null): void;
+  importStylesheet(stylesheetNode: Node, stylesheetUri?: string): void;
+  transform(sourceNode: Node, ownerDocument: Document): DocumentFragment;
+  transformToDocument(sourceNode: Node): Document;
+  transformToString(sourceNode: Node): string;
+
+  outputSettings: OutputSettings;
+}
+
+/**
+ * xsl:output settings driving the result serialization
+ * (XSLT 1.0 section 16). Accepts the raw stylesheet values, so the yes/no
+ * attributes are strings and cdata-section-elements may be a name list.
+ */
+export interface OutputSettings {
+  method?: 'xml' | 'html' | 'xhtml' | 'text' | 'auto' | string;
+  version?: string;
+  encoding?: string;
+  standalone?: 'yes' | 'no' | string | null;
+  indent?: 'yes' | 'no' | boolean;
+  omitXmlDeclaration?: 'yes' | 'no' | boolean;
+  doctypePublic?: string | null;
+  doctypeSystem?: string | null;
+  mediaType?: string | null;
+  cdataSectionElements?: string[] | string;
+}
+
+/**
+ * Serialize a transformation result honoring the xsl:output settings.
+ * @param node - Result document, fragment or element
+ * @param outputSettings - xsl:output settings
+ * @returns The serialized result, or an empty string for a null node
+ */
+export function serializeResult(
+  node: Node | null,
+  outputSettings?: OutputSettings
+): string;
+
+/**
+ * Mark a text node as produced with disable-output-escaping="yes".
+ */
+export function markRawText<T extends Node | null>(node: T): T;
+
+/**
+ * Check whether a node must be serialized without output escaping.
+ */
+export function isRawText(node: Node | null): boolean;
+
+/**
+ * Normalize raw xsl:output settings for the serializers.
+ */
+export function resolveOutputSettings(
+  outputSettings: OutputSettings | null,
+  node: Node | null
+): Required<OutputSettings> & { indent: boolean; omitXmlDeclaration: boolean; cdataSectionElements: Set<string> };
+
+/**
+ * Version information.
+ */
+export const VERSION: string;
+
+/**
+ * Check if running in a browser environment.
+ */
+export const isBrowser: boolean;
+
+/**
+ * Check if running in Node.js.
+ */
+export const isNode: boolean;
+
+export default XSLTProcessor;

package/dist/xslt-processor.d.ts

@@ -1,18 +1,46 @@
 /**
- * @cv-xslt/xslt-processor - TypeScript Declarations
+ * @tradik/xslt-processor - TypeScript Declarations
  */
 
+/**
+ * Loader used to resolve xsl:import and xsl:include references.
+ *
+ * The loader is synchronous: it must return the external stylesheet as a
+ * Document or as an XML string (which is parsed automatically).
+ *
+ * @param href - The resolved URI of the referenced stylesheet
+ * @param baseUri - The URI of the importing/including stylesheet, if known
+ */
+export type StylesheetLoader = (href: string, baseUri?: string) => Document | string;
+
 /**
  * XSLTProcessor - Applies XSLT stylesheet transformations to XML documents.
  */
 export class XSLTProcessor {
   constructor();
 
+  /**
+   * The underlying XSLT engine (advanced usage).
+   * Null until a stylesheet has been imported.
+   */
+  readonly engine: XsltEngine | null;
+
+  /**
+   * Sets the loader used to resolve xsl:import and xsl:include references.
+   * Call it before importStylesheet() so the loader is available while the
+   * stylesheet is compiled; calling it afterwards updates the live engine.
+   * @param loader - The loader function, or null to remove it
+   * @returns This processor, to allow chaining
+   */
+  setStylesheetLoader(loader: StylesheetLoader | null): this;
+
   /**
    * Imports the XSLT stylesheet.
    * @param style - The XSLT stylesheet to import (Document or Element)
+   * @param stylesheetUri - Optional base URI used to resolve relative
+   *   xsl:import/xsl:include hrefs
    */
-  importStylesheet(style: Node): void;
+  importStylesheet(style: Node, stylesheetUri?: string): void;
 
   /**
    * Transforms the node source and returns a document fragment.
@@ -29,6 +57,14 @@ export class XSLTProcessor {
    */
   transformToDocument(source: Node): XMLDocument | null;
 
+  /**
+   * Transforms the node source and serializes the result to a string,
+   * honoring the stylesheet xsl:output settings (non-W3C convenience method).
+   * @param source - The XML document to transform
+   * @returns The serialized result, or null on a transformation error
+   */
+  transformToString(source: Node): string | null;
+
   /**
    * Sets a parameter in the XSLT stylesheet.
    * @param namespaceURI - The namespace URI (use null for no namespace)
@@ -59,6 +95,7 @@ export class XSLTProcessor {
 
   /**
    * Removes all parameters and stylesheets from the XSLTProcessor.
+   * The stylesheet loader is configuration, not stylesheet state, and is preserved.
    */
   reset(): void;
 }
@@ -186,13 +223,64 @@ export class XsltContext {
  * XSLT processing engine.
  */
 export class XsltEngine {
-  constructor();
+  constructor(options?: { stylesheetLoader?: StylesheetLoader | null; baseUri?: string });
 
-  importStylesheet(stylesheetNode: Node): void;
+  setStylesheetLoader(loader: StylesheetLoader | null): void;
+  importStylesheet(stylesheetNode: Node, stylesheetUri?: string): void;
   transform(sourceNode: Node, ownerDocument: Document): DocumentFragment;
   transformToDocument(sourceNode: Node): Document;
+  transformToString(sourceNode: Node): string;
+
+  outputSettings: OutputSettings;
 }
 
+/**
+ * xsl:output settings driving the result serialization
+ * (XSLT 1.0 section 16). Accepts the raw stylesheet values, so the yes/no
+ * attributes are strings and cdata-section-elements may be a name list.
+ */
+export interface OutputSettings {
+  method?: 'xml' | 'html' | 'xhtml' | 'text' | 'auto' | string;
+  version?: string;
+  encoding?: string;
+  standalone?: 'yes' | 'no' | string | null;
+  indent?: 'yes' | 'no' | boolean;
+  omitXmlDeclaration?: 'yes' | 'no' | boolean;
+  doctypePublic?: string | null;
+  doctypeSystem?: string | null;
+  mediaType?: string | null;
+  cdataSectionElements?: string[] | string;
+}
+
+/**
+ * Serialize a transformation result honoring the xsl:output settings.
+ * @param node - Result document, fragment or element
+ * @param outputSettings - xsl:output settings
+ * @returns The serialized result, or an empty string for a null node
+ */
+export function serializeResult(
+  node: Node | null,
+  outputSettings?: OutputSettings
+): string;
+
+/**
+ * Mark a text node as produced with disable-output-escaping="yes".
+ */
+export function markRawText<T extends Node | null>(node: T): T;
+
+/**
+ * Check whether a node must be serialized without output escaping.
+ */
+export function isRawText(node: Node | null): boolean;
+
+/**
+ * Normalize raw xsl:output settings for the serializers.
+ */
+export function resolveOutputSettings(
+  outputSettings: OutputSettings | null,
+  node: Node | null
+): Required<OutputSettings> & { indent: boolean; omitXmlDeclaration: boolean; cdataSectionElements: Set<string> };
+
 /**
  * Version information.
  */