xml-js

xml-js is a JavaScript library for converting between XML text and JavaScript objects (or JSON text), in both directions. Unlike many XML-to-JSON converters that collapse sibling elements of the same name into an array and lose ordering, xml-js offers a non-compact output mode that preserves the exact order elements appeared in the original document, alongside a compact mode for when space matters more than fidelity.

The library exposes four functions — xml2js, xml2json, js2xml, and json2xml — backed by a single dependency (sax) for parsing. It fully supports elements, attributes, text nodes, comments, CDATA sections, DOCTYPE declarations, XML declarations, and processing instructions, and the conversion is reversible: XML converted to JSON and back produces the original structure. Extensive options let consumers rename output keys, ignore specific node types, coerce values to native types, and hook custom processing functions into the traversal.

It ships with TypeScript typings and a command-line interface for converting files without writing code, making it usable both as a library dependency and as a standalone conversion tool in build scripts and pipelines.

What You Get

• Four conversion functions covering every direction: xml2js, xml2json, js2xml, and json2xml
• A non-compact output mode that preserves element order even when sibling elements share a name
• A compact output mode for smaller, more ergonomic JSON when strict order-fidelity isn’t required
• Full support for XML attributes, text, comments, CDATA, DOCTYPE, declarations, and processing instructions
• Configurable key names (e.g. renaming _attributes, _text, _cdata) and custom processing hooks for elements, attributes, and text
• A bundled CLI for converting XML/JSON files from the command line without writing code
• First-class TypeScript type definitions shipped in the package

Common Use Cases

• Converting legacy XML APIs or feeds (RSS, SOAP, config files) into JSON for use in modern JavaScript/Node applications
• Generating XML output (e.g. sitemaps, RSS feeds, SOAP requests) from JavaScript data structures
• Round-tripping XML documents through JSON for programmatic editing while preserving element order and structure
• One-off file conversion in build scripts or CI pipelines via the CLI, without writing custom parsing code
• Parsing XML in browser bundles (via Browserify/Webpack/JSPM) where a lightweight, dependency-minimal parser is preferred

Under The Hood

Architecture The library is organized as four small, single-purpose modules under lib/: xml2js.js and js2xml.js hold the actual conversion logic, while xml2json.js and json2xml.js are thin wrappers that add JSON.stringify/JSON.parse around the JS-object conversions. A shared options-helper.js centralizes default-option handling (ensureFlagExists, ensureKeyExists) so both conversion directions apply consistent defaults, and array-helper.js provides a small isArray utility. lib/index.js aggregates all four functions into a single exported object, and the package’s bin/cli.js sits entirely outside the library, depending only on the public xml2json/json2xml entry points to implement file-based conversion — keeping the CLI decoupled from the core parsing logic.

Tech Stack Written in plain, pre-ES6 JavaScript (var-based, Node-style CommonJS) with a single production dependency, sax, a pure-JavaScript streaming XML parser that xml2js.js drives via event callbacks (onopentag, ontext, oncdata, etc.) to build its element tree. Browser builds are produced via Webpack (webpack.config.js) into dist/, with Babel used for tooling/tests. TypeScript typings are maintained separately in types/index.d.ts and validated with tsc rather than being the implementation language. CI configuration spans Travis, AppVeyor, CircleCI, and GitLab CI, with coverage reported to Coveralls, Codecov, and Codacy.

Code Quality The test/ directory is extensive, with dedicated spec files per concern — xml2js-options.spec.js, xml2js-callbacks.spec.js, xml2js-issues.spec.js, xml2js-keys.spec.js, and equivalent js2xml-* files, plus cli.spec.js, array-helper.spec.js, and options-helper.spec.js. Tests run under both Jasmine and Jest, and a test:types script type-checks the shipped .d.ts file against a dedicated test file. Option validation is explicit and centralized rather than scattered, and the CLI helper throws clear errors for missing required arguments. Inline code comments are sparse — the codebase relies on descriptive function and option names rather than commentary. The project itself has been inactive since mid-2024, with 126 open issues and no releases since 2019, despite the code and tests remaining functional.

API Design The public surface is deliberately small — four functions sharing one options object — which keeps the learning curve low for common conversions. Boolean ignoreX toggles (ignoreComment, ignoreCdata, ignoreDeclaration, etc.) and key-renaming options (textKey, attributesKey, cdataKey) cover nearly every XML construct, letting consumers reshape output without post-processing. Full TypeScript typings and a documented CLI reduce the ramp-up cost further. The API is fully synchronous with no streaming or promise-based interface, and its _-prefixed compact-mode keys follow a different convention than some competing libraries, which can require adjustment when migrating from another XML parser.