function

XML.parse

function parse(
input: string | ArrayBufferLike | TypedArray<ArrayBufferLike> | DataView<ArrayBufferLike> | Blob,
options?: ParseOptions & { compact: true }

Parse an XML 1.0 document.

Bun.XML is a conforming, non-validating XML processor. The document — including any internal DTD subset — must be well-formed or a SyntaxError is thrown; there is no lenient mode. Internal entities are expanded (within an expansion limit), attribute values are normalized, and attribute defaults declared in the internal subset are applied. External DTDs and external entities are never read. Nothing is coerced: every value is a string.

compact selects a structure; it never alters character data. The text of an element is the same in both shapes — as written, whitespace included. The compact shape only does what having a single "#text" forces: an element's text runs are concatenated, and a whitespace-only run between child elements (the document's layout) is left out.

A reference to an entity that only an unread external DTD could declare is not an error (XML 1.0 §4.1) and is kept in the text as written ("&name;" — indistinguishable afterwards from an escaped &amp;name;).

A string is parsed as already-decoded text. Bytes (Buffer, TypedArray, DataView, ArrayBuffer, Blob) are decoded per the XML rules: a byte-order mark or the encoding declared in <?xml ...?> selects UTF-8, UTF-16, or ISO-8859-1; other encodings throw.

@param input

The XML document

import { XML } from "bun";

XML.parse(`<order id="A1"><item sku="x">Tea</item><item sku="y">Mug</item><paid/></order>`);
// {
//   order: {
//     "@id": "A1",
//     item: [ { "@sku": "x", "#text": "Tea" }, { "@sku": "y", "#text": "Mug" } ],
//     paid: "",
//   },
// }

XML.parse(`<p>Hello <b>world</b>!<!-- bye --></p>`, { compact: false });
// {
//   name: "p",
//   attributes: {},
//   children: [ "Hello ", { name: "b", attributes: {}, children: ["world"] }, "!", { comment: " bye " } ],
// }
function parse(
input: string | ArrayBufferLike | TypedArray<ArrayBufferLike> | DataView<ArrayBufferLike> | Blob,
options: ParseOptions & { compact: false }
): Node;

Parse an XML 1.0 document.

Bun.XML is a conforming, non-validating XML processor. The document — including any internal DTD subset — must be well-formed or a SyntaxError is thrown; there is no lenient mode. Internal entities are expanded (within an expansion limit), attribute values are normalized, and attribute defaults declared in the internal subset are applied. External DTDs and external entities are never read. Nothing is coerced: every value is a string.

compact selects a structure; it never alters character data. The text of an element is the same in both shapes — as written, whitespace included. The compact shape only does what having a single "#text" forces: an element's text runs are concatenated, and a whitespace-only run between child elements (the document's layout) is left out.

A reference to an entity that only an unread external DTD could declare is not an error (XML 1.0 §4.1) and is kept in the text as written ("&name;" — indistinguishable afterwards from an escaped &amp;name;).

A string is parsed as already-decoded text. Bytes (Buffer, TypedArray, DataView, ArrayBuffer, Blob) are decoded per the XML rules: a byte-order mark or the encoding declared in <?xml ...?> selects UTF-8, UTF-16, or ISO-8859-1; other encodings throw.

@param input

The XML document

import { XML } from "bun";

XML.parse(`<order id="A1"><item sku="x">Tea</item><item sku="y">Mug</item><paid/></order>`);
// {
//   order: {
//     "@id": "A1",
//     item: [ { "@sku": "x", "#text": "Tea" }, { "@sku": "y", "#text": "Mug" } ],
//     paid: "",
//   },
// }

XML.parse(`<p>Hello <b>world</b>!<!-- bye --></p>`, { compact: false });
// {
//   name: "p",
//   attributes: {},
//   children: [ "Hello ", { name: "b", attributes: {}, children: ["world"] }, "!", { comment: " bye " } ],
// }
function parse(
input: string | ArrayBufferLike | TypedArray<ArrayBufferLike> | DataView<ArrayBufferLike> | Blob,
options?: ParseOptions

Parse an XML 1.0 document.

Bun.XML is a conforming, non-validating XML processor. The document — including any internal DTD subset — must be well-formed or a SyntaxError is thrown; there is no lenient mode. Internal entities are expanded (within an expansion limit), attribute values are normalized, and attribute defaults declared in the internal subset are applied. External DTDs and external entities are never read. Nothing is coerced: every value is a string.

compact selects a structure; it never alters character data. The text of an element is the same in both shapes — as written, whitespace included. The compact shape only does what having a single "#text" forces: an element's text runs are concatenated, and a whitespace-only run between child elements (the document's layout) is left out.

A reference to an entity that only an unread external DTD could declare is not an error (XML 1.0 §4.1) and is kept in the text as written ("&name;" — indistinguishable afterwards from an escaped &amp;name;).

A string is parsed as already-decoded text. Bytes (Buffer, TypedArray, DataView, ArrayBuffer, Blob) are decoded per the XML rules: a byte-order mark or the encoding declared in <?xml ...?> selects UTF-8, UTF-16, or ISO-8859-1; other encodings throw.

@param input

The XML document

import { XML } from "bun";

XML.parse(`<order id="A1"><item sku="x">Tea</item><item sku="y">Mug</item><paid/></order>`);
// {
//   order: {
//     "@id": "A1",
//     item: [ { "@sku": "x", "#text": "Tea" }, { "@sku": "y", "#text": "Mug" } ],
//     paid: "",
//   },
// }

XML.parse(`<p>Hello <b>world</b>!<!-- bye --></p>`, { compact: false });
// {
//   name: "p",
//   attributes: {},
//   children: [ "Hello ", { name: "b", attributes: {}, children: ["world"] }, "!", { comment: " bye " } ],
// }

Referenced types

class Blob

A file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system.

MDN Reference

  • readonly size: number
  • readonly type: string

  • Returns a promise that resolves to the contents of the blob as an ArrayBuffer

  • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

    Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes). Equivalent to new Uint8Array(await blob.arrayBuffer())

  • formData(): Promise<FormData>;

    Read the data from the blob as a FormData object.

    This first decodes the data from UTF-8, then parses it as a multipart/form-data body or an application/x-www-form-urlencoded body.

    The blob's type property determines the format of the body.

    This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

  • options?: ConstructorOptions
    ): Image;

    Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

    await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");
  • json(): Promise<any>;

    Read the data from the blob as a JSON object.

    This first decodes the data from UTF-8, then parses it as JSON.

  • start?: number,
    end?: number,
    contentType?: string
    ): Blob;

  • Returns a readable stream of the blob's contents

  • text(): Promise<string>;

    Returns a promise that resolves to the contents of the blob as a string

interface ParseOptions

  • compact?: boolean

    Selects the shape of the result.

    • true (default): the compact Document — elements keyed by name, leaves as strings. The shape for data. It does not keep the relative order of differently named siblings, where text sat relative to child elements, comments, or processing instructions.
    • false: the root element as a Node tree, which keeps all of those, in document order. The shape for documents.

    Neither shape represents the XML declaration, the document type declaration, or anything outside the root element.

interface Document

A parsed document in the compact shape: exactly one key, the root element's name. This is also what importing an .xml file evaluates to.

interface Node

An element in the tree parse returns with { compact: false }.

  • attributes: Record<string, string>

    Attribute values by name as written, in document order, after attribute-value normalization and with defaults declared in the internal DTD subset applied. Namespace declarations (xmlns, xmlns:*) are ordinary attributes.

  • children: string | Node | Comment | ProcessingInstruction[]

    The element's content in document order: character data as strings (exact — CDATA sections, character references and internal entities expanded, whitespace untouched, adjacent text merged into one string), child elements, comments and processing instructions. An object here is an element if it has name, a comment if it has comment, and a processing instruction if it has target.

  • name: string

    The element name as written, including any namespace prefix ("soap:Envelope").