Remove XMLSerializer export

This changes the package to stop exporting the XMLSerializer class, since it was fairly useless anyway. Instead, the main module default exports the serialize() function directly, which is more straightforward and just as good for standalone consumers. jsdom can wrap serialize() in its own XMLSerializer implementation.

The serialize() function was changed from taking a boolean second parameter to taking an options object. Additionally, it no longer catches exceptions and re-throws them as DOMExceptions using the domexception package; instead it throws Errors (for well-formedness) or TypeErrors (for misuse) directly.

We also consolidate all the tests into a single file, as the division between them was fuzzy.

Finally, the package now requires Node.js v10 or later.

Author: domenic

.eslintignore

@@ -25,7 +25,7 @@
     "no-empty-character-class": "error",
     "no-ex-assign": "error",
     "no-extra-boolean-cast": "error",
-    "no-extra-parens": ["error", "all", { "conditionalAssign": false, "nestedBinaryExpressions": false, "returnAssign": false }],
+    "no-extra-parens": ["error", "all", { "conditionalAssign": false, "nestedBinaryExpressions": false, "returnAssign": false, "enforceForNewInMemberExpressions": false }],
     "no-extra-semi": "error",
     "no-func-assign": "error",
     "no-inner-declarations": "off",

.eslintrc.json

@@ -1,4 +1 @@
 node_modules/
-
-lib/utils.js
-lib/XMLSerializer.js

.gitignore

@@ -1,7 +1,16 @@
 language: node_js
 node_js:
-  - 8
+  - 10
+  - 12
   - stable
+
+install:
+  - yarn --frozen-lockfile
+
 script:
-  - npm run lint
-  - npm test
+  - yarn lint
+  - yarn test
+
+branches:
+  only:
+    - master

.travis.yml

@@ -2,19 +2,40 @@
 
 An XML serializer that follows the [W3C specification](https://w3c.github.io/DOM-Parsing/).
 
-This module is mostly used as an internal part of [jsdom](https://github.com/jsdom/jsdom). However, you can use it independently with some care. That isn't very well-documented yet, but hopefully the below sample can give you an idea.
+This package can be used in Node.js, as long as you feed it a DOM node, e.g. one produced by [jsdom](https://github.com/jsdom/jsdom).
 
 ## Basic usage
 
+Assume you have a DOM tree rooted at a node `node`. In Node.js, you could create this using [jsdom](https://github.com/jsdom/jsdom) as follows:
+
 ```js
-const { XMLSerializer } = require("w3c-xmlserializer");
 const { JSDOM } = require("jsdom");
 
 const { document } = new JSDOM().window;
-const XMLSerializer = XMLSerializer.interface;
-const serializer = new XMLSerializer();
-const doc = document.createElement("akomaNtoso");
+const node = document.createElement("akomaNtoso");
+```
+
+Then, you use this package as follows:
+
 
-console.log(serializer.serializeToString(doc));
+```js
+const serialize = require("w3c-xmlserializer");
+
+console.log(serialize(node));
 // => '<akomantoso xmlns="http://www.w3.org/1999/xhtml"></akomantoso>'
 ```
+
+## `requireWellFormed` option
+
+By default the input DOM tree is not required to be "well-formed"; any given input will serialize to some output string. You can instead require well-formedness via
+
+```js
+serialize(node, { requireWellFormed: true });
+```
+
+which will cause `Error`s to be thrown when non-well-formed constructs are encountered. [Per the spec](https://w3c.github.io/DOM-Parsing/#dfn-require-well-formed), this largely is about imposing constraints on the names of elements, attributes, etc.
+
+As a point of reference, on the web platform:
+
+* The [`innerHTML` getter](https://w3c.github.io/DOM-Parsing/#dom-innerhtml-innerhtml) uses the require-well-formed mode, i.e. trying to get the `innerHTML` of non-well-formed subtrees will throw.
+* The [`xhr.send()` method](https://xhr.spec.whatwg.org/#the-send()-method) does not require well-formedness, i.e. sending non-well-formed `Document`s will serialize and send them anyway.

README.md

@@ -1,6 +1,5 @@
 "use strict";
 
-const DOMException = require("domexception");
 const xnv = require("xml-name-validator");
 
 const attributeUtils = require("./attributes");
@@ -61,15 +60,15 @@ function recordNamespaceInformation(element, map, prefixMap) {
 
 function serializeDocumentType(node, namespace, prefixMap, requireWellFormed) {
   if (requireWellFormed && !PUBID_CHAR.test(node.publicId)) {
-    throw new Error("Node publicId is not well formed");
+    throw new Error("Failed to serialize XML: document type node publicId is not well-formed.");
   }
 
   if (
     requireWellFormed &&
     (!XML_CHAR.test(node.systemId) ||
       (node.systemId.includes('"') && node.systemId.includes("'")))
   ) {
-    throw new Error("Node systemId is not well formed");
+    throw new Error("Failed to serialize XML: document type node systemId is not well-formed.");
   }
 
   let markup = `<!DOCTYPE ${node.name}`;
@@ -94,13 +93,13 @@ function serializeProcessingInstruction(
     requireWellFormed &&
     (node.target.includes(":") || asciiCaseInsensitiveMatch(node.target, "xml"))
   ) {
-    throw new Error("Node target is not well formed");
+    throw new Error("Failed to serialize XML: processing instruction node target is not well-formed.");
   }
   if (
     requireWellFormed &&
     (!XML_CHAR.test(node.data) || node.data.includes("?>"))
   ) {
-    throw new Error("Node data is not well formed");
+    throw new Error("Failed to serialize XML: processing instruction node data is not well-formed.");
   }
   return `<?${node.target} ${node.data}?>`;
 }
@@ -113,7 +112,7 @@ function serializeDocument(
   refs
 ) {
   if (requireWellFormed && node.documentElement === null) {
-    throw new Error("Document does not have a document element");
+    throw new Error("Failed to serialize XML: document does not have a document element.");
   }
   let serializedDocument = "";
   for (const child of node.childNodes) {
@@ -150,7 +149,7 @@ function serializeDocumentFragment(
 
 function serializeText(node, namespace, prefixMap, requireWellFormed) {
   if (requireWellFormed && !XML_CHAR.test(node.data)) {
-    throw new Error("Node data is not well formed");
+    throw new Error("Failed to serialize XML: text node data is not well-formed.");
   }
 
   return node.data
@@ -161,14 +160,14 @@ function serializeText(node, namespace, prefixMap, requireWellFormed) {
 
 function serializeComment(node, namespace, prefixMap, requireWellFormed) {
   if (requireWellFormed && !XML_CHAR.test(node.data)) {
-    throw new Error("Node data is not well formed");
+    throw new Error("Failed to serialize XML: comment node data is not well-formed.");
   }
 
   if (
     requireWellFormed &&
     (node.data.includes("--") || node.data.endsWith("-"))
   ) {
-    throw new Error("Found hyphens in illegal places");
+    throw new Error("Failed to serialize XML: found hyphens in illegal places in comment node data.");
   }
   return `<!--${node.data}-->`;
 }
@@ -178,7 +177,7 @@ function serializeElement(node, namespace, prefixMap, requireWellFormed, refs) {
     requireWellFormed &&
     (node.localName.includes(":") || !xnv.name(node.localName))
   ) {
-    throw new Error("localName is not a valid XML name");
+    throw new Error("Failed to serialize XML: element node localName is not a valid XML name.");
   }
   let markup = "<";
   let qualifiedName = "";
@@ -208,7 +207,7 @@ function serializeElement(node, namespace, prefixMap, requireWellFormed, refs) {
     let candidatePrefix = attributeUtils.preferredPrefixString(map, ns, prefix);
     if (prefix === "xmlns") {
       if (requireWellFormed) {
-        throw new Error("Elements can't have xmlns prefix");
+        throw new Error("Failed to serialize XML: element nodes can't have a prefix of \"xmlns\".");
       }
       candidatePrefix = "xmlns";
     }
@@ -359,21 +358,14 @@ function xmlSerialization(node, namespace, prefixMap, requireWellFormed, refs) {
     case NODE_TYPES.CDATA_SECTION_NODE:
       return serializeCDATASection(node);
     default:
-      throw new TypeError("Only Nodes and Attr objects can be serialized");
+      throw new TypeError("Failed to serialize XML: only Nodes can be serialized.");
   }
 }
 
-module.exports.produceXMLSerialization = (root, requireWellFormed) => {
+module.exports = (root, { requireWellFormed = false } = {}) => {
   const namespacePrefixMap = Object.create(null);
   namespacePrefixMap["http://www.w3.org/XML/1998/namespace"] = ["xml"];
-  try {
-    return xmlSerialization(root, null, namespacePrefixMap, requireWellFormed, {
-      prefixIndex: 1
-    });
-  } catch (e) {
-    throw new DOMException(
-      "Failed to serialize XML: " + e.message,
-      "InvalidStateError"
-    );
-  }
+  return xmlSerialization(root, null, namespacePrefixMap, requireWellFormed, {
+    prefixIndex: 1
+  });
 };

lib/XMLSerializer-impl.js

@@ -10,25 +10,23 @@
   "version": "1.1.2",
   "license": "MIT",
   "dependencies": {
-    "domexception": "^1.0.1",
-    "webidl-conversions": "^4.0.2",
     "xml-name-validator": "^3.0.0"
   },
   "devDependencies": {
-    "eslint": "^5.15.2",
-    "jest": "^24.5.0",
-    "jsdom": "^14.0.0",
-    "webidl2js": "^9.2.0"
+    "eslint": "^6.8.0",
+    "jest": "^24.9.0",
+    "jsdom": "^15.2.1"
   },
   "repository": "jsdom/w3c-xmlserializer",
   "files": [
     "lib/"
   ],
-  "main": "lib/index.js",
+  "main": "lib/serialize.js",
   "scripts": {
-    "prepare": "node scripts/convert-idl.js",
-    "pretest": "node scripts/convert-idl.js",
     "test": "jest",
     "lint": "eslint ."
+  },
+  "engines": {
+    "node": ">=10"
   }
 }