@xmldom/xmldom 0.9.0-beta.9 → 0.9.0

package/lib/dom-parser.js

@@ -2,6 +2,7 @@
 
 var conventions = require('./conventions');
 var dom = require('./dom');
+var errors = require('./errors');
 var entities = require('./entities');
 var sax = require('./sax');
 
@@ -12,7 +13,7 @@ var isHTMLMimeType = conventions.isHTMLMimeType;
 var isValidMimeType = conventions.isValidMimeType;
 var MIME_TYPE = conventions.MIME_TYPE;
 var NAMESPACE = conventions.NAMESPACE;
-var ParseError = conventions.ParseError;
+var ParseError = errors.ParseError;
 
 var XMLReader = sax.XMLReader;
 
@@ -28,14 +29,15 @@ var XMLReader = sax.XMLReader;
  * > as if it normalized all line breaks in external parsed entities (including the document entity)
  * > on input, before parsing, by translating all of the following to a single #xA character:
  * >
- * > 1. the two-character sequence #xD #xA
- * > 2. the two-character sequence #xD #x85
- * > 3. the single character #x85
- * > 4. the single character #x2028
+ * > 1. the two-character sequence #xD #xA,
+ * > 2. the two-character sequence #xD #x85,
+ * > 3. the single character #x85,
+ * > 4. the single character #x2028,
  * > 5. any #xD character that is not immediately followed by #xA or #x85.
  *
  * @param {string} input
  * @returns {string}
+ * @prettierignore
  */
 function normalizeLineEndings(input) {
 	return input.replace(/\r[\n\u0085]/g, '\n').replace(/[\r\u0085\u2028]/g, '\n');
@@ -49,17 +51,18 @@ function normalizeLineEndings(input) {
 
 /**
  * @typedef DOMParserOptions
- * @property {typeof conventions.assign} [assign=Object.assign || conventions.assign]
- * The method to use instead of `Object.assign` (or if not available `conventions.assign`),
- * which is used to copy values from the options before they are used for parsing.
+ * @property {typeof assign} [assign]
+ * The method to use instead of `conventions.assign`, which is used to copy values from
+ * `options` before they are used for parsing.
  * @property {typeof DOMHandler} [domHandler]
- * For internal testing: The class for creating an instance for handling events from the SAX parser.
- * __**Warning: By configuring a faulty implementation,
- * the specified behavior can completely be broken.**__
- *
+ * For internal testing: The class for creating an instance for handling events from the SAX
+ * parser.
+ * *****Warning: By configuring a faulty implementation, the specified behavior can completely
+ * be broken.*****.
  * @property {Function} [errorHandler]
  * DEPRECATED! use `onError` instead.
- * @property {function(level:ErrorLevel, message:string, context: DOMHandler):void} [onError]
+ * @property {function(level:ErrorLevel, message:string, context: DOMHandler):void}
+ * [onError]
  * A function that is invoked for every error that occurs during parsing.
  *
  * If it is not provided, all errors are reported to `console.error`
@@ -68,36 +71,32 @@ function normalizeLineEndings(input) {
  * If the provided method throws, a `ParserError` is thrown,
  * which prevents any further processing.
  *
- * Be aware that many `warning`s are considered an error
- * that prevents further processing in most implementations.
- *.
+ * Be aware that many `warning`s are considered an error that prevents further processing in
+ * most implementations.
  * @property {boolean} [locator=true]
- * Configures if the nodes created during parsing
- * will have a `lineNumber` and a `columnNumber` attribute
- * describing their location in the XML string.
+ * Configures if the nodes created during parsing will have a `lineNumber` and a `columnNumber`
+ * attribute describing their location in the XML string.
  * Default is true.
  * @property {(string) => string} [normalizeLineEndings]
  * used to replace line endings before parsing, defaults to `normalizeLineEndings`
- * @property {object} [xmlns]
+ * @property {Object} [xmlns]
  * The XML namespaces that should be assumed when parsing.
  * The default namespace can be provided by the key that is the empty string.
  * When the `mimeType` for HTML, XHTML or SVG are passed to `parseFromString`,
  * the default namespace that will be used,
  * will be overridden according to the specification.
- *
- * @see normalizeLineEndings
+ * @see {@link normalizeLineEndings}
  */
 
 /**
- * The DOMParser interface provides the ability to parse XML or HTML source code
- * from a string into a DOM `Document`.
+ * The DOMParser interface provides the ability to parse XML or HTML source code from a string
+ * into a DOM `Document`.
  *
- * _xmldom is different from the spec in that it allows an `options` parameter,
- * to control the behavior._
+ * ***xmldom is different from the spec in that it allows an `options` parameter,
+ * to control the behavior***.
  *
+ * @class
  * @param {DOMParserOptions} [options]
- * @constructor
- *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser
  * @see https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#dom-parsing-and-serialization
  */
@@ -105,23 +104,26 @@ function DOMParser(options) {
 	options = options || { locator: true };
 
 	/**
-	 * The method to use instead of `Object.assign` (defaults to or `conventions.assign`),
-	 * which is used to copy values from the options before they are used for parsing.
+	 * The method to use instead of `conventions.assign`, which is used to copy values from
+	 * `options`
+	 * before they are used for parsing.
 	 *
-	 * @type {function (target: object, source: object | null | undefined): object}
-	 * @readonly
+	 * @type {conventions.assign}
 	 * @private
-	 * @see conventions.assign
+	 * @see {@link conventions.assign}
+	 * @readonly
 	 */
 	this.assign = options.assign || conventions.assign;
 
 	/**
-	 * For internal testing: The class for creating an instance for handling events from the SAX parser.
-	 * __**Warning: By configuring a faulty implementation, the specified behavior can completely be broken.**__
+	 * For internal testing: The class for creating an instance for handling events from the SAX
+	 * parser.
+	 * *****Warning: By configuring a faulty implementation, the specified behavior can completely
+	 * be broken*****.
 	 *
 	 * @type {typeof DOMHandler}
-	 * @readonly
 	 * @private
+	 * @readonly
 	 */
 	this.domHandler = options.domHandler || DOMHandler;
 
@@ -134,13 +136,12 @@ function DOMParser(options) {
 	 * If the provided method throws, a `ParserError` is thrown,
 	 * which prevents any further processing.
 	 *
-	 * Be aware that many `warning`s are considered an error
-	 * that prevents further processing in most implementations.
+	 * Be aware that many `warning`s are considered an error that prevents further processing in
+	 * most implementations.
 	 *
 	 * @type {function(level:ErrorLevel, message:string, context: DOMHandler):void}
-	 *
-	 * @see onErrorStopParsing
-	 * @see onWarningStopParsing
+	 * @see {@link onErrorStopParsing}
+	 * @see {@link onWarningStopParsing}
 	 */
 	this.onError = options.onError || options.errorHandler;
 	if (options.errorHandler && typeof options.errorHandler !== 'function') {
@@ -158,10 +159,11 @@ function DOMParser(options) {
 	this.normalizeLineEndings = options.normalizeLineEndings || normalizeLineEndings;
 
 	/**
-	 * Configures if the nodes created during parsing
-	 * will have a `lineNumber` and a `columnNumber` attribute
-	 * describing their location in the XML string.
+	 * Configures if the nodes created during parsing will have a `lineNumber` and a
+	 * `columnNumber`
+	 * attribute describing their location in the XML string.
 	 * Default is true.
+	 *
 	 * @type {boolean}
 	 * @readonly
 	 */
@@ -172,36 +174,39 @@ function DOMParser(options) {
 	 * When the `mimeType` for HTML, XHTML or SVG are passed to `parseFromString`,
 	 * the default namespace that will be used,
 	 * will be overridden according to the specification.
-	 * @type {Readonly<object>}
+	 *
+	 * @type {Readonly<Object>}
 	 * @readonly
 	 */
-	this.xmlns = options.xmlns || {};
+	this.xmlns = this.assign(Object.create(null), options.xmlns);
 }
 
 /**
  * Parses `source` using the options in the way configured by the `DOMParserOptions` of `this`
- * `DOMParser`. If `mimeType` is `text/html` an HTML `Document` is created, otherwise an XML
- * `Document` is created.
+ * `DOMParser`. If `mimeType` is `text/html` an HTML `Document` is created,
+ * otherwise an XML `Document` is created.
  *
  * __It behaves different from the description in the living standard__:
- * - Uses the `options` passed to the `DOMParser` constructor to modify the
- *   behavior.
- * - Any unexpected input is reported to `onError` with either a `warning`, `error` or `fatalError` level.
- *   - Any `fatalError` throws a `ParseError` which prevents further processing.
- *   - Any error thrown by `onError` is converted to a `ParseError` which prevents further processing
- * - If no `Document` was created during parsing it is reported as a `fatalError`.
- * __**Warning: By configuring a faulty DOMHandler implementation,
- * the specified behavior can completely be broken.**__
+ * - Uses the `options` passed to the `DOMParser` constructor to modify the behavior.
+ * - Any unexpected input is reported to `onError` with either a `warning`,
+ * `error` or `fatalError` level.
+ * - Any `fatalError` throws a `ParseError` which prevents further processing.
+ * - Any error thrown by `onError` is converted to a `ParseError` which prevents further
+ * processing - If no `Document` was created during parsing it is reported as a `fatalError`.
+ * *****Warning: By configuring a faulty DOMHandler implementation,
+ * the specified behavior can completely be broken*****.
  *
- * @param {string} source The XML mime type only allows string input!
+ * @param {string} source
+ * The XML mime type only allows string input!
  * @param {string} [mimeType='application/xml']
- *        the mimeType or contentType of the document to be created
- *        determines the `type` of document created (XML or HTML)
- *
- * @throws ParseError for any `fatalError` or anything that is thrown by `onError`
- * @throws TypeError for any invalid `mimeType`
- * @returns the `Document` node
- *
+ * the mimeType or contentType of the document to be created determines the `type` of document
+ * created (XML or HTML)
+ * @returns {Document}
+ * The `Document` node.
+ * @throws {ParseError}
+ * for any `fatalError` or anything that is thrown by `onError`
+ * @throws {TypeError}
+ * for any invalid `mimeType`
  * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString
  * @see https://html.spec.whatwg.org/#dom-domparser-parsefromstring-dev
  */
@@ -209,7 +214,7 @@ DOMParser.prototype.parseFromString = function (source, mimeType) {
 	if (!isValidMimeType(mimeType)) {
 		throw new TypeError('DOMParser.parseFromString: the provided mimeType "' + mimeType + '" is not valid.');
 	}
-	var defaultNSMap = this.assign({}, this.xmlns);
+	var defaultNSMap = this.assign(Object.create(null), this.xmlns);
 	var entityMap = entities.XML_ENTITIES;
 	var defaultNamespace = defaultNSMap[''] || null;
 	if (hasDefaultHTMLNamespace(mimeType)) {
@@ -248,15 +253,16 @@ DOMParser.prototype.parseFromString = function (source, mimeType) {
 /**
  * @typedef DOMHandlerOptions
  * @property {string} [mimeType=MIME_TYPE.XML_APPLICATION]
- * @property {string|null} [defaultNamespace=null]
+ * @property {string | null} [defaultNamespace=null]
  */
 /**
- * The class that is used to handle events from the SAX parser to create the related DOM elements.
+ * The class that is used to handle events from the SAX parser to create the related DOM
+ * elements.
  *
  * Some methods are only implemented as an empty function,
  * since they are (at least currently) not relevant for xmldom.
  *
- * @constructor
+ * @class
  * @param {DOMHandlerOptions} [options]
  * @see http://www.saxproject.org/apidoc/org/xml/sax/ext/DefaultHandler2.html
  */
@@ -268,8 +274,8 @@ function DOMHandler(options) {
 	 * It defaults to MIME_TYPE.XML_APPLICATION.
 	 *
 	 * @type {string}
+	 * @see {@link MIME_TYPE}
 	 * @readonly
-	 * @see MIME_TYPE
 	 */
 	this.mimeType = opt.mimeType || MIME_TYPE.XML_APPLICATION;
 
@@ -277,21 +283,23 @@ function DOMHandler(options) {
 	 * The namespace to use to create an XML document.
 	 * For the following reasons this is required:
 	 * - The SAX API for `startDocument` doesn't offer any way to pass a namespace,
-	 *   since at that point there is no way for the parser to know what the default namespace from the document will be.
-	 * - When creating using `DOMImplementation.createDocument` it is required to pass a namespace,
-	 *   to determine the correct `Document.contentType`, which should match `this.mimeType`.
+	 * since at that point there is no way for the parser to know what the default namespace from
+	 * the document will be.
+	 * - When creating using `DOMImplementation.createDocument` it is required to pass a
+	 * namespace,
+	 * to determine the correct `Document.contentType`, which should match `this.mimeType`.
 	 * - When parsing an XML document with the `application/xhtml+xml` mimeType,
-	 *   the HTML namespace needs to be the default namespace.
+	 * the HTML namespace needs to be the default namespace.
 	 *
-	 * @type {string|null}
-	 * @readonly
+	 * @type {string | null}
 	 * @private
+	 * @readonly
 	 */
 	this.defaultNamespace = opt.defaultNamespace || null;
 
 	/**
-	 * @private
 	 * @type {boolean}
+	 * @private
 	 */
 	this.cdata = false;
 
@@ -317,14 +325,14 @@ function DOMHandler(options) {
 
 	/**
 	 * The locator is stored as part of setDocumentLocator.
-	 * It is controlled and mutated by the SAX parser
-	 * to store the current parsing position.
+	 * It is controlled and mutated by the SAX parser to store the current parsing position.
 	 * It is used by DOMHandler to set `columnNumber` and `lineNumber`
 	 * on the DOM nodes.
 	 *
 	 * @type {Readonly<Locator> | undefined}
-	 * @readonly (the sax parser currently sometimes set's it)
 	 * @private
+	 * @readonly (the
+	 * sax parser currently sometimes set's it)
 	 */
 	this.locator = undefined;
 	/**
@@ -346,7 +354,7 @@ DOMHandler.prototype = {
 	 * and it will not contain any `childNodes`.
 	 * If it is an HTML document, it will be created without any `childNodes`.
 	 *
-	 * @see  http://www.saxproject.org/apidoc/org/xml/sax/ContentHandler.html
+	 * @see http://www.saxproject.org/apidoc/org/xml/sax/ContentHandler.html
 	 */
 	startDocument: function () {
 		var impl = new DOMImplementation();
@@ -463,9 +471,12 @@ DOMHandler.prototype = {
 	/**
 	 * This function reports a fatal error and throws a ParseError.
 	 *
-	 * @param {string} message - The message to be used for reporting and throwing the error.
-	 * @returns {never} This function always throws an error and never returns a value.
-	 * @throws {ParseError} Always throws a ParseError with the provided message.
+	 * @param {string} message
+	 * - The message to be used for reporting and throwing the error.
+	 * @returns {never}
+	 * This function always throws an error and never returns a value.
+	 * @throws {ParseError}
+	 * Always throws a ParseError with the provided message.
 	 */
 	fatalError: function (message) {
 		this.reportError('fatalError', message);
@@ -544,8 +555,8 @@ function appendElement(handler, node) {
  * A method that prevents any further parsing when an `error`
  * with level `error` is reported during parsing.
  *
- * @see DOMParserOptions.onError
- * @see onWarningStopParsing
+ * @see {@link DOMParserOptions.onError}
+ * @see {@link onWarningStopParsing}
  */
 function onErrorStopParsing(level) {
 	if (level === 'error') throw 'onErrorStopParsing';
@@ -554,8 +565,8 @@ function onErrorStopParsing(level) {
 /**
  * A method that prevents any further parsing when any `error` is reported during parsing.
  *
- * @see DOMParserOptions.onError
- * @see onErrorStopParsing
+ * @see {@link DOMParserOptions.onError}
+ * @see {@link onErrorStopParsing}
  */
 function onWarningStopParsing() {
 	throw 'onWarningStopParsing';