{"id":16468,"library":"node-xml-stream-parser","title":"Node XML Stream Parser","description":"node-xml-stream-parser (current version 1.0.12) is a lightweight, fast XML/HTML stream parser designed for Node.js environments. It specializes in processing streaming XML, making it particularly suitable for tasks like parsing RSS, ATOM, or RDF feeds efficiently. The library's focus is on simplicity and performance, emitting events for `opentag`, `closetag`, `text`, `cdata`, and `instruction` as it processes the stream. It differentiates itself from more heavy-weight parsers (like `node-sax`) by offering a streamlined API and intentionally omitting support for less common XML features like comments, DOCTYPES, and ENTITY declarations, optimizing for speed and minimal overhead. It has seen consistent, though not rapid, updates, with the latest publish around 6 years ago on NPM, but GitHub activity suggests some more recent minor updates, making it a `maintenance` status.","status":"maintenance","version":"1.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/mfahlandt/node-xml-stream-parser","tags":["javascript","XML","XML Parser","XML Stream Parser","XML Stream","Streaming XML","Fast XML Parser","nodeJS"],"install":[{"cmd":"npm install node-xml-stream-parser","lang":"bash","label":"npm"},{"cmd":"yarn add node-xml-stream-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-xml-stream-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Parser = require('node-xml-stream');","symbol":"Parser","correct":"import Parser from 'node-xml-stream-parser';"},{"note":"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.","wrong":"parser.addListener('opentag', handler);","symbol":"parser.on","correct":"parser.on('opentag', (name, attrs) => { /* ... */ });"}],"quickstart":{"code":"import { createReadStream } from 'fs';\nimport Parser from 'node-xml-stream-parser';\n\nconst xmlString = '<root><item attr=\"value\">Hello</item><![CDATA[Some Cdata]]><item/></root>';\n\nconst parser = new Parser();\n\nparser.on('opentag', (name, attrs) => {\n  console.log(`Open Tag: ${name}, Attributes:`, attrs);\n});\n\nparser.on('closetag', name => {\n  console.log(`Close Tag: ${name}`);\n});\n\nparser.on('text', text => {\n  if (text.trim() !== '') {\n    console.log(`Text: '${text.trim()}'`);\n  }\n});\n\nparser.on('cdata', cdata => {\n  console.log(`CDATA: '${cdata}'`);\n});\n\nparser.on('error', err => {\n  console.error('Parsing Error:', err.message);\n});\n\nparser.on('finish', () => {\n  console.log('XML stream parsing finished.');\n});\n\n// Option 1: Write data directly\nconsole.log('--- Parsing from string ---');\nparser.write(xmlString);\nparser.end();\n\n// Option 2: Pipe a file stream (for larger files)\n// Ensure 'feed.atom' exists with valid XML content for this part to run.\n// For example, create a dummy feed.atom: <feed><entry><title>Test</title></entry></feed>\nconst filePath = './feed.atom';\nconsole.log(`\\n--- Piping from file: ${filePath} ---`);\n// Create a dummy file for demonstration\nimport { writeFileSync } from 'fs';\nwriteFileSync(filePath, '<feed><entry><title>Hello World</title><content>Some content.</content></entry></feed>');\n\nconst fileStreamParser = new Parser();\nfileStreamParser.on('opentag', (name) => console.log(`[File] Open Tag: ${name}`));\nfileStreamParser.on('closetag', (name) => console.log(`[File] Close Tag: ${name}`));\nfileStreamParser.on('text', (text) => { if (text.trim() !== '') console.log(`[File] Text: '${text.trim()}'`); });\nfileStreamParser.on('error', (err) => console.error('[File] Error:', err.message));\nfileStreamParser.on('finish', () => console.log('[File] Parsing from file finished.'));\n\ncreateReadStream(filePath).pipe(fileStreamParser);","lang":"javascript","description":"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."},"warnings":[{"fix":"Always use `require('node-xml-stream-parser')` or `import Parser from 'node-xml-stream-parser'`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If full XML feature support is required, consider alternative parsers like `node-sax` or `xml2js` which offer more comprehensive XML specification compliance.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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 `/`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For critical projects requiring active maintenance and frequent updates, assess the current GitHub activity or consider more actively maintained XML parsing libraries.","message":"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.","severity":"maintenance","affected_versions":"<=1.0.12"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change the import statement to `require('node-xml-stream-parser')` for CommonJS or `import Parser from 'node-xml-stream-parser'` for ESM.","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.","error":"Error: Cannot find module 'node-xml-stream'"},{"fix":"Ensure you instantiate the parser correctly with `let parser = new Parser();` before attempting to attach event listeners.","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.","error":"TypeError: parser.on is not a function"},{"fix":"Verify that your XML input correctly includes the specific XML constructs you expect to trigger these events. Also, double-check event handler registration.","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').","error":"Events like 'instruction' or 'cdata' are not firing for valid XML that contains them."}],"ecosystem":"npm"}