@office-open/xml 0.1.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@
 ![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, drop-in replacement for xml + xml-js.
 
 ## Features
 
@@ -13,7 +13,7 @@
 - **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, 16-33x faster than the xml→xml2js bridge
+- **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
 
@@ -103,31 +103,31 @@ Performance comparison against original `xml` (1.0.1) and `xml-js` (1.6.11) pack
 
 | Scenario                | @office-open/xml |        xml |   Speedup |
 | ----------------------- | ---------------: | ---------: | --------: |
-| Simple element          |     4,103,029 hz | 734,685 hz | **5.58x** |
-| Nested element          |       940,333 hz | 321,791 hz | **2.92x** |
-| Nested with declaration |       800,517 hz | 262,125 hz | **3.05x** |
+| Simple element          |     4,023,269 hz | 742,728 hz | **5.42x** |
+| Nested element          |     1,030,612 hz | 322,801 hz | **3.19x** |
+| Nested with declaration |       963,725 hz | 276,547 hz | **3.49x** |
 
 ### Parsing (xml2js)
 
 | Scenario           | @office-open/xml |    xml-js |    Speedup |
 | ------------------ | ---------------: | --------: | ---------: |
-| Simple XML         |     1,002,659 hz | 83,057 hz | **12.07x** |
-| Complex OOXML      |       357,081 hz | 48,687 hz |  **7.34x** |
-| With captureSpaces |       361,555 hz | 44,868 hz |  **8.06x** |
+| Simple XML         |     1,147,347 hz | 95,579 hz | **12.00x** |
+| Complex OOXML      |       401,553 hz | 52,327 hz |  **7.67x** |
+| With captureSpaces |       387,082 hz | 52,317 hz |  **7.40x** |
 
 ### Stringifying (js2xml)
 
 | Scenario       | @office-open/xml |     xml-js |   Speedup |
 | -------------- | ---------------: | ---------: | --------: |
-| Simple element |       780,070 hz | 161,521 hz | **4.83x** |
-| Complex OOXML  |       276,878 hz | 106,527 hz | **2.60x** |
+| Simple element |       778,368 hz | 197,520 hz | **3.94x** |
+| Complex OOXML  |       344,376 hz | 127,493 hz | **2.70x** |
 
 ### Direct Conversion (toElement vs bridge)
 
 | Scenario |   toElement() | xml() + xml2js() bridge |    Speedup |
 | -------- | ------------: | ----------------------: | ---------: |
-| Simple   | 14,119,071 hz |              853,290 hz | **16.55x** |
-| Nested   |  3,745,934 hz |              422,217 hz |  **8.87x** |
+| Simple   | 14,953,390 hz |              803,917 hz | **18.61x** |
+| Nested   |  4,530,626 hz |              466,126 hz |  **9.72x** |
 
 ## Bundle Size
 

package/dist/_chunks/utils-DlOOMr6B.d.mts

@@ -0,0 +1,175 @@
+//#region src/types.d.ts
+interface Attributes {
+  [key: string]: string | number | undefined;
+}
+interface DeclarationAttributes {
+  version?: string | number;
+  encoding?: string;
+  standalone?: string;
+}
+interface Element {
+  declaration?: {
+    attributes?: DeclarationAttributes;
+  };
+  instruction?: string;
+  attributes?: Attributes;
+  cdata?: string;
+  doctype?: string;
+  comment?: string;
+  text?: string | number | boolean;
+  type?: string;
+  name?: string;
+  elements?: Element[];
+  parent?: Element;
+}
+interface ElementCompact {
+  [key: string]: any;
+  _declaration?: {
+    _attributes?: DeclarationAttributes;
+  };
+  _instruction?: {
+    [key: string]: string;
+  };
+  _attributes?: Attributes;
+  _cdata?: string;
+  _doctype?: string;
+  _comment?: string;
+  _text?: string | number;
+}
+interface IgnoreOptions {
+  ignoreDeclaration?: boolean;
+  ignoreInstruction?: boolean;
+  ignoreAttributes?: boolean;
+  ignoreComment?: boolean;
+  ignoreCdata?: boolean;
+  ignoreDoctype?: boolean;
+  ignoreText?: boolean;
+}
+interface Xml2JsOptions extends IgnoreOptions {
+  compact?: boolean;
+  trim?: boolean;
+  sanitize?: boolean;
+  nativeType?: boolean;
+  nativeTypeAttributes?: boolean;
+  addParent?: boolean;
+  alwaysArray?: boolean | string[];
+  alwaysChildren?: boolean;
+  instructionHasAttributes?: boolean;
+  captureSpacesBetweenElements?: boolean;
+  doctypeFn?: (value: string, parentElement: object) => string;
+  instructionFn?: (value: string, instructionName: string, parentElement: string) => string;
+  cdataFn?: (value: string, parentElement: object) => string;
+  commentFn?: (value: string, parentElement: object) => string;
+  textFn?: (value: string, parentElement: object) => string;
+  instructionNameFn?: (instructionName: string, instructionValue: string, parentElement: string) => string;
+  elementNameFn?: (value: string, parentElement: object) => string;
+  attributeNameFn?: (attributeName: string, attributeValue: string, parentElement: string) => string;
+  attributeValueFn?: (attributeValue: string, attributeName: string, parentElement: string) => string;
+  attributesFn?: (value: Attributes, parentElement: string) => Attributes;
+}
+interface Js2XmlOptions extends IgnoreOptions {
+  spaces?: number | string;
+  compact?: boolean;
+  indentText?: boolean;
+  indentCdata?: boolean;
+  indentAttributes?: boolean;
+  indentInstruction?: boolean;
+  fullTagEmptyElement?: boolean;
+  noQuotesForNativeAttributes?: boolean;
+  doctypeFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
+  instructionFn?: (instructionValue: string, instructionName: string, currentElementName: string, currentElementObj: object) => string;
+  cdataFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
+  commentFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
+  textFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
+  instructionNameFn?: (instructionName: string, instructionValue: string, currentElementName: string, currentElementObj: object) => string;
+  elementNameFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
+  attributeNameFn?: (attributeName: string, attributeValue: string, currentElementName: string, currentElementObj: object) => string;
+  attributeValueFn?: (attributeValue: string, attributeName: string, currentElementName: string, currentElementObj: object) => string;
+  attributesFn?: (value: Attributes, currentElementName: string, currentElementObj: object) => Attributes;
+  fullTagEmptyElementFn?: (currentElementName: string, currentElementObj: object) => boolean;
+}
+interface XmlOption {
+  indent?: string;
+  stream?: boolean;
+  declaration?: boolean | {
+    encoding?: string;
+    standalone?: string;
+  };
+}
+interface XmlAttrs {
+  [attr: string]: XmlAtom;
+}
+type XmlAtom = string | number | boolean | null;
+interface ElementObject {
+  push(xmlObject: XmlObject): void;
+  close(xmlObject?: XmlObject): void;
+}
+type XmlDesc = {
+  _attr: XmlAttrs;
+} | {
+  _cdata: string;
+} | {
+  _attr: XmlAttrs;
+  _cdata: string;
+} | XmlAtom | XmlAtom[] | XmlDescArray;
+interface XmlDescArray {
+  [index: number]: {
+    _attr: XmlAttrs;
+  } | XmlObject;
+}
+type XmlObject = {
+  [tag: string]: ElementObject | XmlDesc;
+} | XmlDesc;
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Find the first direct child element with the given name.
+ */
+declare function findChild(parent: Element | undefined, name: string): Element | undefined;
+/**
+ * Get all direct child elements matching the given name.
+ */
+declare function children(parent: Element | undefined, name: string): Element[];
+/**
+ * Get all direct child elements.
+ */
+declare function allChildren(parent: Element | undefined): Element[];
+/**
+ * Get text content of the first child element with the given name.
+ */
+declare function childText(parent: Element | undefined, name: string): string;
+/**
+ * Get text content of an element.
+ * Handles cases where text may be directly on .text or in a child element.
+ */
+declare function textOf(element: Element | undefined): string;
+/**
+ * Collect text from all direct text nodes within an element.
+ */
+declare function collectText(element: Element | undefined): string;
+/**
+ * Get an attribute value as a string.
+ */
+declare function attr(element: Element | undefined, name: string): string | undefined;
+/**
+ * Get an attribute value as a number.
+ */
+declare function attrNum(element: Element | undefined, name: string): number | undefined;
+/**
+ * Get an attribute value as a boolean.
+ */
+declare function attrBool(element: Element | undefined, name: string): boolean | undefined;
+/**
+ * Check if an element has a specific child element.
+ */
+declare function hasChild(parent: Element | undefined, name: string): boolean;
+/**
+ * Find deep descendant elements matching the given name.
+ */
+declare function findDeep(parent: Element | undefined, name: string): Element[];
+/**
+ * Get the number of direct child elements.
+ */
+declare function childCount(parent: Element | undefined): number;
+//#endregion
+export { XmlDesc as C, XmlOption as E, XmlAttrs as S, XmlObject as T, ElementObject as _, childCount as a, Xml2JsOptions as b, collectText as c, hasChild as d, textOf as f, ElementCompact as g, Element as h, attrNum as i, findChild as l, DeclarationAttributes as m, attr as n, childText as o, Attributes as p, attrBool as r, children as s, allChildren as t, findDeep as u, IgnoreOptions as v, XmlDescArray as w, XmlAtom as x, Js2XmlOptions as y };

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { C as XmlDesc, E as XmlOption, S as XmlAttrs, T as XmlObject, _ as ElementObject, a as childCount, b as Xml2JsOptions, c as collectText, d as hasChild, f as textOf, g as ElementCompact, h as Element, i as attrNum, l as findChild, m as DeclarationAttributes, n as attr, o as childText, p as Attributes, r as attrBool, s as children, t as allChildren, u as findDeep, v as IgnoreOptions, w as XmlDescArray, x as XmlAtom, y as Js2XmlOptions } from "./_chunks/utils-DlOOMr6B.mjs";
+
 //#region src/serialize.d.ts
 declare function xml(input: Record<string, any> | Record<string, any>[], options?: boolean | string | {
   indent?: boolean | string;
@@ -7,129 +9,6 @@ declare function xml(input: Record<string, any> | Record<string, any>[], options
   };
 }): string;
 //#endregion
-//#region src/types.d.ts
-interface Attributes {
-  [key: string]: string | number | undefined;
-}
-interface DeclarationAttributes {
-  version?: string | number;
-  encoding?: string;
-  standalone?: string;
-}
-interface Element {
-  declaration?: {
-    attributes?: DeclarationAttributes;
-  };
-  instruction?: string;
-  attributes?: Attributes;
-  cdata?: string;
-  doctype?: string;
-  comment?: string;
-  text?: string | number | boolean;
-  type?: string;
-  name?: string;
-  elements?: Element[];
-  parent?: Element;
-}
-interface ElementCompact {
-  [key: string]: any;
-  _declaration?: {
-    _attributes?: DeclarationAttributes;
-  };
-  _instruction?: {
-    [key: string]: string;
-  };
-  _attributes?: Attributes;
-  _cdata?: string;
-  _doctype?: string;
-  _comment?: string;
-  _text?: string | number;
-}
-interface IgnoreOptions {
-  ignoreDeclaration?: boolean;
-  ignoreInstruction?: boolean;
-  ignoreAttributes?: boolean;
-  ignoreComment?: boolean;
-  ignoreCdata?: boolean;
-  ignoreDoctype?: boolean;
-  ignoreText?: boolean;
-}
-interface Xml2JsOptions extends IgnoreOptions {
-  compact?: boolean;
-  trim?: boolean;
-  sanitize?: boolean;
-  nativeType?: boolean;
-  nativeTypeAttributes?: boolean;
-  addParent?: boolean;
-  alwaysArray?: boolean | string[];
-  alwaysChildren?: boolean;
-  instructionHasAttributes?: boolean;
-  captureSpacesBetweenElements?: boolean;
-  doctypeFn?: (value: string, parentElement: object) => string;
-  instructionFn?: (value: string, instructionName: string, parentElement: string) => string;
-  cdataFn?: (value: string, parentElement: object) => string;
-  commentFn?: (value: string, parentElement: object) => string;
-  textFn?: (value: string, parentElement: object) => string;
-  instructionNameFn?: (instructionName: string, instructionValue: string, parentElement: string) => string;
-  elementNameFn?: (value: string, parentElement: object) => string;
-  attributeNameFn?: (attributeName: string, attributeValue: string, parentElement: string) => string;
-  attributeValueFn?: (attributeValue: string, attributeName: string, parentElement: string) => string;
-  attributesFn?: (value: Attributes, parentElement: string) => Attributes;
-}
-interface Js2XmlOptions extends IgnoreOptions {
-  spaces?: number | string;
-  compact?: boolean;
-  indentText?: boolean;
-  indentCdata?: boolean;
-  indentAttributes?: boolean;
-  indentInstruction?: boolean;
-  fullTagEmptyElement?: boolean;
-  noQuotesForNativeAttributes?: boolean;
-  doctypeFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
-  instructionFn?: (instructionValue: string, instructionName: string, currentElementName: string, currentElementObj: object) => string;
-  cdataFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
-  commentFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
-  textFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
-  instructionNameFn?: (instructionName: string, instructionValue: string, currentElementName: string, currentElementObj: object) => string;
-  elementNameFn?: (value: string, currentElementName: string, currentElementObj: object) => string;
-  attributeNameFn?: (attributeName: string, attributeValue: string, currentElementName: string, currentElementObj: object) => string;
-  attributeValueFn?: (attributeValue: string, attributeName: string, currentElementName: string, currentElementObj: object) => string;
-  attributesFn?: (value: Attributes, currentElementName: string, currentElementObj: object) => Attributes;
-  fullTagEmptyElementFn?: (currentElementName: string, currentElementObj: object) => boolean;
-}
-interface XmlOption {
-  indent?: string;
-  stream?: boolean;
-  declaration?: boolean | {
-    encoding?: string;
-    standalone?: string;
-  };
-}
-interface XmlAttrs {
-  [attr: string]: XmlAtom;
-}
-type XmlAtom = string | number | boolean | null;
-interface ElementObject {
-  push(xmlObject: XmlObject): void;
-  close(xmlObject?: XmlObject): void;
-}
-type XmlDesc = {
-  _attr: XmlAttrs;
-} | {
-  _cdata: string;
-} | {
-  _attr: XmlAttrs;
-  _cdata: string;
-} | XmlAtom | XmlAtom[] | XmlDescArray;
-interface XmlDescArray {
-  [index: number]: {
-    _attr: XmlAttrs;
-  } | XmlObject;
-}
-type XmlObject = {
-  [tag: string]: ElementObject | XmlDesc;
-} | XmlDesc;
-//#endregion
 //#region src/parse.d.ts
 declare function xml2js(xmlString: string, options?: Xml2JsOptions): Element;
 //#endregion
@@ -158,4 +37,4 @@ declare function escapeAttributeValue(str: string): string;
 /** Convert XML string to JSON string — xml-js compatible export */
 declare function xml2json(xml: string, options?: Xml2JsOptions): string;
 //#endregion
-export { Attributes, DeclarationAttributes, Element, ElementCompact, ElementObject, IgnoreOptions, Js2XmlOptions, Xml2JsOptions, XmlAtom, XmlAttrs, XmlDesc, XmlDescArray, XmlObject, XmlOption, escapeAttributeValue, escapeXml, js2xml, json2xml, toElement, xml, xml2js, xml2json };
+export { Attributes, DeclarationAttributes, Element, ElementCompact, ElementObject, IgnoreOptions, Js2XmlOptions, Xml2JsOptions, XmlAtom, XmlAttrs, XmlDesc, XmlDescArray, XmlObject, XmlOption, allChildren, attr, attrBool, attrNum, childCount, childText, children, collectText, escapeAttributeValue, escapeXml, findChild, findDeep, hasChild, js2xml, json2xml, textOf, toElement, xml, xml2js, xml2json };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { allChildren, attr, attrBool, attrNum, childCount, childText, children, collectText, findChild, findDeep, hasChild, textOf } from "./utils.mjs";
 //#region src/escape.ts
 const XML_CHAR_MAP = {
 	"&": "&",
@@ -499,4 +500,4 @@ function xml2json(xml, options) {
 	return JSON.stringify(xml2js(xml, options));
 }
 //#endregion
-export { escapeAttributeValue, escapeXml, js2xml, json2xml, toElement, xml, xml2js, xml2json };
+export { allChildren, attr, attrBool, attrNum, childCount, childText, children, collectText, escapeAttributeValue, escapeXml, findChild, findDeep, hasChild, js2xml, json2xml, textOf, toElement, xml, xml2js, xml2json };

package/dist/utils.d.mts

@@ -0,0 +1,2 @@
+import { a as childCount, c as collectText, d as hasChild, f as textOf, i as attrNum, l as findChild, n as attr, o as childText, r as attrBool, s as children, t as allChildren, u as findDeep } from "./_chunks/utils-DlOOMr6B.mjs";
+export { allChildren, attr, attrBool, attrNum, childCount, childText, children, collectText, findChild, findDeep, hasChild, textOf };

package/dist/utils.mjs

@@ -0,0 +1,102 @@
+//#region src/utils.ts
+/**
+* Find the first direct child element with the given name.
+*/
+function findChild(parent, name) {
+	return parent?.elements?.find((e) => e.name === name);
+}
+/**
+* Get all direct child elements matching the given name.
+*/
+function children(parent, name) {
+	return parent?.elements?.filter((e) => e.name === name) ?? [];
+}
+/**
+* Get all direct child elements.
+*/
+function allChildren(parent) {
+	return parent?.elements ?? [];
+}
+/**
+* Get text content of the first child element with the given name.
+*/
+function childText(parent, name) {
+	return textOf(findChild(parent, name));
+}
+/**
+* Get text content of an element.
+* Handles cases where text may be directly on .text or in a child element.
+*/
+function textOf(element) {
+	if (!element) return "";
+	if (element.text !== void 0 && typeof element.text === "string") return element.text;
+	if (element.elements && element.elements.length > 0) return element.elements.map((e) => typeof e.text === "string" ? e.text : "").join("");
+	return "";
+}
+/**
+* Collect text from all direct text nodes within an element.
+*/
+function collectText(element) {
+	if (!element) return "";
+	const parts = [];
+	collectTextRecursive(element, parts);
+	return parts.join("");
+}
+function collectTextRecursive(element, parts) {
+	if (!element) return;
+	if (element.text !== void 0 && typeof element.text === "string") parts.push(element.text);
+	if (element.elements) for (const child of element.elements) collectTextRecursive(child, parts);
+}
+/**
+* Get an attribute value as a string.
+*/
+function attr(element, name) {
+	const v = element?.attributes?.[name];
+	return v !== void 0 ? String(v) : void 0;
+}
+/**
+* Get an attribute value as a number.
+*/
+function attrNum(element, name) {
+	const v = element?.attributes?.[name];
+	if (v === void 0) return void 0;
+	const n = Number(v);
+	return isNaN(n) ? void 0 : n;
+}
+/**
+* Get an attribute value as a boolean.
+*/
+function attrBool(element, name) {
+	const v = element?.attributes?.[name];
+	if (v === void 0) return void 0;
+	if (typeof v === "boolean") return v;
+	const lower = String(v).toLowerCase();
+	if (lower === "true" || lower === "1") return true;
+	if (lower === "false" || lower === "0") return false;
+}
+/**
+* Check if an element has a specific child element.
+*/
+function hasChild(parent, name) {
+	return parent?.elements?.some((e) => e.name === name) ?? false;
+}
+/**
+* Find deep descendant elements matching the given name.
+*/
+function findDeep(parent, name) {
+	const result = [];
+	if (!parent) return result;
+	for (const child of parent.elements ?? []) {
+		if (child.name === name) result.push(child);
+		result.push(...findDeep(child, name));
+	}
+	return result;
+}
+/**
+* Get the number of direct child elements.
+*/
+function childCount(parent) {
+	return parent?.elements?.length ?? 0;
+}
+//#endregion
+export { allChildren, attr, attrBool, attrNum, childCount, childText, children, collectText, findChild, findDeep, hasChild, textOf };

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@office-open/xml",
-  "version": "0.1.0",
-  "description": "XML parsing and serialization, replacing xml + xml-js",
+  "version": "0.3.0",
+  "description": "XML parsing and serialization for Office Open XML. Zero dependencies, drop-in replacement for xml + xml-js.",
   "keywords": [
     "office-open",
     "ooxml",
     "parse",
     "serialize",
-    "xml"
+    "xml",
+    "zero-dependencies"
   ],
   "homepage": "https://github.com/DemoMacro/office-open#readme",
   "bugs": {
@@ -33,6 +34,10 @@
     ".": {
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.mts",
+      "import": "./dist/utils.mjs"
     }
   },
   "devDependencies": {