Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

complex-types.d.ts

@@ -1,39 +1,4 @@
-import type {Parent} from 'unist'
-import type {PhrasingContent, BlockContent} from 'mdast'
+// To do: next major: remove this file.
+export type {ContainerDirective, LeafDirective, TextDirective} from './index.js'
 
-type DirectiveAttributes = Record<string, string>
-
-/* eslint-disable @typescript-eslint/consistent-type-definitions */
-
-interface DirectiveFields {
-  name: string
-  attributes?: DirectiveAttributes
-}
-
-export interface TextDirective extends Parent, DirectiveFields {
-  type: 'textDirective'
-  children: PhrasingContent[]
-}
-
-export interface LeafDirective extends Parent, DirectiveFields {
-  type: 'leafDirective'
-  children: PhrasingContent[]
-}
-
-export interface ContainerDirective extends Parent, DirectiveFields {
-  type: 'containerDirective'
-  children: BlockContent[]
-}
-
-declare module 'mdast' {
-  interface StaticPhrasingContentMap {
-    textDirective: TextDirective
-  }
-
-  interface BlockContentMap {
-    containerDirective: ContainerDirective
-    leafDirective: LeafDirective
-  }
-}
-
-/* eslint-enable @typescript-eslint/consistent-type-definitions */
+/// <reference types="./index.js" />

index.d.ts

@@ -1,12 +1,75 @@
-export type {
-  ContainerDirective,
-  Directive,
-  LeafDirective,
-  TextDirective
-} from './lib/index.js'
+import type {BlockContent, PhrasingContent} from 'mdast'
 
 export {directiveFromMarkdown, directiveToMarkdown} from './lib/index.js'
 
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+interface DirectiveFields {
+  /**
+   * Directive name.
+   */
+  name: string
+
+  /**
+   * Directive attributes.
+   */
+  attributes?: Record<string, string> | undefined
+}
+
+/**
+ * Directive in flow content (such as in the root document, or block
+ * quotes), which contains further flow content.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface ContainerDirective extends Parent, DirectiveFields {
+  /**
+   * Node type.
+   */
+  type: 'containerDirective'
+
+  /**
+   * Content.
+   */
+  children: BlockContent[]
+}
+
+/**
+ * Directive in flow content (such as in the root document, or block
+ * quotes), which contains nothing.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface LeafDirective extends Parent, DirectiveFields {
+  /**
+   * Node type.
+   */
+  type: 'leafDirective'
+
+  /**
+   * Content.
+   */
+  children: PhrasingContent[]
+}
+
+/**
+ * Directive in phrasing content (such as in paragraphs, headings).
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export interface TextDirective extends Parent, DirectiveFields {
+  /**
+   * Node type.
+   */
+  type: 'textDirective'
+
+  /**
+   * Content.
+   */
+  children: PhrasingContent[]
+}
+
+/**
+ * The different directive nodes.
+ */
+export type Directive = ContainerDirective | LeafDirective | TextDirective
+
 // Add custom data tracked to turn markdown into a tree.
 declare module 'mdast-util-from-markdown' {
   // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
@@ -18,6 +81,7 @@ declare module 'mdast-util-from-markdown' {
   }
 }
 
+// Add custom data tracked to turn a syntax tree into markdown.
 declare module 'mdast-util-to-markdown' {
   // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
   interface ConstructNameMap {
@@ -85,3 +149,29 @@ declare module 'mdast-util-to-markdown' {
     textDirectiveLabel: 'textDirectiveLabel'
   }
 }
+
+// Add nodes to content.
+declare module 'mdast' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface StaticPhrasingContentMap {
+    /**
+     * Directive in phrasing content (such as in paragraphs, headings).
+     */
+    textDirective: TextDirective
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface BlockContentMap {
+    /**
+     * Directive in flow content (such as in the root document, or block
+     * quotes), which contains further flow content.
+     */
+    containerDirective: ContainerDirective
+
+    /**
+     * Directive in flow content (such as in the root document, or block
+     * quotes), which contains nothing.
+     */
+    leafDirective: LeafDirective
+  }
+}

lib/index.js

@@ -1,19 +1,20 @@
 /**
  * @typedef {import('mdast').BlockContent} BlockContent
- * @typedef {import('mdast').Root} Root
  * @typedef {import('mdast').Paragraph} Paragraph
- * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
- * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
+ *
  * @typedef {import('mdast-util-from-markdown').CompileContext} CompileContext
+ * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
+ * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
  * @typedef {import('mdast-util-from-markdown').Token} Token
+ *
  * @typedef {import('mdast-util-to-markdown').ConstructName} ConstructName
- * @typedef {import('mdast-util-to-markdown/lib/types.js').Handle} ToMarkdownHandle
+ * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
+ * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
  * @typedef {import('mdast-util-to-markdown').State} State
- * @typedef {import('mdast-util-to-markdown/lib/types.js').Options} ToMarkdownExtension
- * @typedef {import('../complex-types.js').ContainerDirective} ContainerDirective
- * @typedef {import('../complex-types.js').LeafDirective} LeafDirective
- * @typedef {import('../complex-types.js').TextDirective} TextDirective
- * @typedef {ContainerDirective|LeafDirective|TextDirective} Directive
+ *
+ * @typedef {import('../index.js').LeafDirective} LeafDirective
+ * @typedef {import('../index.js').TextDirective} TextDirective
+ * @typedef {import('../index.js').Directive} Directive
  */
 
 import {parseEntities} from 'parse-entities'
@@ -24,6 +25,9 @@ import {containerPhrasing} from 'mdast-util-to-markdown/lib/util/container-phras
 import {checkQuote} from 'mdast-util-to-markdown/lib/util/check-quote.js'
 import {track} from 'mdast-util-to-markdown/lib/util/track.js'
 
+// To do: next major: replace `containerFlow`, `containerPhrasing`, `track`
+// with `state` methods.
+
 const own = {}.hasOwnProperty
 
 const shortcut = /^[^\t\n\r "#'.<=>`}]+$/
@@ -173,7 +177,7 @@ function enterAttributes() {
  * @type {FromMarkdownHandle}
  */
 function exitAttributeIdValue(token) {
-  const list = /** @type {Array.<[string, string]>} */ (
+  const list = /** @type {Array<[string, string]>} */ (
     this.getData('directiveAttributes')
   )
   list.push([
@@ -189,7 +193,7 @@ function exitAttributeIdValue(token) {
  * @type {FromMarkdownHandle}
  */
 function exitAttributeClassValue(token) {
-  const list = /** @type {Array.<[string, string]>} */ (
+  const list = /** @type {Array<[string, string]>} */ (
     this.getData('directiveAttributes')
   )
   list.push([
@@ -205,7 +209,7 @@ function exitAttributeClassValue(token) {
  * @type {FromMarkdownHandle}
  */
 function exitAttributeValue(token) {
-  const list = /** @type {Array.<[string, string]>} */ (
+  const list = /** @type {Array<[string, string]>} */ (
     this.getData('directiveAttributes')
   )
   list[list.length - 1][1] = parseEntities(this.sliceSerialize(token), {
@@ -218,7 +222,7 @@ function exitAttributeValue(token) {
  * @type {FromMarkdownHandle}
  */
 function exitAttributeName(token) {
-  const list = /** @type {Array.<[string, string]>} */ (
+  const list = /** @type {Array<[string, string]>} */ (
     this.getData('directiveAttributes')
   )
 
@@ -232,10 +236,10 @@ function exitAttributeName(token) {
  * @type {FromMarkdownHandle}
  */
 function exitAttributes() {
-  const list = /** @type {Array.<[string, string]>} */ (
+  const list = /** @type {Array<[string, string]>} */ (
     this.getData('directiveAttributes')
   )
-  /** @type {Record.<string, string>} */
+  /** @type {Record<string, string>} */
   const cleaned = {}
   let index = -1
 
@@ -336,13 +340,13 @@ function attributes(node, state) {
   const quote = checkQuote(state)
   const subset = node.type === 'textDirective' ? [quote] : [quote, '\n', '\r']
   const attrs = node.attributes || {}
-  /** @type {Array.<string>} */
+  /** @type {Array<string>} */
   const values = []
-  /** @type {string|undefined} */
+  /** @type {string | undefined} */
   let classesFull
-  /** @type {string|undefined} */
+  /** @type {string | undefined} */
   let classes
-  /** @type {string|undefined} */
+  /** @type {string | undefined} */
   let id
   /** @type {string} */
   let key
@@ -359,9 +363,9 @@ function attributes(node, state) {
         id = shortcut.test(value) ? '#' + value : quoted('id', value)
       } else if (key === 'class') {
         const list = value.split(/[\t\n\r ]+/g)
-        /** @type {Array.<string>} */
+        /** @type {Array<string>} */
         const classesFullList = []
-        /** @type {Array.<string>} */
+        /** @type {Array<string>} */
         const classesList = []
         let index = -1
 
@@ -429,7 +433,20 @@ function fence(node) {
   let size = 0
 
   if (node.type === 'containerDirective') {
-    visitParents(node, 'containerDirective', onvisit)
+    visitParents(node, function (node, parents) {
+      if (node.type === 'containerDirective') {
+        let index = parents.length
+        let nesting = 0
+
+        while (index--) {
+          if (parents[index].type === 'containerDirective') {
+            nesting++
+          }
+        }
+
+        if (nesting > size) size = nesting
+      }
+    })
     size += 3
   } else if (node.type === 'leafDirective') {
     size = 2
@@ -438,18 +455,4 @@ function fence(node) {
   }
 
   return ':'.repeat(size)
-
-  /** @type {import('unist-util-visit-parents').BuildVisitor<Root, Directive>} */
-  function onvisit(_, parents) {
-    let index = parents.length
-    let nesting = 0
-
-    while (index--) {
-      if (parents[index].type === 'containerDirective') {
-        nesting++
-      }
-    }
-
-    if (nesting > size) size = nesting
-  }
 }

package.json

@@ -39,6 +39,7 @@
   "dependencies": {
     "@types/mdast": "^3.0.0",
     "@types/unist": "^2.0.0",
+    "mdast-util-from-markdown": "^1.3.0",
     "mdast-util-to-markdown": "^1.5.0",
     "parse-entities": "^4.0.0",
     "stringify-entities": "^4.0.0",