xml2js-fxp

xml2js-compatible XML-to-JS parsing API, backed by @nodable/flexible-xml-parser.

Purpose: Users of xml2js can use new features without massive API migration overhead

import xml2js from 'xml2js-fxp';

const result = await xml2js.parseStringPromise('<root><item id="1">hello</item></root>');
// { root: { item: { $: { id: '1' }, _: 'hello' } } }

API

import { Parser, parseString, parseStringPromise, processors, defaults } from 'xml2js-fxp';

const parser = new Parser({ explicitArray: false });
const result = await parser.parseStringPromise(xml);

parseString(xml, (err, result) => { /* ... */ });
parseString(xml, { trim: true }, (err, result) => { /* ... */ });

Supported options

| Option | Default | Status | |---|---|---| | attrkey | '$' | ✅ | | charkey | '_' | ✅ | | explicitCharkey | false | ✅ | | trim | false | ✅ | | normalize | false | ✅ (custom whitespace-collapse parser) | | normalizeTags | false | ✅ | | explicitRoot | true | ✅ | | explicitArray | true | ✅ (root element is never array-wrapped) | | emptyTag | '' | ✅ (string or factory function) | | ignoreAttrs | false | ✅ | | mergeAttrs | false | ✅ | | validator | null | ✅ (post-parse hook, errors reject the promise / pass to callback) | | xmlns | false | ✅ (adds $ns: {local, uri} per element) | | explicitChildren | false | ✅ | | childkey | '$$' | ✅ | | preserveChildrenOrder | false | ✅ (adds #name to each $$ entry) | | charsAsChildren | false | ✅ | | includeWhiteChars | false | ✅ | | async | false | ✅ | | strict | true | ⚠️ approximate — maps to autoClose: null / 'html' | | attrNameProcessors | null | ✅ | | attrValueProcessors | null | ✅ | | tagNameProcessors | null | ✅ | | valueProcessors | null | ✅ |

xml2js.processors re-exports normalize, firstCharLowerCase, stripPrefix, parseNumbers, parseBooleans.

xml2js.defaults['0.1'] and ['0.2'] are provided for parity with xml2js.defaults, but must be applied manually (spread into your options) — they are not auto-selected.

Limitations

• strict maps to autoClose: null (strict, default) or autoClose: 'html' (lenient). This is an approximation of sax-js's strict mode and may not produce identical recovery behavior for all malformed documents.
• xml2js.Builder (JS object → XML serialization) is not implemented. This package covers parsing only. Consider xmlbuilder2 for the reverse direction.
• Namespace support (xmlns: true) covers element namespace resolution ($ns: {local, uri}) for elements with prefixed/default namespaces. Namespace-prefixed attributes are not specially resolved beyond their literal name.

License

MIT