Add XML fragment parsing and enhance XmlDocument functionality; update TypeScript configuration and add new tests

Author: daniel-sc

.npmignore

@@ -3,3 +3,5 @@
 
 *.spec.ts
 *.spec.js
+
+*.tgz

README.md

@@ -14,6 +14,37 @@ If you have an XML file that you want to read, modify, and write back, this libr
 - Retains XML processing instructions (including the XML declaration)
 - Retains CDATA sections
 
+## Example
+
+The following XML:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<root>
+  <!-- my comment -->
+  <element attribute="value" />
+  <element attribute='value'></element>
+</root>
+```
+
+Will get parsed by `XmlParser.parse(..)` to:
+
+```ts
+new XmlDocument([
+  new XmlProcessing('xml',' ', 'version="1.0" encoding="UTF-8"'),
+  new XmlText('\n'),
+  new XmlElement('root', [], [
+    new XmlText('\n  '),
+    new XmlComment(' my comment '),
+    new XmlText('\n  '),
+    new XmlElement('element', [new XmlAttribute('attribute', 'value')], [], ' ', true),
+    new XmlText('\n  '),
+    new XmlElement('element', [new XmlAttribute('attribute', 'value', ' ', '', '', "'")], [], '', false),
+    new XmlText('\n')
+  ])
+]);
+```
+
 ## Development
 
 This project is written in Typescript and uses Bun.

model/xmlCData.spec.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'bun:test';
+import { XmlCData } from './xmlCData';
+
+describe('XmlCData', () => {
+  it('CDATA section', () => {
+    const cdata = '<tag>Some data</tag>';
+    const node = new XmlCData(cdata);
+    expect(node.toString()).toBe(`<![CDATA[${cdata}]]>`);
+  });
+});

model/xmlComment.spec.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'bun:test';
+import { XmlComment } from './xmlComment';
+
+describe('XmlComment', () => {
+  it('Comment node roundtrip', () => {
+    const comment = 'This is a comment';
+    const node = new XmlComment(comment);
+    expect(node.toString()).toBe(`<!--${comment}-->`);
+  });
+});

model/xmlDoctype.spec.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'bun:test';
+import { XmlDoctype } from './xmlDoctype';
+
+describe('XmlDoctype', () => {
+
+  it('DOCTYPE declaration', () => {
+    const content = 'note SYSTEM "Note.dtd"';
+    const node = new XmlDoctype(content);
+    expect(node.toString()).toBe(`<!DOCTYPE ${content}>`);
+  });
+});

model/xmlDocument.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'bun:test';
+import { XmlDocument } from './xmlDocument';
+import { XmlElement } from './xmlElement';
+
+describe('XmlDocument', () => {
+  describe('getRootElement', () => {
+    it('should return the root element', () => {
+      const root = new XmlElement('root');
+      const document = new XmlDocument([root]);
+      expect(document.getRootElement()).toBe(root);
+    });
+
+    it('should throw if no root element found', () => {
+      const document = new XmlDocument([]);
+      expect(() => document.getRootElement()).toThrowError('No root element found');
+    });
+  })
+});

model/xmlDocument.ts

@@ -1,11 +1,20 @@
 import { XmlNode } from './xmlNode';
+import { XmlElement } from './xmlElement';
 
 /// The document node is simply a container for a sequence of XML nodes.
 export class XmlDocument extends XmlNode {
   constructor(public children: XmlNode[]) {
     super();
   }
 
+  getRootElement(): XmlElement {
+    const root = this.children.find((child) => child instanceof XmlElement);
+    if (!root) {
+      throw new Error('No root element found');
+    }
+    return root;
+  }
+
   toString(): string {
     return this.children.map((child) => child.toString()).join('');
   }

model/xmlElement.spec.ts

@@ -4,6 +4,49 @@ import { XmlText } from './xmlText';
 import { XmlAttribute } from './xmlAttribute';
 
 describe('XmlElement', () => {
+  describe('toString', () => {
+    it('Element with attributes and text', () => {
+      const attrDate = new XmlAttribute('date', '2025-02-22', ' ', '', ' ', '"');
+      const attrAuthor = new XmlAttribute(
+        'author',
+        'John Doe',
+        ' ',
+        ' ',
+        '',
+        '\''
+      );
+      const elem = new XmlElement(
+        'note',
+        [attrDate, attrAuthor],
+        [new XmlText('Some content')],
+        ' ',
+        false,
+        ''
+      );
+      const expected = `<note date= "2025-02-22" author ='John Doe' >Some content</note>`;
+      expect(elem.toString()).toBe(expected);
+    });
+
+    it('Self-closing element', () => {
+      const elem = new XmlElement('br', [], [], ' ', true, '');
+      const expected = `<br />`;
+      expect(elem.toString()).toBe(expected);
+    });
+
+    it('Nested elements', () => {
+      const child = new XmlElement(
+        'child',
+        [],
+        [new XmlText('Text')],
+        ' ',
+        false,
+        ''
+      );
+      const root = new XmlElement('root', [], [child], '', false, '');
+      const expected = `<root><child >Text</child></root>`;
+      expect(root.toString()).toBe(expected);
+    });
+  });
   describe('addElement', () => {
     it('should add a child element', () => {
       const existingChild = new XmlElement('child1');
@@ -19,7 +62,7 @@ describe('XmlElement', () => {
       const element = new XmlElement(
         'test',
         [],
-        [existingChild1, existingChild2],
+        [existingChild1, existingChild2]
       );
       const child = new XmlElement('child');
       element.addElement(child, { after: existingChild1 });
@@ -32,7 +75,7 @@ describe('XmlElement', () => {
       const element = new XmlElement(
         'test',
         [],
-        [existingChild1, existingChild2],
+        [existingChild1, existingChild2]
       );
       const child = new XmlElement('child');
       element.addElement(child, { before: existingChild2 });
@@ -52,33 +95,46 @@ describe('XmlElement', () => {
         const element = new XmlElement(
           'test',
           [],
-          [new XmlText('\n  '), existingChild, new XmlText('\n')],
+          [new XmlText('\n  '), existingChild, new XmlText('\n')]
         );
         const child = new XmlElement('new-child');
         element.addElement(child, {
-          after: existingChild,
-          guessFormatting: true,
+          after: existingChild
         });
         expect(element.toString()).toEqual(
-          `<test>\n  <child></child>\n  <new-child></new-child>\n</test>`,
+          `<test>\n  <child></child>\n  <new-child></new-child>\n</test>`
         );
       });
       it('should add whitespace according previous node with before', () => {
         const existingChild = new XmlElement('child');
         const element = new XmlElement(
           'test',
           [],
-          [new XmlText('\n  '), existingChild, new XmlText('\n')],
+          [new XmlText('\n  '), existingChild, new XmlText('\n')]
         );
         const child = new XmlElement('new-child');
         element.addElement(child, {
-          before: existingChild,
-          guessFormatting: true,
+          before: existingChild
         });
         expect(element.toString()).toEqual(
-          `<test>\n  <new-child></new-child>\n  <child></child>\n</test>`,
+          `<test>\n  <new-child></new-child>\n  <child></child>\n</test>`
         );
       });
+      it('should handle trailing whitespace', () => {
+        const element = new XmlElement('root', [], [
+          new XmlText('\n  '),
+          new XmlElement('child'),
+          new XmlText('\n')
+        ]);
+        element.addElement(new XmlElement('new-child'));
+        expect(element).toEqual(new XmlElement('root', [], [
+          new XmlText('\n  '),
+          new XmlElement('child'),
+          new XmlText('\n  '),
+          new XmlElement('new-child'),
+          new XmlText('\n')
+        ]));
+      });
     });
   });
   describe('getAttributeValue', () => {
@@ -92,4 +148,53 @@ describe('XmlElement', () => {
       expect(element.getAttributeValue('key')).toBeUndefined();
     });
   });
+  describe('setAttributeValue', () => {
+    it('should set the value of the attribute', () => {
+      const element = new XmlElement('test', [new XmlAttribute('key', 'value')]);
+      element.setAttributeValue('key', 'new & value');
+      expect(element.getAttributeValue('key')).toBe('new & value');
+      expect(element.attributes).toEqual([new XmlAttribute('key', 'new &amp; value')]);
+    });
+
+    it('should add the attribute if it does not exist', () => {
+      const element = new XmlElement('test');
+      element.setAttributeValue('key', 'value');
+      expect(element.getAttributeValue('key')).toBe('value');
+    });
+
+    it('should add the attribute with analogous formatting', () => {
+      const element = new XmlElement('test', [new XmlAttribute('key', 'value', '\n  ', ' ', ' ', '\'')]);
+      element.setAttributeValue('another-key', 'value');
+      expect(element.toString()).toBe(`<test
+  key = 'value'
+  another-key = 'value'></test>`);
+    });
+  });
+  describe('getFirstElementByName', () => {
+    it('should return the first element with the given name', () => {
+      const child1 = new XmlElement('child');
+      const child2 = new XmlElement('child');
+      const element = new XmlElement('test', [], [child1, child2]);
+      expect(element.getFirstElementByName('child')).toBe(child1);
+    });
+
+    it('should return undefined if no element with the given name exists', () => {
+      const element = new XmlElement('test');
+      expect(element.getFirstElementByName('child')).toBeUndefined();
+    });
+  });
+
+  describe('getElementsByName', () => {
+    it('should return all elements with the given name', () => {
+      const child1 = new XmlElement('child');
+      const child2 = new XmlElement('child');
+      const element = new XmlElement('test', [], [child1, child2]);
+      expect(element.getElementsByName('child')).toEqual([child1, child2]);
+    });
+
+    it('should return an empty array if no element with the given name exists', () => {
+      const element = new XmlElement('test');
+      expect(element.getElementsByName('child')).toEqual([]);
+    });
+  });
 });