Change to improve types

Now it’s know what the actual parent of a heading can be, and what siblings
can be passed and can be returned.

Author: wooorm

lib/index.js

@@ -1,28 +1,115 @@
 /**
- * @typedef {import('mdast').Content} Content
  * @typedef {import('mdast').Heading} Heading
  * @typedef {import('mdast').Root} Root
+ * @typedef {import('unist').Node} UnistNode
  * @typedef {import('unist').Parent} UnistParent
  */
 
-// To do: use `Nodes`, `Parents` from `mdast` when released.
 /**
- * @typedef {Content | Root} Node
- * @typedef {Extract<Node, UnistParent>} Parent
+ * @typedef {0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10} Uint
+ *   Number; capped reasonably.
+ */
+
+/**
+ * @typedef {I extends 0 ? 1 : I extends 1 ? 2 : I extends 2 ? 3 : I extends 3 ? 4 : I extends 4 ? 5 : I extends 5 ? 6 : I extends 6 ? 7 : I extends 7 ? 8 : I extends 8 ? 9 : 10} Increment
+ *   Increment a number in the type system.
+ * @template {Uint} [I=0]
+ *   Index.
+ */
+
+/**
+ * @typedef {(
+ *   Tree extends UnistParent
+ *     ? Depth extends Max
+ *       ? Tree
+ *       : Tree | InclusiveDescendant<Tree['children'][number], Max, Increment<Depth>>
+ *     : Tree
+ * )} InclusiveDescendant
+ *   Collect all (inclusive) descendants of `Tree`.
+ *
+ *   > 👉 **Note**: for performance reasons, this seems to be the fastest way to
+ *   > recurse without actually running into an infinite loop, which the
+ *   > previous version did.
+ *   >
+ *   > Practically, a max of `2` is typically enough assuming a `Root` is
+ *   > passed, but it doesn’t improve performance.
+ *   > It gets higher with `List > ListItem > Table > TableRow > TableCell`.
+ *   > Using up to `10` doesn’t hurt or help either.
+ * @template {UnistNode} Tree
+ *   Tree type.
+ * @template {Uint} [Max=10]
+ *   Max; searches up to this depth.
+ * @template {Uint} [Depth=0]
+ *   Current depth.
+ */
+
+/**
+ * @typedef {(
+ *   Node extends {children: Array<infer Child>}
+ *   ? Child
+ *   : never
+ * )} InternalChild
+ *   Collect nodes that can be parents of `Child`.
+ * @template {UnistNode} Node
+ *   All node types in a tree.
+ * @template {UnistNode} Parent
+ *   Node to search for.
+ */
+
+/**
+ * @typedef {(
+ *   Node extends UnistParent
+ *   ? Node extends {children: Array<infer Children>}
+ *     ? Kind extends Children ? Node : never
+ *     : never
+ *   : never
+ * )} InternalParent
+ *   Collect nodes that can be parents of `Child`.
+ * @template {UnistNode} Node
+ *   All node types in a tree.
+ * @template {UnistNode} Kind
+ *   Node to search for.
+ */
+
+/**
+ * @typedef {InternalChild<InclusiveDescendant<Tree>, Kind>} Child
+ *   Collect nodes in `Tree` that can be parents of `Child`.
+ * @template {UnistNode} Tree
+ *   All node types in a tree.
+ * @template {UnistNode} Kind
+ *   Node to search for.
+ */
+
+/**
+ * @typedef {InternalParent<InclusiveDescendant<Tree>, Kind>} Parent
+ *   Collect nodes in `Tree` that can be parents of `Child`.
+ * @template {UnistNode} Tree
+ *   All node types in a tree.
+ * @template {UnistNode} Kind
+ *   Node to search for.
+ */
+
+/**
+ * @typedef {Child<Root, Parent<Root, Heading>>} Sibling
+ *   Collect nodes in `Tree` that can be parents of `Child`.
+ * @template {UnistNode} Tree
+ *   All node types in a tree.
+ * @template {UnistNode} Node
+ *   Node to search for.
  */
 
 /**
  * @callback Handler
  *   Callback called when a section is found.
  * @param {Heading} start
  *   Start of section (a heading node matching `test`).
- * @param {Array<Node>} between
+ * @param {Array<Sibling<Root, Heading>>} between
  *   Nodes between `start` and `end`.
- * @param {Node | undefined} end
+ * @param {Sibling<Root, Heading> | undefined} end
  *   End of section, if any.
  * @param {Info} scope
  *   Extra info.
- * @returns {Array<Node | null | undefined> | null | undefined | void}
+ * @returns {Array<Sibling<Root, Heading> | null | undefined> | null | undefined | void}
  *   Results.
  *
  *   If nothing is returned, nothing will be changed.
@@ -31,7 +118,7 @@
  *
  * @typedef Info
  *   Extra info.
- * @property {Parent} parent
+ * @property {Parent<Root, Heading>} parent
  *   Parent of the section.
  * @property {number} start
  *   Index of `start` in `parent`.
@@ -78,7 +165,7 @@ import {toString} from 'mdast-util-to-string'
  * If `ignoreFinalDefinitions: true`, final definitions “in” the section are
  * excluded.
  *
- * @param {Node} tree
+ * @param {Parent<Root, Heading>} tree
  *   Tree to change.
  * @param {Options | Test} options
  *   Configuration.
@@ -91,7 +178,7 @@ import {toString} from 'mdast-util-to-string'
 export function headingRange(tree, options, handler) {
   let test = options
   // To do: smarter types to allow siblings of headings.
-  /** @type {Array<Node>} */
+  /** @type {Array<Sibling<Root, Heading>>} */
   const children = 'children' in tree ? tree.children : []
   let ignoreFinalDefinitions = false
 
@@ -163,7 +250,9 @@ export function headingRange(tree, options, handler) {
     const parent = tree
     assert('children' in parent, 'parent is a parent')
 
-    const nodes = handler(head, children.slice(start + 1, end), children[end], {
+    const from = children.slice(start + 1, end)
+
+    const nodes = handler(head, from, children[end], {
       parent,
       start,
       end: children[end] ? end : null
@@ -172,7 +261,7 @@ export function headingRange(tree, options, handler) {
     if (nodes) {
       // Ensure no empty nodes are inserted.
       // This could be the case if `end` is in `nodes` but no `end` node exists.
-      /** @type {Array<Node>} */
+      /** @type {Array<Sibling<Root, Heading>>} */
       const result = []
       let index = -1
 

test.js

@@ -43,7 +43,12 @@ test('headingRange', async function (t) {
       const tree = {type: 'inlineCode', value: 'asd'}
 
       assert.doesNotThrow(function () {
-        headingRange(tree, 'x', function () {})
+        headingRange(
+          // @ts-expect-error: types know that `InlineCode` can’t have `Heading` as a child.
+          tree,
+          'x',
+          function () {}
+        )
       })
     }
   )