Add JSDoc based types

Closes GH-72.

Reviewed-by: Christian Murphy <[email protected]>

Author: wooorm

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/

index.js

@@ -1 +1,6 @@
+/**
+ * @typedef {import('./lib/index.js').Options} Options
+ * @typedef {import('./lib/index.js').Result} Result
+ */
+
 export {toc} from './lib/index.js'

lib/contents.js

@@ -1,7 +1,28 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('mdast').List} List
+ * @typedef {import('mdast').ListItem} ListItem
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ * @typedef {import('mdast').StaticPhrasingContent} StaticPhrasingContent
+ * @typedef {import('./search.js').SearchEntry} SearchEntry
+ *
+ * @typedef ContentsOptions
+ * @property {boolean} [tight=false] Whether to compile list-items tightly.
+ * @property {boolean} [ordered=false] Whether to compile list-items as an ordered list, otherwise they are unordered.
+ * @property {string} [prefix=null] Add a prefix to links to headings in the table of contents. Useful for example when later going from mdast to hast and sanitizing with `hast-util-sanitize`.
+ */
+
 import extend from 'extend'
 
-// Transform a list of heading objects to a markdown list.
-export function contents(map, tight, prefix, ordered) {
+/**
+ * Transform a list of heading objects to a markdown list.
+ *
+ * @param {Array.<SearchEntry>} map
+ * @param {ContentsOptions} settings
+ */
+export function contents(map, settings) {
+  const {ordered = false, tight = false, prefix = null} = settings
+  /** @type {List} */
   const table = {type: 'list', ordered, spread: false, children: []}
   let minDepth = Number.POSITIVE_INFINITY
   let index = -1
@@ -24,103 +45,130 @@ export function contents(map, tight, prefix, ordered) {
   index = -1
 
   while (++index < map.length) {
-    insert(map[index], table, tight, prefix, ordered)
+    insert(map[index], table, {ordered, tight, prefix})
   }
 
   return table
 }
 
-// Insert an entry into `parent`.
-// eslint-disable-next-line max-params
-function insert(entry, parent, tight, prefix, ordered) {
-  const siblings = parent.children
-  const tail = siblings[siblings.length - 1]
+/**
+ * Insert an entry into `parent`.
+ *
+ * @param {SearchEntry} entry
+ * @param {List|ListItem} parent
+ * @param {ContentsOptions} settings
+ */
+function insert(entry, parent, settings) {
   let index = -1
 
-  if (entry.depth === 1) {
-    siblings.push({
-      type: 'listItem',
-      spread: false,
-      children: [
-        {
-          type: 'paragraph',
-          children: [
-            {
-              type: 'link',
-              title: null,
-              url: '#' + (prefix || '') + entry.id,
-              children: all(entry.children)
-            }
-          ]
-        }
-      ]
-    })
-  } else if (tail && tail.type === 'listItem') {
-    insert(entry, siblings[siblings.length - 1], tight, prefix, ordered)
-  } else if (tail && tail.type === 'list') {
+  if (parent.type === 'list') {
+    if (entry.depth === 1) {
+      parent.children.push({
+        type: 'listItem',
+        spread: false,
+        children: [
+          {
+            type: 'paragraph',
+            children: [
+              {
+                type: 'link',
+                title: null,
+                url: '#' + (settings.prefix || '') + entry.id,
+                children: all(entry.children)
+              }
+            ]
+          }
+        ]
+      })
+    } else if (parent.children.length > 0) {
+      insert(entry, parent.children[parent.children.length - 1], settings)
+    } else {
+      /** @type {ListItem} */
+      const item = {type: 'listItem', spread: false, children: []}
+      parent.children.push(item)
+      insert(entry, item, settings)
+    }
+  }
+  // List item
+  else if (
+    parent.children[parent.children.length - 1] &&
+    parent.children[parent.children.length - 1].type === 'list'
+  ) {
     entry.depth--
-    insert(entry, tail, tight, prefix, ordered)
-  } else if (parent.type === 'list') {
-    const item = {type: 'listItem', spread: false, children: []}
-    siblings.push(item)
-    insert(entry, item, tight, prefix, ordered)
+    insert(
+      entry,
+      // @ts-ignore It’s a `list`, we just checked.
+      parent.children[parent.children.length - 1],
+      settings
+    )
   } else {
+    /** @type {List} */
     const item = {
       type: 'list',
-      ordered,
+      ordered: settings.ordered,
       spread: false,
       children: []
     }
-    siblings.push(item)
+    parent.children.push(item)
     entry.depth--
-    insert(entry, item, tight, prefix, ordered)
+    insert(entry, item, settings)
   }
 
-  if (parent.type === 'list' && !tight) {
+  if (parent.type === 'list' && !settings.tight) {
     parent.spread = false
 
-    while (++index < siblings.length) {
-      if (siblings[index].children.length > 1) {
+    while (++index < parent.children.length) {
+      if (parent.children[index].children.length > 1) {
         parent.spread = true
         break
       }
     }
   } else {
-    parent.spread = !tight
+    parent.spread = !settings.tight
   }
 }
 
-function all(children) {
+/**
+ * @param {Array.<PhrasingContent>} [nodes]
+ * @returns {Array.<StaticPhrasingContent>}
+ */
+function all(nodes) {
+  /** @type {Array.<StaticPhrasingContent>} */
   let result = []
   let index = -1
 
-  if (children) {
-    while (++index < children.length) {
-      result = result.concat(one(children[index]))
+  if (nodes) {
+    while (++index < nodes.length) {
+      result = result.concat(one(nodes[index]))
     }
   }
 
   return result
 }
 
+/**
+ * @param {PhrasingContent} node
+ * @returns {StaticPhrasingContent|Array.<StaticPhrasingContent>}
+ */
 function one(node) {
   if (
     node.type === 'link' ||
     node.type === 'linkReference' ||
     node.type === 'footnote' ||
     node.type === 'footnoteReference'
   ) {
+    // @ts-ignore Looks like a parent.
     return all(node.children)
   }
 
   let copy = extend({}, node)
-
   delete copy.children
   delete copy.position
 
   copy = extend(true, {}, copy)
 
   if (node.children) {
+    // @ts-ignore Looks like a parent.
     copy.children = all(node.children)
   }
 

lib/index.js

@@ -1,28 +1,38 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('mdast').List} List
+ * @typedef {import('./search.js').SearchOptions} SearchOptions
+ * @typedef {import('./contents.js').ContentsOptions} ContentsOptions
+ * @typedef {SearchOptions & ContentsOptions & ExtraOptions} Options
+ *
+ * @typedef ExtraOptions
+ * @property {string} [heading] Heading to look for, wrapped in `new RegExp('^(' + value + ')$', 'i')`.
+ *
+ * @typedef Result
+ * @property {number} index
+ * @property {number} endIndex
+ * @property {List} map
+ */
+
 import {search} from './search.js'
 import {contents} from './contents.js'
 import {toExpression} from './to-expression.js'
 
-// Get a TOC representation of `node`.
+/**
+ * Get a TOC representation of `node`.
+ *
+ * @param {Node} node
+ * @param {Options} [options]
+ * @returns {Result}
+ */
 export function toc(node, options) {
   const settings = options || {}
   const heading = settings.heading ? toExpression(settings.heading) : null
   const result = search(node, heading, settings)
 
-  result.map =
-    result.map.length > 0
-      ? contents(
-          result.map,
-          settings.tight,
-          settings.prefix,
-          settings.ordered || false
-        )
-      : null
-
-  // No given heading.
-  if (!heading) {
-    result.endIndex = null
-    result.index = null
+  return {
+    index: heading ? result.index : null,
+    endIndex: heading ? result.endIndex : null,
+    map: result.map.length > 0 ? contents(result.map, settings) : null
   }
-
-  return result
 }

lib/search.js

@@ -1,3 +1,28 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('mdast').Heading} Heading
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ * @typedef {import('unist-util-visit').Visitor<Heading>} HeadingVisitor
+ * @typedef {import('unist-util-is').Type} IsType
+ * @typedef {import('unist-util-is').Props} IsProps
+ * @typedef {import('unist-util-is').TestFunctionAnything} IsTestFunctionAnything
+ *
+ * @typedef SearchOptions
+ * @property {string} [skip] Headings to skip, wrapped in `new RegExp('^(' + value + ')$', 'i')`. Any heading matching this expression will not be present in the table of contents.
+ * @property {IsType|IsProps|IsTestFunctionAnything|Array.<IsType|IsProps|IsTestFunctionAnything>} [parents]
+ * @property {Heading['depth']} [maxDepth=6] Maximum heading depth to include in the table of contents. This is inclusive: when set to `3`, level three headings are included (those with three hashes, `###`).
+ *
+ * @typedef SearchEntry
+ * @property {Heading['depth']} depth
+ * @property {Array.<PhrasingContent>} children
+ * @property {string} id
+ *
+ * @typedef SearchResult
+ * @property {number} index
+ * @property {number} endIndex
+ * @property {Array.<SearchEntry>} map
+ */
+
 import Slugger from 'github-slugger'
 import {toString} from 'mdast-util-to-string'
 import {visit} from 'unist-util-visit'
@@ -6,33 +31,45 @@ import {toExpression} from './to-expression.js'
 
 const slugs = new Slugger()
 
-// Search a node for a location.
+/**
+ * Search a node for a toc.
+ *
+ * @param {Node} root
+ * @param {RegExp} expression
+ * @param {SearchOptions} settings
+ * @returns {SearchResult}
+ */
 export function search(root, expression, settings) {
   const skip = settings.skip && toExpression(settings.skip)
   const parents = convert(settings.parents || root)
+  /** @type {Array.<SearchEntry>} */
   const map = []
+  /** @type {number} */
   let index
+  /** @type {number} */
   let endIndex
+  /** @type {Heading} */
   let opening
 
   slugs.reset()
 
   // Visit all headings in `root`.  We `slug` all headings (to account for
-  // duplicates), but only create a TOC from top-level headings.
+  // duplicates), but only create a TOC from top-level headings (by default).
   visit(root, 'heading', onheading)
 
   return {
     index: index || -1,
     // <sindresorhus/eslint-plugin-unicorn#980>
-    // eslint-disable-next-line unicorn/explicit-length-check
-    endIndex: index ? endIndex || root.children.length : -1,
+    // @ts-ignore Looks like a parent.
+    endIndex: index ? endIndex || root.children.length : -1, // eslint-disable-line unicorn/explicit-length-check
     map
   }
 
+  /** @type {HeadingVisitor} */
   function onheading(node, position, parent) {
     const value = toString(node, {includeImageAlt: false})
-    // Remove this when `remark-attr` is up to date w/ micromark.
-    /* c8 ignore next */
+    /** @type {string} */
+    // @ts-ignore `hProperties` from <https://github.com/syntax-tree/mdast-util-to-hast>
     const id = node.data && node.data.hProperties && node.data.hProperties.id
     const slug = slugs.slug(id || value)
 

lib/to-expression.js

@@ -1,4 +1,9 @@
-// Transform a string into an applicable expression.
+/**
+ * Transform a string into an applicable expression.
+ *
+ * @param {string} value
+ * @returns {RegExp}
+ */
 export function toExpression(value) {
   return new RegExp('^(' + value + ')$', 'i')
 }