wikiparser-node 0.5.0 → 0.6.1

package/lib/node.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const {typeError, externalUse} = require('../util/debug'),
+const {typeError} = require('../util/debug'),
 	{text} = require('../util/string'),
 	assert = require('assert/strict'),
 	EventEmitter = require('events'),
@@ -21,11 +21,11 @@ class AstNode {
 	 * @throws `RangeError` 指定位置不存在子节点
 	 */
 	#verifyChild = (i, addition = 0) => {
-		if (typeof i !== 'number') {
+		if (!Number.isInteger(i)) {
 			this.typeError('verifyChild', 'Number');
 		}
 		const {childNodes: {length}} = this;
-		if (i < -length || i >= length + addition || !Number.isInteger(i)) {
+		if (i < -length || i >= length + addition) {
 			throw new RangeError(`不存在第 ${i} 个子节点！`);
 		}
 	};
@@ -45,17 +45,6 @@ class AstNode {
 		return this.#parentNode;
 	}
 
-	/** 是否具有根节点 */
-	get isConnected() {
-		return this.getRootNode().type === 'root';
-	}
-
-	/** 不是自身的根节点 */
-	get ownerDocument() {
-		const root = this.getRootNode();
-		return root.type === 'root' && root !== this ? root : undefined;
-	}
-
 	/**
 	 * 后一个兄弟节点
 	 * @complexity `n`
@@ -96,6 +85,17 @@ class AstNode {
 		return childNodes?.slice(0, i)?.findLast(({type}) => type !== 'text');
 	}
 
+	/** 是否具有根节点 */
+	get isConnected() {
+		return this.getRootNode().type === 'root';
+	}
+
+	/** 不是自身的根节点 */
+	get ownerDocument() {
+		const root = this.getRootNode();
+		return root.type === 'root' && root !== this ? root : undefined;
+	}
+
 	/**
 	 * 后方是否还有其他节点（不含后代）
 	 * @returns {boolean}
@@ -113,9 +113,14 @@ class AstNode {
 		return nextSibling === undefined && parentNode?.eof;
 	}
 
+	constructor() {
+		Object.defineProperty(this, 'childNodes', {writable: false});
+		Object.freeze(this.childNodes);
+	}
+
 	/**
 	 * 标记仅用于代码调试的方法
-	 * @param {string} method 方法名称
+	 * @param {string} method
 	 * @throws `Error`
 	 */
 	debugOnly(method = 'debugOnly') {
@@ -124,7 +129,7 @@ class AstNode {
 
 	/**
 	 * 抛出`TypeError`
-	 * @param {string} method 方法名称
+	 * @param {string} method
 	 * @param  {...string} types 可接受的参数类型
 	 */
 	typeError(method, ...types) {
@@ -146,17 +151,12 @@ class AstNode {
 		}
 		for (const key of keys) {
 			Object.defineProperty(this, key, {
-				writable: false, enumerable: Boolean(this[key]), configurable: !permanent,
+				writable: false, enumerable: !permanent && Boolean(this[key]), configurable: !permanent,
 			});
 		}
 		return this;
 	}
 
-	constructor() {
-		Object.defineProperty(this, 'childNodes', {writable: false});
-		Object.freeze(this.childNodes);
-	}
-
 	/**
 	 * 是否是全同节点
 	 * @param {this} node 待比较的节点
@@ -174,32 +174,6 @@ class AstNode {
 		return true;
 	}
 
-	/**
-	 * 是否具有某属性
-	 * @param {PropertyKey} key 属性键
-	 */
-	hasAttribute(key) {
-		const type = typeof key;
-		return type === 'string' || type === 'number' || type === 'symbol'
-			? key in this
-			: this.typeError('hasAttribute', 'String', 'Number', 'Symbol');
-	}
-
-	/**
-	 * 获取属性值。除非用于私有属性，否则总是返回字符串。
-	 * @template {string} T
-	 * @param {T} key 属性键
-	 * @returns {TokenAttribute<T>}
-	 */
-	getAttribute(key) {
-		if (key === 'optional') {
-			return [...this.#optional];
-		} else if (key === 'verifyChild') {
-			return this.#verifyChild;
-		}
-		return this.hasAttribute(key) ? String(this[key]) : undefined;
-	}
-
 	/** 获取所有属性键 */
 	getAttributeNames() {
 		const names = Object.getOwnPropertyNames(this);
@@ -211,38 +185,6 @@ class AstNode {
 		return this.getAttributeNames().length > 0;
 	}
 
-	/**
-	 * 设置属性
-	 * @template {string} T
-	 * @param {T} key 属性键
-	 * @param {TokenAttribute<T>} value 属性值
-	 * @throws `RangeError` 禁止手动指定的属性
-	 */
-	setAttribute(key, value) {
-		if (key === 'parentNode') {
-			if (externalUse('setAttribute')) {
-				throw new RangeError(`禁止手动指定 ${key} 属性！`);
-			}
-			this.#parentNode = value;
-		} else if (this.hasAttribute(key)) {
-			const descriptor = Object.getOwnPropertyDescriptor(this, key);
-			if (!descriptor || !descriptor.writable && externalUse('setAttribute')) {
-				throw new RangeError(`禁止手动指定 ${key} 属性！`);
-			} else if (this.#optional.includes(key)) {
-				descriptor.enumerable = Boolean(value);
-			}
-			const oldValue = this[key],
-				frozen = oldValue !== null && typeof oldValue === 'object' && Object.isFrozen(oldValue);
-			Object.defineProperty(this, key, {...descriptor, value});
-			if (frozen && value !== null && typeof value === 'object') {
-				Object.freeze(value);
-			}
-		} else {
-			this[key] = value;
-		}
-		return this;
-	}
-
 	/**
 	 * 移除某属性
 	 * @param {PropertyKey} key 属性键
@@ -274,116 +216,55 @@ class AstNode {
 	}
 
 	/**
-	 * 可见部分
-	 * @param {string} separator 子节点间的连接符
-	 * @returns {string}
-	 * @complexity `n`
-	 */
-	text(separator = '') {
-		return text(this.childNodes, separator);
-	}
-
-	/** 是否具有子节点 */
-	hasChildNodes() {
-		return this.childNodes.length > 0;
-	}
-
-	/**
-	 * 是自身或后代节点
-	 * @param {this} node 待检测节点
-	 * @returns {boolean}
-	 * @complexity `n`
+	 * 是否具有某属性
+	 * @param {PropertyKey} key 属性键
 	 */
-	contains(node) {
-		return node instanceof AstNode
-			? node === this || this.childNodes.some(child => child.contains(node))
-			: this.typeError('contains', 'AstNode');
+	hasAttribute(key) {
+		const type = typeof key;
+		return type === 'string' || type === 'number' || type === 'symbol'
+			? key in this
+			: this.typeError('hasAttribute', 'String', 'Number', 'Symbol');
 	}
 
 	/**
-	 * 添加事件监听
-	 * @param {string|string[]} types 事件类型
-	 * @param {AstListener} listener 监听函数
-	 * @param {{once: boolean}} options 选项
+	 * 获取属性值。除非用于私有属性，否则总是返回字符串。
+	 * @template {string} T
+	 * @param {T} key 属性键
+	 * @returns {TokenAttribute<T>}
 	 */
-	addEventListener(types, listener, options) {
-		if (Array.isArray(types)) {
-			for (const type of types) {
-				this.addEventListener(type, listener, options);
-			}
-		} else if (typeof types !== 'string' || typeof listener !== 'function') {
-			this.typeError('addEventListener', 'String', 'Function');
-		} else {
-			this.#events[options?.once ? 'once' : 'on'](types, listener);
+	getAttribute(key) {
+		if (key === 'optional') {
+			return [...this.#optional];
+		} else if (key === 'verifyChild') {
+			return this.#verifyChild;
 		}
+		return this.hasAttribute(key) ? String(this[key]) : undefined;
 	}
 
 	/**
-	 * 移除事件监听
-	 * @param {string|string[]} types 事件类型
-	 * @param {AstListener} listener 监听函数
+	 * 设置属性
+	 * @template {string} T
+	 * @param {T} key 属性键
+	 * @param {TokenAttribute<T>} value 属性值
 	 */
-	removeEventListener(types, listener) {
-		if (Array.isArray(types)) {
-			for (const type of types) {
-				this.removeEventListener(type, listener);
+	setAttribute(key, value) {
+		if (key === 'parentNode') {
+			this.#parentNode = value;
+		} else if (Object.hasOwn(this, key)) {
+			const descriptor = Object.getOwnPropertyDescriptor(this, key);
+			if (this.#optional.includes(key)) {
+				descriptor.enumerable = Boolean(value);
 			}
-		} else if (typeof types !== 'string' || typeof listener !== 'function') {
-			this.typeError('removeEventListener', 'String', 'Function');
-		} else {
-			this.#events.off(types, listener);
-		}
-	}
-
-	/**
-	 * 移除事件的所有监听
-	 * @param {string|string[]} types 事件类型
-	 */
-	removeAllEventListeners(types) {
-		if (Array.isArray(types)) {
-			for (const type of types) {
-				this.removeAllEventListeners(type);
+			const oldValue = this[key],
+				frozen = oldValue !== null && typeof oldValue === 'object' && Object.isFrozen(oldValue);
+			Object.defineProperty(this, key, {...descriptor, value});
+			if (frozen && value !== null && typeof value === 'object') {
+				Object.freeze(value);
 			}
-		} else if (types !== undefined && typeof types !== 'string') {
-			this.typeError('removeAllEventListeners', 'String');
 		} else {
-			this.#events.removeAllListeners(types);
-		}
-	}
-
-	/**
-	 * 列举事件监听
-	 * @param {string} type 事件类型
-	 * @returns {AstListener[]}
-	 */
-	listEventListeners(type) {
-		return typeof type === 'string' ? this.#events.listeners(type) : this.typeError('listEventListeners', 'String');
-	}
-
-	/**
-	 * 触发事件
-	 * @param {AstEvent} e 事件对象
-	 * @param {any} data 事件数据
-	 */
-	dispatchEvent(e, data) {
-		if (!(e instanceof Event)) {
-			this.typeError('dispatchEvent', 'Event');
-		} else if (!e.target) { // 初始化
-			Object.defineProperty(e, 'target', {value: this, enumerable: true});
-
-			/** 终止冒泡 */
-			e.stopPropagation = function() {
-				Object.defineProperty(this, 'bubbles', {value: false});
-			};
-		}
-		Object.defineProperties(e, { // 每次bubble更新
-			prevTarget: {value: e.currentTarget, enumerable: true, configurable: true},
-			currentTarget: {value: this, enumerable: true, configurable: true},
-		});
-		this.#events.emit(e.type, e, data);
-		if (e.bubbles && this.parentNode) {
-			this.parentNode.dispatchEvent(e, data);
+			this[key] = value;
 		}
+		return this;
 	}
 
 	/**
@@ -396,34 +277,8 @@ class AstNode {
 			[node] = childNodes.splice(i, 1),
 			e = new Event('remove', {bubbles: true});
 		node.setAttribute('parentNode');
-		this.setAttribute('childNodes', childNodes).dispatchEvent(e, {position: i, removed: node});
-		return node;
-	}
-
-	/**
-	 * 获取子节点的位置
-	 * @param {this} node 子节点
-	 * @complexity `n`
-	 * @throws `RangeError` 找不到子节点
-	 */
-	#getChildIndex(node) {
-		const {childNodes} = this,
-			i = childNodes.indexOf(node);
-		if (i === -1) {
-			Parser.error('找不到子节点！', node);
-			throw new RangeError('找不到子节点！');
-		}
-		return i;
-	}
-
-	/**
-	 * 移除子节点
-	 * @template {this} T
-	 * @param {T} node 子节点
-	 * @complexity `n`
-	 */
-	removeChild(node) {
-		this.removeAt(this.#getChildIndex(node));
+		this.setAttribute('childNodes', childNodes);
+		this.dispatchEvent(e, {position: i, removed: node});
 		return node;
 	}
 
@@ -453,8 +308,35 @@ class AstNode {
 			childNodes.splice(j, 1);
 		}
 		childNodes.splice(i, 0, node);
-		this.setAttribute('childNodes', childNodes)
-			.dispatchEvent(e, {position: i < 0 ? i + this.childNodes.length - 1 : i, inserted: node});
+		this.setAttribute('childNodes', childNodes);
+		this.dispatchEvent(e, {position: i < 0 ? i + this.childNodes.length - 1 : i, inserted: node});
+		return node;
+	}
+
+	/**
+	 * 获取子节点的位置
+	 * @param {this} node 子节点
+	 * @complexity `n`
+	 * @throws `RangeError` 找不到子节点
+	 */
+	#getChildIndex(node) {
+		const {childNodes} = this,
+			i = childNodes.indexOf(node);
+		if (i === -1) {
+			Parser.error('找不到子节点！', node);
+			throw new RangeError('找不到子节点！');
+		}
+		return i;
+	}
+
+	/**
+	 * 移除子节点
+	 * @template {this} T
+	 * @param {T} node 子节点
+	 * @complexity `n`
+	 */
+	removeChild(node) {
+		this.removeAt(this.#getChildIndex(node));
 		return node;
 	}
 
@@ -476,7 +358,7 @@ class AstNode {
 	 * @complexity `n`
 	 */
 	insertBefore(child, reference) {
-		return reference === undefined ? this.appendChild(child) : this.insertAt(child, this.#getChildIndex(reference));
+		return reference === undefined ? this.insertAt(child) : this.insertAt(child, this.#getChildIndex(reference));
 	}
 
 	/**
@@ -552,6 +434,156 @@ class AstNode {
 		this.remove();
 	}
 
+	/**
+	 * 可见部分
+	 * @param {string} separator 子节点间的连接符
+	 * @returns {string}
+	 * @complexity `n`
+	 */
+	text(separator = '') {
+		return text(this.childNodes, separator);
+	}
+
+	/** 是否具有子节点 */
+	hasChildNodes() {
+		return this.childNodes.length > 0;
+	}
+
+	/**
+	 * 是自身或后代节点
+	 * @param {this} node 待检测节点
+	 * @returns {boolean}
+	 * @complexity `n`
+	 */
+	contains(node) {
+		return node instanceof AstNode
+			? node === this || this.childNodes.some(child => child.contains(node))
+			: this.typeError('contains', 'AstNode');
+	}
+
+	/**
+	 * 添加事件监听
+	 * @param {string|string[]} types 事件类型
+	 * @param {AstListener} listener 监听函数
+	 * @param {{once: boolean}} options 选项
+	 */
+	addEventListener(types, listener, options) {
+		if (Array.isArray(types)) {
+			for (const type of types) {
+				this.addEventListener(type, listener, options);
+			}
+		} else if (typeof types === 'string' && typeof listener === 'function') {
+			this.#events[options?.once ? 'once' : 'on'](types, listener);
+		} else {
+			this.typeError('addEventListener', 'String', 'Function');
+		}
+	}
+
+	/**
+	 * 移除事件监听
+	 * @param {string|string[]} types 事件类型
+	 * @param {AstListener} listener 监听函数
+	 */
+	removeEventListener(types, listener) {
+		if (Array.isArray(types)) {
+			for (const type of types) {
+				this.removeEventListener(type, listener);
+			}
+		} else if (typeof types === 'string' && typeof listener === 'function') {
+			this.#events.off(types, listener);
+		} else {
+			this.typeError('removeEventListener', 'String', 'Function');
+		}
+	}
+
+	/**
+	 * 移除事件的所有监听
+	 * @param {string|string[]} types 事件类型
+	 */
+	removeAllEventListeners(types) {
+		if (Array.isArray(types)) {
+			for (const type of types) {
+				this.removeAllEventListeners(type);
+			}
+		} else if (types === undefined || typeof types === 'string') {
+			this.#events.removeAllListeners(types);
+		} else {
+			this.typeError('removeAllEventListeners', 'String');
+		}
+	}
+
+	/**
+	 * 列举事件监听
+	 * @param {string} type 事件类型
+	 * @returns {AstListener[]}
+	 */
+	listEventListeners(type) {
+		return typeof type === 'string' ? this.#events.listeners(type) : this.typeError('listEventListeners', 'String');
+	}
+
+	/**
+	 * 触发事件
+	 * @param {AstEvent} e 事件对象
+	 * @param {*} data 事件数据
+	 */
+	dispatchEvent(e, data) {
+		if (!(e instanceof Event)) {
+			this.typeError('dispatchEvent', 'Event');
+		} else if (!e.target) { // 初始化
+			Object.defineProperty(e, 'target', {value: this, enumerable: true});
+
+			/** 终止冒泡 */
+			e.stopPropagation = function() {
+				Object.defineProperty(this, 'bubbles', {value: false});
+			};
+		}
+		Object.defineProperties(e, { // 每次bubble更新
+			prevTarget: {value: e.currentTarget, enumerable: true, configurable: true},
+			currentTarget: {value: this, enumerable: true, configurable: true},
+		});
+		this.#events.emit(e.type, e, data);
+		if (e.bubbles && this.parentNode) {
+			this.parentNode.dispatchEvent(e, data);
+		}
+	}
+
+	/** 获取所有祖先节点 */
+	getAncestors() {
+		const /** @type {this[]} */ ancestors = [];
+		let {parentNode} = this;
+		while (parentNode) {
+			ancestors.push(parentNode);
+			({parentNode} = parentNode);
+		}
+		return ancestors;
+	}
+
+	/**
+	 * 比较和另一个节点的相对位置
+	 * @param {this} other 待比较的节点
+	 * @complexity `n`
+	 * @throws `Error` 不在同一个语法树
+	 */
+	compareDocumentPosition(other) {
+		if (!(other instanceof AstNode)) {
+			this.typeError('compareDocumentPosition', 'AstNode');
+		} else if (this === other) {
+			return 0;
+		} else if (this.contains(other)) {
+			return -1;
+		} else if (other.contains(this)) {
+			return 1;
+		} else if (this.getRootNode() !== other.getRootNode()) {
+			throw new Error('不在同一个语法树！');
+		}
+		const aAncestors = [...this.getAncestors().reverse(), this],
+			bAncestors = [...other.getAncestors().reverse(), other],
+			depth = aAncestors.findIndex((ancestor, i) => bAncestors[i] !== ancestor),
+			commonAncestor = aAncestors[depth - 1],
+			{childNodes} = commonAncestor;
+		return childNodes.indexOf(aAncestors[depth]) - childNodes.indexOf(bAncestors[depth]);
+	}
+
 	/**
 	 * 合并相邻的文本子节点
 	 * @complexity `n`
@@ -588,11 +620,11 @@ class AstNode {
 	 * @complexity `n`
 	 */
 	posFromIndex(index) {
-		if (typeof index !== 'number') {
+		if (!Number.isInteger(index)) {
 			this.typeError('posFromIndex', 'Number');
 		}
 		const str = String(this);
-		if (index >= -str.length && index <= str.length && Number.isInteger(index)) {
+		if (index >= -str.length && index <= str.length) {
 			const lines = str.slice(0, index).split('\n');
 			return {top: lines.length - 1, left: lines.at(-1).length};
 		}
@@ -606,12 +638,11 @@ class AstNode {
 	 * @complexity `n`
 	 */
 	indexFromPos(top, left) {
-		if (typeof top !== 'number' || typeof left !== 'number') {
+		if (!Number.isInteger(top) || !Number.isInteger(left)) {
 			this.typeError('indexFromPos', 'Number');
 		}
 		const lines = String(this).split('\n');
-		return top >= 0 && left >= 0 && Number.isInteger(top) && Number.isInteger(left)
-			&& lines.length >= top + 1 && lines[top].length >= left
+		return top >= 0 && left >= 0 && lines.length >= top + 1 && lines[top].length >= left
 			? lines.slice(0, top).reduce((acc, curLine) => acc + curLine.length + 1, 0) + left
 			: undefined;
 	}
@@ -641,9 +672,6 @@ class AstNode {
 	 * @complexity `n`
 	 */
 	getRelativeIndex(j) {
-		if (j !== undefined && typeof j !== 'number') {
-			this.typeError('getRelativeIndex', 'Number');
-		}
 		let /** @type {this[]} */ childNodes;
 
 		/**
@@ -714,6 +742,14 @@ class AstNode {
 		return this.#getDimension().width;
 	}
 
+	/**
+	 * 位置、大小和padding
+	 * @complexity `n`
+	 */
+	get style() {
+		return {...this.#getPosition(), ...this.#getDimension(), padding: this.getPadding()};
+	}
+
 	/**
 	 * 相对于父容器的行号
 	 * @complexity `n`
@@ -729,14 +765,6 @@ class AstNode {
 	get offsetLeft() {
 		return this.#getPosition().left;
 	}
-
-	/**
-	 * 位置、大小和padding
-	 * @complexity `n`
-	 */
-	get style() {
-		return {...this.#getPosition(), ...this.#getDimension(), padding: this.getPadding()};
-	}
 }
 
 Parser.classes.AstNode = __filename;

package/lib/ranges.js

@@ -62,7 +62,7 @@ class Range {
 
 	/**
 	 * 将Range转换为针对特定数组的下标集
-	 * @param {number|any[]} arr 参考数组
+	 * @param {number|*[]} arr 参考数组
 	 * @complexity `n`
 	 */
 	applyTo(arr) {
@@ -99,7 +99,7 @@ class Ranges extends Array {
 
 	/**
 	 * 将Ranges转换为针对特定Array的下标集
-	 * @param {number|any[]} arr 参考数组
+	 * @param {number|*[]} arr 参考数组
 	 * @complexity `n`
 	 */
 	applyTo(arr) {