just-jx

Fast, typed XML-to-JSON converter for Node.js and the browser.

import { justJx } from 'just-jx';

justJx('<user id="1"><name>Alice</name></user>');
// → { user: { "@id": "1", name: "Alice" } }

Installation

npm install just-jx
pnpm add just-jx
yarn add just-jx

Usage

Basic

import { justJx } from 'just-jx';

justJx('<root><child>hello</child></root>');
// → { root: { child: "hello" } }

Attributes

Attributes are prefixed with @ by default:

justJx('<user id="42" active="true">Alice</user>');
// → { user: { "@id": "42", "@active": "true", "#text": "Alice" } }

Repeated elements → arrays

A single occurrence stays as an object; multiple occurrences become an array automatically:

justJx(`
  <items>
    <item>Apple</item>
    <item>Banana</item>
    <item>Cherry</item>
  </items>
`);
// → { items: { item: ["Apple", "Banana", "Cherry"] } }

CDATA

CDATA sections are treated transparently — their content is merged into the text value:

justJx('<root><![CDATA[Hello <World> & "friends"]]></root>');
// → { root: "Hello <World> & \"friends\"" }

Namespaces

Namespace prefixes are preserved by default:

justJx(`
  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body />
  </soap:Envelope>
`);
// → { "soap:Envelope": { "@xmlns:soap": "http://...", "soap:Body": "" } }

Strip prefixes with stripNamespaces:

justJx(xml, { stripNamespaces: true });
// → { Envelope: { Body: "" } }

Self-closing tags

justJx('<root><br/><img src="photo.jpg" alt="a photo"/></root>');
// → { root: { br: "", img: { "@src": "photo.jpg", "@alt": "a photo" } } }

Options

interface Options {
  /**
   * Prefix prepended to attribute keys.
   * @default "@"
   */
  attributePrefix?: string;

  /**
   * Key used for text content and transparent CDATA.
   * @default "#text"
   */
  textKey?: string;

  /**
   * Wrap every element in an array, even single occurrences.
   * @default false
   */
  forceArray?: boolean;

  /**
   * Element names that are always arrays, even when appearing once.
   * @default []
   */
  alwaysArray?: string[];

  /**
   * Strip namespace prefixes from element and attribute names.
   * @default false
   */
  stripNamespaces?: boolean;
}

forceArray

justJx('<root><child>hello</child></root>', { forceArray: true });
// → { root: [{ child: ["hello"] }] }

alwaysArray

Useful for elements that may appear once or multiple times in a schema:

justJx('<items><item>only one</item></items>', { alwaysArray: ['item'] });
// → { items: { item: ["only one"] } }

Custom attributePrefix and textKey

justJx('<el id="1">text</el>', { attributePrefix: '$', textKey: '_' });
// → { el: { "$id": "1", "_": "text" } }

Error handling

justJx throws on invalid XML with a message that includes the line and column:

try {
  justJx('<unclosed>');
} catch (e) {
  console.error(e.message);
  // Invalid XML at 1:1 — Unclosed tag 'unclosed'.
}

Roadmap

• [ ] Replace fast-xml-parser with a custom zero-dependency XML parser

License

MIT