fix(xml)!: rename options to parse_options/stringify_options and add additional typings for each sub-options for clarity (#103)

Author: lowlighter

xml/README.md

@@ -64,6 +64,22 @@ console.log(stringify({
   - Support for custom `reviver` and `replacer` functions
 - Support for metadata stored into non-enumerable properties (advanced usage).
 
+## 🕊️ Migrating from `6.x.x` to `7.x.x`
+
+For both `stringify` and `parse`, the type `options` has been renamed and prefixed by their scope for more clarity.
+
+```diff ts
+- import type { options } from "jsr:@libs/xml@6/stringify"
++ import type { stringify_options } from "jsr:@libs/xml@7/stringify"
+```
+
+```diff ts
+- import type { options } from "jsr:@libs/xml@6/parse"
++ import type { parse_options } from "jsr:@libs/xml@7/parse"
+```
+
+If you didn't use these typings, no further changes are required.
+
 ## 🕊️ Migrating from `5.x.x` to `6.x.x`
 
 Version `6.x.x` and onwards require Deno `2.x.x` or later.

xml/_types.ts

@@ -40,7 +40,10 @@ export type xml_document = xml_node & {
 }
 
 /** Synchronous reader. */
-export type ReaderSync = { readSync(buffer: Uint8Array): Nullable<number> }
+export type ReaderSync = {
+  /** Read synchronously some data into a buffer and returns the number of bytes read. */
+  readSync(buffer: Uint8Array): Nullable<number>
+}
 
 /** A laxer type for what can be stringified. We won’t ever create this, but we’ll accept it. */
 export type stringifyable = Partial<Omit<xml_document, "@version" | "@standalone"> & { "@version": string; "@standalone": string }>

xml/mod.ts

@@ -1,3 +1,3 @@
-export { type options as parse_options, parse } from "./parse.ts"
-export { cdata, comment, type options as stringify_options, stringify } from "./stringify.ts"
+export * from "./parse.ts"
+export * from "./stringify.ts"
 export type * from "./_types.ts"

xml/parse.ts

@@ -6,58 +6,17 @@
 // Imports
 import { initSync, JsReader, source, Token, tokenize } from "./wasm_xml_parser/wasm_xml_parser.js"
 import type { Nullable, ReaderSync, xml_document, xml_node, xml_text } from "./_types.ts"
-export type { Nullable, ReaderSync, xml_document, xml_node, xml_text }
+export type * from "./_types.ts"
 initSync(source())
 
 /** XML parser options. */
-export type options = {
+export type parse_options = {
   /** Remove elements from result. */
-  clean?: {
-    /** Remove attributes from result. */
-    attributes?: boolean
-    /** Remove comments from result. */
-    comments?: boolean
-    /** Remove XML doctype from result. */
-    doctype?: boolean
-    /** Remove XML processing instructions from result. */
-    instructions?: boolean
-  }
+  clean?: clean_options
   /** Flatten result depending on node content. */
-  flatten?: {
-    /** If node only contains attributes values (i.e. with key starting with `@`), it'll be flattened as a regular object without `@` prefixes. */
-    attributes?: boolean
-    /** If node only contains a `#text` value, it'll be flattened as a string (defaults to `true`). */
-    text?: boolean
-    /** If node does not contains any attribute or text, it'll be flattened to `null` (defaults to `true`). */
-    empty?: boolean
-  }
+  flatten?: flatten_options
   /** Revive result. */
-  revive?: {
-    /**
-     * Trim texts (this is applied before other revivals, defaults to `true`).
-     * It honors `xml:space="preserve"` attribute.
-     */
-    trim?: boolean
-    /**
-     * Revive XML entities (defaults to `true`).
-     * Automatically unescape XML entities and replace common entities with their respective characters.
-     */
-    entities?: boolean
-    /** Revive booleans (matching `/^(?:[Tt]rue|[Ff]alse)$/`).*/
-    booleans?: boolean
-    /**
-     * Revive finite numbers.
-     * Note that the version of the XML prolog is always treated as a string to avoid breaking documents.
-     */
-    numbers?: boolean
-    /**
-     * Custom reviver (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
-  }
+  revive?: revive_options
   /**
    * Parsing mode.
    * Using `html` is more permissive and will not throw on some invalid XML syntax.
@@ -66,6 +25,62 @@ export type options = {
   mode?: "xml" | "html"
 }
 
+/** XML parser {@linkcode parse_options}`.clean` */
+export type clean_options = {
+  /** Remove attributes from result. */
+  attributes?: boolean
+  /** Remove comments from result. */
+  comments?: boolean
+  /** Remove XML doctype from result. */
+  doctype?: boolean
+  /** Remove XML processing instructions from result. */
+  instructions?: boolean
+}
+
+/** XML parser {@linkcode parse_options}`.flatten` */
+export type flatten_options = {
+  /** If node only contains attributes values (i.e. with key starting with `@`), it'll be flattened as a regular object without `@` prefixes. */
+  attributes?: boolean
+  /** If node only contains a `#text` value, it'll be flattened as a string (defaults to `true`). */
+  text?: boolean
+  /** If node does not contains any attribute or text, it'll be flattened to `null` (defaults to `true`). */
+  empty?: boolean
+}
+
+/** XML parser {@linkcode parse_options}`.revive` */
+export type revive_options = {
+  /**
+   * Trim texts (this is applied before other revivals, defaults to `true`).
+   * It honors `xml:space="preserve"` attribute.
+   */
+  trim?: boolean
+  /**
+   * Revive XML entities (defaults to `true`).
+   * Automatically unescape XML entities and replace common entities with their respective characters.
+   */
+  entities?: boolean
+  /** Revive booleans (matching `/^(?:[Tt]rue|[Ff]alse)$/`).*/
+  booleans?: boolean
+  /**
+   * Revive finite numbers.
+   * Note that the version of the XML prolog is always treated as a string to avoid breaking documents.
+   */
+  numbers?: boolean
+  /**
+   * Custom reviver (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?: reviver
+}
+
+/**
+ * Custom XML parser reviver.
+ * It can be used to change the way some nodes are parsed.
+ */
+export type reviver = (args: { name: string; key: Nullable<string>; value: Nullable<string>; node: Readonly<xml_node> }) => unknown
+
 /**
  * Parse a XML string into an object.
  *
@@ -115,7 +130,7 @@ export type options = {
  * console.log(parse(file))
  * ```
  */
-export function parse(content: string | ReaderSync, options?: options): xml_document {
+export function parse(content: string | ReaderSync, options?: parse_options): xml_document {
   const xml = xml_node("~xml") as xml_document
   const stack = [xml] as Array<xml_node>
   const tokens = [] as Array<[number, string, string?]>
@@ -322,7 +337,7 @@ function xml_node(name: string, { parent = null as Nullable<xml_node> } = {}): x
 }
 
 /** Post-process xml node. */
-function postprocess(node: xml_node, options: options) {
+function postprocess(node: xml_node, options: parse_options) {
   // Clean XML document if required
   if (node["~name"] === "~xml") {
     if (options?.clean?.doctype) {
@@ -419,7 +434,7 @@ const entities = {
 } as const
 
 /** Revive value. */
-function revive(node: xml_node | xml_text, key: string, options: options) {
+function revive(node: xml_node | xml_text, key: string, options: parse_options) {
   let value = (node as xml_node)[key] as string
   if (options?.revive?.trim) {
     value = value.trim()

xml/stringify.ts

@@ -5,39 +5,45 @@
 
 // Imports
 import type { Nullable, stringifyable, xml_document, xml_node, xml_text } from "./_types.ts"
-export type { Nullable, stringifyable, xml_document, xml_node, xml_text }
+export type * from "./_types.ts"
 
 /** XML stringifier options. */
-export type options = {
+export type stringify_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
-  }
+  format?: format_options
   /** 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
-  }
+  replace?: replace_options
+}
+
+/** XML stringifier {@linkcode stringify_options}`.format` */
+export type format_options = {
+  /**
+   * 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
+}
+
+/** XML stringifier {@linkcode stringify_options}`.replace` */
+export type replace_options = {
+  /**
+   * 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"]> }
+type _options = stringify_options & { format: NonNullable<stringify_options["format"]> }
 
 /** Internal symbol to store properties without erasing user-provided ones. */
 const internal = Symbol("internal")
@@ -66,7 +72,7 @@ const internal = Symbol("internal")
  * }))
  * ```
  */
-export function stringify(document: stringifyable, options?: options): string {
+export function stringify(document: stringifyable, options?: stringify_options): string {
   options ??= {}
   options.format ??= {}
   options.format.indent ??= "  "
@@ -237,7 +243,7 @@ function xml_node(node: xml_node, { format: { breakline = 0, indent = "" }, repl
 }
 
 /** Extract children from node. */
-function xml_children(node: xml_node, options: options): Array<xml_node> {
+function xml_children(node: xml_node, options: stringify_options): Array<xml_node> {
   const children = Object.keys(node)
     .filter((key) => /^[A-Za-z_]/.test(key))
     .flatMap((key) =>
@@ -274,7 +280,7 @@ function xml_children(node: xml_node, options: options): Array<xml_node> {
 }
 
 /** Extract attributes from node. */
-function xml_attributes(node: xml_node, options: options): Array<[string, string]> {
+function xml_attributes(node: xml_node, options: stringify_options): Array<[string, string]> {
   return Object.entries(node!)
     .filter(([key]) => key.startsWith("@"))
     .map(([key]) => [key.slice(1), replace(node!, key, { ...options, escape: ["&", '"', "'"] })])
@@ -291,7 +297,7 @@ const entities = {
 } as const
 
 /** Replace value. */
-function replace(node: xml_node | xml_text, key: string, options: options & { escape?: Array<keyof typeof entities> }) {
+function replace(node: xml_node | xml_text, key: string, options: stringify_options & { escape?: Array<keyof typeof entities> }) {
   let value = `${(node as xml_node)[key]}` as string
   if (options?.escape) {
     if (options?.replace?.entities) {

xml/stringify_test.ts

@@ -1,5 +1,5 @@
-import { type options as parse_options, parse } from "./parse.ts"
-import { cdata, comment, type options as stringify_options, stringify } from "./stringify.ts"
+import { parse, type parse_options } from "./parse.ts"
+import { cdata, comment, stringify, type stringify_options } from "./stringify.ts"
 import { expect, test } from "@libs/testing"
 
 // This operation ensure that reforming a parsed XML will still yield same data