xmlbuilder2

When converting objects, you can specify element or attribute namespaces by appending the namespace URI to the key using the @ symbol.

Example: {'elementName@namespaceURI': 'value'}

const obj = {
  'root@http://example.com/ns1': 'foo'
};
// Result: <root xmlns="http://example.com/ns1">foo</root>

A round trip from a raw string to an XML document and back to a string may result in different string representations for certain characters due to how they are parsed and re-serialized.

• CDATA, Comment, and Processing Instruction nodes: These are safe and will result in the same string.
• Text nodes: May change. For example, ' is decoded to ', but when re-serialized, it remains ' (not '). Numeric references like 	 are decoded to \t and re-serialized as the literal character \t rather than the entity.
• Attribute nodes: May change. While " is preserved, whitespace characters like 
 (hexadecimal newline) are normalized to 
 (decimal newline) during the round trip.

A round trip from an XML document to its string representation and back to an XML document is safe. All encoded values are correctly decoded back to their original character representations, ensuring data integrity for text and attribute nodes.

• CDATA, Comment, and Processing Instruction nodes: Safe (no processing).
• Text nodes: Safe (all encoded values are decoded back).
• Attribute nodes: Safe (all encoded values are decoded back).

The createCB and fragmentCB functions allow you to create XML documents in chunks. This is useful for generating very large XML documents without keeping the entire tree in memory, preventing memory exhaustion.

Key Differences:

• Memory Efficiency: Unlike the standard create function, these functions serialize data as it is built.
• Object Type: They return an instance of XMLBuilderCB, which is different from the XMLBuilder returned by create. While method signatures are similar, XMLBuilderCB methods do not return XML node wrappers; instead, they modify the state of the same object instance.
• Use Case: Use these if you only need the final XML string (or stream). If you need to traverse or process intermediate nodes, use the standard create function instead.

const { createCB, fragmentCB } = require('xmlbuilder2');

In xmlbuilder2, child element nodes automatically inherit the namespace of their parent element. If a parent element is created with a specific namespace URI, all subsequent children created without an explicit namespace will belong to that same URI.

const { create } = require('xmlbuilder2');

const root = create()
  .ele('http:/example.com', 'root')
    .ele('node')
  .up();

const node = root.node.firstElementChild;
console.log(node.namespaceURI); // 'http:/example.com'

When serializing an XML document to a string, encoding rules vary by node type:

• CDATA, Comment, and Processing Instruction nodes: No special processing is performed.
• Text nodes: Only &, <, and > are encoded into predefined entities. Other characters are left as-is.
• Attribute nodes: &, <, >, and " are encoded. Note that the apostrophe (') is not encoded because attribute values are always serialized with double quotes. Additionally, whitespace characters \t, \n, and \r are encoded into numeric character references.

When parsing an XML string, xmlbuilder2 applies different decoding rules depending on the node type:

• CDATA, Comment, and Processing Instruction nodes: No special processing is performed. All characters from the input string are passed to the node value as-is.
• Text and Attribute nodes: The parser decodes the five predefined XML entities, numeric character references (&#nnnn;), and hexadecimal numeric character references (&#xhhhh; - note that the x must be lowercase).

Because xmlbuilder2 implements the DOM specification, you can use it with any library compatible with DOM interfaces, such as the xpath module. To perform XPath queries on an xmlbuilder2 document, pass doc.node (the underlying DOM node) to the library's selection function.

Namespaces are fully supported via standard XPath functions like local-name() and namespace-uri().

const { create } = require('xmlbuilder2');
const { select } = require('xpath');

const doc = create("<book><title>The Book</title></book>");
const nodes = select("//title", doc.node);

console.log(nodes[0].localName); // "title"
console.log(nodes[0].firstChild.data); // "The Book"
console.log(nodes[0].toString()); // "<title>The Book</title>"

To use xmlbuilder2 in your Node.js project, install it using npm:

npm install xmlbuilder2