Refactor code-style

*   Add support for `null` in API input types
*   Add more docs to JSDoc

Author: wooorm

lib/index.js

@@ -1,96 +1,111 @@
 /**
- * @typedef {import('hast').Parent} HastParent
  * @typedef {import('hast').Root} HastRoot
  * @typedef {import('hast').DocType} HastDoctype
  * @typedef {import('hast').Element} HastElement
  * @typedef {import('hast').Text} HastText
  * @typedef {import('hast').Comment} HastComment
- * @typedef {import('hast').Content} HastChild
- * @typedef {HastChild|HastRoot} HastNode
+ * @typedef {import('hast').Content} HastContent
+ */
+
+/**
+ * @typedef {HastContent | HastRoot} HastNode
  *
  * @callback AfterTransform
- *   Called when a DOM node was transformed into a hast node.
+ *   Callback called when each node is transformed.
  * @param {Node} domNode
- *   DOM node that was transformed.
+ *   DOM node that was handled.
  * @param {HastNode} hastNode
- *   hast node the transform yielded.
+ *   Corresponding hast node.
  * @returns {void}
  *   Nothing.
  *
  * @typedef Options
- * @property {AfterTransform} [afterTransform]
- *   Called when a DOM node was transformed into a hast node.
+ *   Configuration.
+ * @property {AfterTransform | null | undefined} [afterTransform]
+ *   Callback called when each node is transformed.
  */
 
 import {webNamespaces} from 'web-namespaces'
 import {h, s} from 'hastscript'
 
-const ELEMENT_NODE = 1
-const TEXT_NODE = 3
-const COMMENT_NODE = 8
-const DOCUMENT_NODE = 9
-const DOCUMENT_TYPE_NODE = 10
-const DOCUMENT_FRAGMENT_NODE = 11
-
 /**
  * Transform a DOM tree to a hast tree.
  *
- * @param {Node} node
- * @param {Options} [options]
+ * @param {Node} tree
+ *   DOM tree to transform.
+ * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
  * @returns {HastNode}
+ *   Equivalent hast node.
  */
-export function fromDom(node, options = {}) {
-  return (
-    (node ? transform(node, options) : undefined) || {
-      type: 'root',
-      children: []
-    }
-  )
+export function fromDom(tree, options) {
+  const result = tree ? transform(tree, options || {}) : undefined
+  return result || {type: 'root', children: []}
 }
 
 /**
  * @param {Node} node
- * @param {Options} ctx
- * @returns {HastNode|undefined}
+ *   DOM node to transform.
+ * @param {Options} options
+ *   Configuration.
+ * @returns {HastNode | undefined}
+ *   Equivalent hast node.
+ *
+ *   Note that certain legacy DOM nodes (i.e., Attr nodes (2),  CDATA, processing instructions)
  */
-function transform(node, ctx) {
-  const transformed = one(node, ctx)
-  if (ctx.afterTransform && transformed) ctx.afterTransform(node, transformed)
+function transform(node, options) {
+  const transformed = one(node, options)
+  if (transformed && options.afterTransform)
+    options.afterTransform(node, transformed)
   return transformed
 }
 
 /**
  * @param {Node} node
- * @param {Options} ctx
- * @returns {HastNode|undefined}
+ *   DOM node to transform.
+ * @param {Options} options
+ *   Configuration.
+ * @returns {HastNode | undefined}
+ *   Equivalent hast node.
  */
-function one(node, ctx) {
+function one(node, options) {
   switch (node.nodeType) {
-    case ELEMENT_NODE: {
+    case 1 /* Element */: {
       // @ts-expect-error TypeScript is wrong.
-      return element(node, ctx)
+      return element(node, options)
     }
 
-    case DOCUMENT_NODE:
-    case DOCUMENT_FRAGMENT_NODE: {
-      // @ts-expect-error TypeScript is wrong.
-      return root(node, ctx)
-    }
+    // Ignore: Attr (2).
 
-    case TEXT_NODE: {
+    case 3 /* Text */: {
       // @ts-expect-error TypeScript is wrong.
       return text(node)
     }
 
-    case COMMENT_NODE: {
+    // Ignore: CDATA (4).
+    // Removed: Entity reference (5)
+    // Removed: Entity (6)
+    // Ignore: Processing instruction (7).
+
+    case 8 /* Comment */: {
       // @ts-expect-error TypeScript is wrong.
       return comment(node)
     }
 
-    case DOCUMENT_TYPE_NODE: {
+    case 9 /* Document */: {
+      // @ts-expect-error TypeScript is wrong.
+      return root(node, options)
+    }
+
+    case 10 /* Document type */: {
       return doctype()
     }
 
+    case 11 /* Document fragment */: {
+      // @ts-expect-error TypeScript is wrong.
+      return root(node, options)
+    }
+
     default: {
       return undefined
     }
@@ -100,18 +115,22 @@ function one(node, ctx) {
 /**
  * Transform a document.
  *
- * @param {Document|DocumentFragment} node
- * @param {Options} ctx
+ * @param {Document | DocumentFragment} node
+ *   DOM node to transform.
+ * @param {Options} options
+ *   Configuration.
  * @returns {HastRoot}
+ *   Equivalent hast node.
  */
-function root(node, ctx) {
-  return {type: 'root', children: all(node, ctx)}
+function root(node, options) {
+  return {type: 'root', children: all(node, options)}
 }
 
 /**
  * Transform a doctype.
  *
  * @returns {HastDoctype}
+ *   Equivalent hast node.
  */
 function doctype() {
   // @ts-expect-error hast types out of date.
@@ -122,7 +141,9 @@ function doctype() {
  * Transform a text.
  *
  * @param {Text} node
+ *   DOM node to transform.
  * @returns {HastText}
+ *   Equivalent hast node.
  */
 function text(node) {
   return {type: 'text', value: node.nodeValue || ''}
@@ -132,7 +153,9 @@ function text(node) {
  * Transform a comment.
  *
  * @param {Comment} node
+ *   DOM node to transform.
  * @returns {HastComment}
+ *   Equivalent hast node.
  */
 function comment(node) {
   return {type: 'comment', value: node.nodeValue || ''}
@@ -142,15 +165,18 @@ function comment(node) {
  * Transform an element.
  *
  * @param {Element} node
- * @param {Options} ctx
+ *   DOM node to transform.
+ * @param {Options} options
+ *   Configuration.
  * @returns {HastElement}
+ *   Equivalent hast node.
  */
-function element(node, ctx) {
+function element(node, options) {
   const space = node.namespaceURI
   const fn = space === webNamespaces.svg ? s : h
   const tagName =
     space === webNamespaces.html ? node.tagName.toLowerCase() : node.tagName
-  /** @type {DocumentFragment|Element} */
+  /** @type {DocumentFragment | Element} */
   const content =
     // @ts-expect-error Types are wrong.
     space === webNamespaces.html && tagName === 'template' ? node.content : node
@@ -163,24 +189,27 @@ function element(node, ctx) {
     props[attributes[index]] = node.getAttribute(attributes[index]) || ''
   }
 
-  return fn(tagName, props, all(content, ctx))
+  return fn(tagName, props, all(content, options))
 }
 
 /**
- * Transform an element.
+ * Transform child nodes in a parent.
  *
- * @param {Document|DocumentFragment|Element} node
- * @param {Options} ctx
- * @returns {Array<HastChild>}
+ * @param {Document | DocumentFragment | Element} node
+ *   DOM node to transform.
+ * @param {Options} options
+ *   Configuration.
+ * @returns {Array<HastContent>}
+ *   Equivalent hast nodes.
  */
-function all(node, ctx) {
+function all(node, options) {
   const nodes = node.childNodes
-  /** @type {Array<HastChild>} */
+  /** @type {Array<HastContent>} */
   const children = []
   let index = -1
 
   while (++index < nodes.length) {
-    const child = transform(nodes[index], ctx)
+    const child = transform(nodes[index], options)
 
     if (child !== undefined) {
       // @ts-expect-error Assume no document inside document.