Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,25 +1,48 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist-util-visit').Type} Type
+ * @typedef {import('unist-util-visit').Props} Props
+ * @typedef {import('unist-util-visit').TestFunctionAnything} TestFunctionAnything
+ *
+ * @typedef {(node: Node) => unknown} KeyFunction
+ */
+
 import {visit} from 'unist-util-visit'
 
 export class Index {
-  constructor(prop, tree, filter) {
-    if (filter === null || filter === undefined) {
-      filter = trueConst
-    }
-
+  /**
+   * @param {string|KeyFunction} prop
+   * @param {Node} [tree]
+   * @param {null|undefined|Type|Props|TestFunctionAnything|Array<Type|Props|TestFunctionAnything>} [test]
+   */
+  constructor(prop, tree, test) {
+    /** @type {Map.<unknown, Array.<Node>>} */
     this.index = new Map()
-    this.keyfn = typeof prop === 'string' ? (node) => node[prop] : prop
+    /** @type {KeyFunction} */
+    this.key =
+      typeof prop === 'string' ? (/** @type {Node} */ node) => node[prop] : prop
 
     if (tree) {
-      visit(tree, filter, (node) => this.add(node))
+      visit(tree, test, (/** @type {Node} */ node) => {
+        this.add(node)
+      })
     }
   }
 
+  /**
+   * @param {unknown} key
+   * @returns {Array.<Node>}
+   */
   get(key) {
     return this.index.get(key) || []
   }
 
+  /**
+   * @param {Node} node
+   */
   add(node) {
-    var key = this.keyfn(node)
+    var key = this.key(node)
+    /** @type {Array.<Node>} */
     var nodes
 
     if (!this.index.has(key)) {
@@ -35,8 +58,11 @@ export class Index {
     return this
   }
 
+  /**
+   * @param {Node} node
+   */
   remove(node) {
-    var key = this.keyfn(node)
+    var key = this.key(node)
     var nodes = this.index.get(key)
     var pos = nodes ? nodes.indexOf(node) : -1
 
@@ -47,7 +73,3 @@ export class Index {
     return this
   }
 }
-
-function trueConst() {
-  return true
-}

package.json

@@ -35,27 +35,36 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/unist": "^2.0.3",
     "unist-util-visit": "^3.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.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",
     "unist-util-select": "^4.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": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -76,5 +85,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('./index.js').KeyFunction} KeyFunction
+ * @typedef {import('./index.js').TestFunctionAnything} TestFunctionAnything
+ */
+
 import test from 'tape'
 import {u} from 'unist-builder'
 import {select} from 'unist-util-select'
@@ -43,10 +48,12 @@ test('Index', function (t) {
 
   t.end()
 
+  /** @type {KeyFunction} */
   function keyFn(node) {
     return node.id
   }
 
+  /** @type {TestFunctionAnything} */
   function filter(node) {
     return node.type === 'a'
   }
@@ -193,6 +200,7 @@ test('index.get', function (t) {
       sst.deepEqual(index.get('bar'), [select('node[word="bar"]', ast)])
       sst.end()
 
+      /** @type {TestFunctionAnything} */
       function filter(node, index, parent) {
         return 'word' in node && index < 2 && parent.type === 'root'
       }
@@ -202,15 +210,18 @@ test('index.get', function (t) {
   })
 
   t.test('computed keys', function (st) {
+    /**
+     * @typedef {{x: number, y: number, z: number}} FunkyNode
+     */
+
     var ast = u('root', {x: 0, y: 4, id: 0}, [
       u('node', {x: 3, y: 2, id: 1}),
       u('node', {x: 2, y: 2, id: 2}),
       u('node', {x: 3, y: 1, id: 3}),
       u('node', {x: 4, y: 1, id: 4})
     ])
-    var index
-
-    index = new Index(xPlusY, ast)
+    // @ts-ignore it’s fine
+    var index = new Index(xPlusY, ast)
     st.deepEqual(index.get(4), [
       select('[id=0]', ast),
       select('[id=2]', ast),
@@ -219,13 +230,17 @@ test('index.get', function (t) {
     st.deepEqual(index.get(0), [])
     st.deepEqual(index.get(5), [select('[id=1]', ast), select('[id=4]', ast)])
 
+    // @ts-ignore it’s fine
     st.deepEqual(new Index(xPlusY, ast, 'node').get(4), [
       select('[id=2]', ast),
       select('[id=3]', ast)
     ])
 
     st.end()
 
+    /**
+     * @param {FunkyNode} node
+     */
     function xPlusY(node) {
       return node.x + node.y
     }

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
+  }
+}