Refactor code-style

Author: wooorm

lib/index.js

@@ -1,47 +1,17 @@
 /**
- * @typedef {import('unist').Parent} UnistParent
  * @typedef {import('mdast').Content} Content
  * @typedef {import('mdast').Heading} Heading
  * @typedef {import('mdast').Root} Root
+ * @typedef {import('unist').Parent} UnistParent
  */
 
+// To do: use `Nodes`, `Parents` from `mdast` when released.
 /**
  * @typedef {Content | Root} Node
  * @typedef {Extract<Node, UnistParent>} Parent
  */
 
 /**
- * @callback TestFunction
- *   Check if a node matches.
- * @param {string} value
- *   Plain-text heading.
- * @param {Heading} node
- *   Heading node.
- * @returns {boolean | null | undefined}
- *   Whether this is the heading that is searched for.
- *
- * @typedef {string | RegExp | TestFunction} Test
- *   Test for a heading.
- *
- *   When `string`, wrapped in `new RegExp('^(' + value + ')$', 'i')`;
- *   when `RegExp`, wrapped in `(value) => expression.test(value)`
- *
- * @typedef Options
- *   Configuration.
- * @property {Test} test
- *   Test for a heading.
- * @property {boolean | null | undefined} [ignoreFinalDefinitions=false]
- *   Ignore final definitions otherwise in the section.
- *
- * @typedef Info
- *   Extra info.
- * @property {Parent} parent
- *   Parent of the section.
- * @property {number} start
- *   Index of `start` in `parent`.
- * @property {number | null} end
- *   Index of `end` in `parent`.
- *
  * @callback Handler
  *   Callback called when a section is found.
  * @param {Heading} start
@@ -58,8 +28,40 @@
  *   If nothing is returned, nothing will be changed.
  *   If an array of nodes (can include `null` and `undefined`) is returned, the
  *   original section will be replaced by those nodes.
+ *
+ * @typedef Info
+ *   Extra info.
+ * @property {Parent} parent
+ *   Parent of the section.
+ * @property {number} start
+ *   Index of `start` in `parent`.
+ * @property {number | null} end
+ *   Index of `end` in `parent`.
+ *
+ * @typedef Options
+ *   Configuration.
+ * @property {Test} test
+ *   Test for a heading.
+ * @property {boolean | null | undefined} [ignoreFinalDefinitions=false]
+ *   Ignore final definitions otherwise in the section (default: `false`).
+ *
+ * @typedef {RegExp | TestFunction | string} Test
+ *   Test for a heading.
+ *
+ *   When `string`, wrapped in `new RegExp('^(' + value + ')$', 'i')`;
+ *   when `RegExp`, wrapped in `(value) => expression.test(value)`
+ *
+ * @callback TestFunction
+ *   Check if a node matches.
+ * @param {string} value
+ *   Plain-text heading.
+ * @param {Heading} node
+ *   Heading node.
+ * @returns {boolean | null | undefined | void}
+ *   Whether this is the heading that is searched for.
  */
 
+import {ok as assert} from 'devlop'
 import {toString} from 'mdast-util-to-string'
 
 // To do: next major: remove `null` in API output.
@@ -78,16 +80,17 @@ import {toString} from 'mdast-util-to-string'
  *
  * @param {Node} tree
  *   Tree to change.
- * @param {Test | Options} options
+ * @param {Options | Test} options
  *   Configuration.
  * @param {Handler} handler
  *   Handle a section.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 // eslint-disable-next-line complexity
 export function headingRange(tree, options, handler) {
   let test = options
+  // To do: smarter types to allow siblings of headings.
   /** @type {Array<Node>} */
   const children = 'children' in tree ? tree.children : []
   let ignoreFinalDefinitions = false
@@ -154,12 +157,11 @@ export function headingRange(tree, options, handler) {
       }
     }
 
-    /** @type {Heading} */
-    // @ts-expect-error `start` points to a heading.
     const head = children[start]
-    /** @type {Parent} */
-    // @ts-expect-error always a parent, or we don’t come here.
+    assert(head.type === 'heading')
+
     const parent = tree
+    assert('children' in parent, 'parent is a parent')
 
     const nodes = handler(head, children.slice(start + 1, end), children[end], {
       parent,

package.json

@@ -36,6 +36,7 @@
   "dependencies": {
     "@types/mdast": "^3.0.0",
     "@types/unist": "^2.0.0",
+    "devlop": "^1.1.0",
     "mdast-util-to-string": "^3.0.0"
   },
   "devDependencies": {

readme.md

@@ -97,12 +97,14 @@ console.log(String(file))
 
 /** @type {import('unified').Plugin<[], import('mdast').Root>} */
 function myPluginThatReplacesFoo() {
-  return (tree) => {
-    headingRange(tree, 'foo', (start, nodes, end) => [
-      start,
-      {type: 'paragraph', children: [{type: 'text', value: 'Qux.'}]},
-      end
-    ])
+  return function (tree) {
+    headingRange(tree, 'foo', function (start, nodes, end) {
+      return [
+        start,
+        {type: 'paragraph', children: [{type: 'text', value: 'Qux.'}]},
+        end
+      ]
+    })
   }
 }
 ```
@@ -146,7 +148,7 @@ excluded.
 
 ###### Returns
 
-Nothing (`void`).
+Nothing (`undefined`).
 
 ### `Handler`