Xml-stream-parser NPM

XML Stream Parser

A high-performance, streaming XML parser for Node.js that converts XML to JSON while preserving attributes, namespaces, and structure. Built with TypeScript for type safety and better developer experience.

Features

🚀 Streaming API for efficient memory usage with large XML files
🔄 Preserves XML attributes and text content
🌳 Handles deeply nested XML structures
📚 Full namespace support
📦 Automatic array handling for repeated elements
💪 TypeScript support with type definitions
🧪 Comprehensive test suite

Installation

npm install xml-stream-parser
# or
yarn add xml-stream-parser

Usage

Basic Example

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

const parser = new XMLStreamParser();

// Handle parsed data
parser.on('data', (data) => {
  console.log(JSON.stringify(data, null, 2));
});

// Handle errors
parser.on('error', (error) => {
  console.error('Parsing error:', error);
});

// Parse XML from a file
createReadStream('example.xml').pipe(parser);

Example with Attributes and Text Content

const xml = `
<root>
  <amount currency="USD">500.00</amount>
  <details type="shipping">
    <address country="US">
      <street>123 Main St</street>
      <city>New York</city>
    </address>
  </details>
</root>
`;

// Will output:
{
  "root": {
    "amount": {
      "#text": "500.00",
      "currency": "USD"
    },
    "details": {
      "type": "shipping",
      "address": {
        "country": "US",
        "street": "123 Main St",
        "city": "New York"
      }
    }
  }
}

Handling Repeated Elements

const xml = `
<root>
  <items>
    <item>1</item>
    <item>2</item>
    <item>3</item>
  </items>
</root>
`;

// Will output:
{
  "root": {
    "items": {
      "item": ["1", "2", "3"]
    }
  }
}

API Reference

XMLStreamParser

The main class that extends Node.js Transform stream.

Constructor

constructor();

Creates a new instance of XMLStreamParser with default settings.

Events

'data': Emitted when the XML document has been parsed into a JSON object
'error': Emitted when an error occurs during parsing
'end': Emitted when the parser has completed processing all input

Types

interface XMLNode {
  [key: string]: XMLValue | undefined;
}

type XMLValue = string | XMLNode | XMLValue[];

Features in Detail

Attribute Handling

Attributes are preserved as properties on the node object. When a node has both attributes and text content, the text is stored in the #text property.