Refactor code-style

Author: wooorm

lib/index.js

@@ -2,100 +2,105 @@
  * @typedef {import('unist').Node} Node
  * @typedef {import('unist').Parent} Parent
  * @typedef {import('unist-util-is').Test} Test
- *
+ */
+
+/**
  * @typedef Options
  *   Configuration.
  * @property {boolean | null | undefined} [cascade=true]
  *   Whether to drop parent nodes if they had children, but all their children
- *   were filtered out.
+ *   were filtered out (default: `true`).
  */
 
 import {convert} from 'unist-util-is'
 
-/** @type {Array<unknown>} */
-const empty = []
-
 /**
  * Change the given `tree` by removing all nodes that pass `test`.
  *
  * The tree is walked in preorder (NLR), visiting the node itself, then its
  * head, etc.
  *
- * @param tree
+ * @template {Node} Tree
+ *   Node kind.
+ *
+ * @overload
+ * @param {Tree} node
+ * @param {Test} [test]
+ * @returns {Tree | undefined}
+ *
+ * @overload
+ * @param {Tree} node
+ * @param {Options | null | undefined} options
+ * @param {Test} [test]
+ * @returns {Tree | undefined}
+ *
+ * @param {Tree} tree
  *   Tree to change.
- * @param options
+ * @param {Options | Test} options
  *   Configuration (optional).
- * @param test
+ * @param {Test} [test]
  *   `unist-util-is` compatible test.
- * @returns
+ * @returns {Tree | undefined}
  *   The given `tree` without nodes that pass `test`.
  *
- *   `null` is returned if `tree` itself didn’t pass the test or is cascaded
- *   away.
+ *   `undefined` is returned if `tree` itself didn’t pass the test or is
+ *   cascaded away.
  */
 // To do: next major: don’t return `tree`.
-export const remove =
-  /**
-   * @type {(
-   *  (<Tree extends Node>(node: Tree, options: Options, test: Test) => Tree | null) &
-   *  (<Tree extends Node>(node: Tree, test: Test) => Tree | null)
-   * )}
-   */
-  (
-    /**
-     * @param {Node} tree
-     * @param {Options | null | undefined} [options]
-     * @param {Test | null | undefined} [test]
-     * @returns {Node | null}
-     */
-    function (tree, options, test) {
-      const is = convert(test || options)
-      const cascade =
-        !options || options.cascade === undefined || options.cascade === null
-          ? true
-          : options.cascade
+export function remove(tree, options, test) {
+  const is = convert(test || options)
+  let cascade = true
 
-      return preorder(tree)
+  if (
+    options &&
+    typeof options === 'object' &&
+    'cascade' in options &&
+    typeof options.cascade === 'boolean'
+  ) {
+    cascade = options.cascade
+  }
 
-      /**
-       * Check and remove nodes recursively in preorder.
-       * For each composite node, modify its children array in-place.
-       *
-       * @param {Node} node
-       * @param {number | null | undefined} [index]
-       * @param {Parent | null | undefined} [parent]
-       * @returns {Node | null}
-       */
-      function preorder(node, index, parent) {
-        /** @type {Array<Node>} */
-        // @ts-expect-error looks like a parent.
-        const children = node.children || empty
-        let childIndex = -1
-        let position = 0
+  return preorder(tree)
 
-        if (is(node, index, parent)) {
-          return null
-        }
+  /**
+   * Check and remove nodes recursively in preorder.
+   * For each composite node, modify its children array in-place.
+   *
+   * @template {Node} Kind
+   * @param {Kind} node
+   * @param {number | undefined} [index]
+   * @param {Parent | undefined} [parent]
+   * @returns {Kind | undefined}
+   */
+  function preorder(node, index, parent) {
+    if (is(node, index, parent)) {
+      return undefined
+    }
 
-        if (children.length > 0) {
-          // Move all living children to the beginning of the children array.
-          while (++childIndex < children.length) {
-            // @ts-expect-error looks like a parent.
-            if (preorder(children[childIndex], childIndex, node)) {
-              children[position++] = children[childIndex]
-            }
-          }
+    if ('children' in node && Array.isArray(node.children)) {
+      const nodeAsParent = /** @type {Parent} */ (node)
+      const children = nodeAsParent.children
+      let oldChildIndex = -1
+      let newChildIndex = 0
 
-          // Cascade delete.
-          if (cascade && !position) {
-            return null
+      if (children.length > 0) {
+        // Move all living children to the beginning of the children array.
+        while (++oldChildIndex < children.length) {
+          if (preorder(children[oldChildIndex], oldChildIndex, nodeAsParent)) {
+            children[newChildIndex++] = children[oldChildIndex]
           }
+        }
 
-          // Drop other nodes.
-          children.length = position
+        // Cascade delete.
+        if (cascade && !newChildIndex) {
+          return undefined
         }
 
-        return node
+        // Drop other nodes.
+        children.length = newChildIndex
       }
     }
-  )
+
+    return node
+  }
+}

readme.md

@@ -83,7 +83,7 @@ const tree = u('root', [
 // Remove all nodes of type `leaf`.
 remove(tree, 'leaf')
 
-console.dir(tree, {depth: null})
+console.dir(tree, {depth: undefined})
 ```
 
 Yields:
@@ -128,7 +128,8 @@ head, etc.
 
 A changed given `tree`, without nodes that pass `test`.
 
-`null` is returned if `tree` itself didn’t pass the test or is cascaded away.
+`undefined` is returned if `tree` itself didn’t pass the test or is cascaded
+away.
 
 ### `Options`