Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,20 +1,31 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('hast').Properties} Properties
+ */
+
 import {toString} from 'mdast-util-to-string'
 import {visit} from 'unist-util-visit'
 import BananaSlug from 'github-slugger'
 
 const slugs = new BananaSlug()
 
-// Patch slugs on heading nodes.
+/**
+ * Plugin to add anchors headings using GitHub’s algorithm.
+ *
+ * @type {import('unified').Plugin<void[], Root>}
+ */
 export default function remarkSlug() {
-  return (ast) => {
+  return (tree) => {
     slugs.reset()
 
-    visit(ast, 'heading', (node) => {
+    visit(tree, 'heading', (node) => {
       const data = node.data || (node.data = {})
-      const props = data.hProperties || (data.hProperties = {})
+      const props = /** @type {Properties} */ (
+        data.hProperties || (data.hProperties = {})
+      )
       let id = props.id
 
-      id = id ? slugs.slug(id, true) : slugs.slug(toString(node))
+      id = id ? slugs.slug(String(id), true) : slugs.slug(toString(node))
 
       data.id = id
       props.id = id

package.json

@@ -30,30 +30,41 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/hast": "^2.3.2",
+    "@types/mdast": "^3.0.0",
     "github-slugger": "^1.0.0",
     "mdast-util-to-string": "^3.0.0",
+    "unified": "^10.0.0",
     "unist-util-visit": "^4.0.0"
   },
   "devDependencies": {
+    "@types/github-slugger": "^1.3.0",
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",
     "remark": "^14.0.0",
     "remark-cli": "^10.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-remove-position": "^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": "npm run format && npm run build && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -64,14 +75,17 @@
     "trailingComma": "none"
   },
   "xo": {
-    "prettier": true,
-    "ignores": [
-      "types/index.d.ts"
-    ]
+    "prettier": true
   },
   "remarkConfig": {
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

test.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ */
+
 import test from 'tape'
 import {remark} from 'remark'
 import {u} from 'unist-builder'
@@ -215,6 +219,10 @@ test('remarkSlug', (t) => {
   t.end()
 })
 
+/**
+ * @param {string|null} label
+ * @param {string} id
+ */
 function heading(label, id) {
   return u(
     'heading',
@@ -223,7 +231,11 @@ function heading(label, id) {
   )
 }
 
-function process(doc, options) {
-  const processor = remark().use(remarkSlug, options)
+/**
+ * @param {string} doc
+ * @returns {Root}
+ */
+function process(doc) {
+  const processor = remark().use(remarkSlug)
   return removePosition(processor.runSync(processor.parse(doc)), true)
 }

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