Add JSDoc based types

.gitignore

@@ -1,5 +1,6 @@
 coverage/
 node_modules/
 .DS_Store
+*.d.ts
 *.log
 yarn.lock

index.js

@@ -1,39 +1,61 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('hast').Root} HastRoot
+ * @typedef {import('mdast').Root} MdastRoot
+ * @typedef {import('mdast-util-to-hast').Options} Options
+ * @typedef {import('unified').Processor<any, any, any, any>} Processor
+ */
+
 import {toHast} from 'mdast-util-to-hast'
 
-// Attacher.
-// If a destination is given, runs the destination with the new hast tree
-// (bridge mode).
-// Without destination, returns the tree: further plugins run on that tree
-// (mutate mode).
-export default function remarkRehype(destination, options) {
-  if (destination && !destination.process) {
-    options = destination
-    destination = null
-  }
+// Note: the `<MdastRoot, HastRoot>` overload doesn’t seem to work :'(
 
-  return destination ? bridge(destination, options) : mutate(options)
-}
-
-// Bridge mode.
-// Runs the destination with the new hast tree.
-function bridge(destination, options) {
-  return transformer
+/**
+ * Plugin to bridge or mutate to rehype.
+ *
+ * If a destination is given, runs the destination with the new hast tree
+ * (bridge-mode).
+ * Without destination, returns the hast tree: further plugins run on that tree
+ * (mutate-mode).
+ *
+ * @param destination
+ *   Optional unified processor.
+ * @param options
+ *   Options passed to `mdast-util-to-hast`.
+ */
+const remarkRehype =
+  /** @type {(import('unified').Plugin<[Processor, Options?]|[Options]|[], MdastRoot>)} */
+  (
+    function (destination, options) {
+      return destination && 'run' in destination
+        ? bridge(destination, options)
+        : mutate(destination)
+    }
+  )
 
-  function transformer(node, file, next) {
-    destination.run(toHast(node, options), file, done)
+export default remarkRehype
 
-    function done(error) {
+/**
+ * Bridge-mode.
+ * Runs the destination with the new hast tree.
+ *
+ * @type {import('unified').Plugin<[Processor, Options?], MdastRoot>}
+ */
+function bridge(destination, options) {
+  return (node, file, next) => {
+    destination.run(toHast(node, options), file, (error) => {
       next(error)
-    }
+    })
   }
 }
 
-// Mutate-mode.
-// Further transformers run on the hast tree.
+/**
+ * Mutate-mode.
+ * Further transformers run on the nlcst tree.
+ *
+ * @type {import('unified').Plugin<[Options?]|void[], MdastRoot, HastRoot>}
+ */
 function mutate(options) {
-  return transformer
-
-  function transformer(node) {
-    return toHast(node, options)
-  }
+  // @ts-expect-error: assume a corresponding node is returned for `toHast`.
+  return (node) => toHast(node, options)
 }

package.json

@@ -29,30 +29,39 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
-    "mdast-util-to-hast": "^11.0.0"
+    "@types/hast": "^2.0.0",
+    "@types/mdast": "^3.0.0",
+    "mdast-util-to-hast": "^11.0.0",
+    "unified": "^10.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",
     "rehype-stringify": "^9.0.0",
     "remark-cli": "^10.0.0",
     "remark-parse": "^10.0.0",
     "remark-preset-wooorm": "^8.0.0",
     "remark-stringify": "^10.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
-    "unified": "^10.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov npm run test-api",
     "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,
@@ -63,14 +72,22 @@
     "trailingComma": "none"
   },
   "xo": {
-    "prettier": true,
-    "ignores": [
-      "types/"
-    ]
+    "prettier": true
   },
   "remarkConfig": {
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true,
+    "#": "needed `any`s",
+    "ignoreFiles": [
+      "index.d.ts",
+      "index.js"
+    ]
   }
 }

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,
+    "strict": true
+  }
+}