@lowlighter/xml 5.2.1 → 5.3.0

package/stringify.ts

@@ -0,0 +1,241 @@
+// Imports
+import type { Nullable, record, rw } from "@libs/typing"
+import type { xml_document, xml_node, xml_text } from "./_types.ts"
+
+// Re-exports
+export type { xml_document, xml_node, xml_text }
+
+/** XML stringifier options. */
+export type options = {
+  /** Format options. */
+  format?: {
+    /**
+     * Indent string (defaults to `"  "`).
+     * Set to empty string to disable indentation and enable minification.
+     */
+    indent?: string
+    /** Break text node if its length is greater than this value (defaults to `128`). */
+    breakline?: number
+  }
+  /** Replace options. */
+  replace?: {
+    /**
+     * Force escape all XML entities.
+     * By default, only the ones that would break the XML structure are escaped.
+     */
+    entities?: boolean
+    /**
+     * Custom replacer (this is applied after other revivals).
+     * When it is applied on an attribute, `key` and `value` will be given.
+     * When it is applied on a node, both `key` and `value` will be `null`.
+     * Return `undefined` to delete either the attribute or the tag.
+     */
+    custom?: (args: { name: string; key: Nullable<string>; value: Nullable<string>; node: Readonly<xml_node> }) => unknown
+  }
+}
+
+/** XML stringifier options (with non-nullable format options). */
+type _options = options & { format: NonNullable<options["format"]> }
+
+//*   - `readonly ["~children"]: Array<xml_node|xml_text>`: node children
+
+/**
+ * Stringify an {@link xml_document} object into a XML string.
+ *
+ * Output can be customized using the {@link options} parameter.
+ *
+ * @example
+ * ```ts
+ * import { stringify } from "./stringify.ts"
+ *
+ * console.log(stringify({
+ *   root: {
+ *     text: "hello",
+ *     array: ["world", "monde", "世界", "🌏"],
+ *     number: 42,
+ *     boolean: true,
+ *     complex: {
+ *       "@attribute": "value",
+ *       "#text": "content",
+ *     },
+ *   }
+ * }))
+ * ```
+ */
+export function stringify(document: Partial<xml_document>, options?: options): string {
+  options ??= {}
+  options.format ??= {}
+  options.format.indent ??= "  "
+  options.format.breakline ??= 128
+  const _options = options as _options
+  let text = ""
+  // Add prolog
+  text += xml_prolog(document as xml_document, _options)
+  // Add processing instructions
+  if (document["#instructions"]) {
+    for (const nodes of Object.values(document["#instructions"])) {
+      for (const node of [nodes].flat()) {
+        text += xml_instruction(node, _options)
+      }
+    }
+  }
+  // Add doctype
+  if (document["#doctype"]) {
+    text += xml_doctype(document["#doctype"] as xml_node, _options)
+  }
+
+  // Add root node
+  const [root, ...garbage] = xml_children(document as xml_document, _options)
+  if (garbage.length) {
+    throw new SyntaxError("Multiple root node detected")
+  }
+  text += xml_node(root, { ..._options, depth: 0 })
+
+  return text.trim()
+}
+
+/** Create XML prolog. */
+function xml_prolog(document: xml_document, options: _options): string {
+  ;(document as rw)["~name"] ??= "xml"
+  return xml_instruction(document, options)
+}
+
+/** Create XML instruction. */
+function xml_instruction(node: xml_node, { format: { indent } }: _options): string {
+  let text = ""
+  const attributes = xml_attributes(node as xml_node, arguments[1])
+  if (attributes.length) {
+    text += `<?${node["~name"].replace(/^~/, "")}`
+    for (const [name, value] of attributes) {
+      text += ` ${name}="${value}"`
+    }
+    text += `?>${indent ? "\n" : ""}`
+  }
+  return text
+}
+
+/** Create XML doctype. */
+function xml_doctype(node: xml_node, { format: { indent } }: _options): string {
+  let text = ""
+  const attributes = xml_attributes(node, arguments[1])
+  const elements = xml_children(node, arguments[1])
+  if (attributes.length + elements.length) {
+    text += `<!DOCTYPE`
+    for (const [name] of attributes) {
+      text += ` ${!/^[A-Za-z0-9_]+$/.test(name) ? `"${name}"` : name}`
+    }
+    if (elements.length) {
+      text += `${indent ? `\n${indent}` : " "}[${indent ? "\n" : ""}`
+      for (const element of elements) {
+        text += `${indent}<!ELEMENT ${element["~name"]} (${element["#text"]})>${indent ? "\n" : ""}`
+      }
+      text += `${indent ? indent : ""}]${indent ? "\n" : ""}`
+    }
+    text += `>${indent ? "\n" : ""}`
+  }
+  return text
+}
+
+/** Create XML node. */
+function xml_node(node: xml_node, { format: { breakline = 0, indent = "" }, replace, depth = 0 }: _options & { depth?: number }): string {
+  if (replace?.custom) {
+    if (replace.custom({ name: node["~name"], key: null, value: null, node }) === undefined) {
+      return ""
+    }
+  }
+  let text = `${indent.repeat(depth)}<${node["~name"]}`
+  const attributes = xml_attributes(node, arguments[1])
+  const children = xml_children(node, arguments[1])
+  const preserve = node["@xml:space"] === "preserve"
+  for (const [name, value] of attributes) {
+    text += ` ${name}="${value}"`
+  }
+  if ((children.length) || (("#text" in node) && (node["#text"].length))) {
+    const inline = indent && (!preserve) && ((children.length) || (node["#text"].length > breakline - indent.length * depth))
+    text += `>${indent && (!preserve) && (children.length) ? "\n" : ""}`
+    if ("#text" in node) {
+      if (inline) {
+        text += `\n${indent.repeat(depth + 1)}`
+      }
+      text += node["#text"]
+      if (inline) {
+        text += "\n"
+      }
+    }
+    for (const child of children) {
+      text += xml_node(child, { ...arguments[1], depth: depth + 1 })
+    }
+    if (inline) {
+      text += indent.repeat(depth)
+    }
+    text += `</${node["~name"]}>${indent ? "\n" : ""}`
+  } else {
+    text += `/>${indent ? "\n" : ""}`
+  }
+  return text
+}
+
+/** Extract children from node. */
+function xml_children(node: xml_node, options: options): Array<xml_node> {
+  const children = Object.keys(node)
+    .filter((key) => /^[A-Za-z_]/.test(key))
+    .flatMap((key) =>
+      [node![key]].flat().map((value) => {
+        switch (true) {
+          case value === null:
+            return ({ ["~name"]: key, ["#text"]: "" })
+          case typeof value === "object":
+            return ({ ["~name"]: key, ...value as record })
+          default:
+            return ({ ["~name"]: key, ["#text"]: `${value}` })
+        }
+      })
+    )
+    .map((node) => {
+      if ("#text" in node) {
+        node["#text"] = replace(node as xml_node, "#text", { ...options, escape: ["<", ">"] }) as string
+        if (node["#text"] === undefined) {
+          delete node["#text"]
+        } else {
+          node["#text"] = `${node["#text"]}`
+        }
+      }
+      return node
+    }) as ReturnType<typeof xml_children>
+  //TODO(@lowlighter): Eventually add node["~children"] support for ordering and possibly bypass the children search
+  return children
+}
+
+/** Extract attributes from node. */
+function xml_attributes(node: xml_node, options: options): Array<[string, string]> {
+  return Object.entries(node!)
+    .filter(([key]) => key.startsWith("@"))
+    .map(([key]) => [key.slice(1), replace(node!, key, { ...options, escape: ['"', "'"] })])
+    .filter(([_, value]) => value !== undefined) as ReturnType<typeof xml_attributes>
+}
+
+/** Entities */
+const entities = {
+  "&": "&amp;", //Keep first
+  '"': "&quot;",
+  "<": "&lt;",
+  ">": "&gt;",
+  "'": "&apos;",
+} as const
+
+/** Replace value. */
+function replace(node: xml_node | xml_text, key: string, options: options & { escape?: Array<keyof typeof entities> }) {
+  let value = `${(node as xml_node)[key]}` as string
+  if (options?.escape) {
+    if (options?.replace?.entities) {
+      options.escape = Object.keys(entities) as Array<keyof typeof entities>
+    }
+    for (const char of options?.escape) {
+      value = `${value}`.replaceAll(char, entities[char])
+    }
+  }
+  if (options?.replace?.custom) {
+    return options.replace.custom({ name: node["~name"], key, value, node: node as xml_node })
+  }
+  return value
+}

package/stringify_test.ts

@@ -0,0 +1,284 @@
+import { type options as parse_options, parse } from "./parse.ts"
+import { type options as stringify_options, stringify } from "./stringify.ts"
+import { expect, test } from "@libs/testing"
+
+// This operation ensure that reforming a parsed XML will still yield same data
+const check = (xml: string, options?: parse_options & stringify_options) => {
+  expect(stringify(parse(xml, options), options), xml)
+  return parse(stringify(parse(xml, options), options), options)
+}
+
+test("all")("stringify(): xml syntax xml prolog", () =>
+  expect(
+    check(
+      `<?xml version="1.0" encoding="UTF-8"?>
+<root/>`,
+    ),
+  ).toEqual(
+    {
+      "@version": "1.0",
+      "@encoding": "UTF-8",
+      root: null,
+    },
+  ))
+
+test("all")("stringify(): xml syntax xml stylesheet", () =>
+  expect(
+    check(
+      `<?xml version="1.0" encoding="UTF-8"?>
+  <?xml-stylesheet href="styles.xsl" type="text/xsl"?>
+  <root/>`,
+    ),
+  ).toEqual(
+    {
+      "@version": "1.0",
+      "@encoding": "UTF-8",
+      "#instructions": {
+        "xml-stylesheet": {
+          "@href": "styles.xsl",
+          "@type": "text/xsl",
+        },
+      },
+      root: null,
+    },
+  ))
+
+test("all")("stringify(): xml syntax doctype", () =>
+  expect(
+    check(
+      `<!DOCTYPE type "quoted attribute" [
+          <!ELEMENT element (value)>
+        ]>
+  <root/>`,
+    ),
+  ).toEqual(
+    {
+      "#doctype": {
+        "@type": "",
+        "@quoted attribute": "",
+        element: "value",
+      },
+      root: null,
+    },
+  ))
+
+for (const indent of ["  ", ""]) {
+  test("all")(`stringify(): xml example w3schools.com#3 (indent = "${indent}")`, () =>
+    expect(
+      check(
+        `
+      <?xml version="1.0" encoding="UTF-8"?>
+      <?xml-stylesheet href="styles.xsl" type="text/xsl"?>
+      <!DOCTYPE type "quoted attribute" [
+        <!ELEMENT element (value)>
+      ]>
+      <bookstore>
+        <notebook/>
+        <book category="cooking">
+          <!-- Comment Node -->
+          <title lang="en">Everyday Italian</title>
+          <author>Giada De Laurentiis</author>
+          <year>2005</year>
+          <price>30</price>
+        </book>
+        <book category="children">
+          <!-- First Comment Node -->
+          <!-- Second Comment Node -->
+          <title lang="en">Harry Potter</title>
+          <author>J K. Rowling</author>
+          <year>2005</year>
+          <price>29.99</price>
+        </book>
+        <book category="web">
+          <title lang="en">XQuery Kick Start</title>
+          <author>James McGovern</author>
+          <author>Per Bothner</author>
+          <author>Kurt Cagle</author>
+          <author>James Linn</author>
+          <author>Vaidyanathan Nagarajan</author>
+          <year>2003</year>
+          <price>49.99</price>
+        </book>
+        <book category="web" cover="paperback">
+          <title lang="en">Learning XML</title>
+          <author>Erik T. Ray</author>
+          <year>2003</year>
+          <price>39.95</price>
+        </book>
+      </bookstore>`,
+        { revive: { booleans: true, numbers: true }, format: { indent } },
+      ),
+    ).toEqual(
+      {
+        "@version": "1.0",
+        "@encoding": "UTF-8",
+        "#instructions": {
+          "xml-stylesheet": {
+            "@href": "styles.xsl",
+            "@type": "text/xsl",
+          },
+        },
+        "#doctype": {
+          "@type": "",
+          "@quoted attribute": "",
+          element: "value",
+        },
+        bookstore: {
+          notebook: null,
+          book: [
+            {
+              "@category": "cooking",
+              title: { "@lang": "en", "#text": "Everyday Italian" },
+              author: "Giada De Laurentiis",
+              year: 2005,
+              price: 30,
+            },
+            {
+              "@category": "children",
+              title: { "@lang": "en", "#text": "Harry Potter" },
+              author: "J K. Rowling",
+              year: 2005,
+              price: 29.99,
+            },
+            {
+              "@category": "web",
+              title: { "@lang": "en", "#text": "XQuery Kick Start" },
+              author: [
+                "James McGovern",
+                "Per Bothner",
+                "Kurt Cagle",
+                "James Linn",
+                "Vaidyanathan Nagarajan",
+              ],
+              year: 2003,
+              price: 49.99,
+            },
+            {
+              "@category": "web",
+              "@cover": "paperback",
+              title: { "@lang": "en", "#text": "Learning XML" },
+              author: "Erik T. Ray",
+              year: 2003,
+              price: 39.95,
+            },
+          ],
+        },
+      },
+    ))
+}
+
+test("all")("stringify(): xml types", () =>
+  expect(
+    check(
+      `<types>
+    <boolean>true</boolean>
+    <null/>
+    <string>hello</string>
+  </types>`,
+      { revive: { booleans: true } },
+    ),
+  ).toEqual(
+    {
+      types: {
+        boolean: true,
+        null: null,
+        string: "hello",
+      },
+    },
+  ))
+
+test("all")("stringify(): xml entities", () =>
+  expect(
+    check(`<string>&quot; &lt; &gt; &amp; &apos;</string>`),
+  ).toEqual(
+    {
+      string: `" < > & '`,
+    },
+  ))
+
+test("all")(
+  "stringify(): xml entities are escaped only where needed",
+  () =>
+    expect(stringify({
+      root: {
+        "@attribute": `<text with escaped quotes (',")>`,
+        text: `only < and > should be escaped, not &, ", '`,
+      },
+    }, { format: { breakline: 0 } })).toEqual(
+      `
+<root attribute="<text with escaped quotes (&apos;,&quot;)>">
+  <text>
+    only &lt; and &gt; should be escaped, not &, ", '
+  </text>
+</root>`.trim(),
+    ),
+)
+
+test("all")(
+  "stringify(): xml entiries are always escaped when escapeAllEntities is true",
+  () =>
+    expect(stringify({
+      root: {
+        "@attribute": `< > &, ", '`,
+        text: `< > &, ", '`,
+      },
+    }, { replace: { entities: true }, format: { breakline: 0 } })).toEqual(
+      `
+<root attribute="&lt; &gt; &amp;, &quot;, &apos;">
+  <text>
+    &lt; &gt; &amp;, &quot;, &apos;
+  </text>
+</root>`.trim(),
+    ),
+)
+
+test("all")("stringify(): xml space preserve", () =>
+  expect(
+    check(`<text xml:space="preserve"> hello world </text>`),
+  ).toEqual(
+    {
+      text: {
+        "#text": " hello world ",
+        "@xml:space": "preserve",
+      },
+    },
+  ))
+
+test("all")("stringify(): cdata is preserved", () =>
+  expect(
+    check(`<string><![CDATA[hello <world>]]></string>`),
+  ).toEqual(
+    {
+      string: `hello <world>`,
+    },
+  ))
+
+// Custom replacer
+
+test("all")("stringify(): xml replacer", () =>
+  expect(
+    stringify({ root: { not: true, yes: true, delete: true, attribute: { "@delete": true } } }, {
+      replace: {
+        custom: ({ name, key, value }) => {
+          if ((name === "delete") || (key === "@delete")) {
+            return undefined
+          }
+          if ((name === "not") && (key === "#text")) {
+            return !value
+          }
+          return value
+        },
+      },
+    }),
+  ).toBe(
+    `
+<root>
+  <not>false</not>
+  <yes>true</yes>
+  <attribute/>
+</root>`.trim(),
+  ))
+
+//Errors checks
+
+test("all")("stringify(): xml syntax unique root", () => expect(() => stringify({ root: null, garbage: null })).toThrow(SyntaxError))

package/wasm_xml_parser/Cargo.lock

@@ -0,0 +1,159 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "bumpalo"
+version = "3.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79296716171880943b8470b5f8d03aa55eb2e645a4874bdbb28adb49162e012c"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
+
+[[package]]
+name = "js-sys"
+version = "0.3.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29c15563dc2726973df627357ce0c9ddddbea194836909d655df6a75d2cf296d"
+dependencies = [
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "log"
+version = "0.4.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90ed8c1e510134f979dbc4f070f87d4313098b704861a105fe34231c70a3901c"
+
+[[package]]
+name = "memchr"
+version = "2.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c8640c5d730cb13ebd907d8d04b52f55ac9a2eec55b440c8892f40d56c76c1d"
+
+[[package]]
+name = "once_cell"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3fdb12b2476b595f9358c5161aa467c2438859caa136dec86c26fdd2efe17b92"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.82"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ad3d49ab951a01fbaafe34f2ec74122942fe18a3f9814c3268f1bb72042131b"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quick-xml"
+version = "0.31.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1004a344b30a54e2ee58d66a71b32d2db2feb0a31f9a2d302bf0536f15de2a33"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fa76aaf39101c457836aec0ce2316dbdc3ab723cdda1c6bd4e6ad4208acaca7"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.64"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ad3dee41f36859875573074334c200d1add8e4a87bb37113ebd31d926b7b11f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b"
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4be2531df63900aeb2bca0daaaddec08491ee64ceecbee5076636a3b026795a8"
+dependencies = [
+ "cfg-if",
+ "wasm-bindgen-macro",
+]
+
+[[package]]
+name = "wasm-bindgen-backend"
+version = "0.2.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "614d787b966d3989fa7bb98a654e369c762374fd3213d212cfc0251257e747da"
+dependencies = [
+ "bumpalo",
+ "log",
+ "once_cell",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1f8823de937b71b9460c0c34e25f3da88250760bec0ebac694b49997550d726"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e94f17b526d0a461a191c78ea52bbce64071ed5c04c9ffe424dcb38f74171bb7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-backend",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af190c94f2773fdb3729c55b007a722abb5384da03bc0986df4c289bf5567e96"
+
+[[package]]
+name = "wasm_xml_parser"
+version = "0.1.0"
+dependencies = [
+ "quick-xml",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77afa9a11836342370f4817622a2f0f418b134426d91a82dfb48f532d2ec13ef"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]

package/wasm_xml_parser/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "wasm_xml_parser"
+version = "0.1.0"
+authors = ["lowlighter"]
+edition = "2021"
+description = "WASM XML parser"
+repository = "https://github.com/lowlighter/libs"
+license = "MIT"
+
+[dependencies]
+quick-xml = "0.31"
+wasm-bindgen = "0.2"
+web-sys = { version = "0.3" }
+
+[lib]
+crate-type = ["cdylib", "rlib"]