Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null`, `undefined` in result

Author: wooorm

lib/index.js

@@ -1,28 +1,38 @@
 /**
- * @typedef {import('mdast').Root|import('mdast').Content} Node
- * @typedef {Extract<Node, import('mdast').Parent>} Parent
+ * @typedef {import('mdast').Parent} MdastParent
+ * @typedef {import('mdast').Content} Content
+ * @typedef {import('mdast').Root} Root
+ */
+
+/**
+ * @typedef {Root | Content} Node
+ * @typedef {Extract<Node, MdastParent>} Parent
  *
  * @typedef ZoneInfo
  *   Extra info.
  * @property {Parent} parent
- *   Parent of the range.
+ *   Parent of the section.
  * @property {number} start
- *   Index of `start` in `parent`
+ *   Index of `start` in `parent`.
  * @property {number} end
- *   Index of `end` in `parent`
+ *   Index of `end` in `parent`.
  *
  * @callback Handler
- *   Callback called when a range is found.
+ *   Callback called when a section is found.
  * @param {Node} start
- *   Start of range.
+ *   Start of section.
  * @param {Array<Node>} between
  *   Nodes between `start` and `end`.
  * @param {Node} end
- *   End of range.
+ *   End of section.
  * @param {ZoneInfo} info
  *   Extra info.
- * @returns {Array<Node>|null|undefined|void}
- *   Nodes to replace.
+ * @returns {Array<Node | null | undefined> | null | undefined | void}
+ *   Results.
+ *
+ *   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.
  */
 
 import {commentMarker} from 'mdast-comment-marker'
@@ -37,59 +47,64 @@ import {visit} from 'unist-util-visit'
  *   Callback called when a range is found.
  */
 export function zone(node, name, callback) {
-  /** @type {number|undefined} */
+  /** @type {number | undefined} */
   let level
-  /** @type {Node|undefined} */
+  /** @type {Node | undefined} */
   let marker
-  /** @type {Parent|undefined} */
+  /** @type {Parent | undefined} */
   let scope
 
-  visit(
-    node,
-    /**
-     * Gather one dimensional zones.
-     */
-    (node, index, parent) => {
-      const info = commentMarker(node)
-      const match =
-        info && info.name === name && info.attributes.match(/(start|end)\b/)
-      const type = match && match[0]
+  visit(node, (node, index, parent) => {
+    const info = commentMarker(node)
+    const match =
+      info && info.name === name ? info.attributes.match(/(start|end)\b/) : null
+    const type = match ? match[0] : undefined
 
-      if (parent && index !== null && type) {
-        if (!scope && type === 'start') {
-          level = 0
-          marker = node
-          scope = /** @type {Parent} */ (parent)
+    if (parent && index !== null && type) {
+      if (!scope && type === 'start') {
+        level = 0
+        marker = node
+        scope = parent
+      }
+
+      if (typeof level === 'number' && marker && scope && parent === scope) {
+        if (type === 'start') {
+          level++
+        } else {
+          level--
         }
 
-        if (typeof level === 'number' && marker && scope && parent === scope) {
-          if (type === 'start') {
-            level++
-          } else {
-            level--
-          }
+        if (type === 'end' && !level) {
+          // @ts-expect-error: Assume `scope` is a valid parent of `node`.
+          const start = scope.children.indexOf(marker)
 
-          if (type === 'end' && !level) {
-            // @ts-expect-error: Assume `scope` is a valid parent of `node`.
-            const start = scope.children.indexOf(marker)
+          const nodes = callback(
+            marker,
+            scope.children.slice(start + 1, index),
+            node,
+            {start, end: index, parent: scope}
+          )
 
-            const result = callback(
-              marker,
-              scope.children.slice(start + 1, index),
-              node,
-              {start, end: index, parent: scope}
-            )
+          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>} */
+            const result = []
+            let offset = -1
 
-            if (result) {
-              // @ts-expect-error: Assume the correct children are passed.
-              scope.children.splice(start, index - start + 1, ...result)
+            while (++offset < nodes.length) {
+              const node = nodes[offset]
+              if (node) result.push(node)
             }
 
-            marker = undefined
-            scope = undefined
+            // @ts-expect-error: Assume the correct children are passed.
+            scope.children.splice(start, index - start + 1, ...result)
           }
+
+          marker = undefined
+          scope = undefined
         }
       }
     }
-  )
+  })
 }

package.json

@@ -73,6 +73,7 @@
   "xo": {
     "prettier": true,
     "rules": {
+      "max-depth": "off",
       "capitalized-comments": "off"
     }
   },