borgar · borgar · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ There are some limitations:
 
 - Comments are discarded.
 - Processing instructions are discarded.
-- Namespace prefixes are preserved but otherwise ignored.
+- Namespace prefixes are preserved on every node; full xmlns validation is opt-in via the `ns` parse option.
 - Doctypes are discarded.
 - Nested doctypes are not supported and will cause errors.
 - Nodes have a limited interface.
@@ -34,10 +34,10 @@ $ npm i @borgar/simple-xml
 import { parseXML } from '@borgar/simple-xml';
 
 const dom = parseXML('<root><node>Lorem ipsum</node></root>');
-console.log(dom.getElementsByTagName('node').textContent);
+console.log(dom.getElementsByTagName('node')[0].textContent);
 ```
 
-The parse function accepts two arguments, the first is an XML source. The second is an options object. There are two options:
+The parse function accepts two arguments, the first is an XML source. The second is an options object. There are three options:
 
 Allow normally forbidden unquoted attributes with `laxAttr`:
 
@@ -51,7 +51,13 @@ Allow normally forbidden "rootless" documents with `emptyDoc`:
 parseXML('', { emptyDoc: true });
 ```
 
-As well as a parse method, the package exports Node classes: Node, Element, Document, TextNode, and CDataNode. They are pretty much what you expect but with an incomplete or altered set of DOM API functions.
+Validate `xmlns` declarations and element/attribute prefixes against them with `ns`. With this flag, an unknown prefix or a re-bound prefix throws a `NamespaceError`:
+
+```js
+parseXML('<root xmlns:x="urn:example"><x:node /></root>', { ns: true });
+```
+
+As well as a parse method, the package exports the node classes (`Node`, `Element`, `Document`, `DocumentFragment`, `TextNode`, `CDataNode`), serialization helpers (`prettyPrint`, `simplePrint`, `escapeXML`), the `isElement` type guard, and an error hierarchy rooted at `XMLError` (`ParserError`, `NamespaceError`, `HierarchyError`, `NotFoundError`). The node classes are pretty much what you'd expect but with an "incomplete" or altered set of DOM API functions.
 
 [See the API documentation.](API.md)
 
@@ -68,20 +74,24 @@ As well as a parse method, the package exports Node classes: Node, Element, Docu
 * `.nodeType`
  A node type number (e.g. `Element.ELEMENT_NODE === 1`)
 
-* `.ns`
- A namespace identifier (`foo` in the case of `<foo:bar>`)
+* `.prefix`
+ The namespace prefix of the element, or `null` if it has none (`foo` in the case of `<foo:bar>`).
+
+* `.localName`
+ The tag name with any namespace prefix stripped (`bar` in the case of `<foo:bar>`).
 
 * `.fullName`
-A full tag name with identifier (`foo:bar` in the case of `<foo:bar>`)
+The full tag name including the prefix (`foo:bar` in the case of `<foo:bar>`).
 
 **Attributes**
 
 * `.getAttribute( attrName )`
 * `.setAttribute( attrName, attrValue )`
 * `.hasAttribute( attrName )`
+* `.hasAttributes()`
 * `.removeAttribute( attrName )`
-
-Attributes are not stored as attribute nodes in a list, but rather they are a simple `{ name: value }` style object on the node.
+* `.attributes`
+ A `NamedNodeMap` of `Attr` nodes — iterable, indexable by name (`el.attributes.foo` returns the `Attr`), and with DOM-style `getNamedItem` / `setNamedItem` / `removeNamedItem` methods.
 
 **Tree & traversal**
 
@@ -105,6 +115,9 @@ Attributes are not stored as attribute nodes in a list, but rather they are a si
 * `.getElementsByTagName( tagName )`
  Lists all Elements in the target's subtree, traversal order, that have `.tagName` equal to the argument. Function is case-sensitive.
 
+* `.querySelector( cssSelector )`
+ Returns the first Element in the target's subtree, traversal order, that matches the supplied CSS selector, or `null` if none match.
+
 * `.querySelectorAll( cssSelector )`
  Lists all Elements in the target's subtree, traversal order, that match the supplied CSS selector. Function should be case-sensitive but may be case insensitive for some.
 
@@ -123,19 +136,19 @@ It will parse to a document which has a `.root` node looking roughly like this:
 {
  nodeType: 1,
  nodeName: 'TAG',
- ns: 'x',
+ prefix: 'x',
+ localName: 'tag',
  tagName: 'tag',
  fullName: 'x:tag',
-attr: { 'foo': 'bar' }
+attributes: NamedNodeMap { /* Attr { name: 'foo', value: 'bar' } */ },
  parentNode: null,
- childNodes = [
+ childNodes: [
  {
  nodeName: '#text',
  nodeType: 3,
-value: 'Text content',
+data: 'Text content',
  parentNode: {...},
  }
  ]
 }
 ```
-
diff --git a/lib/Attr.ts b/lib/Attr.ts
@@ -0,0 +1,47 @@
+import { Node } from './Node.js';
+import { ATTRIBUTE_NODE } from './constants.js';
+import { splitTagName } from './splitTagName.ts';
+
+/**
+ * A class describing an attribute.
+ *
+ * @augments Node
+ */
+export class Attr extends Node {
+ /** The namespace prefix of the element, or null' if no prefix is specified. */
+ prefix: string | null;
+ /** The name of the tag for the given element, excluding any namespace prefix. */
+ localName: string;
+
+ /** The node's name. */
+ name: string;
+ /** The node's data value. */
+ value: string;
+
+ /**
+ * Constructs a new Attr instance.
+ *
+ * @param name The name of the attribute.
+ * @param value The data of the attribute.
+ */
+ constructor (name: string, value: any) {
+ super();
+
+ const [ prefix, localName ] = splitTagName(name);
+ this.prefix = prefix;
+ this.localName = localName;
+ this.name = localName;
+ this.nodeName = localName;
+
+ this.value = String(value);
+
+ this.nodeType = ATTRIBUTE_NODE;
+ }
+
+ /** The full name of the tag for the given element, including a namespace prefix. */
+ get fullName () {
+ return this.prefix
+ ? this.prefix + ':' + this.localName
+ : this.localName;
+ }
+}
diff --git a/lib/CreateChildArgument.ts b/lib/CreateChildArgument.ts
@@ -0,0 +1,4 @@
+import type { DocumentFragment } from './DocumentFragment.ts';
+import type { Node } from './Node.ts';
+
+export type CreateChildArgument = Node | DocumentFragment | string | boolean | number | null | undefined;
diff --git a/lib/Document.ts b/lib/Document.ts
@@ -2,10 +2,17 @@ import { JsonML, type JsonMLElement } from './JsonML.js';
 import { Node } from './Node.js';
 import { Element } from './Element.js';
 import { appendChild } from './appendChild.js';
-import { DOCUMENT_NODE } from './constants.js';
+import { DOCUMENT_NODE, XML_DECLARATION } from './constants.js';
 import { domQuery } from './domQuery/index.js';
 import { findAll } from './findAll.js';
 import { isElement } from './isElement.ts';
+import { DocumentFragment } from './DocumentFragment.ts';
+import { NSMap } from './NSMap.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+import type { CreateChildArgument } from './CreateChildArgument.ts';
+import type { XMLAttr } from './XMLAttr.ts';
+import { HierarchyError, NamespaceError } from './errors.js';
 
 /**
  * This class describes an XML document.
@@ -14,6 +21,8 @@ import { isElement } from './isElement.ts';
  */
 export class Document extends Node {
  root: Element | null = null;
+ /** @ignore */
+ namespaces = new NSMap();
 
  /**
  * Constructs a new Document instance.
@@ -25,6 +34,31 @@ export class Document extends Node {
  this.nodeType = DOCUMENT_NODE;
  }
 
+ /**
+ * Attach a namespace to the document.
+ *
+ * @param namespaceURI The namespace URI to attach.
+ * @param [prefix] Prefix to use on elements belonging to the namespace.
+ */
+ attachNS (namespaceURI: string, prefix = ''): (name: string, attr?: XMLAttr | null, ...children: (CreateChildArgument | CreateChildArgument[])[]) => Element {
+ this.namespaces.add(namespaceURI, prefix);
+ this._updateNS();
+
+ // Return a new create function bound to the namespace
+ return this.createElementNS.bind(this, namespaceURI);
+ }
+
+ /** @ignore */
+ private _updateNS () {
+ // ensure that namespaces exist on the root node
+ if (this.root) {
+ for (const [ namespaceURI, prefix ] of this.namespaces.list()) {
+ const key = 'xmlns' + (prefix ? ':' + prefix : '');
+ this.root.setAttribute(key, namespaceURI);
+ }
+ }
+ }
+
  // overwrites super
  get textContent () {
  return this.root ? this.root.textContent : '';
@@ -37,6 +71,58 @@ export class Document extends Node {
  return this.childNodes.filter(isElement);
  }
 
+ /**
+ * Create a new element node.
+ *
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElement = (
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const element = new Element(qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
+ /**
+ * Create a new element node associated with a given namespace.
+ *
+ * @param namespaceURI The namespaceURI to associate with the element.
+ * @param qualifiedName The local tagName of the element.
+ * @param attr A record of attributes to assign to the new element.
+ * If the value is null or undefined, the attribute will be omitted.
+ * @param children Nodes to insert as children.
+ * Strings will be converted to TextNodes and arrays will be flattened.
+ * @returns A new Element instance.
+ */
+ createElementNS = (
+ namespaceURI: string,
+ qualifiedName: string,
+ attr: XMLAttr | null | undefined,
+ ...children: (CreateChildArgument | CreateChildArgument[])[]
+ ): Element => {
+ const ns = this.namespaces.get(namespaceURI);
+ if (ns == null) {
+ throw new NamespaceError('Unknown namespace ' + namespaceURI);
+ }
+ const element = new Element(ns ? ns + ':' + qualifiedName : qualifiedName);
+ element.setAttrValues(attr ?? null);
+ for (const child of children) {
+ element.append(child);
+ }
+ return element;
+ };
+
  /**
  * Return all descendant elements that have the specified tag name.
  *
@@ -45,7 +131,7 @@ export class Document extends Node {
  */
  getElementsByTagName (tagName: string): Element[] {
  if (!tagName) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return findAll(this, tagName, []);
  }
@@ -58,7 +144,7 @@ export class Document extends Node {
  */
  querySelector (selector: string): Element | null {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector)[0] || null;
  }
@@ -71,18 +157,32 @@ export class Document extends Node {
  */
  querySelectorAll (selector: string): Element[] {
  if (!selector) {
- throw new Error('1 argument required, but 0 present.');
+ throw new TypeError('1 argument required, but 0 present.');
  }
  return domQuery(this, selector);
  }
 
  // overwrites super
- appendChild (node: Element): Element {
- if (this.root) {
- throw new Error('A document may only have one child/root element.');
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ if (this.root || (node instanceof DocumentFragment && node.childNodes.length > 1)) {
+ throw new HierarchyError('A document must have only one child element.');
+ }
+ let root: Element;
+ if (node instanceof DocumentFragment) {
+ if (!(node.childNodes[0] instanceof Element)) {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ root = node.childNodes[0];
+ }
+ else if (node instanceof Element) {
+ root = node;
  }
- appendChild(this, node);
- this.root = node;
+ else {
+ throw new HierarchyError('Document root node must be an Element');
+ }
+ appendChild(this, root);
+ this.root = root;
+ this._updateNS();
  return node;
  }
 
@@ -94,4 +194,19 @@ export class Document extends Node {
  toJS (): JsonMLElement | [] {
  return this.root ? JsonML(this.root) : [];
  }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ if (!(this.root instanceof Element)) {
+ throw new HierarchyError('root element is missing');
+ }
+ return `${XML_DECLARATION}\n` + (
+ pretty ? prettyPrint(this.root) : simplePrint(this.root)
+ );
+ }
 }
diff --git a/lib/DocumentFragment.ts b/lib/DocumentFragment.ts
@@ -0,0 +1,43 @@
+import { appendChild } from './appendChild.ts';
+import { DOCUMENT_FRAGMENT_NODE } from './constants.ts';
+import type { Node } from './Node.ts';
+import { prettyPrint } from './prettyPrint.ts';
+import { simplePrint } from './simplePrint.ts';
+
+/**
+ * A class describing a DocumentFragment.
+ */
+export class DocumentFragment {
+ /** The immediate children contained in the fragment. */
+ childNodes: Node[] = [];
+ /** A numerical node type identifier. */
+ nodeType: number = DOCUMENT_FRAGMENT_NODE;
+
+ /**
+ * Appends a child node into the document fragment.
+ *
+ * @param node The new child node
+ * @returns The same node that was passed in.
+ */
+ appendChild<T extends Node | DocumentFragment> (node: T): T {
+ appendChild(this, node);
+ return node;
+ }
+
+ /** @ignore */
+ toString (): string {
+ return '#document-fragment';
+ }
+
+ /**
+ * Print the document as a string.
+ *
+ * @param pretty Apply automatic linebreaks and indentation to the output.
+ * @returns The document as an XML string.
+ */
+ print (pretty = false): string {
+ return pretty
+ ? prettyPrint(this)
+ : simplePrint(this);
+ }
+}