@office-open/xml 0.8.0 → 0.9.0

package/README.md

@@ -143,4 +143,4 @@ Performance comparison against original `xml` (1.0.1) and `xml-js` (1.6.11) pack
 
 ## License
 
-- [MIT](LICENSE) © [Demo Macro](https://imst.xyz/)
+- [MIT](LICENSE) © [Demo Macro](https://www.demomacro.com/)

package/dist/index.d.mts

@@ -1,6 +1,11 @@
 import { C as XmlAttrs, D as XmlOption, E as XmlObject, S as XmlAtom, T as XmlDescArray, _ as ElementCompact, a as childCount, b as Js2XmlOptions, c as collectText, d as findDeep, f as hasChild, g as Element, h as DeclarationAttributes, i as attrNum, l as colorAttr, m as Attributes, n as attr, o as childText, p as textOf, r as attrBool, s as children, t as allChildren, u as findChild, v as ElementObject, w as XmlDesc, x as Xml2JsOptions, y as IgnoreOptions } from "./utils-DJSm61Ws.mjs";
 
 //#region src/serialize.d.ts
+/**
+ * Serialize IXmlableObject to XML string.
+ * @deprecated Use `stringify` (Element → string) instead. This IXmlableObject path
+ * will be removed once the Descriptor migration is complete.
+ */
 declare function xml(input: Record<string, unknown> | Record<string, unknown>[], options?: boolean | string | {
   indent?: boolean | string;
   declaration?: boolean | {
@@ -12,12 +17,12 @@ declare function xml(input: Record<string, unknown> | Record<string, unknown>[],
 //#region src/parse.d.ts
 declare function unescapeXml(str: string): string;
 declare function nativeTypeValue(value: string): string | number | boolean;
-declare function xml2js(xmlString: string, options?: Xml2JsOptions): Element;
+declare function parse(xmlString: string, options?: Xml2JsOptions): Element;
 declare function parseAttributes(str: string): Record<string, string>;
 //#endregion
 //#region src/stringify.d.ts
-declare function js2xml(js: Element, options?: Js2XmlOptions): string;
-/** Alias for js2xml — xml-js compatible export */
+declare function stringify(js: Element, options?: Js2XmlOptions): string;
+/** @deprecated Use `stringify` instead. xml-js compatible alias. */
 declare function json2xml(json: Element, options?: Js2XmlOptions): string;
 //#endregion
 //#region src/convert.d.ts
@@ -45,9 +50,26 @@ declare function attrs(record: Record<string, string | number | boolean | undefi
  * `attrStr` is a pre-serialized attribute string (from `attrs()`) or undefined.
  */
 declare function selfCloseElement(tag: string, attrStr?: string): string;
+/**
+ * Build a complete XML element string from name, optional attributes, and string children.
+ *
+ * Replaces `new BuilderElement({...})` + `.toXml()` / `.serialize()` with a
+ * single function call returning a string — zero object allocation.
+ *
+ * @param name  Element tag name (e.g. `"a:srgbClr"`)
+ * @param attrRecord  Optional flat attribute map; `undefined` values are skipped
+ * @param children  Optional pre-serialized child XML strings
+ *
+ * @example
+ * ```ts
+ * element("a:solidFill", undefined, [element("a:srgbClr", { val: "FF0000" })])
+ * // => '<a:solidFill><a:srgbClr val="FF0000"/></a:solidFill>'
+ * ```
+ */
+declare function element(name: string, attrRecord?: Readonly<Record<string, string | number | boolean | undefined>>, children?: readonly string[]): string;
 //#endregion
 //#region src/json.d.ts
 /** Convert XML string to JSON string — xml-js compatible export */
 declare function xml2json(xml: string, options?: Xml2JsOptions): string;
 //#endregion
-export { type Attributes, type DeclarationAttributes, type Element, type ElementCompact, type ElementObject, type IgnoreOptions, type Js2XmlOptions, type Xml2JsOptions, type XmlAtom, type XmlAttrs, type XmlDesc, type XmlDescArray, type XmlObject, type XmlOption, allChildren, attr, attrBool, attrNum, attrs, childCount, childText, children, collectText, colorAttr, escapeXml, findChild, findDeep, hasChild, js2xml, json2xml, nativeTypeValue, parseAttributes, selfCloseElement, textOf, toElement, unescapeXml, xml, xml2js, xml2json };
+export { type Attributes, type DeclarationAttributes, type Element, type ElementCompact, type ElementObject, type IgnoreOptions, type Js2XmlOptions, type Xml2JsOptions, type XmlAtom, type XmlAttrs, type XmlDesc, type XmlDescArray, type XmlObject, type XmlOption, allChildren, attr, attrBool, attrNum, attrs, childCount, childText, children, collectText, colorAttr, element, escapeXml, findChild, findDeep, hasChild, stringify as js2xml, stringify, json2xml, nativeTypeValue, parse, parse as xml2js, parseAttributes, selfCloseElement, textOf, toElement, unescapeXml, xml, xml2json };

package/dist/index.mjs

@@ -41,13 +41,13 @@ function escapeXml(str) {
 * // => ' id="1" name="foo"'
 */
 function attrs(record) {
-	let s = "";
+	const parts = [];
 	const keys = Object.keys(record);
 	for (let i = 0; i < keys.length; i++) {
 		const v = record[keys[i]];
-		if (v !== void 0) s += ` ${keys[i]}="${typeof v === "string" ? escapeXml(v) : v}"`;
+		if (v !== void 0) parts.push(` ${keys[i]}="${typeof v === "string" ? escapeXml(v) : v}"`);
 	}
-	return s;
+	return parts.join("");
 }
 /**
 * Build a self-closing XML element: `<tag attrStr/>`.
@@ -56,9 +56,36 @@ function attrs(record) {
 function selfCloseElement(tag, attrStr) {
 	return attrStr ? `<${tag}${attrStr}/>` : `<${tag}/>`;
 }
+/**
+* Build a complete XML element string from name, optional attributes, and string children.
+*
+* Replaces `new BuilderElement({...})` + `.toXml()` / `.serialize()` with a
+* single function call returning a string — zero object allocation.
+*
+* @param name  Element tag name (e.g. `"a:srgbClr"`)
+* @param attrRecord  Optional flat attribute map; `undefined` values are skipped
+* @param children  Optional pre-serialized child XML strings
+*
+* @example
+* ```ts
+* element("a:solidFill", undefined, [element("a:srgbClr", { val: "FF0000" })])
+* // => '<a:solidFill><a:srgbClr val="FF0000"/></a:solidFill>'
+* ```
+*/
+function element(name, attrRecord, children) {
+	const attrStr = attrRecord ? attrs(attrRecord) : void 0;
+	if (!children || children.length === 0) return selfCloseElement(name, attrStr);
+	const body = children.join("");
+	return body.length === 0 ? selfCloseElement(name, attrStr) : `<${name}${attrStr ?? ""}>${body}</${name}>`;
+}
 //#endregion
 //#region src/serialize.ts
 const DEFAULT_INDENT = "    ";
+/**
+* Serialize IXmlableObject to XML string.
+* @deprecated Use `stringify` (Element → string) instead. This IXmlableObject path
+* will be removed once the Descriptor migration is complete.
+*/
 function xml(input, options) {
 	const opts = normalizeOptions$1(options);
 	const parts = [];
@@ -66,10 +93,10 @@ function xml(input, options) {
 		const declOpts = opts.declaration === true ? {} : opts.declaration;
 		const enc = declOpts.encoding || "UTF-8";
 		const sa = declOpts.standalone;
-		let decl = "<?xml version=\"1.0\" encoding=\"" + enc + "\"";
-		if (sa) decl += " standalone=\"" + sa + "\"";
-		decl += "?>";
-		parts.push(decl);
+		const declParts = [`<?xml version="1.0" encoding="${enc}"`];
+		if (sa) declParts.push(` standalone="${sa}"`);
+		declParts.push("?>");
+		parts.push(declParts.join(""));
 		if (opts.indent) parts.push("\n");
 	}
 	const items = Array.isArray(input) ? input : [input];
@@ -171,7 +198,7 @@ function nativeTypeValue(value) {
 	if (lower === "false") return false;
 	return value;
 }
-function xml2js(xmlString, options) {
+function parse(xmlString, options) {
 	const captureSpaces = options?.captureSpacesBetweenElements ?? false;
 	const trim = options?.trim ?? false;
 	const ignoreDeclaration = options?.ignoreDeclaration ?? false;
@@ -355,16 +382,16 @@ function isWhitespace(ch) {
 }
 //#endregion
 //#region src/stringify.ts
-function js2xml(js, options) {
+function stringify(js, options) {
 	const opts = normalizeOptions(options);
 	const parts = [];
 	if (js.declaration && !opts.ignoreDeclaration) parts.push(writeDeclaration(js.declaration));
 	if (js.elements?.length) parts.push(writeElements(js.elements, opts, 0, !parts.length));
 	return parts.join("");
 }
-/** Alias for js2xml — xml-js compatible export */
+/** @deprecated Use `stringify` instead. xml-js compatible alias. */
 function json2xml(json, options) {
-	return js2xml(json, options);
+	return stringify(json, options);
 }
 function normalizeOptions(options) {
 	if (!options) return {
@@ -399,10 +426,10 @@ function writeIndentation(spaces, depth, firstLine) {
 function writeDeclaration(declaration) {
 	const attrs = declaration.attributes;
 	if (!attrs) return "<?xml version=\"1.0\"?>";
-	let result = "<?xml version=\"1.0\"";
-	if (attrs.encoding) result += ` encoding="${attrs.encoding}"`;
-	if (attrs.standalone) result += ` standalone="${attrs.standalone}"`;
-	return result + "?>";
+	const parts = [`<?xml version="1.0"`];
+	if (attrs.encoding) parts.push(` encoding="${attrs.encoding}"`);
+	if (attrs.standalone) parts.push(` standalone="${attrs.standalone}"`);
+	return parts.join("") + "?>";
 }
 function writeAttributes(attributes, elementName, element, attributeValueFn) {
 	const parts = [];
@@ -550,7 +577,7 @@ function toElement(xmlObject) {
 //#region src/json.ts
 /** Convert XML string to JSON string — xml-js compatible export */
 function xml2json(xml, options) {
-	return JSON.stringify(xml2js(xml, options));
+	return JSON.stringify(parse(xml, options));
 }
 //#endregion
-export { allChildren, attr, attrBool, attrNum, attrs, childCount, childText, children, collectText, colorAttr, escapeXml, findChild, findDeep, hasChild, js2xml, json2xml, nativeTypeValue, parseAttributes, selfCloseElement, textOf, toElement, unescapeXml, xml, xml2js, xml2json };
+export { allChildren, attr, attrBool, attrNum, attrs, childCount, childText, children, collectText, colorAttr, element, escapeXml, findChild, findDeep, hasChild, stringify as js2xml, stringify, json2xml, nativeTypeValue, parse, parse as xml2js, parseAttributes, selfCloseElement, textOf, toElement, unescapeXml, xml, xml2json };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@office-open/xml",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "XML parsing and serialization for Office Open XML. Zero dependencies, drop-in replacement for xml + xml-js.",
   "keywords": [
     "office-open",
@@ -18,7 +18,7 @@
   "author": {
     "name": "Demo Macro",
     "email": "abc@imst.xyz",
-    "url": "https://imst.xyz/"
+    "url": "https://www.demomacro.com/"
   },
   "repository": {
     "type": "git",