Node XML Stream Parser

Common errors

• Error: Cannot find module 'node-xml-stream'

  cause Attempting to `require()` or `import` the package using the incorrect name specified in the README's usage example, instead of the actual npm package name.
  fix Change the import statement to `require('node-xml-stream-parser')` for CommonJS or `import Parser from 'node-xml-stream-parser'` for ESM.

• TypeError: parser.on is not a function

  cause The `Parser` class itself is being called like a function, or `new Parser()` was not used, resulting in an undefined or improperly initialized object that does not expose the event emitter methods.
  fix Ensure you instantiate the parser correctly with `let parser = new Parser();` before attempting to attach event listeners.

• Events like 'instruction' or 'cdata' are not firing for valid XML that contains them.

  cause This is typically not an error but a misunderstanding of which events are emitted by the parser. While the parser supports these events, they only fire if the input XML stream actually contains the corresponding elements (e.g., `<?xml ...?>` for 'instruction' or `<![CDATA[...]]>` for 'cdata').
  fix Verify that your XML input correctly includes the specific XML constructs you expect to trigger these events. Also, double-check event handler registration.

Warnings

• gotcha The package name for `require` in the README example (`node-xml-stream`) is incorrect. The actual npm package to install and import is `node-xml-stream-parser`.
  Fix: Always use `require('node-xml-stream-parser')` or `import Parser from 'node-xml-stream-parser'`.
• gotcha This parser is designed to be lightweight and fast, intentionally ignoring comments (`<!-- -->`), `<!DOCTYPES>`, and `<!ENTITY>` declarations. If your application relies on parsing these XML features, this library will not extract them.
  Fix: If full XML feature support is required, consider alternative parsers like `node-sax` or `xml2js` which offer more comprehensive XML specification compliance.
• gotcha Self-closing tags that do not have an empty space before the closing slash (e.g., `<tag/>` instead of `<tag />`) may behave unexpectedly if the tag name itself ends with a `/`. The parser strips the last `/` character from the tag name in such cases, which can lead to misinterpretation if your tag is genuinely named something ending with `/`.
  Fix: Ensure all self-closing tags conform to the standard `<tag />` format with a space before the slash, or avoid tag names ending with `/` if using this parser.
• maintenance This project is a fork of an inactive `node-xml-stream` project, as noted in its README. While this fork has seen some updates, the `last publish` date on npm for version 1.0.12 is 6 years ago (February 10, 2020). While the GitHub repository may show more recent activity, be aware that official releases are infrequent.
  Fix: For critical projects requiring active maintenance and frequent updates, assess the current GitHub activity or consider more actively maintained XML parsing libraries.

Install

• npm install node-xml-stream-parser npm
• yarn add node-xml-stream-parser yarn
• pnpm add node-xml-stream-parser pnpm

Imports

• Parser
  wrong:

  const Parser = require('node-xml-stream');

  correct:

  import Parser from 'node-xml-stream-parser';

  The README example shows `require('node-xml-stream')`, but the correct package name for installation is `node-xml-stream-parser`. While it primarily uses CommonJS `require`, modern Node.js applications might attempt ESM `import`. It's generally safe to assume that a package primarily designed for CommonJS will work with default ESM imports if Node.js's module interop is enabled, but explicit CommonJS is shown in the quickstart.
• parser.on
  wrong:

  parser.addListener('opentag', handler);

  correct:

  parser.on('opentag', (name, attrs) => { /* ... */ });

  The primary interaction model is event-driven using `.on()`, similar to Node.js's EventEmitter, which the parser extends. While `addListener` technically works, `on` is the idiomatic choice.

Quickstart

This quickstart demonstrates how to instantiate the XML stream parser, register event listeners for various XML node types (open/close tags, text, CDATA), handle errors, and detect the stream's completion. It includes examples for both directly writing XML strings and piping from a file stream.

import { createReadStream } from 'fs';
import Parser from 'node-xml-stream-parser';

const xmlString = '<root><item attr="value">Hello</item><![CDATA[Some Cdata]]><item/></root>';

const parser = new Parser();

parser.on('opentag', (name, attrs) => {
  console.log(`Open Tag: ${name}, Attributes:`, attrs);
});

parser.on('closetag', name => {
  console.log(`Close Tag: ${name}`);
});

parser.on('text', text => {
  if (text.trim() !== '') {
    console.log(`Text: '${text.trim()}'`);
  }
});

parser.on('cdata', cdata => {
  console.log(`CDATA: '${cdata}'`);
});

parser.on('error', err => {
  console.error('Parsing Error:', err.message);
});

parser.on('finish', () => {
  console.log('XML stream parsing finished.');
});

// Option 1: Write data directly
console.log('--- Parsing from string ---');
parser.write(xmlString);
parser.end();

// Option 2: Pipe a file stream (for larger files)
// Ensure 'feed.atom' exists with valid XML content for this part to run.
// For example, create a dummy feed.atom: <feed><entry><title>Test</title></entry></feed>
const filePath = './feed.atom';
console.log(`\n--- Piping from file: ${filePath} ---`);
// Create a dummy file for demonstration
import { writeFileSync } from 'fs';
writeFileSync(filePath, '<feed><entry><title>Hello World</title><content>Some content.</content></entry></feed>');

const fileStreamParser = new Parser();
fileStreamParser.on('opentag', (name) => console.log(`[File] Open Tag: ${name}`));
fileStreamParser.on('closetag', (name) => console.log(`[File] Close Tag: ${name}`));
fileStreamParser.on('text', (text) => { if (text.trim() !== '') console.log(`[File] Text: '${text.trim()}'`); });
fileStreamParser.on('error', (err) => console.error('[File] Error:', err.message));
fileStreamParser.on('finish', () => console.log('[File] Parsing from file finished.'));

createReadStream(filePath).pipe(fileStreamParser);