fix(xml): narrowed typing for version and standalone (#62)

xml/README.md

@@ -244,6 +244,24 @@ Note that while you can _theoretically_ use internal API properties, 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 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
 
 ```plaintext

xml/_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. */

xml/stringify.ts

@@ -40,6 +40,9 @@ type _options = options & { format: NonNullable<options["format"]> }
 /** Internal symbol to store properties without erasing user-provided ones. */
 const internal = Symbol("internal")
 
+/** 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 }>
+
 /**
  * Stringify an {@link xml_document} object into a XML string.
  *
@@ -50,6 +53,8 @@ const internal = Symbol("internal")
  * import { stringify } from "./stringify.ts"
  *
  * console.log(stringify({
+ *   "@version": "1.0",
+ *   "@standalone": "yes",
  *   root: {
  *     text: "hello",
  *     array: ["world", "monde", "世界", "🌏"],
@@ -63,7 +68,7 @@ const internal = Symbol("internal")
  * }))
  * ```
  */
-export function stringify(document: Partial<xml_document>, options?: options): string {
+export function stringify(document: stringifyable, options?: options): string {
   options ??= {}
   options.format ??= {}
   options.format.indent ??= "  "