Refactor code-style

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

Author: wooorm

lib/index.js

@@ -5,7 +5,7 @@
  *
  * @typedef Options
  *   Configuration (optional).
- * @property {boolean} [cascade=true]
+ * @property {boolean | null | undefined} [cascade=true]
  *   Whether to drop parent nodes if they had children, but all their children
  *   were filtered out.
  */
@@ -27,59 +27,61 @@ const own = {}.hasOwnProperty
  *   `unist-util-is`-compatible test (such as a type).
  * @returns
  *   New filtered tree.
+ *
  *   `null` is returned if `tree` itself didn’t pass the test, or is cascaded
  *   away.
  */
 export const filter =
   /**
    * @type {(
-   *  (<Tree extends Node, Check extends Test>(node: Tree, options: Options, test: Check) => import('../complex-types.js').Matches<Tree, Check>) &
+   *  (<Tree extends Node, Check extends Test>(node: Tree, options: Options | null | undefined, test: Check) => import('../complex-types.js').Matches<Tree, Check>) &
    *  (<Tree extends Node, Check extends Test>(node: Tree, test: Check) => import('../complex-types.js').Matches<Tree, Check>) &
-   *  (<Tree extends Node>(node: Tree, options?: Options) => Tree)
+   *  (<Tree extends Node>(node: Tree, options?: Options | null | undefined) => Tree)
    * )}
    */
   (
     /**
      * @param {Node} tree
-     * @param {Options} options
-     * @param {Test} test
-     * @returns {Node|null}
+     * @param {Options | Test | null | undefined} [options]
+     * @param {Test | null | undefined} [test]
+     * @returns {Node | null}
      */
     function (tree, options, test) {
       const is = convert(test || options)
+      /** @type {boolean | null | undefined} */
+      const cascadeRaw =
+        options && typeof options === 'object' && 'cascade' in options
+          ? /** @type {boolean | null | undefined} */ (options.cascade)
+          : undefined
       const cascade =
-        options.cascade === undefined || options.cascade === null
-          ? true
-          : options.cascade
+        cascadeRaw === undefined || cascadeRaw === null ? true : cascadeRaw
 
       return preorder(tree)
 
       /**
        * @param {Node} node
-       * @param {number|undefined} [index]
-       * @param {Parent|undefined} [parent]
-       * @returns {Node|null}
+       *   Current node.
+       * @param {number | undefined} [index]
+       *   Index of `node` in `parent`.
+       * @param {Parent | undefined} [parent]
+       *   Parent node.
+       * @returns {Node | null}
+       *   Shallow copy of `node`.
        */
       function preorder(node, index, parent) {
         /** @type {Array<Node>} */
         const children = []
-        /** @type {number} */
-        let childIndex
-        /** @type {Node} */
-        let result
-        /** @type {string} */
-        let key
 
         if (!is(node, index, parent)) return null
 
         // @ts-expect-error: Looks like a parent.
         if (node.children) {
-          childIndex = -1
+          let childIndex = -1
 
           // @ts-expect-error Looks like a parent.
           while (++childIndex < node.children.length) {
             // @ts-expect-error Looks like a parent.
-            result = preorder(node.children[childIndex], childIndex, node)
+            const result = preorder(node.children[childIndex], childIndex, node)
 
             if (result) {
               children.push(result)
@@ -95,6 +97,8 @@ export const filter =
         /** @type {typeof node} */
         // @ts-expect-error all the fields will be copied over.
         const next = {}
+        /** @type {string} */
+        let key
 
         for (key in node) {
           if (own.call(node, key)) {