From fe83c3ee405b2fd973a9d46e4b2ff40f68a5471f Mon Sep 17 00:00:00 2001
From: hyperbola <me@hyperbola.me>
Date: Sat, 18 Nov 2023 12:35:43 +0800
Subject: [PATCH] fix: nullable return types of HTMLElement

Fix that some methods of HTMLElement can return `null` or `undefined`.
---
 README.md         | 20 ++++++++++----------
 src/nodes/html.ts | 24 +++++++++++++-----------
 2 files changed, 23 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 79884d6..29a272a 100644
--- a/README.md
+++ b/README.md
@@ -202,7 +202,7 @@ Note: Full range of CSS3 selectors supported since v3.0.0.
 
 ### querySelector(selector)
 
-Query CSS Selector to find matching node.
+Query CSS Selector to find matching node. `null` if not found.
 
 ### getElementsByTagName(tagName)
 
@@ -212,7 +212,7 @@ Note: Use * for all elements.
 
 ### closest(selector)
 
-Query closest element by css selector.
+Query closest element by css selector. `null` if not found.
 
 ### appendChild(node)
 
@@ -236,7 +236,7 @@ Remove `key` attribute.
 
 ### getAttribute(key: string)
 
-Get `key` attribute.
+Get `key` attribute. `undefined` if not set.
 
 ### exchangeChild(oldNode: Node, newNode: Node)
 
@@ -292,7 +292,7 @@ Get class names.
 
 Clone a node.
 
-#### getElementById(id: string): HTMLElement
+#### getElementById(id: string): HTMLElement | null
 
 Get element by it's ID.
 
@@ -322,11 +322,11 @@ Get DOM structure.
 
 ### firstChild
 
-Get first child node.
+Get first child node. `undefined` if no child.
 
 ### lastChild
 
-Get last child node.
+Get last child node. `undefined` if no child
 
 ### innerHTML
 
@@ -338,19 +338,19 @@ Get outerHTML.
 
 ### nextSibling
 
-Returns a reference to the next child node of the current element's parent.
+Returns a reference to the next child node of the current element's parent. `null` if not found.
 
 ### nextElementSibling
 
-Returns a reference to the next child element of the current element's parent.
+Returns a reference to the next child element of the current element's parent. `null` if not found.
 
 ### previousSibling
 
-Returns a reference to the previous child node of the current element's parent.
+Returns a reference to the previous child node of the current element's parent. `null` if not found.
 
 ### previousElementSibling
 
-Returns a reference to the previous child element of the current element's parent.
+Returns a reference to the previous child element of the current element's parent. `null` if not found.
 
 ### textContent
 
diff --git a/src/nodes/html.ts b/src/nodes/html.ts
index a9b6b2e..6d6b559 100644
--- a/src/nodes/html.ts
+++ b/src/nodes/html.ts
@@ -528,8 +528,9 @@ export default class HTMLElement extends Node {
 	/**
 	 * find element by it's id
 	 * @param {string} id the id of the element to select
+	 * @returns {HTMLElement | null} the element with the given id or null if not found
 	 */
-	public getElementById(id: string) {
+	public getElementById(id: string): HTMLElement | null {
 		const stack: Array<number> = [];
 
 		let currentNodeReference = this as Node;
@@ -572,8 +573,9 @@ export default class HTMLElement extends Node {
 	/**
 	 * traverses the Element and its parents (heading toward the document root) until it finds a node that matches the provided selector string. Will return itself or the matching ancestor. If no such element exists, it returns null.
 	 * @param selector a DOMString containing a selector list
+	 * @returns {HTMLElement | null} the element with the given id or null if not found
 	 */
-	public closest(selector: string) {
+	public closest(selector: string): HTMLElement | null {
 		type Predicate = (node: Node) => node is HTMLElement;
 
 		const mapChild = new Map<Node, Node>();
@@ -642,17 +644,17 @@ export default class HTMLElement extends Node {
 
 	/**
 	 * Get first child node
-	 * @return {Node} first child node
+	 * @return {Node | undefined} first child node; or undefined if none
 	 */
-	public get firstChild() {
+	public get firstChild(): Node | undefined {
 		return this.childNodes[0];
 	}
 
 	/**
 	 * Get last child node
-	 * @return {Node} last child node
+	 * @return {Node | undefined} last child node; or undefined if none
 	 */
-	public get lastChild() {
+	public get lastChild(): Node | undefined {
 		return arr_back(this.childNodes);
 	}
 
@@ -737,7 +739,7 @@ export default class HTMLElement extends Node {
 
 	/**
 	 * Get an attribute
-	 * @return {string} value of the attribute
+	 * @return {string | undefined} value of the attribute; or undefined if not exist
 	 */
 	public getAttribute(key: string): string | undefined {
 		return this.attrs[key.toLowerCase()];
@@ -839,7 +841,7 @@ export default class HTMLElement extends Node {
 		// }
 	}
 
-	public get nextSibling() {
+	public get nextSibling(): Node | null {
 		if (this.parentNode) {
 			const children = this.parentNode.childNodes;
 			let i = 0;
@@ -851,7 +853,7 @@ export default class HTMLElement extends Node {
 		}
 	}
 
-	public get nextElementSibling(): HTMLElement {
+	public get nextElementSibling(): HTMLElement | null {
 		if (this.parentNode) {
 			const children = this.parentNode.childNodes;
 			let i = 0;
@@ -870,7 +872,7 @@ export default class HTMLElement extends Node {
 		}
 	}
 
-	public get previousSibling() {
+	public get previousSibling(): Node | null {
 		if (this.parentNode) {
 			const children = this.parentNode.childNodes;
 			let i = children.length;
@@ -882,7 +884,7 @@ export default class HTMLElement extends Node {
 		}
 	}
 
-	public get previousElementSibling(): HTMLElement {
+	public get previousElementSibling(): HTMLElement | null {
 		if (this.parentNode) {
 			const children = this.parentNode.childNodes;
 			let i = children.length;