ltxmlts
    Preparing search index...

    Class XDocument

    Represents a complete XML document.

    An XDocument may contain at most one XElement (the root). XAttribute and XCData are not valid document content and will throw. Non-whitespace string content will also throw.

    const doc = new XDocument(
      new XDeclaration('1.0', 'UTF-8', 'yes'),
      new XElement('root', new XElement('child')),
    );
    doc.declaration?.version; // '1.0'
    doc.root?.name.localName; // 'root'

    const doc = XDocument.parse("<?xml version='1.0'?><root/>");

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    declaration nodeType parent

    Accessors

    document firstNode lastNode nextNode previousNode root

    Methods

    add addAfterSelf addAnnotation addBeforeSelf addFirst ancestors annotation annotations deepEquals descendantNodes descendants element elements elementsAfterSelf elementsBeforeSelf equals insertAfterChild insertBeforeChild nodes nodesAfterSelf nodesBeforeSelf remove removeAnnotations removeChild removeNodes replaceChild replaceNodes replaceWith toString toStringWithIndentation deepEquals load loadAsync parse

    Constructors

    • Creates a new empty XDocument.

      Returns XDocument

      • new XDocument() creates an empty document.
      • new XDocument(declaration) creates a document with an XML declaration.
      • new XDocument(other) deep-clones an existing document.
      • new XDocument(...content) creates a document with content nodes.
      • new XDocument(declaration, ...content) creates a document with both.

    • Creates a new XDocument with an XML declaration.

      Parameters

      Returns XDocument

    • Deep-clones an existing XDocument.

      Parameters

      Returns XDocument

    • Creates a new XDocument with the specified content.

      Parameters

      • ...content: unknown[]

        Root element, comments, processing instructions, or whitespace-only strings.

      Returns XDocument

    • Creates a new XDocument with an XML declaration and content.

      Parameters

      • declaration: XDeclaration

        The XML declaration.

      • ...content: unknown[]

        Root element, comments, processing instructions, or whitespace-only strings.

      Returns XDocument

    Properties

    declaration: XDeclaration | null

    The XML declaration for this document, or null if none was specified.

    nodeType: XmlNodeType = null

    The kind of XML node this object represents.

    const el = new XElement('root');
    console.log(el.nodeType); // 'Element'
    parent: XObject | null = null

    The parent of this object in the XML tree, or null if it is a root.

    const child = new XElement('child');
    const parent = new XElement('parent', child);
    console.log(child.parent === parent); // true

    Accessors

    • get document(): XDocument | null

      Gets the XDocument that contains this object, or null if the object is not part of a document tree.

      Returns XDocument | null

      const doc = new XDocument(new XElement('root', new XElement('child')));
      const child = doc.root!.elements()[0];
      console.log(child.document === doc); // true
    • get firstNode(): XNode | null

      Gets the first child node, or null if the container is empty.

      Returns XNode | null

    • get lastNode(): XNode | null

      Gets the last child node, or null if the container is empty.

      Returns XNode | null

    • get nextNode(): XNode | null

      Gets the next sibling node, or null if this is the last node.

      Returns XNode | null

    • get previousNode(): XNode | null

      Gets the previous sibling node, or null if this is the first node.

      Returns XNode | null

    Methods

    • Appends content as children of this container.

      Parameters

      • ...content: unknown[]

        Nodes, strings, or arrays to add.

      Returns void

      Content rules:

      • XElement and other XNode subclasses are added as child nodes.
      • Strings are wrapped in XText.
      • Arrays are recursively unpacked.
      • XAttribute objects passed here are silently ignored; pass attributes to the XElement constructor or use XElement.setAttributeValue instead.
      • If a node already has a parent, it is cloned before being added.

    • Inserts the specified content immediately after this node in its parent.

      Parameters

      • ...content: unknown[]

        One or more nodes or strings to insert.

      Returns void

      Error if this node has no parent.

      const parent = new XElement('p', new XElement('a'), new XElement('c'));
      const a = parent.elements()[0];
      a.addAfterSelf(new XElement('b'));
      // parent now contains <a/>, <b/>, <c/>

    • Attaches an arbitrary annotation object to this XML object.

      Parameters

      • obj: unknown

        The annotation object to attach.

      Returns void

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));

    • Inserts the specified content immediately before this node in its parent.

      Parameters

      • ...content: unknown[]

        One or more nodes or strings to insert.

      Returns void

      Error if this node has no parent.

    • Inserts content as the first children of this container.

      Parameters

      • ...content: unknown[]

        Nodes, strings, or arrays to prepend.

      Returns void

    • Returns a collection of the ancestor elements of this node.

      Returns XElement[]

      An array of ancestor XElement instances.

      When called with no arguments, returns all ancestor elements from the immediate parent up to the root. When a name is supplied, only ancestors with that name are returned. The collection is ordered from nearest ancestor to farthest.

      const xml = XElement.parse('<root><a><b/></a></root>');
      const b = xml.descendants('b')[0];
      b.ancestors();        // [<a>, <root>]
      b.ancestors('root');  // [<root>]

    • Returns a collection of the ancestor elements of this node filtered by name.

      Parameters

      • name: string | XName

        Name to filter ancestors by.

      Returns XElement[]

    • Returns the first annotation of the specified type, or null if none exists.

      Type Parameters

      • T

        The annotation class to look up.

      Parameters

      • ctor: new (...args: any[]) => T

        Constructor of the annotation type to retrieve.

      Returns T | null

      The first matching annotation, or null.

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));
      const m = el.annotation(MyMeta);
      console.log(m?.tag); // 'important'

    • Returns all annotations of the specified type.

      Type Parameters

      • T

        The annotation class to look up.

      Parameters

      • ctor: new (...args: any[]) => T

        Constructor of the annotation type to retrieve.

      Returns T[]

      An array of matching annotations (may be empty).

    • Performs a deep structural comparison of this node with another.

      Parameters

      • other: XNode

        The node to compare against.

      Returns boolean

      true if the two nodes are structurally identical.

      Two nodes are deeply equal when they have the same node type and their content (including all descendants and attributes for elements) is equal.

      const e1 = XElement.parse('<a x="1"><b/></a>');
      const e2 = XElement.parse('<a x="1"><b/></a>');
      e1.deepEquals(e2); // true

    • Compares this document with another for structural equality, including the declaration and all child nodes.

      Parameters

      • other: XDocument

        The document to compare against.

      Returns boolean

      true if the documents are structurally identical.

    • Inserts content immediately after an existing child node.

      Parameters

      • child: XNode

        The reference child node.

      • ...content: unknown[]

        Content to insert after the child.

      Returns void

    • Inserts content immediately before an existing child node.

      Parameters

      • child: XNode

        The reference child node.

      • ...content: unknown[]

        Content to insert before the child.

      Returns void

    • Removes this node from its parent.

      Returns void

      Error if this node has no parent.

    • Removes annotations from this object.

      Returns void

      When called with no arguments, all annotations are removed. When called with a constructor, only annotations of that type are removed.

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));
      el.removeAnnotations(MyMeta);  // removes only MyMeta annotations
      el.removeAnnotations();        // removes everything

    • Removes annotations from this object.

      Type Parameters

      • T

      Parameters

      • ctor: new (...args: any[]) => T

      Returns void

      When called with no arguments, all annotations are removed. When called with a constructor, only annotations of that type are removed.

      class MyMeta { constructor(public tag: string) {} }
      const el = new XElement('item');
      el.addAnnotation(new MyMeta('important'));
      el.removeAnnotations(MyMeta);  // removes only MyMeta annotations
      el.removeAnnotations();        // removes everything

    • Replaces an existing child node with the specified content.

      Parameters

      • child: XNode

        The child node to replace.

      • ...content: unknown[]

        Content that replaces the child.

      Returns void

    • Replaces all child nodes with the specified content.

      Parameters

      • ...content: unknown[]

        New content to use as children.

      Returns void

    • Replaces this node with the specified content.

      Parameters

      • ...content: unknown[]

        One or more nodes or strings that replace this node.

      Returns void

      Error if this node has no parent.

    • Serialises this document to an XML string.

      Returns string

      The XML string representation, including the declaration if present.

    • Serialises this document to an indented (pretty-printed) XML string.

      Returns string

      The indented XML string.

    • Static convenience method for deep structural comparison of two nodes.

      Parameters

      Returns boolean

      true if the two nodes are structurally identical.

      const e1 = XElement.parse('<a x="1"><b/></a>');
      const e2 = XElement.parse('<a x="1"><b/></a>');
      XNode.deepEquals(e1, e2); // true

    • Loads an XML file asynchronously and parses it into an XDocument.

      Parameters

      • filePath: string

        Path to the XML file.

      Returns Promise<XDocument>

      A promise that resolves to the parsed document.

    • Parses an XML string into an XDocument.

      Parameters

      • xml: string

        The XML string to parse.

      Returns XDocument

      The parsed document.

      const doc = XDocument.parse("<?xml version='1.0'?><root/>");

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods