@xmldom/xmldom 0.9.0-beta.8 → 0.9.0

package/lib/conventions.js

@@ -3,15 +3,15 @@
 /**
  * Ponyfill for `Array.prototype.find` which is only available in ES6 runtimes.
  *
- * Works with anything that has a `length` property and index access properties, including NodeList.
+ * Works with anything that has a `length` property and index access properties,
+ * including NodeList.
  *
- * @template {unknown} T
- * @param {Array<T> | ({length:number, [number]: T})} list
- * @param {function (item: T, index: number, list:Array<T> | ({length:number, [number]: T})):boolean} predicate
- * @param {Partial<Pick<ArrayConstructor['prototype'], 'find'>>?} ac `Array.prototype` by default,
- * 				allows injecting a custom implementation in tests
+ * @param {T[] | { length: number; [number]: T }} list
+ * @param {function (item: T, index: number, list:T[]):boolean} predicate
+ * @param {Partial<Pick<ArrayConstructor['prototype'], 'find'>>?} ac
+ * Allows injecting a custom implementation in tests (`Array.prototype` by default).
  * @returns {T | undefined}
- *
+ * @template {unknown} T
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
  * @see https://tc39.es/ecma262/multipage/indexed-collections.html#sec-array.prototype.find
  */
@@ -23,7 +23,7 @@ function find(list, predicate, ac) {
 		return ac.find.call(list, predicate);
 	}
 	for (var i = 0; i < list.length; i++) {
-		if (Object.prototype.hasOwnProperty.call(list, i)) {
+		if (hasOwn(list, i)) {
 			var item = list[i];
 			if (predicate.call(undefined, item, i, list)) {
 				return item;
@@ -39,31 +39,51 @@ function find(list, predicate, ac) {
  *
  * Is used to create "enum like" objects.
  *
- * @template T
- * @param {T} object the object to freeze
- * @param {Pick<ObjectConstructor, 'freeze'>} [oc=Object] `Object` by default,
- * 				allows to inject custom object constructor for tests
- * @returns {Readonly<T>}
+ * If `Object.getOwnPropertyDescriptors` is available,
+ * a new object with all properties of object but without any prototype is created and returned
+ * after freezing it.
  *
+ * @param {T} object
+ * The object to freeze.
+ * @param {Pick<ObjectConstructor, 'create' | 'freeze' | 'getOwnPropertyDescriptors'>} [oc=Object]
+ * `Object` by default,
+ * allows to inject custom object constructor for tests.
+ * @returns {Readonly<T>}
+ * @template {Object} T
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze
+ * @prettierignore
  */
 function freeze(object, oc) {
 	if (oc === undefined) {
 		oc = Object;
 	}
+	if (oc && typeof oc.getOwnPropertyDescriptors === 'function') {
+		object = oc.create(null, oc.getOwnPropertyDescriptors(object));
+	}
 	return oc && typeof oc.freeze === 'function' ? oc.freeze(object) : object;
 }
 
 /**
- * Since we can not rely on `Object.assign` we provide a simplified version
- * that is sufficient for our needs.
+ * Implementation for `Object.hasOwn` but ES5 compatible.
+ *
+ * @param {any} object
+ * @param {string | number} key
+ * @returns {boolean}
+ */
+function hasOwn(object, key) {
+	return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+/**
+ * Since xmldom can not rely on `Object.assign`,
+ * it uses/provides a simplified version that is sufficient for its needs.
  *
  * @param {Object} target
  * @param {Object | null | undefined} source
- *
- * @returns {Object} target
- * @throws TypeError if target is not an object
- *
+ * @returns {Object}
+ * The target with the merged/overridden properties.
+ * @throws {TypeError}
+ * If target is not an object.
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
  * @see https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.assign
  */
@@ -72,7 +92,7 @@ function assign(target, source) {
 		throw new TypeError('target is not an object');
 	}
 	for (var key in source) {
-		if (Object.prototype.hasOwnProperty.call(source, key)) {
+		if (hasOwn(source, key)) {
 			target[key] = source[key];
 		}
 	}
@@ -84,8 +104,8 @@ function assign(target, source) {
  * The presence of a boolean attribute on an element represents the `true` value,
  * and the absence of the attribute represents the `false` value.
  *
- * If the attribute is present, its value must either be the empty string
- * or a value that is an ASCII case-insensitive match for the attribute's canonical name,
+ * If the attribute is present, its value must either be the empty string, or a value that is
+ * an ASCII case-insensitive match for the attribute's canonical name,
  * with no leading or trailing whitespace.
  *
  * Note: The values `"true"` and `"false"` are not allowed on boolean attributes.
@@ -123,28 +143,46 @@ var HTML_BOOLEAN_ATTRIBUTES = freeze({
 
 /**
  * Check if `name` is matching one of the HTML boolean attribute names.
- * This method doesn't check if such attributes are allowed in the context of the current document/parsing.
+ * This method doesn't check if such attributes are allowed in the context of the current
+ * document/parsing.
  *
  * @param {string} name
- * @return {boolean}
- * @see HTML_BOOLEAN_ATTRIBUTES
+ * @returns {boolean}
+ * @see {@link HTML_BOOLEAN_ATTRIBUTES}
  * @see https://html.spec.whatwg.org/#boolean-attributes
  * @see https://html.spec.whatwg.org/#attributes-3
  */
 function isHTMLBooleanAttribute(name) {
-	return HTML_BOOLEAN_ATTRIBUTES.hasOwnProperty(name.toLowerCase());
+	return hasOwn(HTML_BOOLEAN_ATTRIBUTES, name.toLowerCase());
 }
 
 /**
  * Void elements only have a start tag; end tags must not be specified for void elements.
- * These elements should be written as self closing like this: `<area />`.
+ * These elements should be written as self-closing like this: `<area />`.
  * This should not be confused with optional tags that HTML allows to omit the end tag for
  * (like `li`, `tr` and others), which can have content after them,
- * so they can not be written as self closing.
- * xmldom does not have any logic for optional end tags cases and will report them as a warning.
- * Content that would go into the unopened element will instead be added as a sibling text node.
+ * so they can not be written as self-closing.
+ * xmldom does not have any logic for optional end tags cases,
+ * and will report them as a warning.
+ * Content that would go into the unopened element,
+ * will instead be added as a sibling text node.
  *
- * @type {Readonly<{area: boolean, col: boolean, img: boolean, wbr: boolean, link: boolean, hr: boolean, source: boolean, br: boolean, input: boolean, param: boolean, meta: boolean, embed: boolean, track: boolean, base: boolean}>}
+ * @type {Readonly<{
+ * 	area: boolean;
+ * 	col: boolean;
+ * 	img: boolean;
+ * 	wbr: boolean;
+ * 	link: boolean;
+ * 	hr: boolean;
+ * 	source: boolean;
+ * 	br: boolean;
+ * 	input: boolean;
+ * 	param: boolean;
+ * 	meta: boolean;
+ * 	embed: boolean;
+ * 	track: boolean;
+ * 	base: boolean;
+ * }>}
  * @see https://html.spec.whatwg.org/#void-elements
  * @see https://html.spec.whatwg.org/#optional-tags
  */
@@ -167,24 +205,24 @@ var HTML_VOID_ELEMENTS = freeze({
 
 /**
  * Check if `tagName` is matching one of the HTML void element names.
- * This method doesn't check if such tags are allowed
- * in the context of the current document/parsing.
+ * This method doesn't check if such tags are allowed in the context of the current
+ * document/parsing.
  *
  * @param {string} tagName
- * @return {boolean}
- * @see HTML_VOID_ELEMENTS
+ * @returns {boolean}
+ * @see {@link HTML_VOID_ELEMENTS}
  * @see https://html.spec.whatwg.org/#void-elements
  */
 function isHTMLVoidElement(tagName) {
-	return HTML_VOID_ELEMENTS.hasOwnProperty(tagName.toLowerCase());
+	return hasOwn(HTML_VOID_ELEMENTS, tagName.toLowerCase());
 }
 
 /**
  * Tag names that are raw text elements according to HTML spec.
  * The value denotes whether they are escapable or not.
  *
- * @see isHTMLEscapableRawTextElement
- * @see isHTMLRawTextElement
+ * @see {@link isHTMLEscapableRawTextElement}
+ * @see {@link isHTMLRawTextElement}
  * @see https://html.spec.whatwg.org/#raw-text-elements
  * @see https://html.spec.whatwg.org/#escapable-raw-text-elements
  */
@@ -197,90 +235,89 @@ var HTML_RAW_TEXT_ELEMENTS = freeze({
 
 /**
  * Check if `tagName` is matching one of the HTML raw text element names.
- * This method doesn't check if such tags are allowed
- * in the context of the current document/parsing.
+ * This method doesn't check if such tags are allowed in the context of the current
+ * document/parsing.
  *
  * @param {string} tagName
- * @return {boolean}
- * @see isHTMLEscapableRawTextElement
- * @see HTML_RAW_TEXT_ELEMENTS
+ * @returns {boolean}
+ * @see {@link isHTMLEscapableRawTextElement}
+ * @see {@link HTML_RAW_TEXT_ELEMENTS}
  * @see https://html.spec.whatwg.org/#raw-text-elements
  * @see https://html.spec.whatwg.org/#escapable-raw-text-elements
  */
 function isHTMLRawTextElement(tagName) {
 	var key = tagName.toLowerCase();
-	return HTML_RAW_TEXT_ELEMENTS.hasOwnProperty(key) && !HTML_RAW_TEXT_ELEMENTS[key];
+	return hasOwn(HTML_RAW_TEXT_ELEMENTS, key) && !HTML_RAW_TEXT_ELEMENTS[key];
 }
 /**
  * Check if `tagName` is matching one of the HTML escapable raw text element names.
- * This method doesn't check if such tags are allowed
- * in the context of the current document/parsing.
+ * This method doesn't check if such tags are allowed in the context of the current
+ * document/parsing.
  *
  * @param {string} tagName
- * @return {boolean}
- * @see isHTMLRawTextElement
- * @see HTML_RAW_TEXT_ELEMENTS
+ * @returns {boolean}
+ * @see {@link isHTMLRawTextElement}
+ * @see {@link HTML_RAW_TEXT_ELEMENTS}
  * @see https://html.spec.whatwg.org/#raw-text-elements
  * @see https://html.spec.whatwg.org/#escapable-raw-text-elements
  */
 function isHTMLEscapableRawTextElement(tagName) {
 	var key = tagName.toLowerCase();
-	return HTML_RAW_TEXT_ELEMENTS.hasOwnProperty(key) && HTML_RAW_TEXT_ELEMENTS[key];
+	return hasOwn(HTML_RAW_TEXT_ELEMENTS, key) && HTML_RAW_TEXT_ELEMENTS[key];
+}
+/**
+ * Only returns true if `value` matches MIME_TYPE.HTML, which indicates an HTML document.
+ *
+ * @param {string} mimeType
+ * @returns {mimeType is 'text/html'}
+ * @see https://www.iana.org/assignments/media-types/text/html
+ * @see https://en.wikipedia.org/wiki/HTML
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString
+ * @see https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-domparser-parsefromstring
+ */
+function isHTMLMimeType(mimeType) {
+	return mimeType === MIME_TYPE.HTML;
+}
+/**
+ * For both the `text/html` and the `application/xhtml+xml` namespace the spec defines that the
+ * HTML namespace is provided as the default.
+ *
+ * @param {string} mimeType
+ * @returns {boolean}
+ * @see https://dom.spec.whatwg.org/#dom-document-createelement
+ * @see https://dom.spec.whatwg.org/#dom-domimplementation-createdocument
+ * @see https://dom.spec.whatwg.org/#dom-domimplementation-createhtmldocument
+ */
+function hasDefaultHTMLNamespace(mimeType) {
+	return isHTMLMimeType(mimeType) || mimeType === MIME_TYPE.XML_XHTML_APPLICATION;
 }
 
 /**
  * All mime types that are allowed as input to `DOMParser.parseFromString`
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString#Argument02 MDN
- * @see https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#domparsersupportedtype WHATWG HTML Spec
- * @see DOMParser.prototype.parseFromString
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString#Argument02
+ *      MDN
+ * @see https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#domparsersupportedtype
+ *      WHATWG HTML Spec
+ * @see {@link DOMParser.prototype.parseFromString}
  */
 var MIME_TYPE = freeze({
 	/**
 	 * `text/html`, the only mime type that triggers treating an XML document as HTML.
 	 *
-	 * @see DOMParser.SupportedType.isHTML
 	 * @see https://www.iana.org/assignments/media-types/text/html IANA MimeType registration
 	 * @see https://en.wikipedia.org/wiki/HTML Wikipedia
 	 * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString MDN
-	 * @see https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-domparser-parsefromstring WHATWG HTML Spec
+	 * @see https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-domparser-parsefromstring
+	 *      WHATWG HTML Spec
 	 */
 	HTML: 'text/html',
 
-	/**
-	 * Helper method to check a mime type if it indicates an HTML document
-	 *
-	 * @param {string} [value]
-	 * @returns {boolean}
-	 *
-	 * @see [IANA MimeType registration](https://www.iana.org/assignments/media-types/text/html)
-	 * @see [Wikipedia](https://en.wikipedia.org/wiki/HTML)
-	 * @see [`DOMParser.parseFromString` @ MDN](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString)
-	 * @see [`DOMParser.parseFromString` @ HTML Specification](https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-domparser-parsefromstring)
-	 */
-	isHTML: function (value) {
-		return value === MIME_TYPE.HTML;
-	},
-
-	/**
-	 * For both the `text/html` and the `application/xhtml+xml` namespace
-	 * the spec defines that the HTML namespace is provided as the default in some cases.
-	 *
-	 * @param {string} mimeType
-	 * @returns {boolean}
-	 *
-	 * @see https://dom.spec.whatwg.org/#dom-document-createelement
-	 * @see https://dom.spec.whatwg.org/#dom-domimplementation-createdocument
-	 * @see https://dom.spec.whatwg.org/#dom-domimplementation-createhtmldocument
-	 */
-	hasDefaultHTMLNamespace: function (mimeType) {
-		return MIME_TYPE.isHTML(mimeType) || mimeType === MIME_TYPE.XML_XHTML_APPLICATION;
-	},
-
 	/**
 	 * `application/xml`, the standard mime type for XML documents.
 	 *
-	 * @see https://www.iana.org/assignments/media-types/application/xml IANA MimeType registration
+	 * @see https://www.iana.org/assignments/media-types/application/xml IANA MimeType
+	 *      registration
 	 * @see https://tools.ietf.org/html/rfc7303#section-9.1 RFC 7303
 	 * @see https://en.wikipedia.org/wiki/XML_and_MIME Wikipedia
 	 */
@@ -299,7 +336,8 @@ var MIME_TYPE = freeze({
 	 * `application/xhtml+xml`, indicates an XML document that has the default HTML namespace,
 	 * but is parsed as an XML document.
 	 *
-	 * @see https://www.iana.org/assignments/media-types/application/xhtml+xml IANA MimeType registration
+	 * @see https://www.iana.org/assignments/media-types/application/xhtml+xml IANA MimeType
+	 *      registration
 	 * @see https://dom.spec.whatwg.org/#dom-domimplementation-createdocument WHATWG DOM Spec
 	 * @see https://en.wikipedia.org/wiki/XHTML Wikipedia
 	 */
@@ -314,7 +352,30 @@ var MIME_TYPE = freeze({
 	 */
 	XML_SVG_IMAGE: 'image/svg+xml',
 });
+/**
+ * @typedef {'application/xhtml+xml' | 'application/xml' | 'image/svg+xml' | 'text/html' | 'text/xml'}
+ * MimeType
+ */
+/**
+ * @type {MimeType[]}
+ * @private
+ * Basically `Object.values`, which is not available in ES5.
+ */
+var _MIME_TYPES = Object.keys(MIME_TYPE).map(function (key) {
+	return MIME_TYPE[key];
+});
 
+/**
+ * Only returns true if `mimeType` is one of the allowed values for
+ * `DOMParser.parseFromString`.
+ *
+ * @param {string} mimeType
+ * @returns {mimeType is 'application/xhtml+xml' | 'application/xml' | 'image/svg+xml' |  'text/html' | 'text/xml'}
+ *
+ */
+function isValidMimeType(mimeType) {
+	return _MIME_TYPES.indexOf(mimeType) > -1;
+}
 /**
  * Namespaces that are used in this code base.
  *
@@ -328,17 +389,6 @@ var NAMESPACE = freeze({
 	 */
 	HTML: 'http://www.w3.org/1999/xhtml',
 
-	/**
-	 * Checks if `uri` equals `NAMESPACE.HTML`.
-	 *
-	 * @param {string} [uri]
-	 *
-	 * @see NAMESPACE.HTML
-	 */
-	isHTML: function (uri) {
-		return uri === NAMESPACE.HTML;
-	},
-
 	/**
 	 * The SVG namespace.
 	 *
@@ -354,44 +404,26 @@ var NAMESPACE = freeze({
 	XML: 'http://www.w3.org/XML/1998/namespace',
 
 	/**
-	 * The `xmlns:` namespace
+	 * The `xmlns:` namespace.
 	 *
 	 * @see https://www.w3.org/2000/xmlns/
 	 */
 	XMLNS: 'http://www.w3.org/2000/xmlns/',
 });
 
-// https://www.w3.org/TR/xml-names/#ns-decl
-// https://www.w3.org/TR/REC-xml/#NT-Name
-// https://www.w3.org/TR/xml-names/#ns-qualnames
-// NAME_START_CHAR without ":"
-var QNAME_START_CHAR =
-	/[A-Z_a-z\xC0-\xD6\xD8-\xF6\u00F8-\u02FF\u0370-\u037D\u037F-\u1FFF\u200C-\u200D\u2070-\u218F\u2C00-\u2FEF\u3001-\uD7FF\uF900-\uFDCF\uFDF0-\uFFFD]/; //\u10000-\uEFFFF
-//[4]   	NameStartChar	   ::=   	":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | [#x370-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
-var NAME_START_CHAR = new RegExp('[:' + QNAME_START_CHAR.source.slice(1, -1) + ']');
-var NAME_CHAR = new RegExp('[\\-\\.0-9' + NAME_START_CHAR.source.slice(1, -1) + '\\u00B7\\u0300-\\u036F\\u203F-\\u2040]');
-//[4a]   	NameChar	   ::=   	NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
-// NAME_CHAR without ":"
-var QNAME_CHAR = new RegExp('[\\-\\.0-9' + QNAME_START_CHAR.source.slice(1, -1) + '\\u00B7\\u0300-\\u036F\\u203F-\\u2040]*');
-// https://www.w3.org/TR/xml-names/#NT-NCName
-var NCNAME = QNAME_START_CHAR.source + QNAME_CHAR.source;
-// https://www.w3.org/TR/xml-names/#ns-qualnames
-var QNAME = new RegExp('^' + NCNAME + '(?::' + NCNAME + ')?$');
-
 exports.assign = assign;
 exports.find = find;
 exports.freeze = freeze;
 exports.HTML_BOOLEAN_ATTRIBUTES = HTML_BOOLEAN_ATTRIBUTES;
 exports.HTML_RAW_TEXT_ELEMENTS = HTML_RAW_TEXT_ELEMENTS;
 exports.HTML_VOID_ELEMENTS = HTML_VOID_ELEMENTS;
+exports.hasDefaultHTMLNamespace = hasDefaultHTMLNamespace;
+exports.hasOwn = hasOwn;
 exports.isHTMLBooleanAttribute = isHTMLBooleanAttribute;
 exports.isHTMLRawTextElement = isHTMLRawTextElement;
 exports.isHTMLEscapableRawTextElement = isHTMLEscapableRawTextElement;
+exports.isHTMLMimeType = isHTMLMimeType;
 exports.isHTMLVoidElement = isHTMLVoidElement;
+exports.isValidMimeType = isValidMimeType;
 exports.MIME_TYPE = MIME_TYPE;
-exports.NAME_CHAR = NAME_CHAR;
-exports.NAME_START_CHAR = NAME_START_CHAR;
 exports.NAMESPACE = NAMESPACE;
-exports.QNAME = QNAME;
-exports.QNAME_CHAR = QNAME_CHAR;
-exports.QNAME_START_CHAR = QNAME_START_CHAR;