Refactor code-style

Author: wooorm

Diff for: index.js

@@ -1,8 +1,8 @@
 /**
+ * @typedef {import('./lib/state.js').Handle} Handle
+ * @typedef {import('./lib/state.js').NodeHandle} NodeHandle
+ * @typedef {import('./lib/state.js').Options} Options
  * @typedef {import('./lib/state.js').State} State
- * @typedef {import('./lib/types.js').Handle} Handle
- * @typedef {import('./lib/types.js').NodeHandle} NodeHandle
- * @typedef {import('./lib/types.js').Options} Options
  */
 
 export {toMdast} from './lib/index.js'

Diff for: lib/handlers/a.js

@@ -1,28 +1,35 @@
 /**
- * @typedef {import('mdast').Link} Link
  * @typedef {import('hast').Element} Element
+ *
+ * @typedef {import('mdast').Link} Link
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {Link}
  *   mdast node.
  */
 export function a(state, node) {
   const properties = node.properties || {}
+  // Allow potentially “invalid” nodes, they might be unknown.
+  // We also support straddling later.
+  const children = /** @type {Array<PhrasingContent>} */ (state.all(node))
 
   /** @type {Link} */
   const result = {
     type: 'link',
     url: state.resolve(String(properties.href || '') || null),
     title: properties.title ? String(properties.title) : null,
-    // @ts-expect-error: allow potentially “invalid” nodes, they might be unknown.
-    // We also support straddling later.
-    children: state.all(node)
+    children
   }
   state.patch(node, result)
   return result

Diff for: lib/handlers/base.js

@@ -1,14 +1,18 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 export function base(state, node) {

Diff for: lib/handlers/blockquote.js

@@ -1,13 +1,18 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').Blockquote} Blockquote
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {Blockquote}
  *   mdast node.

Diff for: lib/handlers/br.js

@@ -1,13 +1,18 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').Break} Break
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {Break}
  *   mdast node.

Diff for: lib/handlers/code.js

@@ -1,6 +1,8 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').Code} Code
+ *
  * @typedef {import('../state.js').State} State
  */
 
@@ -12,15 +14,15 @@ const prefix = 'language-'
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {Code}
  *   mdast node.
  */
 export function code(state, node) {
   const children = node.children
   let index = -1
-  /** @type {Array<string | number> | undefined} */
+  /** @type {Array<number | string> | undefined} */
   let classList
   /** @type {string | undefined} */
   let lang

Diff for: lib/handlers/comment.js

@@ -1,19 +1,24 @@
 /**
  * @typedef {import('hast').Comment} Comment
- * @typedef {import('mdast').HTML} HTML
+ *
+ * @typedef {import('mdast').Html} Html
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Comment} node
+ * @param {Readonly<Comment>} node
  *   hast element to transform.
- * @returns {HTML}
+ * @returns {Html}
  *   mdast node.
  */
 export function comment(state, node) {
-  /** @type {HTML} */
+  /** @type {Html} */
   const result = {
     type: 'html',
     value: '<!--' + node.value + '-->'

Diff for: lib/handlers/del.js

@@ -1,25 +1,29 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').Delete} Delete
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {Delete}
  *   mdast node.
  */
 export function del(state, node) {
+  // Allow potentially “invalid” nodes, they might be unknown.
+  // We also support straddling later.
+  const children = /** @type {Array<PhrasingContent>} */ (state.all(node))
   /** @type {Delete} */
-  const result = {
-    type: 'delete',
-    // @ts-expect-error: allow potentially “invalid” nodes, they might be unknown.
-    // We also support straddling later.
-    children: state.all(node)
-  }
+  const result = {type: 'delete', children}
   state.patch(node, result)
   return result
 }

Diff for: lib/handlers/dl.js

@@ -1,12 +1,18 @@
 /**
  * @typedef {import('hast').Element} Element
  * @typedef {import('hast').ElementContent} ElementContent
- * @typedef {import('mdast').List} List
+ *
  * @typedef {import('mdast').BlockContent} BlockContent
  * @typedef {import('mdast').DefinitionContent} DefinitionContent
+ * @typedef {import('mdast').List} List
  * @typedef {import('mdast').ListContent} ListContent
+ * @typedef {import('mdast').ListItem} ListItem
+ *
  * @typedef {import('../state.js').State} State
  *
+ */
+
+/**
  * @typedef Group
  *   Title/definition group.
  * @property {Array<Element>} titles
@@ -20,7 +26,7 @@ import {listItemsSpread} from '../util/list-items-spread.js'
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {List | undefined}
  *   mdast node.
@@ -44,7 +50,7 @@ export function dl(state, node) {
   }
 
   /** @type {Group} */
-  let group = {titles: [], definitions: []}
+  let group = {definitions: [], titles: []}
   index = -1
 
   // Group titles and definitions.
@@ -60,7 +66,7 @@ export function dl(state, node) {
         previous.tagName === 'dd'
       ) {
         groups.push(group)
-        group = {titles: [], definitions: []}
+        group = {definitions: [], titles: []}
       }
 
       group.titles.push(child)
@@ -116,12 +122,7 @@ export function dl(state, node) {
  *   mdast nodes.
  */
 function handle(state, children) {
-  const nodes = state.all({
-    type: 'element',
-    tagName: 'x',
-    properties: {},
-    children
-  })
+  const nodes = state.all({type: 'root', children})
   const listItems = state.toSpecificContent(nodes, create)
 
   if (listItems.length === 0) {
@@ -144,7 +145,7 @@ function handle(state, children) {
 }
 
 /**
- * @returns {ListContent}
+ * @returns {ListItem}
  */
 function create() {
   return {type: 'listItem', spread: false, checked: null, children: []}

Diff for: lib/handlers/em.js

@@ -1,21 +1,30 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').Emphasis} Emphasis
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {Emphasis}
  *   mdast node.
  */
 export function em(state, node) {
+  // Allow potentially “invalid” nodes, they might be unknown.
+  // We also support straddling later.
+  const children = /** @type {Array<PhrasingContent>} */ (state.all(node))
+
   /** @type {Emphasis} */
-  // @ts-expect-error: allow potentially “invalid” nodes, they might be unknown.
-  const result = {type: 'emphasis', children: state.all(node)}
+  const result = {type: 'emphasis', children}
   state.patch(node, result)
   return result
 }

Diff for: lib/handlers/heading.js

@@ -1,29 +1,32 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').Heading} Heading
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {Heading}
  *   mdast node.
  */
 export function heading(state, node) {
-  /* c8 ignore next */
-  const depth = Number(node.tagName.charAt(1)) || 1
+  const depth = /** @type {Heading['depth']} */ (
+    /* c8 ignore next */
+    Number(node.tagName.charAt(1)) || 1
+  )
+  const children = /** @type {Array<PhrasingContent>} */ (state.all(node))
 
   /** @type {Heading} */
-  const result = {
-    type: 'heading',
-    // @ts-expect-error: fine.
-    depth,
-    // @ts-expect-error: allow potentially “invalid” nodes, they might be unknown.
-    children: state.all(node)
-  }
+  const result = {type: 'heading', depth, children}
   state.patch(node, result)
   return result
 }

Diff for: lib/handlers/hr.js

@@ -1,13 +1,18 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').ThematicBreak} ThematicBreak
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
  * @returns {ThematicBreak}
  *   mdast node.

Diff for: lib/handlers/iframe.js

@@ -1,15 +1,20 @@
 /**
  * @typedef {import('hast').Element} Element
+ *
  * @typedef {import('mdast').Link} Link
+ *
  * @typedef {import('../state.js').State} State
  */
 
+// Fix to let VS Code see references to the above types.
+''
+
 /**
  * @param {State} state
  *   State.
- * @param {Element} node
+ * @param {Readonly<Element>} node
  *   hast element to transform.
- * @returns {Link | void}
+ * @returns {Link | undefined}
  *   mdast node.
  */
 export function iframe(state, node) {