Refactor code-style

*   Add support for `null` as input of API types
*   Add more docs to JSDoc
*   Refactor tons of code

Author: wooorm

lib/all.js

@@ -1,47 +1,56 @@
 /**
+ * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').Content} Content
+ * @typedef {import('mdast').Content} MdastContent
  * @typedef {import('./types.js').H} H
- * @typedef {import('./types.js').Node} Node
- * @typedef {import('./types.js').MdastNode} MdastNode
+ */
+
+/**
+ * @typedef {Root | Content} Node
+ * @typedef {Extract<Node, import('unist').Parent>} Parent
  */
 
 import {one} from './one.js'
 
 /**
  * @param {H} h
- * @param {Node} parent
- * @returns {Array<MdastNode>}
+ *   Context.
+ * @param {Parent} parent
+ *   Parent to transform.
+ * @returns {Array<MdastContent>}
+ *   mdast nodes.
  */
 export function all(h, parent) {
-  /** @type {Array<Node>} */
-  // @ts-expect-error Assume `parent` is a parent.
-  const nodes = parent.children || []
-  /** @type {Array<MdastNode>} */
-  const values = []
+  const children = parent.children || []
+  /** @type {Array<MdastContent>} */
+  const results = []
   let index = -1
 
-  while (++index < nodes.length) {
-    // @ts-expect-error assume `parent` is a parent.
-    const result = one(h, nodes[index], parent)
+  while (++index < children.length) {
+    const child = children[index]
+    const result = one(h, child, parent)
 
     if (Array.isArray(result)) {
-      values.push(...result)
+      // @ts-expect-error: assume no `root`.
+      results.push(...result)
     } else if (result) {
-      values.push(result)
+      // @ts-expect-error: assume no `root`.
+      results.push(result)
     }
   }
 
   let start = 0
-  let end = values.length
+  let end = results.length
 
-  while (start < end && values[start].type === 'break') {
+  while (start < end && results[start].type === 'break') {
     start++
   }
 
-  while (end > start && values[end - 1].type === 'break') {
+  while (end > start && results[end - 1].type === 'break') {
     end--
   }
 
-  return start === 0 && end === values.length
-    ? values
-    : values.slice(start, end)
+  return start === 0 && end === results.length
+    ? results
+    : results.slice(start, end)
 }

lib/handlers/a.js

@@ -1,8 +1,7 @@
 /**
+ * @typedef {import('mdast').Link} Link
+ * @typedef {import('hast').Element} Element
  * @typedef {import('../types.js').H} H
- * @typedef {import('../types.js').Element} Element
- * @typedef {import('../types.js').Properties} Properties
- * @typedef {import('../types.js').MdastNode} Content
  */
 
 import {all} from '../all.js'
@@ -13,20 +12,25 @@ import {resolve} from '../util/resolve.js'
  *   Context.
  * @param {Element} node
  *   hast element to transform.
- * @returns {Content}
+ * @returns {Link}
  *   mdast node.
  */
 export function a(h, node) {
-  /** @type {Properties} */
-  // @ts-expect-error: `props` are defined.
-  const props = node.properties
-  return h(
-    node,
-    'link',
-    {
-      title: props.title || null,
-      url: resolve(h, String(props.href || '') || null)
-    },
-    all(h, node)
-  )
+  const properties = node.properties || {}
+
+  /** @type {Link} */
+  const result = {
+    type: 'link',
+    url: resolve(h, String(properties.href || '') || null),
+    title: properties.title ? String(properties.title) : null,
+    // @ts-expect-error: assume valid children.
+    children: all(h, node)
+  }
+
+  // To do: clean.
+  if (node.position) {
+    result.position = node.position
+  }
+
+  return result
 }

lib/handlers/base.js

@@ -1,6 +1,6 @@
 /**
+ * @typedef {import('hast').Element} Element
  * @typedef {import('../types.js').H} H
- * @typedef {import('../types.js').Element} Element
  */
 
 /**
@@ -9,12 +9,12 @@
  * @param {Element} node
  *   hast element to transform.
  * @returns {void}
- *   Nothing
+ *   Nothing.
  */
 export function base(h, node) {
   if (!h.baseFound) {
     h.frozenBaseUrl =
-      String((node.properties && node.properties.href) || '') || null
+      String((node.properties && node.properties.href) || '') || undefined
     h.baseFound = true
   }
 }

lib/handlers/blockquote.js

@@ -1,7 +1,7 @@
 /**
+ * @typedef {import('hast').Element} Element
+ * @typedef {import('mdast').Blockquote} Blockquote
  * @typedef {import('../types.js').H} H
- * @typedef {import('../types.js').Element} Element
- * @typedef {import('../types.js').MdastNode} Content
  */
 
 import {wrapChildren} from '../util/wrap-children.js'
@@ -11,9 +11,20 @@ import {wrapChildren} from '../util/wrap-children.js'
  *   Context.
  * @param {Element} node
  *   hast element to transform.
- * @returns {Content}
+ * @returns {Blockquote}
  *   mdast node.
  */
 export function blockquote(h, node) {
-  return h(node, 'blockquote', wrapChildren(h, node))
+  /** @type {Blockquote} */
+  const result = {
+    type: 'blockquote',
+    children: wrapChildren(h, node)
+  }
+
+  // To do: clean.
+  if (node.position) {
+    result.position = node.position
+  }
+
+  return result
 }

lib/handlers/br.js

@@ -1,17 +1,26 @@
 /**
+ * @typedef {import('hast').Element} Element
+ * @typedef {import('mdast').Break} Break
+ * @typedef {import('mdast').Text} Text
  * @typedef {import('../types.js').H} H
- * @typedef {import('../types.js').Element} Element
- * @typedef {import('../types.js').MdastNode} Content
  */
 
 /**
  * @param {H} h
  *   Context.
  * @param {Element} node
  *   hast element to transform.
- * @returns {Content}
+ * @returns {Break | Text}
  *   mdast node.
  */
 export function br(h, node) {
-  return h.wrapText ? h(node, 'break') : h(node, 'text', ' ')
+  /** @type {Break | Text} */
+  const result = h.wrapText ? {type: 'break'} : {type: 'text', value: ' '}
+
+  // To do: clean.
+  if (node.position) {
+    result.position = node.position
+  }
+
+  return result
 }

lib/handlers/code.js

@@ -1,41 +1,38 @@
 /**
+ * @typedef {import('hast').Element} Element
+ * @typedef {import('mdast').Code} Code
  * @typedef {import('../types.js').H} H
- * @typedef {import('../types.js').Element} Element
- * @typedef {import('../types.js').MdastNode} Content
  */
 
-import {convertElement} from 'hast-util-is-element'
 import {toText} from 'hast-util-to-text'
 import {trimTrailingLines} from 'trim-trailing-lines'
 import {wrapText} from '../util/wrap-text.js'
 
 const prefix = 'language-'
 
-const pre = convertElement('pre')
-const isCode = convertElement('code')
-
 /**
  * @param {H} h
  *   Context.
  * @param {Element} node
  *   hast element to transform.
- * @returns {Content}
+ * @returns {Code}
  *   mdast node.
  */
 export function code(h, node) {
   const children = node.children
   let index = -1
-  /** @type {Array<string|number>|undefined} */
+  /** @type {Array<string | number> | undefined} */
   let classList
-  /** @type {string|undefined} */
+  /** @type {string | undefined} */
   let lang
 
-  if (pre(node)) {
+  if (node.tagName === 'pre') {
     while (++index < children.length) {
       const child = children[index]
 
       if (
-        isCode(child) &&
+        child.type === 'element' &&
+        child.tagName === 'code' &&
         child.properties &&
         child.properties.className &&
         Array.isArray(child.properties.className)
@@ -57,10 +54,18 @@ export function code(h, node) {
     }
   }
 
-  return h(
-    node,
-    'code',
-    {lang: lang || null, meta: null},
-    trimTrailingLines(wrapText(h, toText(node)))
-  )
+  /** @type {Code} */
+  const result = {
+    type: 'code',
+    lang: lang || null,
+    meta: null,
+    value: trimTrailingLines(wrapText(h, toText(node)))
+  }
+
+  // To do: clean.
+  if (node.position) {
+    result.position = node.position
+  }
+
+  return result
 }

lib/handlers/comment.js

@@ -1,7 +1,7 @@
 /**
+ * @typedef {import('hast').Comment} Comment
+ * @typedef {import('mdast').HTML} HTML
  * @typedef {import('../types.js').H} H
- * @typedef {import('../types.js').Comment} Comment
- * @typedef {import('../types.js').MdastNode} Content
  */
 
 import {wrapText} from '../util/wrap-text.js'
@@ -11,9 +11,17 @@ import {wrapText} from '../util/wrap-text.js'
  *   Context.
  * @param {Comment} node
  *   hast element to transform.
- * @returns {Content}
+ * @returns {HTML}
  *   mdast node.
  */
 export function comment(h, node) {
-  return h(node, 'html', '<!--' + wrapText(h, node.value) + '-->')
+  /** @type {HTML} */
+  const result = {type: 'html', value: '<!--' + wrapText(h, node.value) + '-->'}
+
+  // To do: clean.
+  if (node.position) {
+    result.position = node.position
+  }
+
+  return result
 }

lib/handlers/del.js

@@ -1,7 +1,7 @@
 /**
+ * @typedef {import('hast').Element} Element
+ * @typedef {import('mdast').Delete} Delete
  * @typedef {import('../types.js').H} H
- * @typedef {import('../types.js').Element} Element
- * @typedef {import('../types.js').MdastNode} Content
  */
 
 import {all} from '../all.js'
@@ -11,9 +11,21 @@ import {all} from '../all.js'
  *   Context.
  * @param {Element} node
  *   hast element to transform.
- * @returns {Content}
+ * @returns {Delete}
  *   mdast node.
  */
 export function del(h, node) {
-  return h(node, 'delete', all(h, node))
+  /** @type {Delete} */
+  const result = {
+    type: 'delete',
+    // @ts-expect-error: assume valid children.
+    children: all(h, node)
+  }
+
+  // To do: clean.
+  if (node.position) {
+    result.position = node.position
+  }
+
+  return result
 }