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