@ooxml-tools/xml 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+<h1>
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://ooxml-tools.github.io/design/images/xml-dark.png">
+        <source media="(prefers-color-scheme: light)" srcset="https://ooxml-tools.github.io/design/images/xml-light.png">
+        <img alt="@ooxml-tools/xml" height="56" src="https://ooxml-tools.github.io/design/images/xml-light.png">
+    </picture>
+</h1>
+
+Some XML helpers to help with OOXML development
+
+> [!NOTE]
+> These are all based around [`xml-js`](https://www.npmjs.com/package/xml-js) and output that modules internal format
+
+
+## API
+
+### `asXmlElement`
+When working with `xml-js` it's really handy to not have to worry about when you're passing an XML string our the `xml-js` JSON type called `Element`
+
+This helper function just outputs an `Element` for either input
+
+```ts
+asXmlElement("<name>foo</name>") // => {name: "name", text: "foo"}
+asXmlElement({name: "name", text: "foo"}) // => {name: "name", text: "foo"}
+```
+
+> [!NOTE]
+> All the other functions in this document that accept XML, also accept this `Element` (using this function) 
+
+### `safeXml`
+An XML tagged template literal with the following features
+
+ - error if XML is incorrect
+ - array support in substitution
+
+The following will error in development, because of mismatched start/end tags 
+ 
+```ts
+safeXml`<foo>hello</bar>`
+```
+
+Substitution of arrays "just works" so you can map values in the tagged template literals  
+ 
+```ts
+const outXml = safeXml`<test>${[1,2,3].map(n => safeXml`<name>item ${1}<name>`)}</test>`
+assert.equal(outXml, `<test><name>item 1</name><name>item 2</name><name>item 3</name></test>`);
+```
+
+This also makes it easy to support <https://prettier.io/docs/en/options#embedded-language-formatting>
+
+### `compact`
+Removes non required whitespace from the XML
+
+```ts
+const outXml = compact(`
+    <test>
+        something
+    </test>
+`);
+assert.equal(outXml, "<test>something</test>");
+```
+
+### `removeFragments`
+For XML to be valid, there must be a single root node. When composing apps it's handy for that not to be true.
+
+For example the following would error
+
+```ts
+const xml = safeXml`
+    <name>foo</name>
+    <name>bar</name>
+`
+```
+
+So instead we'd like something like a HTML fragment
+
+```ts
+const xml = safeXml`
+    <XML_FRAGMENT>
+        <name>foo</name>
+        <name>bar</name>
+    </XML_FRAGMENT>
+`
+```
+
+So we did just that, `removeFragments` walks over a tree removing `<XML_FRAGMENT>...</XML_FRAGMENT>` nodes.
+
+```ts
+const innerBit = safeXml`
+    <XML_FRAGMENT>
+        <name>foo</name>
+        <name>bar</name>
+    </XML_FRAGMENT>
+`
+const newXml = removeFragments(
+    safeXml`
+        <doc>
+            ${innerBit}
+        </doc>
+    `
+)
+assert.equal(newXml, `
+    <doc>
+        <name>foo</name>
+        <name>bar</name>
+    </doc>
+`)
+```
+
+### `cdata`
+From [the wikipedia page](https://en.wikipedia.org/wiki/CDATA)
+
+> CDATA section is a piece of element content that is marked up to be interpreted literally, as textual data, not as marked-up content.
+
+But `<name><![CDATA[one < two]]><name>` is ugly and hard to read, so instead
+
+```ts
+safeXml`<name>${cdata("one < two")}</name>`
+```
+
+## License
+
+MIT

package/dist/npm/index.js

@@ -0,0 +1,101 @@
+import { xml2js, js2xml } from 'xml-js';
+
+function asXmlElement(xml) {
+    if (typeof xml === "string") {
+        return xml2js(xml, {
+            compact: false,
+            captureSpacesBetweenElements: false,
+        });
+    }
+    else {
+        return xml;
+    }
+}
+
+/**
+ * @param templateStrings template strings
+ * @param templateValues tamplate values
+ * @returns xml string
+ */
+function safeXml(templateStrings, ...templateValues) {
+    let xml = "";
+    for (let i = 0; i < templateStrings.length; i++) {
+        if (templateValues[i] !== undefined) {
+            const value = templateValues[i];
+            const xmlPart = Array.isArray(value) ? value.join("") : value;
+            xml += `${templateStrings[i]}${xmlPart}`;
+        }
+        else {
+            xml += `${templateStrings[i]}`;
+        }
+    }
+    if (process.env.NODE_ENV === "development") {
+        // This will "throw" if the XML is invalid
+        xml2js(xml, {
+            compact: false,
+            captureSpacesBetweenElements: false,
+        });
+    }
+    return xml;
+}
+
+function cdata(input) {
+    return `<![CDATA[${input}]]>`;
+}
+
+function compact(xml) {
+    const parsed = xml2js(xml, {
+        compact: false,
+        trim: true,
+    });
+    return js2xml(parsed);
+}
+
+function createFragment(elements) {
+    return {
+        type: "element",
+        name: "XML_FRAGMENT",
+        elements: elements,
+    };
+}
+function _collapseFragments(orig) {
+    var _a;
+    let node = orig;
+    const cloneIfRequired = () => {
+        if (node === orig) {
+            return Object.assign(Object.assign({}, node), { elements: node.elements ? [...node.elements] : undefined });
+        }
+        return node;
+    };
+    if (node.elements) {
+        for (let i = node.elements.length - 1; i >= 0; i--) {
+            if (node.elements) {
+                const child = node.elements[i];
+                const out = _collapseFragments(child);
+                if (Array.isArray(out)) {
+                    node = cloneIfRequired();
+                    node.elements.splice(i, 1, ...out);
+                }
+                else if (out !== child) {
+                    node = cloneIfRequired();
+                    if (node.elements) {
+                        node.elements[i] = out;
+                    }
+                }
+            }
+        }
+    }
+    if (node.name === "XML_FRAGMENT") {
+        return (_a = node.elements) !== null && _a !== void 0 ? _a : [];
+    }
+    return node;
+}
+function collapseFragments(root) {
+    const out = _collapseFragments(asXmlElement(root));
+    if (Array.isArray(out)) {
+        return createFragment(out);
+    }
+    return out;
+}
+
+export { asXmlElement, cdata, collapseFragments, compact, createFragment, safeXml };

package/dist/npm/types.d.ts

@@ -0,0 +1,19 @@
+import { Element } from 'xml-js';
+
+declare function asXmlElement(xml: string | Element): Element;
+
+/**
+ * @param templateStrings template strings
+ * @param templateValues tamplate values
+ * @returns xml string
+ */
+declare function safeXml(templateStrings: TemplateStringsArray, ...templateValues: (string | number | (string | number)[])[]): string;
+
+declare function cdata(input: string | number): string;
+
+declare function compact(xml: string): string;
+
+declare function createFragment(elements: Element[]): Element;
+declare function collapseFragments(root: string | Element): Element;
+
+export { asXmlElement, cdata, collapseFragments, compact, createFragment, safeXml };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ooxml-tools/xml",
+  "description": "Some XML helpers to help with OOXML development",
+  "version": "0.1.0",
+  "license": "MIT",
+  "main": "./dist/npm/index.js",
+  "types": "./dist/npm/types.d.ts",
+  "type": "module",
+  "scripts": {
+    "lint": "npx prettier . --check",
+    "test": "vitest",
+    "lint:format": "npx prettier . --write",
+    "build": "rollup -c rollup.config.ts --configPlugin typescript"
+  },
+  "exports": {
+    ".": "./dist/npm/index.js",
+    "./commands": "./dist/npm/commands.js"
+  },
+  "files": [
+    "./dist/npm",
+    "./package.json",
+    "./README.md"
+  ],
+  "devDependencies": {
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@rollup/plugin-virtual": "^3.0.2",
+    "@tsconfig/node22": "^22.0.0",
+    "@types/yargs": "^17.0.32",
+    "prettier": "^3.4.2",
+    "rollup": "^4.18.1",
+    "rollup-plugin-copy": "^3.5.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "rollup-plugin-preserve-shebang": "^1.0.1",
+    "rollup-plugin-typescript-paths": "^1.5.0",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.6.3",
+    "tsx": "^4.17.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.6"
+  },
+  "engines": {
+    "node": ">=20.x"
+  },
+  "dependencies": {
+    "xml-js": "^1.6.11"
+  }
+}