Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,2 +1,3 @@
+*.d.ts
 coverage/
 node_modules/

.prettierignore

@@ -1,3 +1,2 @@
 coverage/
-*.json
 *.md

index.js

@@ -1,42 +1,87 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Parent} Parent
+ *
+ * @typedef {import('unist-util-is').Type} Type
+ * @typedef {import('unist-util-is').Props} Props
+ * @typedef {import('unist-util-is').TestFunctionAnything} TestFunctionAnything
+ */
+
+/**
+ * @typedef {Object} RemoveOptions
+ * @property {boolean} [cascade] Whether to drop parent nodes if they had children, but all their children were filtered out test
+ */
+
 import {convert} from 'unist-util-is'
 
-export function remove(tree, options, test) {
-  var is = convert(test || options)
-  var cascade =
-    options.cascade === undefined || options.cascade === null
-      ? true
-      : options.cascade
+/** @type {Array.<Node>} */
+var empty = []
 
-  return preorder(tree, null, null)
+export var remove =
+  /**
+   * @type {(
+   *  (<T extends Node>(node: T, options: RemoveOptions, test: Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>) => T|null) &
+   *  (<T extends Node>(node: T, test: Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>) => T|null)
+   * )}
+   */
+  (
+    /**
+     * Mutate 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 {Node} tree Tree to filter
+     * @param {RemoveOptions} options Whether to drop parent nodes if they had children, but all their children were filtered out. Default is `{cascade: true}`
+     * @param {Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>} test is-compatible test (such as a type)
+     * @returns {Node|null}
+     */
+    function (tree, options, test) {
+      var is = convert(test || options)
+      var cascade =
+        options.cascade === undefined || options.cascade === null
+          ? true
+          : options.cascade
 
-  // Check and remove nodes recursively in preorder.
-  // For each composite node, modify its children array in-place.
-  function preorder(node, index, parent) {
-    var children = node.children
-    var childIndex = -1
-    var position = 0
+      return preorder(tree, null, null)
 
-    if (is(node, index, parent)) {
-      return null
-    }
+      /**
+       * Check and remove nodes recursively in preorder.
+       * For each composite node, modify its children array in-place.
+       *
+       * @param {Node} node
+       * @param {number|null} index
+       * @param {Parent|null} parent
+       * @returns {Node|null}
+       */
+      function preorder(node, index, parent) {
+        /** @type {Array.<Node>} */
+        // @ts-ignore looks like a parent.
+        var children = node.children || empty
+        var childIndex = -1
+        var position = 0
 
-    if (children && children.length > 0) {
-      // Move all living children to the beginning of the children array.
-      while (++childIndex < children.length) {
-        if (preorder(children[childIndex], childIndex, node)) {
-          children[position++] = children[childIndex]
+        if (is(node, index, parent)) {
+          return null
         }
-      }
 
-      // Cascade delete.
-      if (cascade && !position) {
-        return null
-      }
+        if (children.length > 0) {
+          // Move all living children to the beginning of the children array.
+          while (++childIndex < children.length) {
+            // @ts-ignore looks like a parent.
+            if (preorder(children[childIndex], childIndex, node)) {
+              children[position++] = children[childIndex]
+            }
+          }
 
-      // Drop other nodes.
-      children.length = position
-    }
+          // Cascade delete.
+          if (cascade && !position) {
+            return null
+          }
+
+          // Drop other nodes.
+          children.length = position
+        }
 
-    return node
-  }
-}
+        return node
+      }
+    }
+  )

package.json

@@ -32,31 +32,36 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
-  "types": "types/index.d.ts",
+  "types": "index.d.ts",
   "files": [
-    "index.js",
-    "types/index.d.ts"
+    "index.d.ts",
+    "index.js"
   ],
   "dependencies": {
+    "@types/unist": "^2.0.0",
     "unist-util-is": "^5.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
-    "dtslint": "^4.0.0",
-    "nyc": "^15.0.0",
     "prettier": "^2.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "unist-builder": "^3.0.0",
     "xo": "^0.38.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
     "test-types": "dtslint types",
-    "test": "npm run format && npm run test-coverage && npm run test-types"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -69,6 +74,7 @@
   "xo": {
     "prettier": true,
     "rules": {
+      "import/no-mutable-exports": "off",
       "no-var": "off",
       "prefer-arrow-callback": "off"
     }
@@ -77,5 +83,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

readme.md

@@ -63,7 +63,7 @@ Yields: (note the parent of `5` is also removed, due to `options.cascade`)
 This package exports the following identifiers: `remove`.
 There is no default export.
 
-### `remove(tree[, options][, test])`
+### `remove(tree[, options], test)`
 
 Mutate the given [tree][] by removing all nodes that pass `test`.
 The tree is walked in [preorder][] (NLR), visiting the node itself, then its
@@ -76,8 +76,7 @@ The tree is walked in [preorder][] (NLR), visiting the node itself, then its
 *   `options.cascade` (`boolean`, default: `true`)
     — Whether to drop parent nodes if they had children, but all their children
     were filtered out
-*   `test` ([`Test`][is], optional) — [`is`][is]-compatible test (such as a
-    [type][])
+*   `test` ([`Test`][is]) — [`is`][is]-compatible test (such as a [type][])
 
 ###### Returns
 

test.js

@@ -1,3 +1,12 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Parent} Parent
+ *
+ * @typedef {import('unist-util-is').Type} Type
+ * @typedef {import('unist-util-is').Props} Props
+ * @typedef {import('unist-util-is').TestFunctionAnything} TestFunctionAnything
+ */
+
 import test from 'tape'
 import {u} from 'unist-builder'
 import {remove} from './index.js'
@@ -32,6 +41,10 @@ test('should remove nodes with children', function (t) {
 
   t.end()
 
+  /**
+   * @param {Node} node
+   * @returns {boolean}
+   */
   function test(node) {
     return node === first
   }
@@ -48,6 +61,7 @@ test('should return `null` if root node is removed', function (t) {
 test('should cascade-remove parent nodes', function (t) {
   var tree = u('root', [u('node', [u('leaf', '1')]), u('leaf', '2')])
   var children = tree.children
+  // @ts-ignore it exists!
   var first = children[0].children[0]
   var last = children[1]
 
@@ -60,6 +74,10 @@ test('should cascade-remove parent nodes', function (t) {
 
   t.end()
 
+  /**
+   * @param {Node} node
+   * @returns {boolean}
+   */
   function test(node) {
     return node === first
   }
@@ -104,6 +122,10 @@ test('should support function tests', function (t) {
 
   t.end()
 
+  /**
+   * @param {Node} node
+   * @returns {boolean}
+   */
   function test(node) {
     return node.value === '1'
   }
@@ -123,6 +145,7 @@ test('opts.cascade = false', function (t) {
   var tree = u('root', [u('node', [u('leaf', '1')]), u('leaf', '2')])
   var siblings = tree.children
   var node = siblings[0]
+  // @ts-ignore it exists!
   var children = node.children
 
   var next = remove(tree, {cascade: false}, 'leaf')
@@ -131,6 +154,7 @@ test('opts.cascade = false', function (t) {
   t.deepEqual(tree, u('root', [u('node', [])]))
   t.equal(tree.children, siblings)
   t.equal(tree.children[0], node)
+  // @ts-ignore it exists!
   t.equal(tree.children[0].children, children)
 
   t.end()

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": ["*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}