feat: add DOM level 4 child element properties

dmitri-gb · dmitri-gb · commit 7f177184a3d7 · 2026-04-09T18:14:59.000+03:00
This adds the properties childElementCount, firstElementChild,
lastElementChild, nextElementSibling and previousElementSibling to
Element. The first three are also added to Document and
DocumentFragment.
diff --git a/lib/dom.js b/lib/dom.js
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -53,7 +53,7 @@
 		"eslint-plugin-n": "17.24.0",
 		"eslint-plugin-prettier": "5.5.5",
 		"get-stream": "6.0.1",
-		"jest": "29.7.0",
+		"jest": "30.3.0",
 		"nodemon": "3.1.14",
 		"np": "8.0.4",
 		"prettier": "3.8.1",
diff --git a/readme.md b/readme.md
@@ -92,7 +92,7 @@ import { DOMParser } from '@xmldom/xmldom'
 	```javascript
 	serializeToString(node)
 	```
-### DOM level2 method and attribute:
+### DOM level 2 method and attribute:
 
 * [Node](http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html#ID-1950641247)
 
@@ -293,8 +293,17 @@ import { DOMParser } from '@xmldom/xmldom'
 
 * [ParentNode](https://dom.spec.whatwg.org/#interface-parentnode) mixin (on `Document`, `DocumentFragment`, `Element`)
 
-  readonly attribute:
+  readonly attributes:
   - `children`
+  - `firstElementChild`
+  - `lastElementChild`
+  - `childElementCount`
+
+* Element (from [NonDocumentTypeChildNode](https://dom.spec.whatwg.org/#nondocumenttypechildnode) mixin)
+
+  readonly attributes:
+  - `previousElementSibling`
+  - `nextElementSibling`
 
 ### DOM extension by xmldom
 
diff --git a/test/__snapshots__/entities.test.js.snap b/test/__snapshots__/entities.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`entity replacement ignores js prototype chain should not pick up 'entities' from the prototype chain 1`] = `
 {
diff --git a/test/conventions/__snapshots__/html.test.js.snap b/test/conventions/__snapshots__/html.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`HTML_BOOLEAN_ATTRIBUTES should contain immutable allowfullscreen with value 'true' 1`] = `
 [
diff --git a/test/conventions/__snapshots__/mime-type.test.js.snap b/test/conventions/__snapshots__/mime-type.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`MIME_TYPE should contain immutable HTML with correct value 1`] = `
 [
diff --git a/test/conventions/__snapshots__/namespace.test.js.snap b/test/conventions/__snapshots__/namespace.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`NAMESPACE should contain immutable HTML with correct value 1`] = `
 [
diff --git a/test/dom-parser.test.js b/test/dom-parser.test.js
@@ -187,15 +187,15 @@ describe('DOMParser', () => {
 
 				// warning
 				expect(() => parser.parseFromString('<xml attr />', MIME_TYPE.XML_TEXT)).not.toThrow(ParseError);
-				expect(onError).toBeCalledTimes(1);
+				expect(onError).toHaveBeenCalledTimes(1);
 				expect(onError).toHaveBeenCalledWith('warning', expect.anything(), expect.anything());
 				// error
 				expect(() => parser.parseFromString('<xml>&e;</xml>', MIME_TYPE.XML_TEXT)).toThrow(ParseError);
-				expect(onError).toBeCalledTimes(2);
+				expect(onError).toHaveBeenCalledTimes(2);
 				expect(onError).toHaveBeenCalledWith('error', expect.anything(), expect.anything());
 				// fatalError
 				expect(() => parser.parseFromString('', MIME_TYPE.XML_TEXT)).toThrow(ParseError);
-				expect(onError).toBeCalledTimes(3);
+				expect(onError).toHaveBeenCalledTimes(3);
 				expect(onError).toHaveBeenCalledWith('fatalError', expect.anything(), expect.anything());
 			});
 			test('should throw for level error when using onWarningStopParsing', () => {
@@ -204,15 +204,15 @@ describe('DOMParser', () => {
 
 				// warning
 				expect(() => parser.parseFromString('<xml attr />', MIME_TYPE.XML_TEXT)).toThrow(ParseError);
-				expect(onError).toBeCalledTimes(1);
+				expect(onError).toHaveBeenCalledTimes(1);
 				expect(onError).toHaveBeenCalledWith('warning', expect.anything(), expect.anything());
 				// error
 				expect(() => parser.parseFromString('<xml>&e;</xml>', MIME_TYPE.XML_TEXT)).toThrow(ParseError);
-				expect(onError).toBeCalledTimes(2);
+				expect(onError).toHaveBeenCalledTimes(2);
 				expect(onError).toHaveBeenCalledWith('error', expect.anything(), expect.anything());
 				// fatalError
 				expect(() => parser.parseFromString('', MIME_TYPE.XML_TEXT)).toThrow(ParseError);
-				expect(onError).toBeCalledTimes(3);
+				expect(onError).toHaveBeenCalledTimes(3);
 				expect(onError).toHaveBeenCalledWith('fatalError', expect.anything(), expect.anything());
 			});
 			test('should throw when errorHandler is not a function', () => {
@@ -222,7 +222,7 @@ describe('DOMParser', () => {
 				var errorHandler = jest.fn();
 				new DOMParser({ errorHandler });
 
-				expect(errorHandler).toBeCalledWith('warning', expect.stringContaining('onError'), expect.anything());
+				expect(errorHandler).toHaveBeenCalledWith('warning', expect.stringContaining('onError'), expect.anything());
 			});
 		});
 	});
diff --git a/test/dom/dom-implementation.test.js b/test/dom/dom-implementation.test.js
@@ -62,6 +62,9 @@ describe('DOMImplementation', () => {
 			expect(root.prefix).toBe(null);
 			expect(root.localName).toBe(NAME);
 			expect(doc.documentElement).toBe(root);
+			expect(doc.childElementCount).toBe(1);
+			expect(doc.firstElementChild).toBe(root);
+			expect(doc.lastElementChild).toBe(root);
 			expect(doc.contentType).toBe(MIME_TYPE.XML_APPLICATION);
 			expect(doc.type).toBe('xml');
 		});
@@ -80,6 +83,9 @@ describe('DOMImplementation', () => {
 			expect(root.tagName).toBe(NAME);
 
 			expect(doc.documentElement).toBe(root);
+			expect(doc.childElementCount).toBe(1);
+			expect(doc.firstElementChild).toBe(root);
+			expect(doc.lastElementChild).toBe(root);
 			expect(doc.contentType).toBe(MIME_TYPE.XML_APPLICATION);
 			expect(doc.type).toBe('xml');
 		});
@@ -99,25 +105,9 @@ describe('DOMImplementation', () => {
 			expect(root.tagName).toBe(qualifiedName);
 
 			expect(doc.documentElement).toBe(root);
-			expect(doc.contentType).toBe(MIME_TYPE.XML_APPLICATION);
-			expect(doc.type).toBe('xml');
-		});
-
-		test('should create a Document with root element in a named namespace', () => {
-			const impl = new DOMImplementation();
-			const qualifiedName = `${PREFIX}:${NAME}`;
-			const doc = impl.createDocument(NS, qualifiedName);
-
-			const root = doc.childNodes.item(0);
-			expect(root).toBeInstanceOf(Element);
-			expect(root.ownerDocument).toBe(doc);
-			expect(root.namespaceURI).toBe(NS);
-			expect(root.prefix).toBe(PREFIX);
-			expect(root.localName).toBe(NAME);
-			expect(root.nodeName).toBe(qualifiedName);
-			expect(root.tagName).toBe(qualifiedName);
-
-			expect(doc.documentElement).toBe(root);
+			expect(doc.childElementCount).toBe(1);
+			expect(doc.firstElementChild).toBe(root);
+			expect(doc.lastElementChild).toBe(root);
 			expect(doc.contentType).toBe(MIME_TYPE.XML_APPLICATION);
 			expect(doc.type).toBe('xml');
 		});
@@ -142,6 +132,9 @@ describe('DOMImplementation', () => {
 			expect(root.tagName).toBe(qualifiedName);
 
 			expect(doc.documentElement).toBe(root);
+			expect(doc.childElementCount).toBe(1);
+			expect(doc.firstElementChild).toBe(root);
+			expect(doc.lastElementChild).toBe(root);
 			expect(doc.contentType).toBe(MIME_TYPE.XML_APPLICATION);
 			expect(doc.type).toBe('xml');
 		});
@@ -210,6 +203,9 @@ describe('DOMImplementation', () => {
 			expect(doc.doctype.ownerDocument).toBe(doc);
 			expect(doc.childNodes.item(0)).toBe(doc.doctype);
 			expect(doc.firstChild).toBe(doc.doctype);
+			expect(doc.childElementCount).toBe(1);
+			expect(doc.firstElementChild).toBe(doc.documentElement);
+			expect(doc.lastElementChild).toBe(doc.documentElement);
 
 			expect(doc.documentElement).not.toBeNull();
 			expect(doc.documentElement.localName).toBe('html');
@@ -219,10 +215,14 @@ describe('DOMImplementation', () => {
 			expect(htmlNode.firstChild).not.toBeNull();
 			expect(htmlNode.firstChild.nodeName).toBe('head');
 			expect(htmlNode.firstChild.childNodes).toHaveLength(0);
+			expect(htmlNode.firstElementChild).toBe(htmlNode.firstChild);
+			expect(htmlNode.firstElementChild.nextElementSibling).toBe(htmlNode.lastChild);
 
 			expect(htmlNode.lastChild).not.toBeNull();
 			expect(htmlNode.lastChild.nodeName).toBe('body');
 			expect(htmlNode.lastChild.childNodes).toHaveLength(0);
+			expect(htmlNode.lastElementChild).toBe(htmlNode.lastChild);
+			expect(htmlNode.lastElementChild.previousElementSibling).toBe(htmlNode.firstChild);
 		});
 		test('should create an HTML document with specified elements including an empty title', () => {
 			const impl = new DOMImplementation();
diff --git a/test/dom/element.test.js b/test/dom/element.test.js
@@ -75,8 +75,8 @@ describe('documentElement', () => {
 		expect(doc.documentElement.toString()).toBe('<test>bye</test>');
 	});
 
-	test('appendElement and removeElement', () => {
-		const dom = new DOMParser().parseFromString(`<root><A/><B/><C/></root>`, MIME_TYPE.XML_TEXT);
+	test('appendChild and removeChild', () => {
+		const dom = new DOMParser().parseFromString(`<root><A/>x<B/>y<C/></root>`, MIME_TYPE.XML_TEXT);
 		const doc = dom.documentElement;
 		const arr = [];
 		while (doc.firstChild) {
@@ -85,26 +85,45 @@ describe('documentElement', () => {
 			expect(node.parentNode).toBeNull();
 			expect(node.previousSibling).toBeNull();
 			expect(node.nextSibling).toBeNull();
+			if (node.nodeType == Node.ELEMENT_NODE) {
+				expect(node.previousElementSibling).toBeNull();
+				expect(node.nextElementSibling).toBeNull();
+			}
 			expect(node.ownerDocument).toBe(dom);
 			expect(doc.firstChild).not.toBe(node);
-			const expectedLength = 3 - arr.length;
+			expect(doc.firstElementChild).not.toBe(node);
+			expect(doc.lastElementChild).not.toBe(node);
+			const expectedLength = 5 - arr.length;
 			expect(doc.childNodes).toHaveLength(expectedLength);
 			expect(doc.childNodes.item(expectedLength)).toBeNull();
 		}
-		expect(arr).toHaveLength(3);
-		while (arr.length) {
-			const node = arr.shift();
+		expect(arr).toHaveLength(5);
+		expect(doc.childElementCount).toBe(0);
+		expect(doc.firstElementChild).toBeNull();
+		expect(doc.lastElementChild).toBeNull();
+		for (let i = 0; i < arr.length; i++) {
+			const node = arr[i];
 			expect(doc.appendChild(node)).toBe(node);
+			expect(doc.childNodes).toHaveLength(i + 1);
+			expect(doc.childNodes.item(i)).toBe(node);
 			expect(node.parentNode).toBe(doc);
-			const expectedLength = 3 - arr.length;
-			expect(doc.childNodes).toHaveLength(expectedLength);
-			expect(doc.childNodes.item(expectedLength - 1)).toBe(node);
-			if (expectedLength > 1) {
-				expect(node.previousSibling).toBeInstanceOf(Element);
-				expect(node.previousSibling.nextSibling).toBe(node);
+			expect(node.previousSibling).toBe(i == 0 ? null : arr[i - 1]);
+			expect(node.nextSibling).toBe(null);
+			if (i > 0) expect(node.previousSibling.nextSibling).toBe(node);
+			if (node.nodeType == Node.ELEMENT_NODE) {
+				expect(doc.lastElementChild).toBe(node);
+				expect(node.previousElementSibling).toBe(i <= 1 ? null : arr[i - 2]);
+				expect(node.nextElementSibling).toBe(null);
+				if (i > 1) expect(node.previousElementSibling.nextElementSibling).toBe(node);
 			}
 		}
-		expect(doc.childNodes.toString()).toBe(`<A/><B/><C/>`);
+		expect(doc.childElementCount).toBe(3);
+		expect(doc.firstElementChild).toBe(arr[0]);
+		expect(doc.childNodes.toString()).toBe(`<A/>x<B/>y<C/>`);
+
+		doc.removeChild(doc.lastChild);
+		expect(doc.lastElementChild).toBe(arr[2]);
+		expect(doc.lastElementChild.nextElementSibling).toBeNull();
 	});
 
 	test('should throw DOMException when trying to append a doctype', () => {
diff --git a/test/errors/__snapshots__/dom-exception.test.js.snap b/test/errors/__snapshots__/dom-exception.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`DOMException should have correct name from code 1 1`] = `"IndexSizeError"`;
 
diff --git a/test/errors/__snapshots__/reported-levels.test.js.snap b/test/errors/__snapshots__/reported-levels.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Encoding_ReplacementCharacter with mimeType text/html should be reported 1`] = `
 [
diff --git a/test/errors/__snapshots__/xml-error.test.js.snap b/test/errors/__snapshots__/xml-error.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`html without reported errors html attribute (missing quote) 1`] = `
 {
diff --git a/test/grammar/__snapshots__/externalid.test.js.snap b/test/grammar/__snapshots__/externalid.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`ExternalID PUBLIC should match ""PUBLIC " a-zA-Z0-9-()+,./:=?;!*#@$_%" '"'"" 1`] = `
 {
diff --git a/test/grammar/__snapshots__/name.test.js.snap b/test/grammar/__snapshots__/name.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`QName should match a single NCNameStartChar NCNameChar(s) ':' NCNameStartChar NCNameChar(s) "_-:_-" (\\u005F\\u002D\\u003A\\u005F\\u002D) 1`] = `
 [
diff --git a/test/grammar/__snapshots__/pi.test.js.snap b/test/grammar/__snapshots__/pi.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`PI should not be greedy 1`] = `
 [
diff --git a/test/grammar/__snapshots__/regexp.test.js.snap b/test/grammar/__snapshots__/regexp.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`all grammar regular expressions should have the expected keys 1`] = `
 [
diff --git a/test/html/__snapshots__/normalize.test.js.snap b/test/html/__snapshots__/normalize.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`html normalizer <Label onClick=doClick..">Hello, World</Label> 1`] = `
 {
diff --git a/test/parse/__snapshots__/locator.test.js.snap b/test/parse/__snapshots__/locator.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`DOMLocator attribute position 1`] = `
 {
diff --git a/test/parse/__snapshots__/parse-element.test.js.snap b/test/parse/__snapshots__/parse-element.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`XML Node Parse closing tag with unquoted value ending with // 1`] = `
 [
diff --git a/test/parse/__snapshots__/simple.test.js.snap b/test/parse/__snapshots__/simple.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`parse simple 1`] = `
 {
diff --git a/test/parse/__snapshots__/test-doc-whitespace.test.js.snap b/test/parse/__snapshots__/test-doc-whitespace.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`errorHandle document source 1`] = `
 {
diff --git a/test/parse/node.test.js b/test/parse/node.test.js
@@ -141,7 +141,12 @@ describe('XML Node Parse', () => {
 
 			expectNeighbours(first, last);
 			expect(fragment.firstChild).toStrictEqual(first);
+			expect(fragment.firstElementChild).toStrictEqual(first);
+			expect(fragment.firstElementChild.nextElementSibling).toStrictEqual(last);
 			expect(fragment.lastChild).toStrictEqual(last);
+			expect(fragment.lastElementChild).toStrictEqual(last);
+			expect(fragment.lastElementChild.previousElementSibling).toStrictEqual(first);
+			expect(fragment.childElementCount).toBe(2);
 		});
 	});
 
@@ -163,10 +168,20 @@ describe('XML Node Parse', () => {
 			const first = fragment.appendChild(dom.createElement('first'));
 			const second = fragment.appendChild(dom.createElement('second'));
 
-			child.parentNode.insertBefore(fragment, child);
+			const parent = child.parentNode;
+			parent.insertBefore(fragment, child);
 
 			expectNeighbours(first, second, child);
-			expect(child.parentNode.firstChild).toStrictEqual(first);
+			expect(parent.firstChild).toStrictEqual(first);
+			expect(parent.childElementCount).toStrictEqual(3);
+			expect(parent.firstElementChild).toStrictEqual(first);
+			expect(parent.lastElementChild).toStrictEqual(child);
+			expect(first.previousElementSibling).toBeNull();
+			expect(first.nextElementSibling).toStrictEqual(second);
+			expect(second.previousElementSibling).toStrictEqual(first);
+			expect(second.nextElementSibling).toStrictEqual(child);
+			expect(child.previousElementSibling).toStrictEqual(second);
+			expect(child.nextElementSibling).toBeNull();
 		});
 	});
 
diff --git a/test/xmltest/__snapshots__/not-wf.test.js.snap b/test/xmltest/__snapshots__/not-wf.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`xmltest/not-wellformed standalone should match 001.xml with snapshot: caught 1`] = `"Opening and ending tag mismatch: "doc" != "a""`;
 
diff --git a/test/xmltest/__snapshots__/valid.test.js.snap b/test/xmltest/__snapshots__/valid.test.js.snap
@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`xmltest/valid standalone should match 001.xml with snapshot 1`] = `
 {

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// Jest Snapshot v1, https://goo.gl/fbAQLP`
	`1`	`+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing`
`2`	`2`
`3`	`3`	exports[`entity replacement ignores js prototype chain should not pick up 'entities' from the prototype chain 1`] = `
`4`	`4`	`{`