@ooxml-tools/xml 0.2.1 → 0.2.2

package/README.md

@@ -11,45 +11,50 @@ 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"}
+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) 
+> 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
+- error if XML is incorrect
+- array support in substitution
+
+The following will error in development, because of mismatched start/end tags
 
-The following will error in development, because of mismatched start/end tags 
- 
 ```ts
-safeXml`<foo>hello</bar>`
+safeXml`<foo>hello</bar>`;
 ```
 
-Substitution of arrays "just works" so you can map values in the tagged template literals  
- 
+Substitution of arrays "just works" so you can map values in the tagged template literals
+
 ```ts
-const items = [1,2,3].map(n => safeXml`<name>item ${1}</name>`);
-const outXml = safeXml`<test>${items}</test>`
-assert.equal(outXml, `<test><name>item 1</name><name>item 2</name><name>item 3</name></test>`);
+const items = [1, 2, 3].map((n) => safeXml`<name>item ${1}</name>`);
+const outXml = safeXml`<test>${items}</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
@@ -62,6 +67,7 @@ assert.equal(outXml, "<test>something</test>");
 ```
 
 ### `collapseFragments`
+
 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
@@ -70,7 +76,7 @@ For example the following would error
 const xml = safeXml`
     <name>foo</name>
     <name>bar</name>
-`
+`;
 ```
 
 So instead we'd like something like a HTML fragment
@@ -81,7 +87,7 @@ const xml = safeXml`
         <name>foo</name>
         <name>bar</name>
     </XML_FRAGMENT>
-`
+`;
 ```
 
 So we did just that, `collapseFragments` walks over a tree removing `<XML_FRAGMENT>...</XML_FRAGMENT>` nodes.
@@ -92,23 +98,27 @@ const innerBit = safeXml`
         <name>foo</name>
         <name>bar</name>
     </XML_FRAGMENT>
-`
+`;
 const newXml = collapseFragments(
-    safeXml`
+  safeXml`
         <doc>
             ${innerBit}
         </doc>
-    `
-)
-assert.equal(newXml, `
+    `,
+);
+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.
@@ -116,28 +126,85 @@ From [the wikipedia page](https://en.wikipedia.org/wiki/CDATA)
 But `<name><![CDATA[one < two]]><name>` is ugly and hard to read, so instead
 
 ```ts
-safeXml`<name>${cdata("one < two")}</name>`
+safeXml`<name>${cdata("one < two")}</name>`;
 ```
 
 ### `format`
+
 Format XML in a consistent way, useful for logging and snapshot testing
 
 ```ts
 format(`
    <test> one
       </test>
-`) /* =>
+`); /* =>
  * <test>
  *   one
  * </test>
  */
 ```
 
+## `getAllByTestId`
+
+```ts
+const element = getAllByTestId(`
+    <root>
+        <name _testid="test">
+            Hello
+        </name>
+    </test>
+`)
+```
+
+## `getByTestId`
+
+```ts
+const element = getByTestId(`
+    <root>
+        <name _testid="test">
+            Hello
+        </name>
+    </test>
+`)
+```
+
+## `getSingleTextNode`
+Returns a single text node if one exists
+
+```ts
+getSingleTextNode(`<test>hello world</test>`) // => {type: "text", text: "hello world"}
+```
+
+Else throws an error
+
+```ts
+getSingleTextNode(`<test>hello <foo>inner node</foo> world</test>`) // => throws Error
+```
+
+## `removeTestIds`
+
+```ts
+const element = removeTestIds(`
+    <root>
+        <name _testid="test">
+            Hello
+        </name>
+    </test>
+`) /* =>
+ * <root>
+ *     <name>
+ *         Hello
+ *     </name>
+ * </test>
+ */
+```
+
+
+
 ## CI
 
 [![codecov](https://codecov.io/gh/ooxml-tools/xml/graph/badge.svg?token=N82AKMVJM7)](https://codecov.io/gh/ooxml-tools/xml)
 
-
 ## License
 
 MIT

package/dist/npm/index.js

@@ -51,13 +51,6 @@ function compact(xml) {
     return js2xml(parsed);
 }
 
-function createFragment(elements) {
-    return {
-        type: "element",
-        name: "XML_FRAGMENT",
-        elements: elements,
-    };
-}
 function _collapseFragments(orig) {
     var _a;
     let node = orig;
@@ -92,9 +85,6 @@ function _collapseFragments(orig) {
 }
 function collapseFragments(root) {
     const out = _collapseFragments(asXmlElement(root));
-    if (Array.isArray(out)) {
-        return createFragment(out);
-    }
     return out;
 }
 
@@ -112,4 +102,63 @@ function format(input, { spaces = 2 } = {}) {
     });
 }
 
-export { asXmlElement, cdata, collapseFragments, compact, createFragment, format, safeXml };
+function createFragment(elements) {
+    return {
+        type: "element",
+        name: "XML_FRAGMENT",
+        elements: elements,
+    };
+}
+
+const TEST_ATTR_NAME = "_testid";
+
+function getAllByTestIdRecursive(root, id, collection) {
+    var _a;
+    const testAttrValue = (_a = root.attributes) === null || _a === void 0 ? void 0 : _a[TEST_ATTR_NAME];
+    if (testAttrValue === id) {
+        collection.push(root);
+    }
+    if (root.elements) {
+        for (const element of root.elements) {
+            getAllByTestIdRecursive(element, id, collection);
+        }
+    }
+    return collection;
+}
+function getAllByTestId(root, id) {
+    return getAllByTestIdRecursive(root, id, []);
+}
+
+function getByTestId(root, id) {
+    const elements = getAllByTestId(root, id);
+    if (elements.length > 1) {
+        throw new Error(`Only expected 1 element with ${TEST_ATTR_NAME}='${id}'`);
+    }
+    return elements[0];
+}
+
+function getSingleTextNode(element) {
+    if (element) {
+        const elements = element.elements;
+        if (elements && elements.length === 1 && elements[0].type === "text") {
+            return elements[0];
+        }
+    }
+    throw new Error("Not a single text node");
+}
+
+function removeTestIdsRecursive(root) {
+    var _a;
+    const attributes = root.attributes ? Object.assign({}, root.attributes) : undefined;
+    if (attributes) {
+        delete attributes[TEST_ATTR_NAME];
+    }
+    return Object.assign(Object.assign({}, root), { attributes, elements: (_a = root.elements) === null || _a === void 0 ? void 0 : _a.map((element) => {
+            return removeTestIdsRecursive(element);
+        }) });
+}
+function removeTestIds(root) {
+    return removeTestIdsRecursive(root);
+}
+
+export { asXmlElement, cdata, collapseFragments, compact, createFragment, format, getAllByTestId, getByTestId, getSingleTextNode, removeTestIds, safeXml };

package/dist/npm/types.d.ts

@@ -1,4 +1,4 @@
-import { Element } from 'xml-js';
+import { Element, ElementCompact } from 'xml-js';
 
 declare function asXmlElement(xml: string | Element): Element;
 
@@ -13,13 +13,22 @@ 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;
+declare function collapseFragments(root: string | Element): Element | Element[];
 
 type FormatOptions = {
     spaces?: number;
 };
 declare function format(input: string, { spaces }?: FormatOptions): string;
 
-export { asXmlElement, cdata, collapseFragments, compact, createFragment, format, safeXml };
+declare function createFragment(elements: Element[]): Element;
+
+declare function getAllByTestId(root: Element | ElementCompact, id: string): (Element | ElementCompact)[];
+
+declare function getByTestId(root: Element | ElementCompact, id: string): Element | ElementCompact | undefined;
+
+declare function getSingleTextNode(element: Element | ElementCompact | undefined): Element;
+
+declare function removeTestIds(root: Element | ElementCompact): Element;
+
+export { asXmlElement, cdata, collapseFragments, compact, createFragment, format, getAllByTestId, getByTestId, getSingleTextNode, removeTestIds, safeXml };
 export type { FormatOptions };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ooxml-tools/xml",
   "description": "Some XML helpers to help with OOXML development",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "MIT",
   "main": "./dist/npm/index.js",
   "types": "./dist/npm/types.d.ts",
@@ -14,8 +14,7 @@
     "build": "rollup -c rollup.config.ts --configPlugin typescript"
   },
   "exports": {
-    ".": "./dist/npm/index.js",
-    "./commands": "./dist/npm/commands.js"
+    ".": "./dist/npm/index.js"
   },
   "files": [
     "./dist/npm",
@@ -29,7 +28,7 @@
     "@rollup/plugin-virtual": "^3.0.2",
     "@tsconfig/node22": "^22.0.0",
     "@types/yargs": "^17.0.32",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.0.10",
     "prettier": "^3.4.2",
     "rollup": "^4.18.1",
     "rollup-plugin-copy": "^3.5.0",
@@ -40,7 +39,7 @@
     "tslib": "^2.6.3",
     "tsx": "^4.17.0",
     "typescript": "^5.5.4",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.10"
   },
   "engines": {
     "node": ">=20.x"