Change types to use mdast types

Author: wooorm

lib/footer.js

@@ -43,6 +43,8 @@ export function footer(h) {
       tail.children.push(backReference)
     } else {
       // @ts-expect-error Indeed, link directly added in block content.
+      // Which we do because that way at least the handlers will be called
+      // for the other HTML we’re generating (as markdown).
       content.push(backReference)
     }
 

lib/handlers/break.js

@@ -1,5 +1,6 @@
 /**
- * @typedef {import('unist').Node} Node
+ * @typedef {import('hast').Element} Element
+ * @typedef {import('hast').Text} Text
  * @typedef {import('mdast').Break} Break
  * @typedef {import('../index.js').Handler} Handler
  */
@@ -9,7 +10,7 @@ import {u} from 'unist-builder'
 /**
  * @type {Handler}
  * @param {Break} node
- * @returns {Array.<Node>}
+ * @returns {Array<Element|Text>}
  */
 export function hardBreak(h, node) {
   return [h(node, 'br'), u('text', '\n')]

lib/handlers/list.js

@@ -31,9 +31,8 @@ export function list(h, node) {
     if (
       item.type === 'element' &&
       item.tagName === 'li' &&
-      // @ts-expect-error looks like properties.
-      item.properties.className &&
-      // @ts-expect-error looks like properties.
+      item.properties &&
+      Array.isArray(item.properties.className) &&
       item.properties.className.includes('task-list-item')
     ) {
       props.className = ['contains-task-list']

lib/handlers/root.js

@@ -12,6 +12,6 @@ import {wrap} from '../wrap.js'
  * @param {Root} node
  */
 export function root(h, node) {
-  // @ts-expect-error top-level is a root.
+  // @ts-expect-error `root`s are also fine.
   return h.augment(node, u('root', wrap(all(h, node))))
 }

lib/index.js

@@ -1,6 +1,7 @@
 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('unist').Parent} Parent
+ * @typedef {import('mdast').Root|import('mdast').Parent['children'][number]} MdastNode
+ * @typedef {import('hast').Root|import('hast').Parent['children'][number]} HastNode
+ * @typedef {import('mdast').Parent} Parent
  * @typedef {import('mdast').Definition} Definition
  * @typedef {import('mdast').FootnoteDefinition} FootnoteDefinition
  * @typedef {import('hast').Properties} Properties
@@ -20,7 +21,7 @@
  *
  * @typedef {Object.<string, unknown> & EmbeddedHastFields} Data unist data with embedded hast fields
  *
- * @typedef {Node & {data?: Data}} NodeWithData unist node with embedded hast data
+ * @typedef {MdastNode & {data?: Data}} NodeWithData unist node with embedded hast data
  *
  * @callback Handler
  * @param {H} h Handle context
@@ -29,14 +30,14 @@
  * @returns {Content|Array.<Content>|null|undefined} hast node
  *
  * @callback HFunctionProps
- * @param {Node|PositionLike|null|undefined} node mdast node or unist position
+ * @param {MdastNode|PositionLike|null|undefined} node mdast node or unist position
  * @param {string} tagName HTML tag name
  * @param {Properties} props Properties
  * @param {Array.<Content>?} [children] hast content
  * @returns {Element}
  *
  * @callback HFunctionNoProps
- * @param {Node|PositionLike|null|undefined} node mdast node or unist position
+ * @param {MdastNode|PositionLike|null|undefined} node mdast node or unist position
  * @param {string} tagName HTML tag name
  * @param {Array.<Content>?} [children] hast content
  * @returns {Element}
@@ -74,7 +75,7 @@ const own = {}.hasOwnProperty
 
 /**
  * Factory to transform.
- * @param {Node} tree mdast node
+ * @param {MdastNode} tree mdast node
  * @param {Options} [options] Configuration
  * @returns {H} `h` function
  */
@@ -85,7 +86,6 @@ function factory(tree, options) {
   const footnoteById = {}
 
   h.dangerous = dangerous
-  // @ts-expect-error: too loose.
   h.definition = definitions(tree)
   h.footnoteById = footnoteById
   /** @type {Array.<string>} */
@@ -182,9 +182,9 @@ function factory(tree, options) {
 /**
  * Transform `tree` (an mdast node) to a hast node.
  *
- * @param {Node} tree mdast node
+ * @param {MdastNode} tree mdast node
  * @param {Options} [options] Configuration
- * @returns {Node} hast node
+ * @returns {HastNode|null|undefined} hast node
  */
 export function toHast(tree, options) {
   const h = factory(tree, options)
@@ -198,6 +198,5 @@ export function toHast(tree, options) {
     node.children.push(u('text', '\n'), foot)
   }
 
-  // @ts-expect-error: too loose.
   return Array.isArray(node) ? {type: 'root', children: node} : node
 }

lib/traverse.js

@@ -1,8 +1,5 @@
 /**
- * @typedef {import('unist').Node} Node
- * @typedef {import('unist').Parent} Parent
- * @typedef {import('mdast').Literal} Literal
- * @typedef {import('mdast').Text} Text
+ * @typedef {import('mdast').Root|import('mdast').Parent['children'][number]} MdastNode
  * @typedef {import('./index.js').H} H
  * @typedef {import('./index.js').Handler} Handler
  * @typedef {import('./index.js').Content} Content
@@ -15,10 +12,19 @@ const own = {}.hasOwnProperty
 /**
  * Transform an unknown node.
  * @type {Handler}
- * @param {Node} node
+ * @param {MdastNode} node
  */
 function unknown(h, node) {
-  if (text(node)) {
+  const data = node.data || {}
+
+  if (
+    'value' in node &&
+    !(
+      own.call(data, 'hName') ||
+      own.call(data, 'hProperties') ||
+      own.call(data, 'hChildren')
+    )
+  ) {
     return h.augment(node, u('text', node.value))
   }
 
@@ -27,7 +33,7 @@ function unknown(h, node) {
 
 /**
  * @type {Handler}
- * @param {Node} node
+ * @param {MdastNode} node
  */
 export function one(h, node, parent) {
   const type = node && node.type
@@ -50,69 +56,50 @@ export function one(h, node, parent) {
   return (typeof fn === 'function' ? fn : unknown)(h, node, parent)
 }
 
-/**
- * Check if the node should be renderered as a text node.
- * @param {Node} node
- * @returns {node is Literal}
- */
-function text(node) {
-  const data = node.data || {}
-
-  if (
-    own.call(data, 'hName') ||
-    own.call(data, 'hProperties') ||
-    own.call(data, 'hChildren')
-  ) {
-    return false
-  }
-
-  return 'value' in node
-}
-
 /**
  * @type {Handler}
- * @param {unknown} node
+ * @param {MdastNode} node
  */
 function returnNode(h, node) {
-  // @ts-expect-error pass through any unknown node.
-  return node.children ? {...node, children: all(h, node)} : node
+  // @ts-expect-error: Pass through custom node.
+  return 'children' in node ? {...node, children: all(h, node)} : node
 }
 
 /**
  * @param {H} h
- * @param {Node} parent
+ * @param {MdastNode} parent
  */
 export function all(h, parent) {
-  /** @type {Array.<Node>} */
-  // @ts-expect-error looks like a parent.
-  const nodes = parent.children || []
   /** @type {Array.<Content>} */
   const values = []
-  let index = -1
 
-  while (++index < nodes.length) {
-    // @ts-expect-error looks like a parent.
-    const result = one(h, nodes[index], parent)
+  if ('children' in parent) {
+    const nodes = parent.children
+    let index = -1
 
-    if (result) {
-      if (index && nodes[index - 1].type === 'break') {
-        if (!Array.isArray(result) && result.type === 'text') {
-          result.value = result.value.replace(/^\s+/, '')
-        }
+    while (++index < nodes.length) {
+      const result = one(h, nodes[index], parent)
 
-        if (!Array.isArray(result) && result.type === 'element') {
-          const head = result.children[0]
+      if (result) {
+        if (index && nodes[index - 1].type === 'break') {
+          if (!Array.isArray(result) && result.type === 'text') {
+            result.value = result.value.replace(/^\s+/, '')
+          }
+
+          if (!Array.isArray(result) && result.type === 'element') {
+            const head = result.children[0]
 
-          if (head && head.type === 'text') {
-            head.value = head.value.replace(/^\s+/, '')
+            if (head && head.type === 'text') {
+              head.value = head.value.replace(/^\s+/, '')
+            }
           }
         }
-      }
 
-      if (Array.isArray(result)) {
-        values.push(...result)
-      } else {
-        values.push(result)
+        if (Array.isArray(result)) {
+          values.push(...result)
+        } else {
+          values.push(result)
+        }
       }
     }
   }

package.json

@@ -37,7 +37,6 @@
     "@types/hast": "^2.0.0",
     "@types/mdast": "^3.0.0",
     "@types/mdurl": "^1.0.0",
-    "@types/unist": "^2.0.0",
     "mdast-util-definitions": "^5.0.0",
     "mdurl": "^1.0.0",
     "unist-builder": "^3.0.0",

test/core.js

@@ -109,25 +109,29 @@ test('toHast()', (t) => {
   )
 
   t.deepEqual(
+    // @ts-expect-error: custom node.
     toHast(u('foo', 'tango')),
     u('text', 'tango'),
     'should transform unknown texts to `text`'
   )
 
   t.deepEqual(
+    // @ts-expect-error: custom node.
     toHast(u('bar', [u('text', 'tango')])),
     u('element', {tagName: 'div', properties: {}}, [u('text', 'tango')]),
     'should transform unknown parents to `div`'
   )
 
   t.deepEqual(
+    // @ts-expect-error: custom node.
     toHast(u('bar')),
     u('element', {tagName: 'div', properties: {}}, []),
     'should transform unknown nodes to `div`'
   )
 
   t.deepEqual(
     toHast(
+      // @ts-expect-error: custom node.
       u(
         'foo',
         {
@@ -147,12 +151,14 @@ test('toHast()', (t) => {
   )
 
   t.deepEqual(
+    // @ts-expect-error: custom node.
     toHast(u('foo', {data: {hChildren: [u('text', 'tango')]}}, 'tango')),
     u('element', {tagName: 'div', properties: {}}, [u('text', 'tango')]),
     'should transform unknown nodes with `data.hChildren` only to `div`'
   )
 
   t.deepEqual(
+    // @ts-expect-error: custom node.
     toHast(u('foo', {data: {hProperties: {className: 'charlie'}}}, 'tango')),
     u('element', {tagName: 'div', properties: {className: 'charlie'}}, []),
     'should transform unknown nodes with `data.hProperties` only to a `element` node'

test/definition.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import('mdast').Paragraph} Paragraph
+ */
+
 import test from 'tape'
 import {u} from 'unist-builder'
 import {toHast} from '../index.js'
@@ -17,11 +21,15 @@ test('Definition', (t) => {
 
   t.deepEqual(
     toHast(
-      u('paragraph', [
-        u('linkReference', {identifier: 'alpha'}, [u('text', 'bravo')]),
-        u('definition', {identifier: 'alpha', url: 'https://charlie.com'}),
-        u('definition', {identifier: 'alpha', url: 'https://delta.com'})
-      ])
+      /** @type {Paragraph} */ (
+        u('paragraph', [
+          u('linkReference', {identifier: 'alpha', referenceType: 'shortcut'}, [
+            u('text', 'bravo')
+          ]),
+          u('definition', {identifier: 'alpha', url: 'https://charlie.com'}),
+          u('definition', {identifier: 'alpha', url: 'https://delta.com'})
+        ])
+      )
     ),
     u('element', {tagName: 'p', properties: {}}, [
       u('element', {tagName: 'a', properties: {href: 'https://charlie.com'}}, [

test/footnote-reference.js

@@ -40,6 +40,7 @@ test('FootnoteReference', (t) => {
   )
 
   t.deepEqual(
+    // @ts-expect-error: supposed to be string.
     toHast(u('footnoteReference', {identifier: 1})),
     u(
       'element',

test/handlers-option.js

@@ -1,5 +1,6 @@
 /**
  * @typedef {import('mdast').Paragraph} Paragraph
+ * @typedef {import('mdast').Root|import('mdast').Content} Node
  */
 
 import assert from 'node:assert'
@@ -23,11 +24,13 @@ test('handlers option', (t) => {
     'should override default handler'
   )
 
-  const customMdast = u('paragraph', [
-    u('custom', 'with value'),
-    u('custom', [u('image', {url: 'with-children.png'})]),
-    u('text', 'bravo')
-  ])
+  const customMdast = /** @type {Paragraph} */ (
+    u('paragraph', [
+      u('custom', 'with value'),
+      u('custom', [u('image', {url: 'with-children.png'})]),
+      u('text', 'bravo')
+    ])
+  )
 
   t.deepEqual(
     toHast(customMdast, {}),
@@ -51,7 +54,7 @@ test('handlers option', (t) => {
   t.deepEqual(
     toHast(customMdast, {
       // @ts-expect-error `hast` expected, but this returns unknown mdast nodes.
-      unknownHandler(_, /** @type {object} */ node) {
+      unknownHandler(_, /** @type {Node} */ node) {
         return node
       }
     }),

test/heading.js

@@ -1,10 +1,16 @@
+/**
+ * @typedef {import('mdast').Heading} Heading
+ */
+
 import test from 'tape'
 import {u} from 'unist-builder'
 import {toHast} from '../index.js'
 
 test('Heading', (t) => {
   t.deepEqual(
-    toHast(u('heading', {depth: 4}, [u('text', 'echo')])),
+    toHast(
+      /** @type {Heading} */ (u('heading', {depth: 4}, [u('text', 'echo')]))
+    ),
     u('element', {tagName: 'h4', properties: {}}, [u('text', 'echo')]),
     'should transform `heading` to a `h[1-6]` element'
   )