xml-reader

library2.4.3jsnpmunverified

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.

serialization data

npm install xml-reader

github ↗package ↗

INSTALL

IMPORT

SIG · XML-READER

xml-reader

serializationjavascriptv2.4.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

XmlReader

✓ const XmlReader = require('xml-reader');

✗ import XmlReader from 'xml-reader';

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.

create

✓ const reader = XmlReader.create();

✗ import { create } from 'xml-reader';

The `create` method is a static function available on the `XmlReader` object obtained via `require('xml-reader')`, not a named export for direct import.

XmlNode

✓ import type { XmlNode } from 'xml-reader';

✗ import { XmlNode } from 'xml-reader';

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.

Demonstrates parsing an XML string using the event-driven API and logging specific elements from the resulting JavaScript object structure.

const XmlReader = require('xml-reader'); const reader = XmlReader.create(); const xml = `<?xml version="1.0" encoding="UTF-8"?> <message> <to>Alice</to> <from>Bob</from> <heading color="blue">Hello</heading> <body color="red">This is a demo!</body> </message>`; reader.on('done', data => { // For demonstration, logging relevant parts console.log('Parsed XML Message:'); console.log('To:', data.children[0].children[0].value); console.log('From:', data.children[1].children[0].value); console.log('Heading:', data.children[2].children[0].value, ' (color:', data.children[2].attributes.color + ')'); console.log('Body:', data.children[3].children[0].value, ' (color:', data.children[3].attributes.color + ')'); }); reader.parse(xml);

Debug

Known issues

breakingIn version 2.x, the `tagPrefix` option's default value changed from an empty string to `'tag:'`. This affects event names, e.g., for `<item>`, the event is now `'tag:item'` instead of `'item'`. If you rely on the old behavior, explicitly set `tagPrefix: ''` during `XmlReader.create()`.

fix

When creating a reader instance, specify `XmlReader.create({ tagPrefix: '' })` to restore the previous behavior for tag-specific events.

affects: >=2.0.0

gotchaWhen 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.

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.

affects: >=1.0.0

gotchaIn '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.

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.

affects: >=1.0.0

gotchaPrior 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.

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.

affects: <2.4.3

Errors

Common errors & fixes

TypeError: reader.on is not a function

Attempting to call `.on` or `.parse` directly on `XmlReader` instead of an instance created by `XmlReader.create()`.

fix

Instantiate the reader correctly: `const reader = XmlReader.create();` before using event listeners or parsing methods.

Error: Unexpected end of document

Using `XmlReader.parseSync()` with an XML string that is incomplete or not properly closed (e.g., missing a closing tag for the root element).

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.

ReferenceError: require is not defined

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).

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.

Upgrade

Version history

2.4.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

42 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pladaria/xml-reader ↗

packagehttps://www.npmjs.com/package/xml-reader ↗