Refactor code-style

*   Refactor to allow `null` in API input types
*   Add more docs to JSDoc
*   Refactor a bunch of code

Author: wooorm

lib/all.js

@@ -1,7 +1,14 @@
 /**
- * @typedef {import('./index.js').Parent} Parent
- * @typedef {import('./index.js').Context} Context
- * @typedef {import('./index.js').Child} Child
+ * @typedef {import('unist').Parent} UnistParent
+ * @typedef {import('xast').Root} Root
+ * @typedef {import('xast').RootChildMap} RootChildMap
+ * @typedef {import('./index.js').State} State
+ */
+
+/**
+ * @typedef {Root | RootChildMap[keyof RootChildMap]} Node
+ * @typedef {Extract<Node, UnistParent>} Parent
+ * @typedef {Parent['children'][number]} Child
  */
 
 import {one} from './one.js'
@@ -10,19 +17,21 @@ import {one} from './one.js'
  * Serialize all children of `parent`.
  *
  * @param {Parent} parent
- * @param {Context} ctx
+ *   xast parent node.
+ * @param {State} state
+ *   Info passed around about the current state.
  * @returns {string}
- *
+ *   Serialized XML.
  */
-export function all(parent, ctx) {
+export function all(parent, state) {
   /** @type {Array<Child>} */
   const children = (parent && parent.children) || []
   let index = -1
   /** @type {Array<string>} */
   const results = []
 
   while (++index < children.length) {
-    results[index] = one(children[index], ctx)
+    results[index] = one(children[index], state)
   }
 
   return results.join('')

lib/cdata.js

@@ -1,6 +1,5 @@
 /**
- * @typedef {import('./index.js').Handle} Handle
- * @typedef {import('./index.js').Cdata} Cdata
+ * @typedef {import('xast').Cdata} Cdata
  */
 
 import {escape} from './util-escape.js'
@@ -11,8 +10,10 @@ const subset = ['>']
 /**
  * Serialize a CDATA section.
  *
- * @type {Handle}
  * @param {Cdata} node
+ *   xast cdata node.
+ * @returns {string}
+ *   Serialized XML.
  */
 export function cdata(node) {
   return '<![CDATA[' + escape(node.value, subset, unsafe) + ']]>'

lib/comment.js

@@ -1,15 +1,16 @@
 /**
- * @typedef {import('./index.js').Handle} Handle
- * @typedef {import('./index.js').Comment} Comment
+ * @typedef {import('xast').Comment} Comment
  */
 
 import {escape} from './util-escape.js'
 
 /**
  * Serialize a comment.
  *
- * @type {Handle}
  * @param {Comment} node
+ *   xast comment node.
+ * @returns {string}
+ *   Serialized XML.
  */
 export function comment(node) {
   return '<!--' + escape(node.value, ['-']) + '-->'

lib/doctype.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import('./index.js').Handle} Handle
- * @typedef {import('./index.js').Doctype} Doctype
+ * @typedef {import('xast').Doctype} Doctype
+ * @typedef {import('./index.js').State} State
  */
 
 import {name} from './name.js'
@@ -9,10 +9,14 @@ import {value} from './value.js'
 /**
  * Serialize a doctype.
  *
- * @type {Handle}
  * @param {Doctype} node
+ *   xast doctype node.
+ * @param {State} state
+ *   Info passed around about the current state.
+ * @returns {string}
+ *   Serialized XML.
  */
-export function doctype(node, ctx) {
+export function doctype(node, state) {
   const nodeName = name(node.name)
   const pub = node.public
   const sys = node.system
@@ -22,14 +26,14 @@ export function doctype(node, ctx) {
     result += ' ' + nodeName
   }
 
-  if (pub !== null && pub !== undefined && pub !== '') {
-    result += ' PUBLIC ' + value(pub, ctx)
-  } else if (sys !== null && sys !== undefined && sys !== '') {
+  if (pub) {
+    result += ' PUBLIC ' + value(pub, state)
+  } else if (sys) {
     result += ' SYSTEM'
   }
 
-  if (sys !== null && sys !== undefined && sys !== '') {
-    result += ' ' + value(sys, ctx)
+  if (sys) {
+    result += ' ' + value(sys, state)
   }
 
   return result + '>'

lib/element.js

@@ -1,7 +1,6 @@
 /**
- * @typedef {import('./index.js').Handle} Handle
- * @typedef {import('./index.js').Element} Element
- * @typedef {import('./index.js').Attributes} Attributes
+ * @typedef {import('xast').Element} Element
+ * @typedef {import('./index.js').State} State
  */
 
 import {all} from './all.js'
@@ -13,28 +12,29 @@ const own = {}.hasOwnProperty
 /**
  * Serialize an element.
  *
- * @type {Handle}
  * @param {Element} node
+ *   xast element node.
+ * @param {State} state
+ *   Info passed around about the current state.
+ * @returns {string}
+ *   Serialized XML.
  */
-export function element(node, ctx) {
+export function element(node, state) {
   const nodeName = name(node.name)
-  const content = all(node, ctx)
-  /** @type {Attributes} */
+  const content = all(node, state)
   const attributes = node.attributes || {}
-  const close = content ? false : ctx.close
+  const close = content ? false : state.options.closeEmptyElements
   /** @type {Array<string>} */
   const attrs = []
   /** @type {string} */
   let key
-  /** @type {Attributes[keyof Attributes]} */
-  let result
 
   for (key in attributes) {
     if (own.call(attributes, key)) {
-      result = attributes[key]
+      const result = attributes[key]
 
       if (result !== null && result !== undefined) {
-        attrs.push(name(key) + '=' + value(result, ctx))
+        attrs.push(name(key) + '=' + value(result, state))
       }
     }
   }
@@ -43,7 +43,7 @@ export function element(node, ctx) {
     '<' +
     nodeName +
     (attrs.length === 0 ? '' : ' ' + attrs.join(' ')) +
-    (close ? (ctx.tight ? '' : ' ') + '/' : '') +
+    (close ? (state.options.tightClose ? '' : ' ') + '/' : '') +
     '>' +
     content +
     (close ? '' : '</' + nodeName + '>')

lib/index.js

@@ -1,73 +1,75 @@
 /**
+ * @typedef {import('xast').Literal} Literal
  * @typedef {import('xast').Root} Root
- * @typedef {import('xast').Element} Element
- * @typedef {import('xast').Cdata} Cdata
- * @typedef {import('xast').Comment} Comment
- * @typedef {import('xast').Doctype} Doctype
- * @typedef {import('xast').Instruction} Instruction
- * @typedef {import('xast').Text} Text
- * @typedef {import('xast').Literal & {type: 'raw'}} Raw
- * @typedef {Root|Element} Parent
- * @typedef {import('xast').Attributes} Attributes
- * @typedef {Root['children'][number]} Child
- * @typedef {Child|Root} Node
+ * @typedef {import('xast').RootChildMap} RootChildMap
+ */
+
+/**
+ * @typedef {Literal & {type: 'raw'}} Raw
+ * @typedef {Root | RootChildMap[keyof RootChildMap]} Node
  *
- * @typedef {'"'|"'"} Quote
+ * @typedef {'"' | "'"} Quote
+ *   XML quotes for attribute values.
  *
  * @typedef Options
- * @property {Quote} [quote='"'] Preferred quote to use
- * @property {boolean} [quoteSmart=false] Use the other quote if that results in
- *   less bytes
- * @property {boolean} [closeEmptyElements=false] Close elements without any
- *   content with slash (/) on the opening tag instead of an end tag:
- *   `<circle />` instead of `<circle></circle>`.
+ *   Configuration.
+ * @property {boolean | null | undefined} [allowDangerousXml=false]
+ *   Allow `raw` nodes and insert them as raw XML.
+ *
+ *   When `false`, `Raw` nodes are encoded.
+ *
+ *   > ⚠️ **Danger**: only set this if you completely trust the content.
+ * @property {boolean | null | undefined} [closeEmptyElements=false]
+ *   Close elements without any content with slash (`/`) on the opening tag
+ *   instead of an end tag: `<circle />` instead of `<circle></circle>`.
+ *
  *   See `tightClose` to control whether a space is used before the slash.
- * @property {boolean} [tightClose=false] Do not use an extra space when closing
- *    self-closing elements: `<circle/>` instead of `<circle />`.
- * @property {boolean} [allowDangerousXml=false] Allow `raw` nodes and insert
- *   them as raw XML. When falsey, encodes `raw` nodes.
- *   Only set this if you completely trust the content!
+ * @property {Quote | null | undefined} [quote='"']
+ *   Preferred quote to use.
+ * @property {boolean | null | undefined} [quoteSmart=false]
+ *   Use the other quote if that results in less bytes.
+ * @property {boolean | null | undefined} [tightClose=false]
+ *   Do not use an extra space when closing self-closing elements: `<circle/>`
+ *   instead of `<circle />`.
  *
- * @typedef Context
- * @property {Quote} quote
- * @property {Quote|undefined} alternative
- * @property {boolean} close
- * @property {boolean} tight
- * @property {boolean} dangerous
+ *   > 👉 **Note**: only used if `closeEmptyElements: true`.
  *
- * @callback Handle
- * @param {Node} node
- * @param {Context} context
- * @returns {string}
+ * @typedef State
+ *   Info passed around about the current state.
+ * @property {Options} options
+ *   Configuration.
  */
 
 import {one} from './one.js'
 
 /**
- * Serialize the given xast tree (or list of nodes).
+ * Serialize a xast tree to XML.
  *
- * @param {Node|Array<Node>} node
- * @param {Options} [options]
+ * @param {Node | Array<Node>} node
+ *   xast node(s) to serialize.
+ * @param {Options | null | undefined} [options]
+ *   Configuration.
  * @returns {string}
+ *   Serialized XML.
  */
-export function toXml(node, options = {}) {
-  const quote = options.quote || '"'
-  /** @type {Quote} */
-  const alternative = quote === '"' ? "'" : '"'
-  const smart = options.quoteSmart
+export function toXml(node, options) {
   /** @type {Node} */
   // @ts-expect-error Assume no `root` in `node`.
   const value = Array.isArray(node) ? {type: 'root', children: node} : node
 
-  if (quote !== '"' && quote !== "'") {
-    throw new Error('Invalid quote `' + quote + '`, expected `\'` or `"`')
+  /** @type {State} */
+  const state = {options: options || {}}
+
+  // Make sure the quote is valid.
+  if (
+    typeof state.options.quote === 'string' &&
+    state.options.quote !== '"' &&
+    state.options.quote !== "'"
+  ) {
+    throw new Error(
+      'Invalid quote `' + state.options.quote + '`, expected `\'` or `"`'
+    )
   }
 
-  return one(value, {
-    dangerous: options.allowDangerousXml || false,
-    close: options.closeEmptyElements || false,
-    tight: options.tightClose || false,
-    quote,
-    alternative: smart ? alternative : undefined
-  })
+  return one(value, state)
 }

lib/instruction.js

@@ -1,6 +1,5 @@
 /**
- * @typedef {import('./index.js').Handle} Handle
- * @typedef {import('./index.js').Instruction} Instruction
+ * @typedef {import('xast').Instruction} Instruction
  */
 
 import {escape} from './util-escape.js'
@@ -12,8 +11,10 @@ const subset = ['>']
 /**
  * Serialize an instruction.
  *
- * @type {Handle}
  * @param {Instruction} node
+ *   xast instruction node.
+ * @returns {string}
+ *   Serialized XML.
  */
 export function instruction(node) {
   const nodeName = name(node.name) || 'x'

lib/name.js

@@ -3,10 +3,12 @@ import {escape} from './util-escape.js'
 const subset = ['\t', '\n', ' ', '"', '&', "'", '/', '<', '=', '>']
 
 /**
- * Serialize a node name.
+ * Encode a node name.
  *
  * @param {string} value
+ *   Raw name.
  * @returns {string}
+ *   Escaped name.
  */
 export function name(value) {
   return escape(value, subset)

lib/one.js

@@ -1,5 +1,11 @@
 /**
- * @typedef {import('./index.js').Handle} Handle
+ * @typedef {import('xast').Root} Root
+ * @typedef {import('xast').RootChildMap} RootChildMap
+ * @typedef {import('./index.js').State} State
+ */
+
+/**
+ * @typedef {Root | RootChildMap[keyof RootChildMap]} Node
  */
 
 import {all} from './all.js'
@@ -27,9 +33,14 @@ const handlers = {
 /**
  * Serialize a node.
  *
- * @type {Handle}
+ * @param {Node} node
+ *   xast node.
+ * @param {State} state
+ *   Info passed around about the current state.
+ * @returns {string}
+ *   Serialized XML.
  */
-export function one(node, ctx) {
+export function one(node, state) {
   const type = node && node.type
 
   if (!type) {
@@ -40,6 +51,9 @@ export function one(node, ctx) {
     throw new Error('Cannot compile unknown node `' + type + '`')
   }
 
-  // @ts-expect-error Hush, it works.
-  return handlers[type](node, ctx)
+  const handle = handlers[type]
+  // @ts-expect-error hush, node matches `type`.
+  const result = handle(node, state)
+
+  return result
 }