@ai-sdk-tool/rxml 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,295 @@
+import { Transform, TransformCallback, Readable } from 'stream';
+
+/**
+ * Core types for the robust-xml parser
+ * Based on TXML structure but enhanced for schema-aware parsing
+ */
+type OnErrorFn = (message: string, metadata?: Record<string, unknown>) => void;
+/**
+ * Represents a parsed XML node in the DOM tree
+ */
+interface RXMLNode {
+    tagName: string;
+    attributes: Record<string, string | null>;
+    children: (RXMLNode | string)[];
+}
+/**
+ * Options for XML parsing
+ */
+interface ParseOptions {
+    /** Position to start parsing from (for streaming) */
+    pos?: number;
+    /** Array of tag names that don't have children and don't need to be closed */
+    noChildNodes?: string[];
+    /** Whether to set position information in result */
+    setPos?: boolean;
+    /** Keep comments in the parsed result */
+    keepComments?: boolean;
+    /** Keep whitespace like spaces, tabs and line breaks as string content */
+    keepWhitespace?: boolean;
+    /** Name of the text node property (default: "#text") */
+    textNodeName?: string;
+    /** Whether to throw on duplicate string tags */
+    throwOnDuplicateStringTags?: boolean;
+    /** Error handling callback */
+    onError?: OnErrorFn;
+    /** Whether to parse a single node instead of children */
+    parseNode?: boolean;
+    /** Filter function for nodes */
+    filter?: (node: RXMLNode, index: number, depth: number, path: string) => boolean;
+    /** Simplify the result structure */
+    simplify?: boolean;
+}
+/**
+ * Options for XML stringification
+ */
+interface StringifyOptions {
+    /** Whether to format the output with indentation */
+    format?: boolean;
+    /** Whether to suppress empty nodes */
+    suppressEmptyNode?: boolean;
+    /**
+     * Whether to use minimal escaping per XML 1.0:
+     * - In character data: escape '&' and '<' (and '>' only in ']]>' sequence)
+     * - In attribute values: escape '&', '<', and only the wrapping quote
+     * Defaults to false (conservative escaping of &, <, >, ", ')
+     */
+    minimalEscaping?: boolean;
+    /** Error handling callback */
+    onError?: OnErrorFn;
+    /**
+     * When true, serialize boolean-like attributes (value === null)
+     * as name="name" to follow strict XML attribute rules.
+     * When false (default), serialize as a convenience flag without value
+     * (e.g., <item checked>), for compatibility with existing outputs.
+     */
+    strictBooleanAttributes?: boolean;
+}
+
+/**
+ * Main XML parser that integrates tokenization, schema awareness, and error tolerance
+ * This replaces the fast-xml-parser dependency with a TXML-based implementation
+ */
+
+/**
+ * Parse XML with schema-aware type coercion
+ */
+declare function parse(xmlInner: string, schema: unknown, options?: ParseOptions): Record<string, unknown>;
+/**
+ * Parse XML without schema (similar to TXML's parse function)
+ */
+declare function parseWithoutSchema(xmlString: string, options?: ParseOptions): (RXMLNode | string)[];
+/**
+ * Parse a single XML node
+ */
+declare function parseNode(xmlString: string, options?: ParseOptions): RXMLNode;
+/**
+ * Simplify parsed XML structure (similar to TXML's simplify)
+ */
+declare function simplify(children: (RXMLNode | string)[]): unknown;
+/**
+ * Filter XML nodes (similar to TXML's filter)
+ */
+declare function filter(children: (RXMLNode | string)[], filterFn: (node: RXMLNode, index: number, depth: number, path: string) => boolean, depth?: number, path?: string): RXMLNode[];
+
+/**
+ * Streaming XML parser based on TXML's transformStream approach
+ * Provides memory-efficient parsing for large XML documents
+ */
+
+/**
+ * Transform stream for parsing XML
+ */
+declare class XMLTransformStream extends Transform {
+    private buffer;
+    private position;
+    private readonly parseOptions;
+    private emittedCount;
+    private sawTagChar;
+    constructor(offset?: number | string, parseOptions?: ParseOptions);
+    _transform(chunk: Buffer, encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    private processBuffer;
+    /**
+     * Emit an element and recursively emit its children as separate events
+     */
+    private emitElementAndChildren;
+}
+/**
+ * Create a transform stream for parsing XML
+ */
+declare function createXMLStream(offset?: number | string, parseOptions?: ParseOptions): XMLTransformStream;
+/**
+ * Parse XML from a readable stream
+ */
+declare function parseFromStream(stream: Readable, offset?: number | string, parseOptions?: ParseOptions): Promise<(RXMLNode | string)[]>;
+/**
+ * Process XML stream with async iterator support
+ */
+declare function processXMLStream(stream: Readable, offset?: number | string, parseOptions?: ParseOptions): AsyncGenerator<RXMLNode | string, void, unknown>;
+/**
+ * Find elements by ID in streaming fashion
+ */
+declare function findElementByIdStream(stream: Readable, id: string, offset?: number | string, parseOptions?: ParseOptions): AsyncGenerator<RXMLNode, void, unknown>;
+/**
+ * Find elements by class name in streaming fashion
+ */
+declare function findElementsByClassStream(stream: Readable, className: string, offset?: number | string, parseOptions?: ParseOptions): AsyncGenerator<RXMLNode, void, unknown>;
+
+/**
+ * XML Tokenizer based on TXML's character-by-character parsing approach
+ * with enhanced error tolerance and schema awareness
+ */
+
+declare class XMLTokenizer {
+    private pos;
+    private readonly xmlString;
+    private readonly options;
+    constructor(xmlString: string, options?: ParseOptions);
+    /**
+     * Parse XML children recursively
+     */
+    parseChildren(tagName?: string): (RXMLNode | string)[];
+    /**
+     * Parse a single XML node
+     */
+    parseNode(): RXMLNode;
+    /**
+     * Parse text content until next tag
+     */
+    private parseText;
+    /**
+     * Handle comments, CDATA, and DOCTYPE declarations
+     */
+    private handleSpecialContent;
+    /**
+     * Handle XML comments
+     */
+    private handleComment;
+    /**
+     * Handle CDATA sections
+     */
+    private handleCData;
+    /**
+     * Handle DOCTYPE declarations
+     */
+    private handleDoctype;
+    /**
+     * Get current position
+     */
+    getPosition(): number;
+    /**
+     * Set position
+     */
+    setPosition(pos: number): void;
+}
+
+/**
+ * Schema-aware type coercion for robust-xml
+ * Integrates with the existing coercion system but adds XML-specific handling
+ */
+
+/**
+ * Get property schema from a parent schema
+ */
+declare function getPropertySchema(toolSchema: unknown, key: string): unknown;
+/**
+ * Convert TXML-style DOM to flat object structure for schema coercion
+ */
+declare function domToObject(nodes: (RXMLNode | string)[], schema: unknown, textNodeName?: string): Record<string, unknown>;
+/**
+ * Coerce DOM object using schema information
+ */
+declare function coerceDomBySchema(domObject: Record<string, unknown>, schema: unknown): Record<string, unknown>;
+/**
+ * Extract string-typed property names from schema
+ */
+declare function getStringTypedProperties(schema: unknown): Set<string>;
+/**
+ * Process array-like structures from XML
+ */
+declare function processArrayContent(value: unknown, schema: unknown, textNodeName: string): unknown;
+/**
+ * Handle indexed tuple structures (elements with numeric keys)
+ */
+declare function processIndexedTuple(obj: Record<string, unknown>, textNodeName: string): unknown[];
+
+/**
+ * Raw content extraction utilities for string-typed properties
+ * This replaces the string-based extraction with DOM-based extraction
+ */
+
+/**
+ * Extract raw inner content from XML string for a specific tag
+ * This is used for string-typed properties to preserve exact content
+ */
+declare function extractRawInner(xmlContent: string, tagName: string): string | undefined;
+/**
+ * Find the first top-level range for a tag
+ */
+declare function findFirstTopLevelRange(xmlContent: string, tagName: string): {
+    start: number;
+    end: number;
+} | undefined;
+/**
+ * Count tag occurrences, excluding specified ranges
+ */
+declare function countTagOccurrences(xmlContent: string, tagName: string, excludeRanges?: Array<{
+    start: number;
+    end: number;
+}>, shouldSkipFirst?: boolean): number;
+
+/**
+ * XML stringification based on TXML's stringify approach
+ * Replaces the fast-xml-parser XMLBuilder with a native implementation
+ */
+
+/**
+ * Stringify an object to XML
+ */
+declare function stringify(rootTag: string, obj: unknown, options?: StringifyOptions): string;
+/**
+ * Stringify parsed XML nodes back to XML string
+ */
+declare function stringifyNodes(nodes: (RXMLNode | string)[], format?: boolean, options?: Pick<StringifyOptions, "strictBooleanAttributes" | "minimalEscaping">): string;
+/**
+ * Stringify a single XML node
+ */
+declare function stringifyNode(node: RXMLNode, depth?: number, format?: boolean, options?: Pick<StringifyOptions, "strictBooleanAttributes" | "minimalEscaping">): string;
+/**
+ * Convert content to a string representation (similar to TXML's toContentString)
+ */
+declare function toContentString(nodes: (RXMLNode | string)[]): string;
+
+/**
+ * Error classes for robust-xml parser
+ */
+declare class RXMLParseError extends Error {
+    cause?: unknown | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+    constructor(message: string, cause?: unknown | undefined, line?: number | undefined, column?: number | undefined);
+}
+declare class RXMLDuplicateStringTagError extends Error {
+    constructor(message: string);
+}
+declare class RXMLCoercionError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+declare class RXMLStringifyError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+declare class RXMLStreamError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+
+interface Options {
+    textNodeName?: string;
+    throwOnDuplicateStringTags?: boolean;
+    onError?: (message: string, context?: Record<string, unknown>) => void;
+}
+
+export { type Options, type ParseOptions, RXMLCoercionError, RXMLDuplicateStringTagError, type RXMLNode, RXMLParseError, RXMLStreamError, RXMLStringifyError, type StringifyOptions, XMLTokenizer, XMLTransformStream, coerceDomBySchema, countTagOccurrences, createXMLStream, domToObject, extractRawInner, filter, findElementByIdStream, findElementsByClassStream, findFirstTopLevelRange, getPropertySchema, getStringTypedProperties, parse, parseFromStream, parseNode, parseWithoutSchema, processArrayContent, processIndexedTuple, processXMLStream, simplify, stringify, stringifyNode, stringifyNodes, toContentString };

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+import { Transform, TransformCallback, Readable } from 'stream';
+
+/**
+ * Core types for the robust-xml parser
+ * Based on TXML structure but enhanced for schema-aware parsing
+ */
+type OnErrorFn = (message: string, metadata?: Record<string, unknown>) => void;
+/**
+ * Represents a parsed XML node in the DOM tree
+ */
+interface RXMLNode {
+    tagName: string;
+    attributes: Record<string, string | null>;
+    children: (RXMLNode | string)[];
+}
+/**
+ * Options for XML parsing
+ */
+interface ParseOptions {
+    /** Position to start parsing from (for streaming) */
+    pos?: number;
+    /** Array of tag names that don't have children and don't need to be closed */
+    noChildNodes?: string[];
+    /** Whether to set position information in result */
+    setPos?: boolean;
+    /** Keep comments in the parsed result */
+    keepComments?: boolean;
+    /** Keep whitespace like spaces, tabs and line breaks as string content */
+    keepWhitespace?: boolean;
+    /** Name of the text node property (default: "#text") */
+    textNodeName?: string;
+    /** Whether to throw on duplicate string tags */
+    throwOnDuplicateStringTags?: boolean;
+    /** Error handling callback */
+    onError?: OnErrorFn;
+    /** Whether to parse a single node instead of children */
+    parseNode?: boolean;
+    /** Filter function for nodes */
+    filter?: (node: RXMLNode, index: number, depth: number, path: string) => boolean;
+    /** Simplify the result structure */
+    simplify?: boolean;
+}
+/**
+ * Options for XML stringification
+ */
+interface StringifyOptions {
+    /** Whether to format the output with indentation */
+    format?: boolean;
+    /** Whether to suppress empty nodes */
+    suppressEmptyNode?: boolean;
+    /**
+     * Whether to use minimal escaping per XML 1.0:
+     * - In character data: escape '&' and '<' (and '>' only in ']]>' sequence)
+     * - In attribute values: escape '&', '<', and only the wrapping quote
+     * Defaults to false (conservative escaping of &, <, >, ", ')
+     */
+    minimalEscaping?: boolean;
+    /** Error handling callback */
+    onError?: OnErrorFn;
+    /**
+     * When true, serialize boolean-like attributes (value === null)
+     * as name="name" to follow strict XML attribute rules.
+     * When false (default), serialize as a convenience flag without value
+     * (e.g., <item checked>), for compatibility with existing outputs.
+     */
+    strictBooleanAttributes?: boolean;
+}
+
+/**
+ * Main XML parser that integrates tokenization, schema awareness, and error tolerance
+ * This replaces the fast-xml-parser dependency with a TXML-based implementation
+ */
+
+/**
+ * Parse XML with schema-aware type coercion
+ */
+declare function parse(xmlInner: string, schema: unknown, options?: ParseOptions): Record<string, unknown>;
+/**
+ * Parse XML without schema (similar to TXML's parse function)
+ */
+declare function parseWithoutSchema(xmlString: string, options?: ParseOptions): (RXMLNode | string)[];
+/**
+ * Parse a single XML node
+ */
+declare function parseNode(xmlString: string, options?: ParseOptions): RXMLNode;
+/**
+ * Simplify parsed XML structure (similar to TXML's simplify)
+ */
+declare function simplify(children: (RXMLNode | string)[]): unknown;
+/**
+ * Filter XML nodes (similar to TXML's filter)
+ */
+declare function filter(children: (RXMLNode | string)[], filterFn: (node: RXMLNode, index: number, depth: number, path: string) => boolean, depth?: number, path?: string): RXMLNode[];
+
+/**
+ * Streaming XML parser based on TXML's transformStream approach
+ * Provides memory-efficient parsing for large XML documents
+ */
+
+/**
+ * Transform stream for parsing XML
+ */
+declare class XMLTransformStream extends Transform {
+    private buffer;
+    private position;
+    private readonly parseOptions;
+    private emittedCount;
+    private sawTagChar;
+    constructor(offset?: number | string, parseOptions?: ParseOptions);
+    _transform(chunk: Buffer, encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    private processBuffer;
+    /**
+     * Emit an element and recursively emit its children as separate events
+     */
+    private emitElementAndChildren;
+}
+/**
+ * Create a transform stream for parsing XML
+ */
+declare function createXMLStream(offset?: number | string, parseOptions?: ParseOptions): XMLTransformStream;
+/**
+ * Parse XML from a readable stream
+ */
+declare function parseFromStream(stream: Readable, offset?: number | string, parseOptions?: ParseOptions): Promise<(RXMLNode | string)[]>;
+/**
+ * Process XML stream with async iterator support
+ */
+declare function processXMLStream(stream: Readable, offset?: number | string, parseOptions?: ParseOptions): AsyncGenerator<RXMLNode | string, void, unknown>;
+/**
+ * Find elements by ID in streaming fashion
+ */
+declare function findElementByIdStream(stream: Readable, id: string, offset?: number | string, parseOptions?: ParseOptions): AsyncGenerator<RXMLNode, void, unknown>;
+/**
+ * Find elements by class name in streaming fashion
+ */
+declare function findElementsByClassStream(stream: Readable, className: string, offset?: number | string, parseOptions?: ParseOptions): AsyncGenerator<RXMLNode, void, unknown>;
+
+/**
+ * XML Tokenizer based on TXML's character-by-character parsing approach
+ * with enhanced error tolerance and schema awareness
+ */
+
+declare class XMLTokenizer {
+    private pos;
+    private readonly xmlString;
+    private readonly options;
+    constructor(xmlString: string, options?: ParseOptions);
+    /**
+     * Parse XML children recursively
+     */
+    parseChildren(tagName?: string): (RXMLNode | string)[];
+    /**
+     * Parse a single XML node
+     */
+    parseNode(): RXMLNode;
+    /**
+     * Parse text content until next tag
+     */
+    private parseText;
+    /**
+     * Handle comments, CDATA, and DOCTYPE declarations
+     */
+    private handleSpecialContent;
+    /**
+     * Handle XML comments
+     */
+    private handleComment;
+    /**
+     * Handle CDATA sections
+     */
+    private handleCData;
+    /**
+     * Handle DOCTYPE declarations
+     */
+    private handleDoctype;
+    /**
+     * Get current position
+     */
+    getPosition(): number;
+    /**
+     * Set position
+     */
+    setPosition(pos: number): void;
+}
+
+/**
+ * Schema-aware type coercion for robust-xml
+ * Integrates with the existing coercion system but adds XML-specific handling
+ */
+
+/**
+ * Get property schema from a parent schema
+ */
+declare function getPropertySchema(toolSchema: unknown, key: string): unknown;
+/**
+ * Convert TXML-style DOM to flat object structure for schema coercion
+ */
+declare function domToObject(nodes: (RXMLNode | string)[], schema: unknown, textNodeName?: string): Record<string, unknown>;
+/**
+ * Coerce DOM object using schema information
+ */
+declare function coerceDomBySchema(domObject: Record<string, unknown>, schema: unknown): Record<string, unknown>;
+/**
+ * Extract string-typed property names from schema
+ */
+declare function getStringTypedProperties(schema: unknown): Set<string>;
+/**
+ * Process array-like structures from XML
+ */
+declare function processArrayContent(value: unknown, schema: unknown, textNodeName: string): unknown;
+/**
+ * Handle indexed tuple structures (elements with numeric keys)
+ */
+declare function processIndexedTuple(obj: Record<string, unknown>, textNodeName: string): unknown[];
+
+/**
+ * Raw content extraction utilities for string-typed properties
+ * This replaces the string-based extraction with DOM-based extraction
+ */
+
+/**
+ * Extract raw inner content from XML string for a specific tag
+ * This is used for string-typed properties to preserve exact content
+ */
+declare function extractRawInner(xmlContent: string, tagName: string): string | undefined;
+/**
+ * Find the first top-level range for a tag
+ */
+declare function findFirstTopLevelRange(xmlContent: string, tagName: string): {
+    start: number;
+    end: number;
+} | undefined;
+/**
+ * Count tag occurrences, excluding specified ranges
+ */
+declare function countTagOccurrences(xmlContent: string, tagName: string, excludeRanges?: Array<{
+    start: number;
+    end: number;
+}>, shouldSkipFirst?: boolean): number;
+
+/**
+ * XML stringification based on TXML's stringify approach
+ * Replaces the fast-xml-parser XMLBuilder with a native implementation
+ */
+
+/**
+ * Stringify an object to XML
+ */
+declare function stringify(rootTag: string, obj: unknown, options?: StringifyOptions): string;
+/**
+ * Stringify parsed XML nodes back to XML string
+ */
+declare function stringifyNodes(nodes: (RXMLNode | string)[], format?: boolean, options?: Pick<StringifyOptions, "strictBooleanAttributes" | "minimalEscaping">): string;
+/**
+ * Stringify a single XML node
+ */
+declare function stringifyNode(node: RXMLNode, depth?: number, format?: boolean, options?: Pick<StringifyOptions, "strictBooleanAttributes" | "minimalEscaping">): string;
+/**
+ * Convert content to a string representation (similar to TXML's toContentString)
+ */
+declare function toContentString(nodes: (RXMLNode | string)[]): string;
+
+/**
+ * Error classes for robust-xml parser
+ */
+declare class RXMLParseError extends Error {
+    cause?: unknown | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+    constructor(message: string, cause?: unknown | undefined, line?: number | undefined, column?: number | undefined);
+}
+declare class RXMLDuplicateStringTagError extends Error {
+    constructor(message: string);
+}
+declare class RXMLCoercionError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+declare class RXMLStringifyError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+declare class RXMLStreamError extends Error {
+    cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+
+interface Options {
+    textNodeName?: string;
+    throwOnDuplicateStringTags?: boolean;
+    onError?: (message: string, context?: Record<string, unknown>) => void;
+}
+
+export { type Options, type ParseOptions, RXMLCoercionError, RXMLDuplicateStringTagError, type RXMLNode, RXMLParseError, RXMLStreamError, RXMLStringifyError, type StringifyOptions, XMLTokenizer, XMLTransformStream, coerceDomBySchema, countTagOccurrences, createXMLStream, domToObject, extractRawInner, filter, findElementByIdStream, findElementsByClassStream, findFirstTopLevelRange, getPropertySchema, getStringTypedProperties, parse, parseFromStream, parseNode, parseWithoutSchema, processArrayContent, processIndexedTuple, processXMLStream, simplify, stringify, stringifyNode, stringifyNodes, toContentString };