@cj-tech-master/excelts 7.2.0 → 7.3.0

package/dist/browser/modules/xml/dom.d.ts

@@ -8,7 +8,7 @@
  * For large documents, prefer SAX-based streaming.
  * This is intended for small-to-medium XML where tree access is convenient.
  */
-import type { XmlDocument, XmlElement, XmlNode, XmlParseOptions } from "./types.js";
+import type { ToPlainObjectOptions, XmlDocument, XmlElement, XmlNode, XmlParseOptions } from "./types.js";
 /**
  * Parse an XML string into a DOM tree.
  *
@@ -49,4 +49,30 @@ declare function attr(element: XmlElement, name: string): string | undefined;
  * Walk all descendant elements depth-first, calling visitor for each.
  */
 declare function walk(element: XmlElement, visitor: (el: XmlElement) => void): void;
-export { parseXml, findChild, findChildren, textContent, attr, walk };
+/**
+ * Convert an {@link XmlElement} DOM tree to a plain JavaScript object.
+ *
+ * Produces output similar to fast-xml-parser: element names become object keys,
+ * attributes are prefixed (default `@_`), text-only elements collapse to their
+ * string value, and repeated sibling names merge into arrays.
+ *
+ * @param element - The element to convert.
+ * @param options - Conversion options.
+ * @returns A plain JavaScript object representing the element.
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<root attr="1"><child>text</child></root>');
+ * const obj = toPlainObject(doc.root);
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<list><item>a</item><item>b</item></list>');
+ * const obj = toPlainObject(doc.root);
+ * // { list: { item: ["a", "b"] } }
+ * ```
+ */
+declare function toPlainObject(element: XmlElement, options?: ToPlainObjectOptions): Record<string, unknown>;
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject };

package/dist/browser/modules/xml/dom.js

@@ -10,6 +10,7 @@
  */
 import { SaxParser } from "./sax.js";
 import { XmlParseError } from "./errors.js";
+import { resolveOptions, resolveValue, addChildValue } from "./to-object-shared.js";
 // =============================================================================
 // Security
 // =============================================================================
@@ -249,4 +250,69 @@ function walk(element, visitor) {
         }
     }
 }
-export { parseXml, findChild, findChildren, textContent, attr, walk };
+// =============================================================================
+// DOM → Plain Object Conversion
+// =============================================================================
+/**
+ * Convert an {@link XmlElement} DOM tree to a plain JavaScript object.
+ *
+ * Produces output similar to fast-xml-parser: element names become object keys,
+ * attributes are prefixed (default `@_`), text-only elements collapse to their
+ * string value, and repeated sibling names merge into arrays.
+ *
+ * @param element - The element to convert.
+ * @param options - Conversion options.
+ * @returns A plain JavaScript object representing the element.
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<root attr="1"><child>text</child></root>');
+ * const obj = toPlainObject(doc.root);
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<list><item>a</item><item>b</item></list>');
+ * const obj = toPlainObject(doc.root);
+ * // { list: { item: ["a", "b"] } }
+ * ```
+ */
+function toPlainObject(element, options) {
+    const opts = resolveOptions(options);
+    function convertElement(el) {
+        const obj = Object.create(null);
+        // Add attributes — el.attributes is created via Object.create(null)
+        // by safeAttributes(), so no prototype keys to guard against.
+        let hasAttributes = false;
+        for (const key in el.attributes) {
+            obj[opts.attrPrefix + key] = el.attributes[key];
+            hasAttributes = true;
+        }
+        // Collect text and child elements in a single pass.
+        let text = "";
+        let hasChildren = false;
+        for (const child of el.children) {
+            switch (child.type) {
+                case "text":
+                    text += child.value;
+                    break;
+                case "cdata":
+                    if (opts.preserveCData) {
+                        text += child.value;
+                    }
+                    break;
+                case "element": {
+                    const value = convertElement(child);
+                    addChildValue(obj, child.name, value, opts.alwaysArray);
+                    hasChildren = true;
+                    break;
+                }
+                // comments and PIs are ignored in plain-object conversion
+            }
+        }
+        return resolveValue(obj, text, hasAttributes, hasChildren, opts);
+    }
+    return { [element.name]: convertElement(element) };
+}
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject };

package/dist/browser/modules/xml/index.d.ts

@@ -10,11 +10,12 @@
  * - Dual-mode: streaming (SAX parser + stream writer) and buffered (DOM parser + writer)
  * - Shared XmlSink interface lets rendering code target both modes transparently
  */
-export type { XmlAttributes, XmlNodeType, XmlElement, XmlText, XmlCData, XmlComment, XmlProcessingInstruction, XmlNode, XmlDocument, XmlSink, SaxTag, SaxEvent, SaxEventAny, SaxHandlers, SaxOptions, WritableTarget, XmlParseOptions } from "./types.js";
+export type { XmlAttributes, XmlNodeType, XmlElement, XmlText, XmlCData, XmlComment, XmlProcessingInstruction, XmlNode, XmlDocument, XmlSink, SaxTag, SaxEvent, SaxEventAny, SaxHandlers, SaxOptions, WritableTarget, XmlParseOptions, ToPlainObjectOptions, ParseXmlToObjectOptions } from "./types.js";
 export { xmlEncode, xmlDecode, xmlEncodeAttr, validateXmlName, encodeCData, validateCommentText } from "./encode.js";
 export { XmlWriter, StdDocAttributes } from "./writer.js";
 export { XmlStreamWriter } from "./stream-writer.js";
 export { SaxParser, parseSax, saxStream } from "./sax.js";
-export { parseXml, findChild, findChildren, textContent, attr, walk } from "./dom.js";
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject } from "./dom.js";
+export { parseXmlToObject } from "./to-object.js";
 export { query, queryAll } from "./query.js";
 export { XmlError, XmlParseError, XmlWriteError, isXmlError, isXmlParseError } from "./errors.js";

package/dist/browser/modules/xml/index.js

@@ -23,7 +23,8 @@ export { XmlStreamWriter } from "./stream-writer.js";
 // Parsers
 // =============================================================================
 export { SaxParser, parseSax, saxStream } from "./sax.js";
-export { parseXml, findChild, findChildren, textContent, attr, walk } from "./dom.js";
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject } from "./dom.js";
+export { parseXmlToObject } from "./to-object.js";
 export { query, queryAll } from "./query.js";
 // =============================================================================
 // Errors

package/dist/browser/modules/xml/to-object-shared.d.ts

@@ -0,0 +1,29 @@
+/**
+ * XML → Plain Object — Shared Conversion Logic
+ *
+ * Internal module used by both `toPlainObject` (DOM path) and
+ * `parseXmlToObject` (SAX-direct path). Not part of the public API.
+ */
+import type { ToPlainObjectOptions } from "./types.js";
+/** Options with all defaults resolved — no more `??` checks at hot-path call sites. */
+export interface ResolvedOptions {
+    readonly attrPrefix: string;
+    readonly textKey: string;
+    readonly alwaysArray: boolean;
+    readonly preserveCData: boolean;
+    readonly ignoreWS: boolean;
+}
+export declare function resolveOptions(options?: ToPlainObjectOptions): ResolvedOptions;
+/**
+ * Determine the final plain-object value for an element given its parts.
+ *
+ * Returns either:
+ * - a string (text-only / empty element)
+ * - the `obj` record (element with attributes and/or children)
+ */
+export declare function resolveValue(obj: Record<string, unknown>, text: string, hasAttributes: boolean, hasChildren: boolean, opts: ResolvedOptions): unknown;
+/**
+ * Add a resolved child value into a parent object, merging repeated names
+ * into arrays.
+ */
+export declare function addChildValue(parent: Record<string, unknown>, name: string, value: unknown, alwaysArray: boolean): void;

package/dist/browser/modules/xml/to-object-shared.js

@@ -0,0 +1,80 @@
+/**
+ * XML → Plain Object — Shared Conversion Logic
+ *
+ * Internal module used by both `toPlainObject` (DOM path) and
+ * `parseXmlToObject` (SAX-direct path). Not part of the public API.
+ */
+export function resolveOptions(options) {
+    return {
+        attrPrefix: options?.attributePrefix ?? "@_",
+        textKey: options?.textKey ?? "#text",
+        alwaysArray: options?.alwaysArray ?? false,
+        preserveCData: options?.preserveCData ?? true,
+        ignoreWS: options?.ignoreWhitespaceText ?? true
+    };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Check if a string contains only whitespace without allocating a trimmed copy. */
+function isWhitespaceOnly(s) {
+    for (let i = 0; i < s.length; i++) {
+        const ch = s.charCodeAt(i);
+        // space, tab, newline, carriage return
+        if (ch !== 0x20 && ch !== 0x09 && ch !== 0x0a && ch !== 0x0d) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
+// Value Resolution
+// =============================================================================
+/**
+ * Determine the final plain-object value for an element given its parts.
+ *
+ * Returns either:
+ * - a string (text-only / empty element)
+ * - the `obj` record (element with attributes and/or children)
+ */
+export function resolveValue(obj, text, hasAttributes, hasChildren, opts) {
+    // Discard whitespace-only text when element has children (formatting indentation).
+    if (opts.ignoreWS && hasChildren && text.length > 0 && isWhitespaceOnly(text)) {
+        text = "";
+    }
+    const hasText = text.length > 0;
+    // Text-only element with no attributes → collapse to string value
+    if (hasText && !hasChildren && !hasAttributes) {
+        return text;
+    }
+    // Add text content
+    if (hasText) {
+        obj[opts.textKey] = text;
+    }
+    // Empty element with no attributes → empty string (like fast-xml-parser)
+    if (!hasAttributes && !hasChildren && !hasText) {
+        return "";
+    }
+    return obj;
+}
+// =============================================================================
+// Child Merging
+// =============================================================================
+/**
+ * Add a resolved child value into a parent object, merging repeated names
+ * into arrays.
+ */
+export function addChildValue(parent, name, value, alwaysArray) {
+    const existing = parent[name];
+    if (existing !== undefined) {
+        if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            parent[name] = [existing, value];
+        }
+    }
+    else {
+        parent[name] = alwaysArray ? [value] : value;
+    }
+}

package/dist/browser/modules/xml/to-object.d.ts

@@ -0,0 +1,35 @@
+/**
+ * XML → Plain Object (SAX-direct)
+ *
+ * Parses an XML string directly into a plain JavaScript object, bypassing the
+ * DOM tree entirely. This is the fastest path for "XML string → plain object →
+ * JSON.stringify" workflows.
+ *
+ * For converting an already-parsed {@link XmlElement} tree, use
+ * {@link toPlainObject} from `./dom` instead.
+ */
+import type { ParseXmlToObjectOptions } from "./types.js";
+/**
+ * Parse an XML string directly into a plain JavaScript object.
+ *
+ * Unlike `parseXml` + `toPlainObject`, this function builds the plain object
+ * in a single SAX pass with **zero intermediate DOM nodes**. Use this when
+ * performance matters and you only need the plain-object output.
+ *
+ * The output format matches {@link toPlainObject}: attributes are prefixed
+ * (default `@_`), text-only elements collapse to strings, and repeated
+ * sibling names merge into arrays.
+ *
+ * @param xml - Complete XML string.
+ * @param options - Conversion and parser options.
+ * @returns A plain JavaScript object representing the root element.
+ * @throws {XmlParseError} If the XML is malformed.
+ *
+ * @example
+ * ```ts
+ * const obj = parseXmlToObject('<root attr="1"><child>text</child></root>');
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ */
+declare function parseXmlToObject(xml: string, options?: ParseXmlToObjectOptions): Record<string, unknown>;
+export { parseXmlToObject };

package/dist/browser/modules/xml/to-object.js

@@ -0,0 +1,121 @@
+/**
+ * XML → Plain Object (SAX-direct)
+ *
+ * Parses an XML string directly into a plain JavaScript object, bypassing the
+ * DOM tree entirely. This is the fastest path for "XML string → plain object →
+ * JSON.stringify" workflows.
+ *
+ * For converting an already-parsed {@link XmlElement} tree, use
+ * {@link toPlainObject} from `./dom` instead.
+ */
+import { SaxParser } from "./sax.js";
+import { XmlParseError } from "./errors.js";
+import { resolveOptions, resolveValue, addChildValue } from "./to-object-shared.js";
+// =============================================================================
+// parseXmlToObject
+// =============================================================================
+/**
+ * Parse an XML string directly into a plain JavaScript object.
+ *
+ * Unlike `parseXml` + `toPlainObject`, this function builds the plain object
+ * in a single SAX pass with **zero intermediate DOM nodes**. Use this when
+ * performance matters and you only need the plain-object output.
+ *
+ * The output format matches {@link toPlainObject}: attributes are prefixed
+ * (default `@_`), text-only elements collapse to strings, and repeated
+ * sibling names merge into arrays.
+ *
+ * @param xml - Complete XML string.
+ * @param options - Conversion and parser options.
+ * @returns A plain JavaScript object representing the root element.
+ * @throws {XmlParseError} If the XML is malformed.
+ *
+ * @example
+ * ```ts
+ * const obj = parseXmlToObject('<root attr="1"><child>text</child></root>');
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ */
+function parseXmlToObject(xml, options) {
+    const opts = resolveOptions(options);
+    const parser = new SaxParser({
+        position: false,
+        fragment: options?.fragment ?? false,
+        maxDepth: options?.maxDepth,
+        maxEntityExpansions: options?.maxEntityExpansions
+    });
+    // Stack: bottom is a synthetic root frame that collects the document root.
+    const syntheticObj = Object.create(null);
+    const stack = [
+        { obj: syntheticObj, text: "", hasChildren: false, hasAttributes: false, name: "" }
+    ];
+    let error;
+    parser.on("error", err => {
+        if (!error) {
+            error = err instanceof XmlParseError ? err : new XmlParseError(err.message);
+        }
+    });
+    parser.on("opentag", tag => {
+        const frame = {
+            obj: Object.create(null),
+            text: "",
+            hasChildren: false,
+            hasAttributes: false,
+            name: tag.name
+        };
+        // Write attributes directly into frame.obj
+        for (const key in tag.attributes) {
+            frame.obj[opts.attrPrefix + key] = tag.attributes[key];
+            frame.hasAttributes = true;
+        }
+        // Mark parent as having children
+        stack[stack.length - 1].hasChildren = true;
+        if (tag.isSelfClosing) {
+            // Resolve immediately — this element has no children or text.
+            finishFrame(frame, stack[stack.length - 1], opts);
+        }
+        else {
+            stack.push(frame);
+        }
+    });
+    parser.on("text", text => {
+        if (text.length > 0) {
+            stack[stack.length - 1].text += text;
+        }
+    });
+    parser.on("cdata", text => {
+        if (opts.preserveCData && text.length > 0) {
+            stack[stack.length - 1].text += text;
+        }
+    });
+    parser.on("closetag", tag => {
+        if (tag.isSelfClosing) {
+            return;
+        }
+        if (stack.length <= 1) {
+            return;
+        }
+        const frame = stack.pop();
+        finishFrame(frame, stack[stack.length - 1], opts);
+    });
+    // Ignore comments and PIs — not needed for plain-object output
+    parser.write(xml);
+    parser.close();
+    if (error) {
+        throw error;
+    }
+    // The synthetic root's obj should contain exactly one key (the document root).
+    return syntheticObj;
+}
+/**
+ * Resolve a completed frame and add it to the parent.
+ * The synthetic root (stack depth 1) never gets `alwaysArray` applied to it.
+ */
+function finishFrame(frame, parent, opts) {
+    const value = resolveValue(frame.obj, frame.text, frame.hasAttributes, frame.hasChildren, opts);
+    // The document root element (child of synthetic root) should never be
+    // wrapped in an array by alwaysArray — it's always a direct value.
+    const isDocRoot = parent.name === "";
+    addChildValue(parent.obj, frame.name, value, isDocRoot ? false : opts.alwaysArray);
+}
+export { parseXmlToObject };

package/dist/browser/modules/xml/types.d.ts

@@ -198,6 +198,59 @@ export interface SaxOptions {
 export interface WritableTarget {
     write(chunk: string | Uint8Array): void;
 }
+/**
+ * Options for `toPlainObject()`.
+ *
+ * Controls how an {@link XmlElement} DOM tree is converted to a plain
+ * JavaScript object (similar to fast-xml-parser output format).
+ */
+export interface ToPlainObjectOptions {
+    /**
+     * Prefix for attribute keys.
+     * Set to `""` to use bare attribute names.
+     * @default "@_"
+     */
+    attributePrefix?: string;
+    /**
+     * Key used for text content when an element has both text and child elements
+     * (mixed content).
+     * @default "#text"
+     */
+    textKey?: string;
+    /**
+     * When true, always wrap child elements in arrays even if there is only one.
+     * When false (default), single children are stored as a plain value.
+     * @default false
+     */
+    alwaysArray?: boolean;
+    /**
+     * When true, include CDATA node values (already merged to text by default
+     * in `parseXml`, only relevant with `cdataAsNodes`).
+     * @default true
+     */
+    preserveCData?: boolean;
+    /**
+     * When true, discard whitespace-only text in elements that also have child
+     * elements (typical of pretty-printed XML indentation). Leaf elements that
+     * contain only whitespace text are **not** affected — their text is preserved.
+     * @default true
+     */
+    ignoreWhitespaceText?: boolean;
+}
+/**
+ * Options for `parseXmlToObject()`.
+ *
+ * Extends {@link ToPlainObjectOptions} with SAX parser settings, since
+ * `parseXmlToObject` handles both parsing and conversion in a single pass.
+ */
+export interface ParseXmlToObjectOptions extends ToPlainObjectOptions {
+    /** Parse as fragment (no root element required). Default: false */
+    fragment?: boolean;
+    /** Maximum element nesting depth. Default: 256. */
+    maxDepth?: number;
+    /** Maximum total entity expansions. Default: 10000. */
+    maxEntityExpansions?: number;
+}
 /** Options for `parseXml()`. */
 export interface XmlParseOptions {
     /** Include comments in the tree. Default: false */

package/dist/cjs/modules/xml/dom.js

@@ -16,8 +16,10 @@ exports.findChildren = findChildren;
 exports.textContent = textContent;
 exports.attr = attr;
 exports.walk = walk;
+exports.toPlainObject = toPlainObject;
 const sax_1 = require("./sax.js");
 const errors_1 = require("./errors.js");
+const to_object_shared_1 = require("./to-object-shared.js");
 // =============================================================================
 // Security
 // =============================================================================
@@ -257,3 +259,68 @@ function walk(element, visitor) {
         }
     }
 }
+// =============================================================================
+// DOM → Plain Object Conversion
+// =============================================================================
+/**
+ * Convert an {@link XmlElement} DOM tree to a plain JavaScript object.
+ *
+ * Produces output similar to fast-xml-parser: element names become object keys,
+ * attributes are prefixed (default `@_`), text-only elements collapse to their
+ * string value, and repeated sibling names merge into arrays.
+ *
+ * @param element - The element to convert.
+ * @param options - Conversion options.
+ * @returns A plain JavaScript object representing the element.
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<root attr="1"><child>text</child></root>');
+ * const obj = toPlainObject(doc.root);
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<list><item>a</item><item>b</item></list>');
+ * const obj = toPlainObject(doc.root);
+ * // { list: { item: ["a", "b"] } }
+ * ```
+ */
+function toPlainObject(element, options) {
+    const opts = (0, to_object_shared_1.resolveOptions)(options);
+    function convertElement(el) {
+        const obj = Object.create(null);
+        // Add attributes — el.attributes is created via Object.create(null)
+        // by safeAttributes(), so no prototype keys to guard against.
+        let hasAttributes = false;
+        for (const key in el.attributes) {
+            obj[opts.attrPrefix + key] = el.attributes[key];
+            hasAttributes = true;
+        }
+        // Collect text and child elements in a single pass.
+        let text = "";
+        let hasChildren = false;
+        for (const child of el.children) {
+            switch (child.type) {
+                case "text":
+                    text += child.value;
+                    break;
+                case "cdata":
+                    if (opts.preserveCData) {
+                        text += child.value;
+                    }
+                    break;
+                case "element": {
+                    const value = convertElement(child);
+                    (0, to_object_shared_1.addChildValue)(obj, child.name, value, opts.alwaysArray);
+                    hasChildren = true;
+                    break;
+                }
+                // comments and PIs are ignored in plain-object conversion
+            }
+        }
+        return (0, to_object_shared_1.resolveValue)(obj, text, hasAttributes, hasChildren, opts);
+    }
+    return { [element.name]: convertElement(element) };
+}

package/dist/cjs/modules/xml/index.js

@@ -12,7 +12,7 @@
  * - Shared XmlSink interface lets rendering code target both modes transparently
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isXmlParseError = exports.isXmlError = exports.XmlWriteError = exports.XmlParseError = exports.XmlError = exports.queryAll = exports.query = exports.walk = exports.attr = exports.textContent = exports.findChildren = exports.findChild = exports.parseXml = exports.saxStream = exports.parseSax = exports.SaxParser = exports.XmlStreamWriter = exports.StdDocAttributes = exports.XmlWriter = exports.validateCommentText = exports.encodeCData = exports.validateXmlName = exports.xmlEncodeAttr = exports.xmlDecode = exports.xmlEncode = void 0;
+exports.isXmlParseError = exports.isXmlError = exports.XmlWriteError = exports.XmlParseError = exports.XmlError = exports.queryAll = exports.query = exports.parseXmlToObject = exports.toPlainObject = exports.walk = exports.attr = exports.textContent = exports.findChildren = exports.findChild = exports.parseXml = exports.saxStream = exports.parseSax = exports.SaxParser = exports.XmlStreamWriter = exports.StdDocAttributes = exports.XmlWriter = exports.validateCommentText = exports.encodeCData = exports.validateXmlName = exports.xmlEncodeAttr = exports.xmlDecode = exports.xmlEncode = void 0;
 // =============================================================================
 // Encoding / Decoding
 // =============================================================================
@@ -45,6 +45,9 @@ Object.defineProperty(exports, "findChildren", { enumerable: true, get: function
 Object.defineProperty(exports, "textContent", { enumerable: true, get: function () { return dom_1.textContent; } });
 Object.defineProperty(exports, "attr", { enumerable: true, get: function () { return dom_1.attr; } });
 Object.defineProperty(exports, "walk", { enumerable: true, get: function () { return dom_1.walk; } });
+Object.defineProperty(exports, "toPlainObject", { enumerable: true, get: function () { return dom_1.toPlainObject; } });
+var to_object_1 = require("./to-object");
+Object.defineProperty(exports, "parseXmlToObject", { enumerable: true, get: function () { return to_object_1.parseXmlToObject; } });
 var query_1 = require("./query");
 Object.defineProperty(exports, "query", { enumerable: true, get: function () { return query_1.query; } });
 Object.defineProperty(exports, "queryAll", { enumerable: true, get: function () { return query_1.queryAll; } });

package/dist/cjs/modules/xml/to-object-shared.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * XML → Plain Object — Shared Conversion Logic
+ *
+ * Internal module used by both `toPlainObject` (DOM path) and
+ * `parseXmlToObject` (SAX-direct path). Not part of the public API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOptions = resolveOptions;
+exports.resolveValue = resolveValue;
+exports.addChildValue = addChildValue;
+function resolveOptions(options) {
+    return {
+        attrPrefix: options?.attributePrefix ?? "@_",
+        textKey: options?.textKey ?? "#text",
+        alwaysArray: options?.alwaysArray ?? false,
+        preserveCData: options?.preserveCData ?? true,
+        ignoreWS: options?.ignoreWhitespaceText ?? true
+    };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Check if a string contains only whitespace without allocating a trimmed copy. */
+function isWhitespaceOnly(s) {
+    for (let i = 0; i < s.length; i++) {
+        const ch = s.charCodeAt(i);
+        // space, tab, newline, carriage return
+        if (ch !== 0x20 && ch !== 0x09 && ch !== 0x0a && ch !== 0x0d) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
+// Value Resolution
+// =============================================================================
+/**
+ * Determine the final plain-object value for an element given its parts.
+ *
+ * Returns either:
+ * - a string (text-only / empty element)
+ * - the `obj` record (element with attributes and/or children)
+ */
+function resolveValue(obj, text, hasAttributes, hasChildren, opts) {
+    // Discard whitespace-only text when element has children (formatting indentation).
+    if (opts.ignoreWS && hasChildren && text.length > 0 && isWhitespaceOnly(text)) {
+        text = "";
+    }
+    const hasText = text.length > 0;
+    // Text-only element with no attributes → collapse to string value
+    if (hasText && !hasChildren && !hasAttributes) {
+        return text;
+    }
+    // Add text content
+    if (hasText) {
+        obj[opts.textKey] = text;
+    }
+    // Empty element with no attributes → empty string (like fast-xml-parser)
+    if (!hasAttributes && !hasChildren && !hasText) {
+        return "";
+    }
+    return obj;
+}
+// =============================================================================
+// Child Merging
+// =============================================================================
+/**
+ * Add a resolved child value into a parent object, merging repeated names
+ * into arrays.
+ */
+function addChildValue(parent, name, value, alwaysArray) {
+    const existing = parent[name];
+    if (existing !== undefined) {
+        if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            parent[name] = [existing, value];
+        }
+    }
+    else {
+        parent[name] = alwaysArray ? [value] : value;
+    }
+}

package/dist/cjs/modules/xml/to-object.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * XML → Plain Object (SAX-direct)
+ *
+ * Parses an XML string directly into a plain JavaScript object, bypassing the
+ * DOM tree entirely. This is the fastest path for "XML string → plain object →
+ * JSON.stringify" workflows.
+ *
+ * For converting an already-parsed {@link XmlElement} tree, use
+ * {@link toPlainObject} from `./dom` instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseXmlToObject = parseXmlToObject;
+const sax_1 = require("./sax.js");
+const errors_1 = require("./errors.js");
+const to_object_shared_1 = require("./to-object-shared.js");
+// =============================================================================
+// parseXmlToObject
+// =============================================================================
+/**
+ * Parse an XML string directly into a plain JavaScript object.
+ *
+ * Unlike `parseXml` + `toPlainObject`, this function builds the plain object
+ * in a single SAX pass with **zero intermediate DOM nodes**. Use this when
+ * performance matters and you only need the plain-object output.
+ *
+ * The output format matches {@link toPlainObject}: attributes are prefixed
+ * (default `@_`), text-only elements collapse to strings, and repeated
+ * sibling names merge into arrays.
+ *
+ * @param xml - Complete XML string.
+ * @param options - Conversion and parser options.
+ * @returns A plain JavaScript object representing the root element.
+ * @throws {XmlParseError} If the XML is malformed.
+ *
+ * @example
+ * ```ts
+ * const obj = parseXmlToObject('<root attr="1"><child>text</child></root>');
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ */
+function parseXmlToObject(xml, options) {
+    const opts = (0, to_object_shared_1.resolveOptions)(options);
+    const parser = new sax_1.SaxParser({
+        position: false,
+        fragment: options?.fragment ?? false,
+        maxDepth: options?.maxDepth,
+        maxEntityExpansions: options?.maxEntityExpansions
+    });
+    // Stack: bottom is a synthetic root frame that collects the document root.
+    const syntheticObj = Object.create(null);
+    const stack = [
+        { obj: syntheticObj, text: "", hasChildren: false, hasAttributes: false, name: "" }
+    ];
+    let error;
+    parser.on("error", err => {
+        if (!error) {
+            error = err instanceof errors_1.XmlParseError ? err : new errors_1.XmlParseError(err.message);
+        }
+    });
+    parser.on("opentag", tag => {
+        const frame = {
+            obj: Object.create(null),
+            text: "",
+            hasChildren: false,
+            hasAttributes: false,
+            name: tag.name
+        };
+        // Write attributes directly into frame.obj
+        for (const key in tag.attributes) {
+            frame.obj[opts.attrPrefix + key] = tag.attributes[key];
+            frame.hasAttributes = true;
+        }
+        // Mark parent as having children
+        stack[stack.length - 1].hasChildren = true;
+        if (tag.isSelfClosing) {
+            // Resolve immediately — this element has no children or text.
+            finishFrame(frame, stack[stack.length - 1], opts);
+        }
+        else {
+            stack.push(frame);
+        }
+    });
+    parser.on("text", text => {
+        if (text.length > 0) {
+            stack[stack.length - 1].text += text;
+        }
+    });
+    parser.on("cdata", text => {
+        if (opts.preserveCData && text.length > 0) {
+            stack[stack.length - 1].text += text;
+        }
+    });
+    parser.on("closetag", tag => {
+        if (tag.isSelfClosing) {
+            return;
+        }
+        if (stack.length <= 1) {
+            return;
+        }
+        const frame = stack.pop();
+        finishFrame(frame, stack[stack.length - 1], opts);
+    });
+    // Ignore comments and PIs — not needed for plain-object output
+    parser.write(xml);
+    parser.close();
+    if (error) {
+        throw error;
+    }
+    // The synthetic root's obj should contain exactly one key (the document root).
+    return syntheticObj;
+}
+/**
+ * Resolve a completed frame and add it to the parent.
+ * The synthetic root (stack depth 1) never gets `alwaysArray` applied to it.
+ */
+function finishFrame(frame, parent, opts) {
+    const value = (0, to_object_shared_1.resolveValue)(frame.obj, frame.text, frame.hasAttributes, frame.hasChildren, opts);
+    // The document root element (child of synthetic root) should never be
+    // wrapped in an array by alwaysArray — it's always a direct value.
+    const isDocRoot = parent.name === "";
+    (0, to_object_shared_1.addChildValue)(parent.obj, frame.name, value, isDocRoot ? false : opts.alwaysArray);
+}

package/dist/esm/modules/xml/dom.js

@@ -10,6 +10,7 @@
  */
 import { SaxParser } from "./sax.js";
 import { XmlParseError } from "./errors.js";
+import { resolveOptions, resolveValue, addChildValue } from "./to-object-shared.js";
 // =============================================================================
 // Security
 // =============================================================================
@@ -249,4 +250,69 @@ function walk(element, visitor) {
         }
     }
 }
-export { parseXml, findChild, findChildren, textContent, attr, walk };
+// =============================================================================
+// DOM → Plain Object Conversion
+// =============================================================================
+/**
+ * Convert an {@link XmlElement} DOM tree to a plain JavaScript object.
+ *
+ * Produces output similar to fast-xml-parser: element names become object keys,
+ * attributes are prefixed (default `@_`), text-only elements collapse to their
+ * string value, and repeated sibling names merge into arrays.
+ *
+ * @param element - The element to convert.
+ * @param options - Conversion options.
+ * @returns A plain JavaScript object representing the element.
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<root attr="1"><child>text</child></root>');
+ * const obj = toPlainObject(doc.root);
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<list><item>a</item><item>b</item></list>');
+ * const obj = toPlainObject(doc.root);
+ * // { list: { item: ["a", "b"] } }
+ * ```
+ */
+function toPlainObject(element, options) {
+    const opts = resolveOptions(options);
+    function convertElement(el) {
+        const obj = Object.create(null);
+        // Add attributes — el.attributes is created via Object.create(null)
+        // by safeAttributes(), so no prototype keys to guard against.
+        let hasAttributes = false;
+        for (const key in el.attributes) {
+            obj[opts.attrPrefix + key] = el.attributes[key];
+            hasAttributes = true;
+        }
+        // Collect text and child elements in a single pass.
+        let text = "";
+        let hasChildren = false;
+        for (const child of el.children) {
+            switch (child.type) {
+                case "text":
+                    text += child.value;
+                    break;
+                case "cdata":
+                    if (opts.preserveCData) {
+                        text += child.value;
+                    }
+                    break;
+                case "element": {
+                    const value = convertElement(child);
+                    addChildValue(obj, child.name, value, opts.alwaysArray);
+                    hasChildren = true;
+                    break;
+                }
+                // comments and PIs are ignored in plain-object conversion
+            }
+        }
+        return resolveValue(obj, text, hasAttributes, hasChildren, opts);
+    }
+    return { [element.name]: convertElement(element) };
+}
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject };

package/dist/esm/modules/xml/index.js

@@ -23,7 +23,8 @@ export { XmlStreamWriter } from "./stream-writer.js";
 // Parsers
 // =============================================================================
 export { SaxParser, parseSax, saxStream } from "./sax.js";
-export { parseXml, findChild, findChildren, textContent, attr, walk } from "./dom.js";
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject } from "./dom.js";
+export { parseXmlToObject } from "./to-object.js";
 export { query, queryAll } from "./query.js";
 // =============================================================================
 // Errors

package/dist/esm/modules/xml/to-object-shared.js

@@ -0,0 +1,80 @@
+/**
+ * XML → Plain Object — Shared Conversion Logic
+ *
+ * Internal module used by both `toPlainObject` (DOM path) and
+ * `parseXmlToObject` (SAX-direct path). Not part of the public API.
+ */
+export function resolveOptions(options) {
+    return {
+        attrPrefix: options?.attributePrefix ?? "@_",
+        textKey: options?.textKey ?? "#text",
+        alwaysArray: options?.alwaysArray ?? false,
+        preserveCData: options?.preserveCData ?? true,
+        ignoreWS: options?.ignoreWhitespaceText ?? true
+    };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Check if a string contains only whitespace without allocating a trimmed copy. */
+function isWhitespaceOnly(s) {
+    for (let i = 0; i < s.length; i++) {
+        const ch = s.charCodeAt(i);
+        // space, tab, newline, carriage return
+        if (ch !== 0x20 && ch !== 0x09 && ch !== 0x0a && ch !== 0x0d) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
+// Value Resolution
+// =============================================================================
+/**
+ * Determine the final plain-object value for an element given its parts.
+ *
+ * Returns either:
+ * - a string (text-only / empty element)
+ * - the `obj` record (element with attributes and/or children)
+ */
+export function resolveValue(obj, text, hasAttributes, hasChildren, opts) {
+    // Discard whitespace-only text when element has children (formatting indentation).
+    if (opts.ignoreWS && hasChildren && text.length > 0 && isWhitespaceOnly(text)) {
+        text = "";
+    }
+    const hasText = text.length > 0;
+    // Text-only element with no attributes → collapse to string value
+    if (hasText && !hasChildren && !hasAttributes) {
+        return text;
+    }
+    // Add text content
+    if (hasText) {
+        obj[opts.textKey] = text;
+    }
+    // Empty element with no attributes → empty string (like fast-xml-parser)
+    if (!hasAttributes && !hasChildren && !hasText) {
+        return "";
+    }
+    return obj;
+}
+// =============================================================================
+// Child Merging
+// =============================================================================
+/**
+ * Add a resolved child value into a parent object, merging repeated names
+ * into arrays.
+ */
+export function addChildValue(parent, name, value, alwaysArray) {
+    const existing = parent[name];
+    if (existing !== undefined) {
+        if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            parent[name] = [existing, value];
+        }
+    }
+    else {
+        parent[name] = alwaysArray ? [value] : value;
+    }
+}

package/dist/esm/modules/xml/to-object.js

@@ -0,0 +1,121 @@
+/**
+ * XML → Plain Object (SAX-direct)
+ *
+ * Parses an XML string directly into a plain JavaScript object, bypassing the
+ * DOM tree entirely. This is the fastest path for "XML string → plain object →
+ * JSON.stringify" workflows.
+ *
+ * For converting an already-parsed {@link XmlElement} tree, use
+ * {@link toPlainObject} from `./dom` instead.
+ */
+import { SaxParser } from "./sax.js";
+import { XmlParseError } from "./errors.js";
+import { resolveOptions, resolveValue, addChildValue } from "./to-object-shared.js";
+// =============================================================================
+// parseXmlToObject
+// =============================================================================
+/**
+ * Parse an XML string directly into a plain JavaScript object.
+ *
+ * Unlike `parseXml` + `toPlainObject`, this function builds the plain object
+ * in a single SAX pass with **zero intermediate DOM nodes**. Use this when
+ * performance matters and you only need the plain-object output.
+ *
+ * The output format matches {@link toPlainObject}: attributes are prefixed
+ * (default `@_`), text-only elements collapse to strings, and repeated
+ * sibling names merge into arrays.
+ *
+ * @param xml - Complete XML string.
+ * @param options - Conversion and parser options.
+ * @returns A plain JavaScript object representing the root element.
+ * @throws {XmlParseError} If the XML is malformed.
+ *
+ * @example
+ * ```ts
+ * const obj = parseXmlToObject('<root attr="1"><child>text</child></root>');
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ */
+function parseXmlToObject(xml, options) {
+    const opts = resolveOptions(options);
+    const parser = new SaxParser({
+        position: false,
+        fragment: options?.fragment ?? false,
+        maxDepth: options?.maxDepth,
+        maxEntityExpansions: options?.maxEntityExpansions
+    });
+    // Stack: bottom is a synthetic root frame that collects the document root.
+    const syntheticObj = Object.create(null);
+    const stack = [
+        { obj: syntheticObj, text: "", hasChildren: false, hasAttributes: false, name: "" }
+    ];
+    let error;
+    parser.on("error", err => {
+        if (!error) {
+            error = err instanceof XmlParseError ? err : new XmlParseError(err.message);
+        }
+    });
+    parser.on("opentag", tag => {
+        const frame = {
+            obj: Object.create(null),
+            text: "",
+            hasChildren: false,
+            hasAttributes: false,
+            name: tag.name
+        };
+        // Write attributes directly into frame.obj
+        for (const key in tag.attributes) {
+            frame.obj[opts.attrPrefix + key] = tag.attributes[key];
+            frame.hasAttributes = true;
+        }
+        // Mark parent as having children
+        stack[stack.length - 1].hasChildren = true;
+        if (tag.isSelfClosing) {
+            // Resolve immediately — this element has no children or text.
+            finishFrame(frame, stack[stack.length - 1], opts);
+        }
+        else {
+            stack.push(frame);
+        }
+    });
+    parser.on("text", text => {
+        if (text.length > 0) {
+            stack[stack.length - 1].text += text;
+        }
+    });
+    parser.on("cdata", text => {
+        if (opts.preserveCData && text.length > 0) {
+            stack[stack.length - 1].text += text;
+        }
+    });
+    parser.on("closetag", tag => {
+        if (tag.isSelfClosing) {
+            return;
+        }
+        if (stack.length <= 1) {
+            return;
+        }
+        const frame = stack.pop();
+        finishFrame(frame, stack[stack.length - 1], opts);
+    });
+    // Ignore comments and PIs — not needed for plain-object output
+    parser.write(xml);
+    parser.close();
+    if (error) {
+        throw error;
+    }
+    // The synthetic root's obj should contain exactly one key (the document root).
+    return syntheticObj;
+}
+/**
+ * Resolve a completed frame and add it to the parent.
+ * The synthetic root (stack depth 1) never gets `alwaysArray` applied to it.
+ */
+function finishFrame(frame, parent, opts) {
+    const value = resolveValue(frame.obj, frame.text, frame.hasAttributes, frame.hasChildren, opts);
+    // The document root element (child of synthetic root) should never be
+    // wrapped in an array by alwaysArray — it's always a direct value.
+    const isDocRoot = parent.name === "";
+    addChildValue(parent.obj, frame.name, value, isDocRoot ? false : opts.alwaysArray);
+}
+export { parseXmlToObject };

package/dist/iife/excelts.iife.js

@@ -1,5 +1,5 @@
 /*!
-* @cj-tech-master/excelts v7.2.0
+* @cj-tech-master/excelts v7.3.0
 * TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.
 * (c) 2026 cjnoname
 * Released under the MIT License

package/dist/iife/excelts.iife.min.js

@@ -1,5 +1,5 @@
 /*!
-* @cj-tech-master/excelts v7.2.0
+* @cj-tech-master/excelts v7.3.0
 * TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.
 * (c) 2026 cjnoname
 * Released under the MIT License

package/dist/types/modules/xml/dom.d.ts

@@ -8,7 +8,7 @@
  * For large documents, prefer SAX-based streaming.
  * This is intended for small-to-medium XML where tree access is convenient.
  */
-import type { XmlDocument, XmlElement, XmlNode, XmlParseOptions } from "./types.js";
+import type { ToPlainObjectOptions, XmlDocument, XmlElement, XmlNode, XmlParseOptions } from "./types.js";
 /**
  * Parse an XML string into a DOM tree.
  *
@@ -49,4 +49,30 @@ declare function attr(element: XmlElement, name: string): string | undefined;
  * Walk all descendant elements depth-first, calling visitor for each.
  */
 declare function walk(element: XmlElement, visitor: (el: XmlElement) => void): void;
-export { parseXml, findChild, findChildren, textContent, attr, walk };
+/**
+ * Convert an {@link XmlElement} DOM tree to a plain JavaScript object.
+ *
+ * Produces output similar to fast-xml-parser: element names become object keys,
+ * attributes are prefixed (default `@_`), text-only elements collapse to their
+ * string value, and repeated sibling names merge into arrays.
+ *
+ * @param element - The element to convert.
+ * @param options - Conversion options.
+ * @returns A plain JavaScript object representing the element.
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<root attr="1"><child>text</child></root>');
+ * const obj = toPlainObject(doc.root);
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const doc = parseXml('<list><item>a</item><item>b</item></list>');
+ * const obj = toPlainObject(doc.root);
+ * // { list: { item: ["a", "b"] } }
+ * ```
+ */
+declare function toPlainObject(element: XmlElement, options?: ToPlainObjectOptions): Record<string, unknown>;
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject };

package/dist/types/modules/xml/index.d.ts

@@ -10,11 +10,12 @@
  * - Dual-mode: streaming (SAX parser + stream writer) and buffered (DOM parser + writer)
  * - Shared XmlSink interface lets rendering code target both modes transparently
  */
-export type { XmlAttributes, XmlNodeType, XmlElement, XmlText, XmlCData, XmlComment, XmlProcessingInstruction, XmlNode, XmlDocument, XmlSink, SaxTag, SaxEvent, SaxEventAny, SaxHandlers, SaxOptions, WritableTarget, XmlParseOptions } from "./types.js";
+export type { XmlAttributes, XmlNodeType, XmlElement, XmlText, XmlCData, XmlComment, XmlProcessingInstruction, XmlNode, XmlDocument, XmlSink, SaxTag, SaxEvent, SaxEventAny, SaxHandlers, SaxOptions, WritableTarget, XmlParseOptions, ToPlainObjectOptions, ParseXmlToObjectOptions } from "./types.js";
 export { xmlEncode, xmlDecode, xmlEncodeAttr, validateXmlName, encodeCData, validateCommentText } from "./encode.js";
 export { XmlWriter, StdDocAttributes } from "./writer.js";
 export { XmlStreamWriter } from "./stream-writer.js";
 export { SaxParser, parseSax, saxStream } from "./sax.js";
-export { parseXml, findChild, findChildren, textContent, attr, walk } from "./dom.js";
+export { parseXml, findChild, findChildren, textContent, attr, walk, toPlainObject } from "./dom.js";
+export { parseXmlToObject } from "./to-object.js";
 export { query, queryAll } from "./query.js";
 export { XmlError, XmlParseError, XmlWriteError, isXmlError, isXmlParseError } from "./errors.js";

package/dist/types/modules/xml/to-object-shared.d.ts

@@ -0,0 +1,29 @@
+/**
+ * XML → Plain Object — Shared Conversion Logic
+ *
+ * Internal module used by both `toPlainObject` (DOM path) and
+ * `parseXmlToObject` (SAX-direct path). Not part of the public API.
+ */
+import type { ToPlainObjectOptions } from "./types.js";
+/** Options with all defaults resolved — no more `??` checks at hot-path call sites. */
+export interface ResolvedOptions {
+    readonly attrPrefix: string;
+    readonly textKey: string;
+    readonly alwaysArray: boolean;
+    readonly preserveCData: boolean;
+    readonly ignoreWS: boolean;
+}
+export declare function resolveOptions(options?: ToPlainObjectOptions): ResolvedOptions;
+/**
+ * Determine the final plain-object value for an element given its parts.
+ *
+ * Returns either:
+ * - a string (text-only / empty element)
+ * - the `obj` record (element with attributes and/or children)
+ */
+export declare function resolveValue(obj: Record<string, unknown>, text: string, hasAttributes: boolean, hasChildren: boolean, opts: ResolvedOptions): unknown;
+/**
+ * Add a resolved child value into a parent object, merging repeated names
+ * into arrays.
+ */
+export declare function addChildValue(parent: Record<string, unknown>, name: string, value: unknown, alwaysArray: boolean): void;

package/dist/types/modules/xml/to-object.d.ts

@@ -0,0 +1,35 @@
+/**
+ * XML → Plain Object (SAX-direct)
+ *
+ * Parses an XML string directly into a plain JavaScript object, bypassing the
+ * DOM tree entirely. This is the fastest path for "XML string → plain object →
+ * JSON.stringify" workflows.
+ *
+ * For converting an already-parsed {@link XmlElement} tree, use
+ * {@link toPlainObject} from `./dom` instead.
+ */
+import type { ParseXmlToObjectOptions } from "./types.js";
+/**
+ * Parse an XML string directly into a plain JavaScript object.
+ *
+ * Unlike `parseXml` + `toPlainObject`, this function builds the plain object
+ * in a single SAX pass with **zero intermediate DOM nodes**. Use this when
+ * performance matters and you only need the plain-object output.
+ *
+ * The output format matches {@link toPlainObject}: attributes are prefixed
+ * (default `@_`), text-only elements collapse to strings, and repeated
+ * sibling names merge into arrays.
+ *
+ * @param xml - Complete XML string.
+ * @param options - Conversion and parser options.
+ * @returns A plain JavaScript object representing the root element.
+ * @throws {XmlParseError} If the XML is malformed.
+ *
+ * @example
+ * ```ts
+ * const obj = parseXmlToObject('<root attr="1"><child>text</child></root>');
+ * // { root: { "@_attr": "1", child: "text" } }
+ * ```
+ */
+declare function parseXmlToObject(xml: string, options?: ParseXmlToObjectOptions): Record<string, unknown>;
+export { parseXmlToObject };

package/dist/types/modules/xml/types.d.ts

@@ -198,6 +198,59 @@ export interface SaxOptions {
 export interface WritableTarget {
     write(chunk: string | Uint8Array): void;
 }
+/**
+ * Options for `toPlainObject()`.
+ *
+ * Controls how an {@link XmlElement} DOM tree is converted to a plain
+ * JavaScript object (similar to fast-xml-parser output format).
+ */
+export interface ToPlainObjectOptions {
+    /**
+     * Prefix for attribute keys.
+     * Set to `""` to use bare attribute names.
+     * @default "@_"
+     */
+    attributePrefix?: string;
+    /**
+     * Key used for text content when an element has both text and child elements
+     * (mixed content).
+     * @default "#text"
+     */
+    textKey?: string;
+    /**
+     * When true, always wrap child elements in arrays even if there is only one.
+     * When false (default), single children are stored as a plain value.
+     * @default false
+     */
+    alwaysArray?: boolean;
+    /**
+     * When true, include CDATA node values (already merged to text by default
+     * in `parseXml`, only relevant with `cdataAsNodes`).
+     * @default true
+     */
+    preserveCData?: boolean;
+    /**
+     * When true, discard whitespace-only text in elements that also have child
+     * elements (typical of pretty-printed XML indentation). Leaf elements that
+     * contain only whitespace text are **not** affected — their text is preserved.
+     * @default true
+     */
+    ignoreWhitespaceText?: boolean;
+}
+/**
+ * Options for `parseXmlToObject()`.
+ *
+ * Extends {@link ToPlainObjectOptions} with SAX parser settings, since
+ * `parseXmlToObject` handles both parsing and conversion in a single pass.
+ */
+export interface ParseXmlToObjectOptions extends ToPlainObjectOptions {
+    /** Parse as fragment (no root element required). Default: false */
+    fragment?: boolean;
+    /** Maximum element nesting depth. Default: 256. */
+    maxDepth?: number;
+    /** Maximum total entity expansions. Default: 10000. */
+    maxEntityExpansions?: number;
+}
 /** Options for `parseXml()`. */
 export interface XmlParseOptions {
     /** Include comments in the tree. Default: false */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.",
   "type": "module",
   "main": "./dist/cjs/index.js",