@lowlighter/xml 5.4.7 → 5.4.9

package/README.md

@@ -8,22 +8,23 @@
 
 ## ✨ Features
 
-- Based on [quick-xml](https://github.com/tafia/quick-xml) rust package (compiled to WASM)
-- Support `XML.parse` and `XML.stringify`
-- Support `<!-- -->` comments
-- Support XML entities (`&amp;`, `&#38;`, `&#x26;`, ...)
-- Support mixed content (text and nodes)
-- Large output transformation options
-  - Auto-flattening of nodes with a single child, text or attributes
-  - Auto-revival of `boolean`, `number`, etc.
-  - Auto-group same-named nodes into arrays
-  - Formatting options (indentation, break lines, etc.)
-  - Custom `reviver` and `replacer` functions
-- Metadata stored into non-enumerable properties for advanced usage
+- Based on the [quick-xml](https://github.com/tafia/quick-xml) Rust package (compiled to WASM).
+- Support for `XML.parse` and `XML.stringify` in the style of the `JSON` global.
+- Support for `<!-- -->` comments.
+- Support for XML entities (`&amp;`, `&#38;`, `&#x26;`, …).
+- Support for mixed content (both text and nodes).
+- Support for large output transformation options:
+  - Auto-flatten nodes with a single child, text or attributes
+  - Auto-revive `boolean`s, `number`s, etc.
+  - Auto-group same-named nodes into arrays.
+  - Format (indentation, break lines, etc.)
+  - Support for custom `reviver` and `replacer` functions
+- Support for metadata stored into non-enumerable properties (advanced usage).
 
 ## 🕊️ Migrating from `4.x.x` to `5.x.x`
 
-Starting from version `5.0.0`, this library use a WASM-compiled binding of the [quick-xml](https://github.com/tafia/quick-xml) rust package. It provides better performances while allowing to support more features.
+Prior to version version `5.0.0`, this library was fully written in TypeScript.
+It now uses a WASM-compiled binding of the [quick-xml](https://github.com/tafia/quick-xml) Rust package, which provides better performance while allowing us to support more features.
 
 ### Internal API changes
 
@@ -40,7 +41,7 @@ The `$XML` internal symbol has been replaced by a set of non-enumerable properti
 </root>
 ```
 
-```diff
+```diff js
   <ref *1> {
 -   [$XML]: { cdata: [ "root", "node" ] },
 +   "~parent": null,
@@ -70,7 +71,7 @@ Processing instructions (like XML stylesheets) are now parsed the same way as re
 <root/>
 ```
 
-```diff
+```diff js
   {
 -   xml: {
 -     "@version": "1.0",
@@ -90,7 +91,8 @@ Processing instructions (like XML stylesheets) are now parsed the same way as re
 
 ### Mixed content support
 
-This breaks any existing code that was expecting mixed content to always be a string. Now mixed content nodes will be parsed as usual, and the `#text` property will contain the "inner text" of the node.
+This breaks any existing code that was expecting mixed content to always be a string.
+Now, mixed content nodes will be parsed as usual, and the `#text` property will contain the "inner text" of the node.
 
 Note that `#text` is actually a getter that recursively gets the `#text` of children nodes (ignoring comment nodes), so it'll also handle nested mixed content correctly.
 
@@ -98,7 +100,7 @@ Note that `#text` is actually a getter that recursively gets the `#text` of chil
 <root>some <b>bold</b> text</root>
 ```
 
-```diff
+```diff js
   {
 -   root: "some <b>bold</b> text",
 +   root: {
@@ -110,15 +112,17 @@ Note that `#text` is actually a getter that recursively gets the `#text` of chil
 
 ### Comments
 
-Comments have been moved into `"#comments"` property. Note that this property is now always an array, even if there is only one comment.
+Comments have been moved into `"#comments"` property.
+Note that this property is now always an array, even if there is only one comment.
 
-Additionally, you can find comments into the `~children` property by searching for nodes with `"~name": "~comment"`. If you call the `#text` getter on a parent node containing comments, it will return the inner text without comments.
+Additionally, you can find comments into the `~children` property by searching for nodes with `"~name": "~comment"`.
+If you call the `#text` getter on a parent node containing comments, it will return the inner text without comments.
 
 ```xml
 <root><!--some comment--></root>
 ```
 
-```diff
+```diff js
   {
     root: {
 -     "#comment": "some comment",
@@ -131,16 +135,17 @@ Additionally, you can find comments into the `~children` property by searching f
 
 #### Options
 
-Parse options are categorized into 4 groups:
+Parsing options are categorized into 4 groups:
 
 - `clean`, which can remove `attributes`, `comments`, xml `doctype` and `instructions` from the output
 - `flatten`, which can flatten nodes with only a `text` node, `empty` ones or transform `attributes` only nodes into objects without the `@` prefix
 - `revive`, which can `trim` content (unless `xml:space="preserve"`), unescape xml `entities`, revive `booleans` and `numbers`
   - You can also provide a `custom` reviver function (applied after other revivals) that will be called on each attribute and node
   - _Note that signature of the reviver function has changed_
-- `mode`, which can be either `xml` or `html`. Choosing the latter will be more permissive than the former.
+- `mode`, which can be either `xml` or `html`.
+  Choosing the latter will be more permissive than the former.
 
-```diff
+```diff js
   const options = {
 -   reviveBooleans: true,
 -   reviveNumbers: true,
@@ -165,13 +170,13 @@ import { parse } from "./parse.ts"
 parse(await Deno.readTextFile("example.xml"))
 ```
 
-Async parsing is not supported yet, but might be added in the future.
+Async parsing is not supported yet, but might be added in the future (see [#49](https://github.com/lowlighter/libs/issues/49)).
 
 ### Stringifying
 
 #### Options
 
-Stringify options are now categorized into 2 groups:
+Stringifying options are now categorized into 2 groups:
 
 - `format`, which can configure the `indent` string and automatically `breakline` when a text node is too long
   - _Since you pass a string rather than a number for indent, it means that you can also use tabs instead of space too_
@@ -179,7 +184,7 @@ Stringify options are now categorized into 2 groups:
   - You can also provide a `custom` replacer function that will be called on each attribute and node
   - _Note that signature of the replacer function has changed_
 
-```diff
+```diff js
   const options = {
 -   indentSize: 2,
 +   format: { indent: "  " },
@@ -196,9 +201,10 @@ Please refer to the [documentation](https://jsr.io/@libs/xml/doc) for more infor
 
 ### Stringifying content
 
-Please refer to the above section about API changes. If you were handling XML document properties, using the `$XML` symbol or `#comment` property, or dealing with mixed nodes content, you'll most likely need to update your code.
+Please refer to the above section about API changes.
+If you were handling XML document properties, using the `$XML` symbol or `#comment` property, or dealing with mixed nodes content, you'll most likely need to update your code.
 
-This library now provides `comment()` and `cdata()` helpers to respectively create comment and CDATA nodes.
+Additionally, the library now provides `comment()` and `cdata()` helpers to respectively create comment and CDATA nodes:
 
 ```ts
 import { cdata, comment, stringify } from "./stringify.ts"
@@ -234,16 +240,31 @@ stringify({
 </root>
 ```
 
-Note that while you can theorethically use internal API properties, we strongly advise against it currently. Supporting `~children` might be added in the future ([#57](https://github.com/lowlighter/libs/issues/57)) for mixed content, but its behavior is not well defined yet.
+Note that while you can _theoretically_ use internal API properties, currently, we strongly advise against doing so.
+Supporting `~children` might be added in the future ([#57](https://github.com/lowlighter/libs/issues/57)) for mixed content, but its behavior is not yet well defined.
 Setting `~name` manually might lead to unexpected behaviors, especially if it differs from the parent key.
 
+> [!TIP]
+> For more type-safety, write `satisfies Partial<xml_document>` after whatever you pass into `stringify`, like so:
+>
+> <!-- TODO(lishaduck): Add ts highlighting once denoland/deno#24164 is resolved -->
+>
+> ```
+> import { stringify, type xml_document } from "./stringify.ts"
+>
+> const ast = {
+>   "@version": "1.0",
+>   "@encoding": "UTF-8",
+>   "root": {},
+> } satisfies Partial<xml_document>
+> const result = stringify(ast)
+> ```
+>
+> We expose lax typing, but `Partial<xml_document>` uses the stricter typing we use internally.
+
 ## 📜 License and credits
 
-```
-Copyright (c) Lecoq Simon <@lowlighter>. (MIT License)
+```plaintext
+Copyright (c) Simon Lecoq <@lowlighter>. (MIT License)
 https://github.com/lowlighter/libs/blob/main/LICENSE
 ```
-
-This library used to be published at [deno.land/x/xml](https://deno.land/x/xml) and [jsr.io/@lowlighter/xml](https://jsr.io/@lowlighter/xml). It was moved into [jsr.io/@libs/xml](https://jsr.io/@libs/xml) starting version `5.0.0`.
-
-Version prior to `5.0.0` used to be fully written in TypeScript but it was rewritten in Rust to improve performances and support more features.

package/_types.ts

@@ -25,11 +25,11 @@ export type xml_node = {
 /** XML document. */
 export type xml_document = xml_node & {
   /** XML version. */
-  ["@version"]?: string
+  ["@version"]?: `1.${number}`
   /** XML character encoding. */
   ["@encoding"]?: string
   /** XML standalone. */
-  ["@standalone"]?: string
+  ["@standalone"]?: "yes" | "no"
   /** XML doctype. */
   ["#doctype"]?: xml_node
   /** XML instructions. */

package/deno.jsonc

@@ -1,7 +1,7 @@
 {
   "icon": "📃",
   "name": "@libs/xml",
-  "version": "5.4.7",
+  "version": "5.4.9",
   "description": "XML parser/stringifier with no dependencies.",
   "keywords": [
     "xml",
@@ -33,9 +33,9 @@
     "./stringify": "./stringify.ts"
   },
   "imports": {
-    "@std/fs/expand-glob": "jsr:@std/fs@0.229.1/expand-glob",
-    "@std/fs/exists": "jsr:@std/fs@0.229.1/exists",
-    "@std/path/from-file-url": "jsr:@std/path@0.225.1/from-file-url",
+    "@std/fs/expand-glob": "jsr:@std/fs@0.229.3/expand-glob",
+    "@std/fs/exists": "jsr:@std/fs@0.229.3/exists",
+    "@std/path/from-file-url": "jsr:@std/path@0.225.2/from-file-url",
     "@libs/typing": "jsr:@libs/typing@2",
     "@libs/testing": "jsr:@libs/testing@1"
   },
@@ -89,6 +89,7 @@
       "**/package-lock.json",
       "**/wasm_*",
       "**/*.mjs"
-    ]
+    ],
+    "proseWrap": "preserve"
   }
 }

package/deno.lock

@@ -2,54 +2,89 @@
   "version": "3",
   "packages": {
     "specifiers": {
-      "jsr:@libs/testing@1": "jsr:@libs/testing@1.0.7",
-      "jsr:@libs/typing@2": "jsr:@libs/typing@2.1.0",
-      "jsr:@std/assert@^0.224.0": "jsr:@std/assert@0.224.0",
-      "jsr:@std/expect@0.224.0": "jsr:@std/expect@0.224.0",
-      "jsr:@std/fmt@^0.224.0": "jsr:@std/fmt@0.224.0",
-      "jsr:@std/fs@0.229.1": "jsr:@std/fs@0.229.1",
-      "jsr:@std/internal@^0.224.0": "jsr:@std/internal@0.224.0",
+      "jsr:@libs/logger@1": "jsr:@libs/logger@1.1.2",
+      "jsr:@libs/run@1": "jsr:@libs/run@1.0.1",
+      "jsr:@libs/testing@1": "jsr:@libs/testing@1.1.0",
+      "jsr:@libs/typing@2": "jsr:@libs/typing@2.3.0",
+      "jsr:@std/assert@^0.225.3": "jsr:@std/assert@0.225.3",
+      "jsr:@std/async@0.224.1": "jsr:@std/async@0.224.1",
+      "jsr:@std/bytes@^1.0.0-rc.3": "jsr:@std/bytes@1.0.1",
+      "jsr:@std/bytes@^1.0.1-rc.3": "jsr:@std/bytes@1.0.1",
+      "jsr:@std/expect@0.224.3": "jsr:@std/expect@0.224.3",
+      "jsr:@std/fs@0.229.3": "jsr:@std/fs@0.229.3",
+      "jsr:@std/internal@^1.0.0": "jsr:@std/internal@1.0.1",
+      "jsr:@std/io@^0.224.0": "jsr:@std/io@0.224.3",
       "jsr:@std/path@0.225.1": "jsr:@std/path@0.225.1",
-      "npm:@types/node": "npm:@types/node@18.16.19"
+      "jsr:@std/path@0.225.2": "jsr:@std/path@0.225.2",
+      "jsr:@std/streams@0.224.2": "jsr:@std/streams@0.224.2"
     },
     "jsr": {
-      "@libs/testing@1.0.7": {
-        "integrity": "b1a7caa9d2e00569f90b9753eb768ec6b16ff5c859f104b73a6ef4611968892e",
+      "@libs/logger@1.1.2": {
+        "integrity": "7d718f54c9a5d1c00f570051bee0217e3b282e8c2131144ec55c794a8ebd5d4f"
+      },
+      "@libs/run@1.0.1": {
+        "integrity": "b22b34ae7629179568c44efecb60f69310af013f65c96e447a5ee8743ff53f42",
+        "dependencies": [
+          "jsr:@libs/logger@1",
+          "jsr:@std/async@0.224.1",
+          "jsr:@std/streams@0.224.2"
+        ]
+      },
+      "@libs/testing@1.1.0": {
+        "integrity": "961fed690ee11a6f0f2cf8ed759b9b3a5c40ca24d319ba6c18cbbdaf73f1b29b",
+        "dependencies": [
+          "jsr:@libs/run@1",
+          "jsr:@std/expect@0.224.3",
+          "jsr:@std/path@0.225.1"
+        ]
+      },
+      "@libs/typing@2.3.0": {
+        "integrity": "8a03098b2d63763bc3b45b58f6e847d9c085405db83330c588aecb6b670587d0"
+      },
+      "@std/assert@0.225.3": {
+        "integrity": "b3c2847aecf6955b50644cdb9cf072004ea3d1998dd7579fc0acb99dbb23bd4f",
         "dependencies": [
-          "jsr:@std/expect@0.224.0"
+          "jsr:@std/internal@^1.0.0"
         ]
       },
-      "@libs/typing@2.1.0": {
-        "integrity": "3c3b93e1da1e4bb45a22dde168fdfd1cc765edbdb371b46bf4ca7873ee79e15d"
+      "@std/async@0.224.1": {
+        "integrity": "2fda2c8151cc5811a6ca37fe825f1f71c95e02a374abb6ef868e0e19eca814a5"
       },
-      "@std/assert@0.224.0": {
-        "integrity": "8643233ec7aec38a940a8264a6e3eed9bfa44e7a71cc6b3c8874213ff401967f"
+      "@std/bytes@1.0.1": {
+        "integrity": "e57c9b243932b95a4c3672f8a038cdadea7492efeeb6b8a774844fee70426815"
       },
-      "@std/expect@0.224.0": {
-        "integrity": "54bc071f7edcbd7bb4531f913e466e5ec3642f401dc3771fe5975f0693f25969",
+      "@std/expect@0.224.3": {
+        "integrity": "eacd71aaa426472bf04ddde7e0765b0b360d3ffa33ad2ca05a96fd7052caea41",
         "dependencies": [
-          "jsr:@std/assert@^0.224.0",
-          "jsr:@std/fmt@^0.224.0",
-          "jsr:@std/internal@^0.224.0"
+          "jsr:@std/assert@^0.225.3",
+          "jsr:@std/internal@^1.0.0"
         ]
       },
-      "@std/fmt@0.224.0": {
-        "integrity": "e20e9a2312a8b5393272c26191c0a68eda8d2c4b08b046bad1673148f1d69851"
+      "@std/fs@0.229.3": {
+        "integrity": "783bca21f24da92e04c3893c9e79653227ab016c48e96b3078377ebd5222e6eb"
       },
-      "@std/fs@0.229.1": {
-        "integrity": "38d3fb31f0ca0a8c1118e039939188f32e291a3f7f17dc0868fec22024bdfadd"
+      "@std/internal@1.0.1": {
+        "integrity": "6f8c7544d06a11dd256c8d6ba54b11ed870aac6c5aeafff499892662c57673e6"
       },
-      "@std/internal@0.224.0": {
-        "integrity": "afc50644f9cdf4495eeb80523a8f6d27226b4b36c45c7c195dfccad4b8509291"
+      "@std/io@0.224.3": {
+        "integrity": "b402edeb99c6b3778d9ae3e9927bc9085b170b41e5a09bbb7064ab2ee394ae2f",
+        "dependencies": [
+          "jsr:@std/bytes@^1.0.1-rc.3"
+        ]
       },
       "@std/path@0.225.1": {
         "integrity": "8c3220635a73730eb51fe43de9e10b79e2724a5bb8638b9355d35ae012fd9429"
-      }
-    },
-    "npm": {
-      "@types/node@18.16.19": {
-        "integrity": "sha512-IXl7o+R9iti9eBW4Wg2hx1xQDig183jj7YLn8F7udNceyfkbn1ZxmzZXuak20gR40D7pIkIY1kYGx5VIGbaHKA==",
-        "dependencies": {}
+      },
+      "@std/path@0.225.2": {
+        "integrity": "0f2db41d36b50ef048dcb0399aac720a5348638dd3cb5bf80685bf2a745aa506"
+      },
+      "@std/streams@0.224.2": {
+        "integrity": "5d437af1423e4f616111b986ea783c15e0bc998b53e23e93b623de7ef0b14c2b",
+        "dependencies": [
+          "jsr:@std/assert@^0.225.3",
+          "jsr:@std/bytes@^1.0.0-rc.3",
+          "jsr:@std/io@^0.224.0"
+        ]
       }
     }
   },
@@ -58,8 +93,8 @@
     "dependencies": [
       "jsr:@libs/testing@1",
       "jsr:@libs/typing@2",
-      "jsr:@std/fs@0.229.1",
-      "jsr:@std/path@0.225.1"
+      "jsr:@std/fs@0.229.3",
+      "jsr:@std/path@0.225.2"
     ]
   }
 }