XML Data Handling: Conversion, Generation, and Streaming Compared

Working with XML in JavaScript often falls into two distinct categories: converting existing XML data into usable objects (parsing) or creating new XML documents from scratch (generation). xml-js handles the former, while xmlbuilder and xmlbuilder2 handle the latter. Understanding these distinctions is critical for architectural decisions, as using a generator for parsing tasks (or vice versa) leads to unnecessary complexity.

🔄 Core Purpose: Conversion vs. Generation

xml-js is a utility for data transformation.

• It converts XML strings to JavaScript objects (JSON) and back.
• It does not build a mutable DOM tree for manipulation.
• Best for reading configs or API payloads.

// xml-js: Convert XML string to JS object
const convert = require('xml-js');
const xml = '<note><to>Tove</to><from>Jani</from></note>';
const result = convert.xml2js(xml, { compact: true });
// Output: { note: { to: { _text: 'Tove' }, from: { _text: 'Jani' } } }

xmlbuilder is a tree builder for generation.

• You create nodes programmatically and chain methods.
• It holds the entire document in memory until you call .end().
• Best for creating SOAP requests or RSS feeds.

// xmlbuilder: Create XML tree
const builder = require('xmlbuilder');
const root = builder.create('note')
  .ele('to').txt('Tove').up()
  .ele('from').txt('Jani').up();
const xml = root.end({ pretty: true });

xmlbuilder2 is the modern tree builder.

• Similar chainable API to xmlbuilder but with streaming support.
• Can write directly to a file or stream without holding everything in RAM.
• Best for large exports or modern Node.js streams.

// xmlbuilder2: Create XML with streaming capability
const { create } = require('xmlbuilder2');
const root = create().ele('note');
root.ele('to').txt('Tove');
root.ele('from').txt('Jani');
const xml = root.end({ prettyPrint: true });

⚡ Performance and Memory: Buffering vs. Streaming

Memory management is the biggest differentiator between the classic and modern builders.

xml-js loads the entire XML string into memory to parse it.

• Suitable for small to medium payloads (e.g., config files).
• Can struggle with very large files (100MB+) due to synchronous parsing.

// xml-js: Synchronous parsing (blocks event loop)
const result = convert.xml2js(largeXmlString);

xmlbuilder builds the full document in memory before outputting.

• Simple to use but risky for large documents.
• If you generate a 500MB XML file, you need 500MB+ of RAM.

// xmlbuilder: In-memory construction
const doc = builder.create('root');
// ... add thousands of nodes ...
const output = doc.end(); // All in memory

xmlbuilder2 supports streaming output.

• You can pipe the output directly to a file or HTTP response.
• Drastically reduces memory footprint for large generations.

// xmlbuilder2: Stream to file
const { create } = require('xmlbuilder2');
const root = create().ele('root');
const writer = root.write({ prettyPrint: true });
writer.pipe(require('fs').createWriteStream('output.xml'));

🛠️ API Design: Functional vs. Chainable

The way you interact with these libraries affects code readability and maintenance.

xml-js uses a functional API.

• You pass data and options to a function.
• Stateless and easy to test.

// xml-js: Functional style
const json = convert.xml2js(xml, { compact: true, spaces: 2 });
const xmlBack = convert.js2xml(json, { compact: true, spaces: 2 });

xmlbuilder uses a chainable, mutable API.

• You modify the tree step-by-step.
• .up() is required to move back to the parent node.

// xmlbuilder: Chainable with .up()
builder.create('book')
  .ele('title').txt('Design Patterns').up()
  .ele('author').txt('Gang of Four').up();

xmlbuilder2 uses a refined chainable API.

• Similar to xmlbuilder but more intuitive.
• Handles namespaces and attributes more cleanly.

// xmlbuilder2: Chainable with namespace support
const doc = create().ele('http://example.com/ns', 'book');
doc.att('id', '123').ele('title').txt('Modern XML');

🌐 Real-World Scenarios

Scenario 1: Parsing a Sitemap

You need to read a sitemap.xml to extract URLs for a crawler.

• ✅ Best choice: xml-js
• Why? You want to convert the XML to a JSON array of URLs quickly.

// xml-js: Parse sitemap
const sitemap = convert.xml2js(fs.readFileSync('sitemap.xml'));
const urls = sitemap.urlset.url.map(u => u.loc);

Scenario 2: Generating a SOAP Request

You need to construct a specific XML payload for a legacy enterprise API.

• ✅ Best choice: xmlbuilder2
• Why? You need precise control over namespaces and structure without manual string concatenation.

// xmlbuilder2: SOAP envelope
const root = create().ele('soap:Envelope').att('xmlns:soap', '...');
root.ele('soap:Body').ele('GetUser').ele('UserID').txt('101');
const payload = root.end();

Scenario 3: Exporting Large Logs

You need to export millions of log entries into a single XML archive file.

• ✅ Best choice: xmlbuilder2 (Streaming)
• Why? xmlbuilder would crash due to memory limits; xml-js is for parsing, not generation.

// xmlbuilder2: Stream large data
const writer = create().ele('logs').write({ prettyPrint: false });
logs.forEach(log => writer.ele('entry').txt(log));
writer.end();

Scenario 4: Reading Build Configuration

Your build tool reads a simple config.xml file to set environment variables.

• ✅ Best choice: xml-js
• Why? Minimal setup, no need for a full DOM, just need key-value pairs.

// xml-js: Read config
const config = convert.xml2js(fs.readFileSync('config.xml'), { compact: true });
const env = config.config.environment._text;

📌 Summary Table

💡 Final Recommendation

Think in terms of data flow direction:

• Reading XML into your app? → Use xml-js. It turns XML into plain JavaScript objects you can work with easily. It is lightweight and perfect for configuration or API data.
• Writing XML from your app? → Use xmlbuilder2. It is the modern standard for generation. It avoids the memory pitfalls of the original xmlbuilder and supports streaming, which is essential for scalability.
• Maintaining old code? → xmlbuilder is still stable and works fine for small tasks, but plan to migrate to xmlbuilder2 for long-term health.

Final Thought: Don't mix tools. Use xml-js for parsing data and xmlbuilder2 for creating documents. This separation keeps your architecture clean and performant.