Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,5 +1,6 @@
 coverage/
 node_modules/
 .DS_Store
+*.d.ts
 *.log
 yarn.lock

index.js

@@ -1,3 +1,20 @@
+/**
+ * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
+ * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Node} Node
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Parent} Parent
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Handle} ToMarkdownHandle
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Context} Context
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Options} ToMarkdownExtension
+ *
+ * @typedef {Record<string, string>} Attributes
+ * @typedef {{name: string, attributes?: Attributes}} Directive
+ *
+ * @typedef {Parent & Directive & {type: 'textDirective', children: Array.<import('mdast').PhrasingContent>}} TextDirective
+ * @typedef {Parent & Directive & {type: 'leafDirective', children: Array.<import('mdast').PhrasingContent>}} LeafDirective
+ * @typedef {Parent & Directive & {type: 'containerDirective', children: Array.<import('mdast').BlockContent>}} ContainerDirective
+ */
+
 import {decodeEntity} from 'parse-entities/decode-entity.js'
 import {stringifyEntitiesLight} from 'stringify-entities'
 import {visitParents} from 'unist-util-visit-parents'
@@ -11,6 +28,7 @@ const shortcut = /^[^\t\n\r "#'.<=>`}]+$/
 
 handleDirective.peek = peekDirective
 
+/** @type {FromMarkdownExtension} */
 export const directiveFromMarkdown = {
   canContainEols: ['textDirective'],
   enter: {
@@ -52,6 +70,7 @@ export const directiveFromMarkdown = {
   }
 }
 
+/** @type {ToMarkdownExtension} */
 export const directiveToMarkdown = {
   unsafe: [
     {
@@ -77,74 +96,104 @@ export const directiveToMarkdown = {
   }
 }
 
+/** @type {FromMarkdownHandle} */
 function enterContainer(token) {
   enter.call(this, 'containerDirective', token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterLeaf(token) {
   enter.call(this, 'leafDirective', token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterText(token) {
   enter.call(this, 'textDirective', token)
 }
 
+/**
+ * @this {ThisParameterType<FromMarkdownHandle>}
+ * @param {string} type
+ * @param {Parameters<FromMarkdownHandle>[0]} token
+ */
 function enter(type, token) {
+  // @ts-expect-error: custom node.
   this.enter({type, name: '', attributes: {}, children: []}, token)
 }
 
+/**
+ * @this {ThisParameterType<FromMarkdownHandle>}
+ * @param {Parameters<FromMarkdownHandle>[0]} token
+ */
 function exitName(token) {
   this.stack[this.stack.length - 1].name = this.sliceSerialize(token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterContainerLabel(token) {
   this.enter(
     {type: 'paragraph', data: {directiveLabel: true}, children: []},
     token
   )
 }
 
+/** @type {FromMarkdownHandle} */
 function exitContainerLabel(token) {
   this.exit(token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterAttributes() {
   this.setData('directiveAttributes', [])
   this.buffer() // Capture EOLs
 }
 
+/** @type {FromMarkdownHandle} */
 function exitAttributeIdValue(token) {
-  this.getData('directiveAttributes').push([
-    'id',
-    decodeLight(this.sliceSerialize(token))
-  ])
+  /** @type {Array.<[string, string]>} */
+  // @ts-expect-error: custom.
+  const list = this.getData('directiveAttributes')
+  list.push(['id', decodeLight(this.sliceSerialize(token))])
 }
 
+/** @type {FromMarkdownHandle} */
 function exitAttributeClassValue(token) {
-  this.getData('directiveAttributes').push([
-    'class',
-    decodeLight(this.sliceSerialize(token))
-  ])
+  /** @type {Array.<[string, string]>} */
+  // @ts-expect-error: custom.
+  const list = this.getData('directiveAttributes')
+  list.push(['class', decodeLight(this.sliceSerialize(token))])
 }
 
+/** @type {FromMarkdownHandle} */
 function exitAttributeValue(token) {
-  const attributes = this.getData('directiveAttributes')
-  attributes[attributes.length - 1][1] = decodeLight(this.sliceSerialize(token))
+  /** @type {Array.<[string, string]>} */
+  // @ts-expect-error: custom.
+  const list = this.getData('directiveAttributes')
+  list[list.length - 1][1] = decodeLight(this.sliceSerialize(token))
 }
 
+/** @type {FromMarkdownHandle} */
 function exitAttributeName(token) {
+  /** @type {Array.<[string, string]>} */
+  // @ts-expect-error: custom.
+  const list = this.getData('directiveAttributes')
+
   // Attribute names in CommonMark are significantly limited, so character
   // references can’t exist.
-  this.getData('directiveAttributes').push([this.sliceSerialize(token), ''])
+  list.push([this.sliceSerialize(token), ''])
 }
 
+/** @type {FromMarkdownHandle} */
 function exitAttributes() {
-  const attributes = this.getData('directiveAttributes')
+  /** @type {Array.<[string, string]>} */
+  // @ts-expect-error: custom.
+  const list = this.getData('directiveAttributes')
+  /** @type {Record.<string, string>} */
   const cleaned = {}
   let index = -1
 
-  while (++index < attributes.length) {
-    const attribute = attributes[index]
+  while (++index < list.length) {
+    const attribute = list[index]
 
     if (attribute[0] === 'class' && cleaned.class) {
       cleaned.class += ' ' + attribute[1]
@@ -158,10 +207,15 @@ function exitAttributes() {
   this.stack[this.stack.length - 1].attributes = cleaned
 }
 
+/** @type {FromMarkdownHandle} */
 function exit(token) {
   this.exit(token)
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {TextDirective|LeafDirective|ContainerDirective} node
+ */
 function handleDirective(node, _, context) {
   const prefix = fence(node)
   const exit = context.enter(node.type)
@@ -181,15 +235,23 @@ function handleDirective(node, _, context) {
   return value
 }
 
+/** @type {ToMarkdownHandle} */
 function peekDirective() {
   return ':'
 }
 
+/**
+ * @param {TextDirective|LeafDirective|ContainerDirective} node
+ * @param {Context} context
+ * @returns {string}
+ */
 function label(node, context) {
+  /** @type {Parent} */
   let label = node
 
   if (node.type === 'containerDirective') {
     if (!inlineDirectiveLabel(node)) return ''
+    // @ts-expect-error: we just asserted it’s a parent.
     label = node.children[0]
   }
 
@@ -201,14 +263,24 @@ function label(node, context) {
   return value ? '[' + value + ']' : ''
 }
 
+/**
+ * @param {TextDirective|LeafDirective|ContainerDirective} node
+ * @param {Context} context
+ * @returns {string}
+ */
 function attributes(node, context) {
   const quote = checkQuote(context)
   const subset = node.type === 'textDirective' ? [quote] : [quote, '\n', '\r']
   const attrs = node.attributes || {}
+  /** @type {Array.<string>} */
   const values = []
+  /** @type {string|undefined} */
   let classesFull
+  /** @type {string|undefined} */
   let classes
+  /** @type {string|undefined} */
   let id
+  /** @type {string} */
   let key
 
   for (key in attrs) {
@@ -217,25 +289,29 @@ function attributes(node, context) {
       attrs[key] !== undefined &&
       attrs[key] !== null
     ) {
-      let value = String(attrs[key])
+      const value = String(attrs[key])
 
       if (key === 'id') {
         id = shortcut.test(value) ? '#' + value : quoted('id', value)
       } else if (key === 'class') {
-        value = value.split(/[\t\n\r ]+/g)
-        classesFull = []
-        classes = []
+        const list = value.split(/[\t\n\r ]+/g)
+        /** @type {Array.<string>} */
+        const classesFullList = []
+        /** @type {Array.<string>} */
+        const classesList = []
         let index = -1
 
-        while (++index < value.length) {
-          ;(shortcut.test(value[index]) ? classes : classesFull).push(
-            value[index]
+        while (++index < list.length) {
+          ;(shortcut.test(list[index]) ? classesList : classesFullList).push(
+            list[index]
           )
         }
 
         classesFull =
-          classesFull.length > 0 ? quoted('class', classesFull.join(' ')) : ''
-        classes = classes.length > 0 ? '.' + classes.join('.') : ''
+          classesFullList.length > 0
+            ? quoted('class', classesFullList.join(' '))
+            : ''
+        classes = classesList.length > 0 ? '.' + classesList.join('.') : ''
       } else {
         values.push(quoted(key, value))
       }
@@ -256,6 +332,11 @@ function attributes(node, context) {
 
   return values.length > 0 ? '{' + values.join(' ') + '}' : ''
 
+  /**
+   * @param {string} key
+   * @param {string} value
+   * @returns {string}
+   */
   function quoted(key, value) {
     return (
       key +
@@ -266,6 +347,11 @@ function attributes(node, context) {
   }
 }
 
+/**
+ * @param {TextDirective|LeafDirective|ContainerDirective} node
+ * @param {Context} context
+ * @returns {string}
+ */
 function content(node, context) {
   return containerFlow(
     inlineDirectiveLabel(node)
@@ -275,26 +361,43 @@ function content(node, context) {
   )
 }
 
+/**
+ * @param {TextDirective|LeafDirective|ContainerDirective} node
+ * @returns {boolean}
+ */
 function inlineDirectiveLabel(node) {
-  return (
+  return Boolean(
     node.children &&
-    node.children[0] &&
-    node.children[0].data &&
-    node.children[0].data.directiveLabel
+      node.children[0] &&
+      node.children[0].data &&
+      node.children[0].data.directiveLabel
   )
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 function decodeLight(value) {
   return value.replace(
     /&(#(\d{1,7}|x[\da-f]{1,6})|[\da-z]{1,31});/gi,
     decodeIfPossible
   )
 }
 
+/**
+ * @param {string} $0
+ * @param {string} $1
+ * @returns {string}
+ */
 function decodeIfPossible($0, $1) {
   return decodeEntity($1) || $0
 }
 
+/**
+ * @param {TextDirective|LeafDirective|ContainerDirective} node
+ * @returns {string}
+ */
 function fence(node) {
   let size = 0
 
@@ -309,7 +412,8 @@ function fence(node) {
 
   return ':'.repeat(size)
 
-  function onvisit(node, parents) {
+  /** @type {import('unist-util-visit-parents').Visitor<TextDirective|LeafDirective|ContainerDirective>} */
+  function onvisit(_, parents) {
     let index = parents.length
     let nesting = 0