Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,3 +1,5 @@
 .DS_Store
+*.d.ts
+*.log
 node_modules/
 coverage/

index.js

@@ -1,50 +1,100 @@
 import {convert} from 'unist-util-is'
 
+/**
+ * @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
+ */
+
+/**
+ * Options for unist util filter
+ *
+ * @typedef {Object} FilterOptions
+ * @property {boolean} [cascade=true] Whether to drop parent nodes if they had children, but all their children were filtered out.
+ */
+
 var own = {}.hasOwnProperty
 
-export function filter(tree, options, test) {
-  var is = convert(test || options)
-  var cascade =
-    options.cascade === undefined || options.cascade === null
-      ? true
-      : options.cascade
+export const filter =
+  /**
+   * @type {(
+   *  (<T extends Node>(node: Node, options: FilterOptions, test: T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>|Array.<T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>>) => T|null) &
+   *  (<T extends Node>(node: Node, test: T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>|Array.<T['type']|Partial<T>|import('unist-util-is').TestFunctionPredicate<T>>) => T|null) &
+   *  ((node: Node, options: FilterOptions, test?: null|undefined|Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>) => Node|null) &
+   *  ((node: Node, test?: null|undefined|Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>) => Node|null)
+   * )}
+   */
+  (
+    /**
+     * Create a new tree consisting of copies of 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 {FilterOptions} options
+     * @param {null|undefined|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
 
-  return preorder(tree, null, null)
+      return preorder(tree)
 
-  function preorder(node, index, parent) {
-    var children
-    var childIndex
-    var result
-    var next
-    var key
+      /**
+       * @param {Node} node
+       * @param {number|undefined} [index]
+       * @param {Parent|undefined} [parent]
+       * @returns {Node|null}
+       */
+      function preorder(node, index, parent) {
+        /** @type {Array.<Node>} */
+        var children = []
+        /** @type {number} */
+        var childIndex
+        /** @type {Node} */
+        var result
+        /** @type {typeof node} */
+        var next
+        /** @type {string} */
+        var key
 
-    if (!is(node, index, parent)) return null
+        if (!is(node, index, parent)) return null
 
-    if (node.children) {
-      children = []
-      childIndex = -1
+        if (node.children) {
+          childIndex = -1
 
-      while (++childIndex < node.children.length) {
-        result = preorder(node.children[childIndex], childIndex, node)
+          // @ts-ignore Looks like a parent.
+          while (++childIndex < node.children.length) {
+            // @ts-ignore Looks like a parent.
+            result = preorder(node.children[childIndex], childIndex, node)
 
-        if (result) {
-          children.push(result)
+            if (result) {
+              children.push(result)
+            }
+          }
+
+          // @ts-ignore Looks like a parent.
+          if (cascade && node.children.length && !children.length) return null
         }
-      }
 
-      if (cascade && node.children.length && !children.length) return null
-    }
+        // Create a shallow clone, using the new children.
+        // @ts-ignore all the fields will be copied over.
+        next = {}
 
-    // Create a shallow clone, using the new children.
-    next = {}
+        for (key in node) {
+          /* istanbul ignore else - Prototype injection. */
+          if (own.call(node, key)) {
+            next[key] = key === 'children' ? children : node[key]
+          }
+        }
 
-    for (key in node) {
-      /* istanbul ignore else - Prototype injection. */
-      if (own.call(node, key)) {
-        next[key] = key === 'children' ? children : node[key]
+        return next
       }
     }
-
-    return next
-  }
-}
+  )

index.test-d.ts

@@ -0,0 +1,13 @@
+import {Node} from 'unist'
+import {expectType, expectError} from 'tsd'
+import {filter} from './index.js'
+import {Heading} from 'mdast'
+
+expectError(filter())
+expectType<Node | null>(filter({type: 'root'}))
+expectType<Node | null>(filter({type: 'root'}, 'root'))
+expectType<Node | null>(filter({type: 'root'}, {}, 'root'))
+expectError(filter({type: 'root'}, {notAnOption: true}, 'root'))
+expectType<Node | null>(filter({type: 'root'}, {cascade: false}, 'root'))
+expectType<Heading | null>(filter<Heading>({type: 'root'}, 'heading'))
+expectError(filter<Heading>({type: 'root'}, 'notAHeading'))

package.json

@@ -27,31 +27,37 @@
   "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/mdast": "^3.0.0",
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
-    "dtslint": "^4.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",
+    "tsd": "^0.14.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 && tsd && 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,
@@ -73,5 +79,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Parent} Parent
+ */
+
 import test from 'tape'
 import {u} from 'unist-builder'
 import {filter} from './index.js'
@@ -11,6 +16,9 @@ test('should not traverse into children of filtered out nodes', function (t) {
 
   t.end()
 
+  /**
+   * @param {Node} node
+   */
   function predicate(node) {
     types[node.type] = (types[node.type] || 0) + 1
     return node.type !== 'node'
@@ -37,10 +45,16 @@ test('should cascade-remove parent nodes', function (t) {
 
   t.end()
 
+  /**
+   * @param {Node} node
+   */
   function notOne(node) {
     return node.value !== '1'
   }
 
+  /**
+   * @param {Node} node
+   */
   function notLeaf(node) {
     return node.type !== 'leaf'
   }
@@ -56,13 +70,15 @@ test('should not cascade-remove nodes that were empty initially', function (t) {
 
 test('should call iterator with `index` and `parent` args', function (t) {
   var tree = u('root', [u('node', [u('leaf', '1')]), u('leaf', '2')])
+  /** @type {Array.<[Node, number|undefined, Parent|undefined]>} */
   var callLog = []
 
   t.deepEqual(filter(tree, predicate), tree)
 
   t.deepEqual(callLog, [
-    [tree, null, null],
+    [tree, undefined, undefined],
     [tree.children[0], 0, tree],
+    // @ts-ignore yeah, it exists.
     [tree.children[0].children[0], 0, tree.children[0]],
     [tree.children[1], 1, tree]
   ])
@@ -105,6 +121,9 @@ test('opts.cascade', function (t) {
 
   t.end()
 
+  /**
+   * @param {Node} node
+   */
   function predicate(node) {
     return node.type !== 'leaf'
   }
@@ -125,6 +144,9 @@ test('example from README', function (t) {
 
   t.end()
 
+  /**
+   * @param {Node} node
+   */
   function predicate(node) {
     return node.type !== 'leaf' || Number(node.value) % 2 === 0
   }

tsconfig.json

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