fast-xml-parser

fast-xml-parser converts XML to JS objects and back without relying on native (C/C++) bindings or callback-based APIs, making it drop-in usable in Node.js, browsers, and bundler-based frontend builds alike. It exposes three focused classes — XMLParser, XMLBuilder, and XMLValidator — that cover the whole round trip: syntactically validating XML, parsing it into plain JS objects (optionally preserving tag order), and building XML back out of JS objects.

The library is tuned for throughput on files up to roughly 100MB, and handles XML/HTML edge cases directly, including unpaired tags (like <br>), stop nodes (like <script> content that shouldn’t be parsed), CDATA, comments, processing-instruction tags, and XML/HTML entity decoding. It ships as CommonJS, ESM, and a browser bundle, and includes a small CLI (fxparser) for ad-hoc validation and conversion from the command line.

What You Get

• XMLParser class that converts XML strings (or byte arrays) into plain JS objects, with an option to preserve original tag order via preserveOrder
• XMLBuilder class that converts JS objects back into XML strings, the inverse of XMLParser
• XMLValidator (via XMLValidator.validate()) for syntactic XML validation with line/column error reporting, independent of parsing
• Fine-grained parsing options: attribute handling, number/boolean coercion, CDATA and comment capture, custom tag/attribute value processors, and namespace-prefix stripping
• Support for unpaired tags (<br>), stop nodes (content like <script>/<style> left unparsed), and configurable entity decoding (XML, HTML, and custom entities)
• A fxparser CLI binary for validating or converting XML files from the terminal without writing any code
• Distribution as CommonJS, native ESM, and a minified browser bundle (loadable via CDN) from a single package

Common Use Cases

• Parsing SOAP/XML API responses into JS objects inside a Node.js backend or serverless function
• Converting RSS/Atom feeds or sitemap XML into structured data for a static site generator or crawler
• Round-tripping configuration or legacy data formats (e.g. Maven POMs, Ant build files, RSS) between XML and JSON
• Validating untrusted XML input for well-formedness before passing it further down a processing pipeline
• Parsing HTML-shaped documents where unpaired tags and stop nodes need explicit handling, distinct from strict XML

Under The Hood

Architecture — The library separates its three responsibilities into independent, composable modules under src/: validator.js for syntactic checks, xmlparser/ for parsing, and xmlbuilder/ (which re-exports the sibling fast-xml-builder package for the build direction). xmlparser/XMLParser.js is a thin public-facing class that wires together OptionsBuilder.js (merges user options over defaultOptions), OrderedObjParser.js (the 869-line core tokenizer/parser that walks the XML string and produces an order-preserving intermediate tree of XmlNode instances), and node2json.js (which, unless preserveOrder is requested, flattens that ordered tree into the conventional nested-object shape consumers expect). DocTypeReader.js handles DOCTYPE/entity declarations as a separate concern feeding into the parser. This gives a clear pipeline: raw XML string → optional validation → ordered node tree → optional prettify/flatten step → final JS object.

Tech Stack — Pure JavaScript with zero C/C++ native dependencies, published as type: module with dual ESM (src/fxp.js) and CommonJS (lib/fxp.cjs, built via Webpack per webpack.cjs.config.js) entry points plus TypeScript type declarations (src/fxp.d.ts, lib/fxp.d.cts). Runtime dependencies are all small, single-purpose sibling packages under the same NaturalIntelligence/nodable umbrella — @nodable/entities (HTML/currency entity tables), fast-xml-builder (the actual build-direction implementation), is-unsafe (prototype-pollution guarding), path-expression-matcher (jPath-style stop-node/array matching), strnum (safe numeric coercion), and xml-naming (tag/attribute naming helpers) — keeping the core parser’s own dependency surface minimal. Tests run on Jasmine with c8 for coverage; ESLint and Prettier enforce style.

Code Quality — The test suite is substantial: 27 spec files under spec/ covering CDATA, comments, entities (including a dedicated entities_security_spec.js for XML-entity-expansion/XXE-style attack vectors), stop nodes, path expressions, array-mode output, and large-file (large_spec.js) handling, run through c8 coverage reporting. OptionsBuilder.js centralizes all ~30 configuration flags with documented defaults, and onDangerousProperty in util.js explicitly guards against prototype-pollution-prone key names (e.g. __proto__) — a sign of security-conscious design given the library sits on the untrusted-input boundary. Public methods carry JSDoc comments describing parameter types and behavior.

API Design — The three-class surface (XMLParser, XMLBuilder, XMLValidator) maps directly onto the library’s stated jobs, and a minimal example (new XMLParser().parse(xml)) works with zero configuration, with power-user behavior (order preservation, custom entities, stop nodes, tag/attribute processors) opted into via a single options object rather than proliferating parameters. addEntity() and getMetaDataSymbol() are the only other public methods beyond parse/build/validate, keeping the API surface small and memorable. Trade-off: because v6 restructures this into a differently-shaped flexible-xml-parser, most current documentation and issue history still targets the v4/v5 API surface documented here.