@office-open/xml 0.10.15 → 0.12.0

package/README.md

@@ -5,17 +5,15 @@
 ![npm license](https://img.shields.io/npm/l/@office-open/xml)
 ![zero dependencies](https://img.shields.io/badge/dependencies-0-green)
 
-> XML parsing and serialization for Office Open XML. Zero dependencies, drop-in replacement for xml + xml-js.
+> XML parsing and serialization for Office Open XML. Zero dependencies, pure TypeScript.
 
 ## Features
 
 - **Zero Dependencies** - No external runtime dependencies, pure TypeScript implementation
-- **xml() Serialization** - Drop-in replacement for the `xml` package
-- **xml2js() Parsing** - Drop-in replacement for `xml-js` XML parsing
-- **js2xml() Stringifying** - Drop-in replacement for `xml-js` JS-to-XML conversion
-- **toElement() Direct Convert** - Direct conversion from xml object format to xml-js Element, 10-19x faster than the xml→xml2js bridge
-- **Complete Type Definitions** - Full type compatibility with `xml` and `xml-js`, import without changes
-- **OOXML Optimized** - Implements all options needed for Office Open XML document generation
+- **parse() / stringify()** - XML string ↔ Element tree, OOXML-optimized
+- **Element Type** - Tolerant element model for round-tripping Office Open XML parts
+- **escapeXml() / unescapeXml()** - Low-level XML entity escaping
+- **OOXML Optimized** - Implements the options needed for Office Open XML document generation and parsing
 
 ## Installation
 
@@ -33,113 +31,72 @@ yarn add @office-open/xml
 bun add @office-open/xml
 ```
 
-## Migration from xml + xml-js
-
-Replace your existing imports:
-
-```typescript
-// Before
-import xml from "xml";
-import { xml2js, js2xml } from "xml-js";
-import type { Element } from "xml-js";
-
-// After
-import { xml, xml2js, js2xml } from "@office-open/xml";
-import type { Element } from "@office-open/xml";
-```
-
-No other code changes needed. All options and output formats are compatible.
-
 ## Quick Start
 
 ```typescript
-import { xml, xml2js, js2xml, toElement } from "@office-open/xml";
-
-// Serialize JS objects to XML
-const xmlStr = xml({ "w:p": [{ _attr: { "w:val": "1" } }, { "w:r": [{ "w:t": "Hello" }] }] });
-// <w:p w:val="1"><w:r><w:t>Hello</w:t></w:r></w:p>
-
-// Parse XML to JS objects
-const parsed = xml2js("<w:t>Hello</w:t>", { compact: false });
+import { parse, stringify } from "@office-open/xml";
 
-// Convert JS objects back to XML
-const output = js2xml(parsed);
+// Parse XML to an Element tree
+const doc = parse("<w:t>Hello</w:t>");
 
-// Direct conversion (faster than xml → xml2js bridge)
-const element = toElement({
-  "w:p": [{ _attr: { "w:val": "1" } }, { "w:r": [{ "w:t": "Hello" }] }],
-});
+// Serialize an Element tree back to XML
+const xml = stringify(doc);
 ```
 
 ## API
 
-### xml(input, options?)
-
-Serialize JavaScript objects to XML string. Compatible with the `xml` package.
-
-### xml2js(xmlString, options?)
+### parse(xmlString, options?)
 
-Parse XML string to JavaScript object. Compatible with `xml-js`.
+Parse an XML string into an `Element` tree. Options include `compact`, `trim`, `nativeType`, `captureSpacesBetweenElements`, the `ignore*` flags, and the `*Fn` transformation hooks.
 
-### js2xml(jsObject, options?)
+### stringify(element, options?)
 
-Convert JavaScript object (xml-js Element format) to XML string. Compatible with `xml-js`.
+Serialize an `Element` tree to an XML string. Options include `spaces` (indentation), the `ignore*` flags, and the `*Fn` hooks.
 
-### json2xml(jsObject, options?)
+### escapeXml(str) / unescapeXml(str)
 
-Alias for `js2xml`.
+Low-level XML entity escaping and unescaping.
 
-### xml2json(xmlString, options?)
+### Element
 
-Convenience function that returns `JSON.stringify(xml2js(xmlString, options))`.
+The tolerant element type used across all office-open packages:
 
-### toElement(input)
-
-Direct conversion from xml object format to xml-js Element format. Much faster than the `xml() → xml2js()` bridge path.
-
-### escapeXml(str) / escapeAttributeValue(str)
-
-Low-level XML entity escaping functions.
+```typescript
+interface Element {
+  declaration?: { attributes?: DeclarationAttributes };
+  attributes?: Attributes;
+  type?: string;
+  name?: string;
+  text?: string | number | boolean;
+  cdata?: string;
+  comment?: string;
+  elements?: Element[];
+}
+```
 
 ## Benchmark
 
-Performance comparison against original `xml` (1.0.1) and `xml-js` (1.6.11) packages:
-
-### Serialization (xml)
-
-| Scenario                | @office-open/xml |        xml |   Speedup |
-| ----------------------- | ---------------: | ---------: | --------: |
-| Simple element          |     5,440,771 hz | 805,545 hz | **6.75x** |
-| Nested element          |     1,050,272 hz | 315,184 hz | **3.33x** |
-| Nested with declaration |       967,945 hz | 275,684 hz | **3.51x** |
-
-### Parsing (xml2js)
-
-| Scenario           | @office-open/xml |     xml-js |   Speedup |
-| ------------------ | ---------------: | ---------: | --------: |
-| Simple XML         |       869,965 hz | 100,507 hz | **8.66x** |
-| Complex OOXML      |       346,440 hz |  53,621 hz | **6.46x** |
-| With captureSpaces |       344,586 hz |  52,414 hz | **6.57x** |
-
-### Stringifying (js2xml)
+Performance vs [txml](https://github.com/TobiasNickel/tXml), [xml-js](https://github.com/nashwaan/xml-js), and [xml](https://github.com/dylang/node-xml) (higher ops/s is better, Windows 11; each scenario runs under both Node 24 and Bun 1.4). `@office-open/xml` is a drop-in replacement for xml-js and xml. The `xml` (npm) package is generation-only (no parser), so it only appears under stringify. `Bun.XML` is Bun-only and its compact parse mode is lossy (`#text` runs concatenate, same-name children collapse into keyed arrays), so it is a throughput reference rather than a drop-in option.
 
-| Scenario       | @office-open/xml |     xml-js |   Speedup |
-| -------------- | ---------------: | ---------: | --------: |
-| Simple element |       793,710 hz | 207,730 hz | **3.82x** |
-| Complex OOXML  |       366,515 hz | 135,815 hz | **2.70x** |
+txml skips entity encoding by default (`encodeEntities: false`), which emits invalid XML when text contains `&`, `<`, or `>`; the `txml` column shows that raw mode and the `txml (entities)` column is the output-equivalent mode.
 
-### Direct Conversion (toElement vs bridge)
+**parse() — XML string → Element tree**
 
-| Scenario |   toElement() | xml() + xml2js() bridge |    Speedup |
-| -------- | ------------: | ----------------------: | ---------: |
-| Simple   | 15,471,913 hz |            1,073,016 hz | **14.42x** |
-| Nested   |  4,278,499 hz |              441,468 hz |  **9.69x** |
+| Scenario      | Runtime | @office-open/xml | txml          | xml-js        | Bun.XML.parse |
+| ------------- | ------- | ---------------- | ------------- | ------------- | ------------- |
+| simple XML    | Node 24 | 1,301,742 ops/s  | 983,046 ops/s | 93,951 ops/s  | —             |
+|               | Bun 1.4 | 1,906,525 ops/s  | 616,562 ops/s | 161,894 ops/s | 828,554 ops/s |
+| complex OOXML | Node 24 | 423,536 ops/s    | 388,743 ops/s | 49,771 ops/s  | —             |
+|               | Bun 1.4 | 483,512 ops/s    | 241,036 ops/s | 63,029 ops/s  | 451,177 ops/s |
 
-## Bundle Size
+**stringify() — Element tree → XML string**
 
-|      | @office-open/xml | xml + xml-js |
-| ---- | ---------------: | -----------: |
-| gzip |      **4.22 kB** |       ~15 kB |
+| Scenario       | Runtime | @office-open/xml | txml (entities) | txml            | xml-js        | xml (npm)     | Bun.XML.stringify |
+| -------------- | ------- | ---------------- | --------------- | --------------- | ------------- | ------------- | ----------------- |
+| simple element | Node 24 | 2,049,617 ops/s  | 1,255,456 ops/s | 2,765,770 ops/s | 190,783 ops/s | 303,724 ops/s | —                 |
+|                | Bun 1.4 | 2,588,728 ops/s  | 1,721,498 ops/s | 4,248,377 ops/s | 438,430 ops/s | 483,526 ops/s | 584,746 ops/s     |
+| complex OOXML  | Node 24 | 583,811 ops/s    | 447,274 ops/s   | 1,326,397 ops/s | 130,335 ops/s | 172,258 ops/s | —                 |
+|                | Bun 1.4 | 510,448 ops/s    | 528,375 ops/s   | 2,303,173 ops/s | 226,645 ops/s | 292,534 ops/s | 251,444 ops/s     |
 
 ## License
 

package/dist/index.d.mts

@@ -1,26 +1,15 @@
-import { A as XmlObject, C as IgnoreOptions, D as XmlAttrs, E as XmlAtom, O as XmlDesc, S as ElementObject, T as Xml2JsOptions, _ as textOf, a as attrMeasure, b as Element, c as childText, d as colorAttr, f as findChild, g as isNonEmpty, h as hasChild, i as attrBool, j as XmlOption, k as XmlDescArray, l as children, m as findFirst, n as allChildren, o as attrNum, p as findDeep, r as attr, s as childCount, t as NonEmptyArray, u as collectText, v as Attributes, w as Js2XmlOptions, x as ElementCompact, y as DeclarationAttributes } from "./utils-BFKTfRa8.mjs";
-
-//#region src/serialize.d.ts
-declare function xml(input: Record<string, unknown> | Record<string, unknown>[], options?: boolean | string | {
-  indent?: boolean | string;
-  declaration?: boolean | {
-    encoding?: string;
-    standalone?: string;
-  };
-}): string;
-//#endregion
+import { C as IgnoreOptions, S as ElementCompact, T as StringifyOptions, _ as isNonEmpty, a as attrBool, b as DeclarationAttributes, c as childCount, d as collectText, f as colorAttr, g as hasChild, h as findFirst, i as attr, l as childText, m as findDeep, n as OOXML_XML_DECLARATION, o as attrMeasure, p as findChild, r as allChildren, s as attrNum, t as NonEmptyArray, u as children, v as textOf, w as ParseOptions, x as Element, y as Attributes } from "./utils-qhk6IlD8.mjs";
 //#region src/parse.d.ts
 declare function unescapeXml(str: string): string;
 declare function nativeTypeValue(value: string): string | number | boolean;
-declare function parse(xmlString: string, options?: Xml2JsOptions): Element;
+declare function parse(xmlString: string, options?: ParseOptions): Element;
 declare function parseAttributes(str: string): Record<string, string>;
 //#endregion
 //#region src/stringify.d.ts
-declare function stringify(js: Element, options?: Js2XmlOptions): string;
-declare function json2xml(json: Element, options?: Js2XmlOptions): string;
+declare function stringify(js: Element, options?: StringifyOptions): string;
 //#endregion
-//#region src/convert.d.ts
-declare function toElement(xmlObject: Record<string, unknown>): Element;
+//#region src/stringify-element.d.ts
+declare function stringifyElement(el: Element): string;
 //#endregion
 //#region src/escape.d.ts
 declare function escapeXml(str: string): string;
@@ -29,8 +18,5 @@ declare function attrsRaw(record: Record<string, string | number | boolean | und
 declare function selfCloseElement(tag: string, attrStr?: string): string;
 declare function element(name: string, attrRecord?: Readonly<Record<string, string | number | boolean | undefined>>, children?: readonly string[]): string;
 //#endregion
-//#region src/json.d.ts
-declare function xml2json(xml: string, options?: Xml2JsOptions): string;
-//#endregion
-export { type Attributes, type DeclarationAttributes, type Element, type ElementCompact, type ElementObject, type IgnoreOptions, type Js2XmlOptions, NonEmptyArray, type Xml2JsOptions, type XmlAtom, type XmlAttrs, type XmlDesc, type XmlDescArray, type XmlObject, type XmlOption, allChildren, attr, attrBool, attrMeasure, attrNum, attrs, attrsRaw, childCount, childText, children, collectText, colorAttr, element, escapeXml, findChild, findDeep, findFirst, hasChild, isNonEmpty, stringify as js2xml, stringify, json2xml, nativeTypeValue, parse, parse as xml2js, parseAttributes, selfCloseElement, textOf, toElement, unescapeXml, xml, xml2json };
+export { type Attributes, type DeclarationAttributes, type Element, type ElementCompact, type IgnoreOptions, NonEmptyArray, OOXML_XML_DECLARATION, type ParseOptions, type StringifyOptions, allChildren, attr, attrBool, attrMeasure, attrNum, attrs, attrsRaw, childCount, childText, children, collectText, colorAttr, element, escapeXml, findChild, findDeep, findFirst, hasChild, isNonEmpty, nativeTypeValue, parse, parseAttributes, selfCloseElement, stringify, stringifyElement, textOf, unescapeXml };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/serialize.ts","../src/parse.ts","../src/stringify.ts","../src/convert.ts","../src/escape.ts","../src/json.ts"],"mappings":";;;iBASgB,GAAA,CACd,KAAA,EAAO,MAAA,oBAA0B,MAAM,qBACvC,OAAA;EAIM,MAAA;EACA,WAAA;IAA0B,QAAA;IAAmB,UAAA;EAAA;AAAA;;;iBCHrC,WAAA,CAAY,GAAW;AAAA,iBAWvB,eAAA,CAAgB,KAAa;AAAA,iBAa7B,KAAA,CAAM,SAAA,UAAmB,OAAA,GAAU,aAAA,GAAgB,OAAO;AAAA,iBAmN1D,eAAA,CAAgB,GAAA,WAAc,MAAM;;;iBCrPpC,SAAA,CAAU,EAAA,EAAI,OAAA,EAAS,OAAA,GAAU,aAAa;AAAA,iBAmB9C,QAAA,CAAS,IAAA,EAAM,OAAA,EAAS,OAAA,GAAU,aAAa;;;iBChB/C,SAAA,CAAU,SAAA,EAAW,MAAA,oBAA0B,OAAO;;;iBCLtD,SAAA,CAAU,GAAW;AAAA,iBA6CrB,KAAA,CAAM,MAA6D,EAArD,MAAM;AAAA,iBAqBpB,QAAA,CAAS,MAA6D,EAArD,MAAM;AAAA,iBAevB,gBAAA,CAAiB,GAAA,UAAa,OAAgB;AAAA,iBAoB9C,OAAA,CACd,IAAA,UACA,UAAA,GAAa,QAAQ,CAAC,MAAA,kDACtB,QAAA;;;iBCrGc,QAAA,CAAS,GAAA,UAAa,OAAA,GAAU,aAAa"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/parse.ts","../src/stringify.ts","../src/stringify-element.ts","../src/escape.ts"],"mappings":";;iBAagB,YAAY;iBAgBZ,gBAAgB;iBA4ChB,MAAM,mBAAmB,UAAU,eAAe;iBAwXlD,gBAAgB,cAAc;;;iBC1b9B,UAAU,IAAI,SAAS,UAAU;;;iBCIjC,iBAAiB,IAAI;;;iBCPrB,UAAU;iBA6BV,MAAM,QAAQ;iBAsBd,SAAS,QAAQ;iBAejB,iBAAiB,aAAa;iBAoB9B,QACd,cACA,aAAa,SAAS,wDACtB"}