{"id":14378,"library":"xml-reader","title":"XML Reader","description":"xml-reader is a lightweight and performant XML parser designed for both Node.js and browser environments, including modern platforms like React Native, ServiceWorkers, and WebWorkers. Currently at stable version 2.4.3, the library focuses on providing a simple, event-driven, and synchronous API for parsing XML documents. It supports incremental processing, allowing for efficient handling of large XML streams with low memory usage in its dedicated stream mode. While not a rapid release cycle, the project receives maintenance updates for bug fixes, such as the recent 2.4.3 patch for parent node references in text nodes. Its key differentiators include its small footprint, versatile environment compatibility, and the ability to process XML piece-by-piece, making it suitable for real-time or resource-constrained applications, particularly when combined with its companion `xml-query` package for data extraction.","status":"active","version":"2.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/pladaria/xml-reader","tags":["javascript","xml","reader","sax","lexer","parser","parsing","parse","ast"],"install":[{"cmd":"npm install xml-reader","lang":"bash","label":"npm"},{"cmd":"yarn add xml-reader","lang":"bash","label":"yarn"},{"cmd":"pnpm add xml-reader","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses CommonJS `require()` syntax in its examples. When used in an ES module context or with bundlers, `import * as XmlReader from 'xml-reader';` might be necessary, but a direct default import is not explicitly supported.","wrong":"import XmlReader from 'xml-reader';","symbol":"XmlReader","correct":"const XmlReader = require('xml-reader');"},{"note":"The `create` method is a static function available on the `XmlReader` object obtained via `require('xml-reader')`, not a named export for direct import.","wrong":"import { create } from 'xml-reader';","symbol":"create","correct":"const reader = XmlReader.create();"},{"note":"XmlNode is a TypeScript interface defining the structure of parsed XML nodes. It should be imported as a type for declaration purposes, not as a runtime value.","wrong":"import { XmlNode } from 'xml-reader';","symbol":"XmlNode","correct":"import type { XmlNode } from 'xml-reader';"}],"quickstart":{"code":"const XmlReader = require('xml-reader');\nconst reader = XmlReader.create();\nconst xml =\n `\n \n Alice\n Bob\n Hello\n This is a demo!\n `;\n\nreader.on('done', data => {\n // For demonstration, logging relevant parts\n console.log('Parsed XML Message:');\n console.log('To:', data.children[0].children[0].value);\n console.log('From:', data.children[1].children[0].value);\n console.log('Heading:', data.children[2].children[0].value, ' (color:', data.children[2].attributes.color + ')');\n console.log('Body:', data.children[3].children[0].value, ' (color:', data.children[3].attributes.color + ')');\n});\nreader.parse(xml);","lang":"javascript","description":"Demonstrates parsing an XML string using the event-driven API and logging specific elements from the resulting JavaScript object structure."},"warnings":[{"fix":"When creating a reader instance, specify `XmlReader.create({ tagPrefix: '' })` to restore the previous behavior for tag-specific events.","message":"In version 2.x, the `tagPrefix` option's default value changed from an empty string to `'tag:'`. This affects event names, e.g., for ``, the event is now `'tag:item'` instead of `'item'`. If you rely on the old behavior, explicitly set `tagPrefix: ''` during `XmlReader.create()`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure the XML string passed to `parseSync()` is a fully enclosed and valid XML document. For streaming or potentially incomplete XML, use the event-driven `parse()` method with a `stream: true` option.","message":"When using `parseSync()`, the XML input must be a complete and well-formed document with all tags properly closed. Attempting to parse incomplete or malformed XML will result in errors or unexpected behavior, as it processes the entire document at once.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you need to access the full parsed tree after processing in stream mode, you must manually accumulate the emitted nodes or process them as they arrive via `tag:` events. The `done` event in stream mode is primarily an indication of parsing completion, not a return of the complete in-memory tree.","message":"In 'stream mode' (`XmlReader.create({ stream: true })`), emitted nodes are removed from the root node's children as they are processed to conserve memory. Consequently, the `data` object received in the final `done` event will have an empty `children` array, reflecting that intermediate nodes have been discarded.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `xml-reader@2.4.3` or newer to ensure correct parent references, where text nodes do not have an extraneous `parent` property.","message":"Prior to version 2.4.3, text nodes incorrectly maintained a reference to their `parent`. While usually not problematic, in specific use cases, this could lead to unexpected behavior or potential memory leaks if not properly handled.","severity":"gotcha","affected_versions":"<2.4.3"}],"env_vars":null,"search_vec":"'2.4.3':33,90 'abil':111 'allow':55 'api':46 'applic':130 'ast':152 'browser':18 'bug':84 'combin':133 'companion':136 'compat':108 'constrain':129 'current':29 'cycl':77 'data':142 'dedic':69 'design':13 'differenti':101 'document':50 'driven':43 'effici':57 'environ':19,107 'event':42 'event-driven':41 'extract':143 'fix':85 'focus':36 'footprint':105 'handl':58 'includ':20,102 'increment':53 'javascript':144 'key':100 'larg':60 'lexer':148 'librari':35 'lightweight':8 'like':23 'low':64 'mainten':81 'make':119 'memori':65 'mode':71 'modern':21 'nativ':25 'node':94,98 'node.js':16 'packag':140 'parent':93 'pars':48,150,151 'parser':12,149 'particular':131 'patch':91 'perform':10 'piec':116,118 'piece-by-piec':115 'platform':22 'process':54,113 'project':79 'provid':38 'queri':139 'rapid':75 'react':24 'reader':2,5,146 'real':124 'real-tim':123 'receiv':80 'recent':89 'refer':95 'releas':76 'resourc':128 'resource-constrain':127 'sax':147 'servicework':26 'simpl':40 'small':104 'stabl':31 'stream':62,70 'suitabl':121 'support':52 'synchron':45 'text':97 'time':125 'updat':82 'usag':66 'versatil':106 'version':32 'webwork':28 'xml':1,4,11,49,61,114,138,145 'xml-queri':137 'xml-reader':3","created_at":"2026-04-20T01:59:24.015500+00:00","updated_at":"2026-04-20T01:59:24.015500+00:00","problems":[{"fix":"Instantiate the reader correctly: `const reader = XmlReader.create();` before using event listeners or parsing methods.","cause":"Attempting to call `.on` or `.parse` directly on `XmlReader` instead of an instance created by `XmlReader.create()`.","error":"TypeError: reader.on is not a function"},{"fix":"Ensure the XML input for `parseSync()` is a complete and valid document. For partial or streaming XML, use the event-driven `reader.parse()` method.","cause":"Using `XmlReader.parseSync()` with an XML string that is incomplete or not properly closed (e.g., missing a closing tag for the root element).","error":"Error: Unexpected end of document"},{"fix":"For ES modules, consider using `import * as XmlReader from 'xml-reader';` or configure your build system to transpile CommonJS to ESM. Alternatively, ensure your file is treated as a CommonJS module.","cause":"Attempting to use `require()` syntax in an ES module context (e.g., in a file with `\"type\": \"module\"` in `package.json` or a `.mjs` file).","error":"ReferenceError: require is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/pladaria/xml-reader","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/xml-reader","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}