XML parser for Deno

Basic usage

import { parse } from "https://deno.land/x/xml/mod.ts";

console.log(parse(`
  <root>
    <!-- This is a comment -->
    <text>hello</text>
    <array>world</array>
    <array>monde</array>
    <array>世界</array>
    <array>🌏</array>
    <number>42</number>
    <boolean>true</boolean>
    <complex attribute="value">content</complex>
  </root>
`));
/*
  Same nodes are grouped into arrays, while numbers and booleans are auto-parsed (can be disabled)
  Nodes with attributes will not be flattened and you'll be able to access them with "@" prefix while
  text nodes are available through "#text" key and comment nodes are available through "#comment" key
  {
    root: {
      "#comment": "This is a comment",
      text: "hello",
      array: ["world", "monde", "世界", "🌏"],
      number: 42,
      boolean: true,
      complex: {
        "@attribute": "value",
        "#text": "content",
      }
    }
  }
*/

import { stringify } from "https://deno.land/x/xml/mod.ts";

console.log(stringify({
  root: {
    "#comment": "This is a comment",
    text: "hello",
    array: ["world", "monde", "世界", "🌏"],
    number: 42,
    boolean: true,
    complex: {
      "@attribute": "value",
      "#text": "content",
    },
  },
}));

Features

Follow XML.com’s Converting between XML and JSON patterns.

Support basic XML features (tags, self-closed tags, nested tags, attributes, …)
Support XML.parse and XML.stringify
Support <?xml ?> prolog declaration
Support <!DOCTYPE> declaration
Support <![CDATA[ ]] strings
Support  comments
Support XML entities (&, &, &, …)
Support auto-conversion of primitives (strings, booleans, numbers, null, …)
Support strings or streams (Deno.ReaderSync & Deno.SeekerSync) inputs
Support custom revivers and replacers
Support metadata (parent, name, …) hidden in a non-enumerable property
Auto-group nodes into arrays when same tag is used
Auto-unwrap nodes when it only has text content

How reliable is deno.land/x/xml? Check parse tests and stringify tests 🧪

Limitations

When using mixed content of texts and child nodes, it will be parsed as a text node
When using mixed group of nodes, XML.stringify(XML.parse())) may result in a different order
- Example: <a><b/><c/><b/></a> will result in <a><b/><b/><c/></a>
- This may or may not be acceptable depending on your use case

Revivers

By default, node contents will be converted to:

null when empty, unless emptyToNull = false
number when matching finite numbers, unless reviveNumbers = false
boolean when matching true or false (case insensitive), unless reviveBooleans = false

XML entities (e.g. &, &, &, …) will be unescaped automatically.

It is also possible to provide a custom reviver for complex transformations:

import { parse } from "./mod.ts";
console.log(parse(
  `
  <prices>
    <product>dakimakura</product>
    <price currency="usd">10.5</price>
    <price currency="eur">10.5</price>
    <price currency="yen">10.5</price>
    <useless/>
  </prices>
`,
  {
    reviver({ value, key, tag, properties }) {
      //Apply special processing for tag, attributes and properties
      if (tag === "price") {
        if (key === "@currency") {
          return { usd: "$", eur: "€", yen: "¥" }[value as string] ?? "?";
        }
        if (key === "#text") {
          delete this["@currency"];
          return `${value}${properties?.["@currency"]}`;
        }
      }
      //Filter out useless elements
      if (tag === "useless") {
        return undefined;
      }
      return value;
    },
  },
));
/*
  Like JSON.parse's reviver, computed value can be transformed before being returned.
  - `this` will refer to the node being edited, meaning that any edition will reflect
    on final parsed value.
  - `properties` can be accessed only after all other node's properties have been
    parsed
  - returning `undefined` (or nothing) will filter out current value
  {
    prices: {
      product: "dakimakura",
      price: [ "10.5$", "10.5€", "10.5¥" ]
    }
  }
*/

Replacers

By default, /// will be converted to:

"" when null, unless nullToEmpty = false

XML entities (e.g. &;, <, >, ", ' …) will be escaped automatically.

It is also possible to provide a custom replacer for complex transformations:

XML metadata

It is possible to access several metadata properties using $XML symbol, like parent node, name, etc.

import { $XML, parse } from "./mod.ts";
console.log($XML);
console.log(Deno.inspect(
  parse(
    `
  <root>
    <child>hello world</child>
  </root>
`,
    { flatten: false },
  ),
  { showHidden: true, compact: false },
));
/*
  Symbol("x/xml")
  {
    root: {
      child: {
        "#text": "hello world",
        [Symbol("x/xml")]: {
          name: "child",
          parent: [Circular]
        }
      },
      [Symbol("x/xml")]: {
        name: "root",
        parent: null
      }
    }
  }
*/

Parsing large files

Parsing large files of several mega bytes can take some time. You can use progress option to pass a callback each time a node has been parsed.

import { parse } from "./mod.ts";
const file = await Deno.open("my.xml");
const { size } = await file.stat();
console.log(parse(file, {
  progress(bytes) {
    Deno.stdout.writeSync(
      new TextEncoder().encode(
        `Parsing document: ${(100 * bytes / size).toFixed(2)}%\r`,
      ),
    );
  },
}));

Why does this use synchronous API ?

While there are no official specs for XML.parse and XML.stringify, it is intended to look like native JSON handler, hence why it is synchronous, and contains replacers and revivers.