Add JSDoc based types

.gitignore

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

index.js

@@ -1,17 +1,38 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ *
+ * @typedef Options
+ *   Configuration.
+ * @property {boolean} [inlineNotes=false]
+ *   Whether to support `^[inline notes]`.
+ */
+
 import {footnote} from 'micromark-extension-footnote'
 import {footnoteFromMarkdown, footnoteToMarkdown} from 'mdast-util-footnote'
 
-export default function remarkFootnotes(options) {
+/**
+ * Plugin to add support for footnotes.
+ *
+ * @type {import('unified').Plugin<[Options?]|void[], Root>}
+ */
+export default function remarkFootnotes(options = {}) {
   const data = this.data()
 
   add('micromarkExtensions', footnote(options))
   add('fromMarkdownExtensions', footnoteFromMarkdown)
   add('toMarkdownExtensions', footnoteToMarkdown)
 
+  /**
+   * @param {string} field
+   * @param {unknown} value
+   */
   function add(field, value) {
-    // Other extensions.
-    /* c8 ignore next */
-    if (data[field]) data[field].push(value)
-    else data[field] = [value]
+    const list = /** @type {unknown[]} */ (
+      // Other extensions
+      /* c8 ignore next 2 */
+      data[field] ? data[field] : (data[field] = [])
+    )
+
+    list.push(value)
   }
 }

package.json

@@ -28,14 +28,19 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.0",
     "mdast-util-footnote": "^1.0.0",
-    "micromark-extension-footnote": "^1.0.0"
+    "micromark-extension-footnote": "^1.0.0",
+    "unified": "^10.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "dtslint": "^4.0.0",
     "prettier": "^2.0.0",
@@ -46,18 +51,21 @@
     "remark-preset-wooorm": "^8.0.0",
     "remark-rehype": "^8.0.0",
     "remark-stringify": "^10.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
     "to-vfile": "^7.0.0",
-    "unified": "^10.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 \"test/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test/index.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 test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -68,14 +76,17 @@
     "trailingComma": "none"
   },
   "xo": {
-    "prettier": true,
-    "ignore": [
-      "types/"
-    ]
+    "prettier": true
   },
   "remarkConfig": {
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

test/index.js

@@ -333,35 +333,41 @@ test('serialize', (t) => {
 
   t.equal(
     p.stringify(
-      u('footnote', [
-        u('text', 'Text with '),
-        u('emphasis', [u('text', 'markup')]),
-        u('text', '.')
+      u('root', [
+        u('footnote', [
+          u('text', 'Text with '),
+          u('emphasis', [u('text', 'markup')]),
+          u('text', '.')
+        ])
       ])
     ),
     '^[Text with *markup*.]\n',
     'should serialize a footnote'
   )
 
   t.equal(
-    p.stringify(u('footnoteReference', {identifier: 'a', label: 'A'})),
+    p.stringify(
+      u('root', [u('footnoteReference', {identifier: 'a', label: 'A'})])
+    ),
     '[^A]\n',
     'should serialize a footnote reference'
   )
 
   t.equal(
-    p.stringify(u('footnoteReference', {identifier: 'a'})),
+    p.stringify(u('root', [u('footnoteReference', {identifier: 'a'})])),
     '[^a]\n',
     'should serialize a footnote reference w/o label'
   )
 
   t.equal(
     p.stringify(
-      u('footnoteDefinition', {identifier: 'a', label: 'A'}, [
-        u('paragraph', [
-          u('text', 'Text with '),
-          u('emphasis', [u('text', 'markup')]),
-          u('text', '.')
+      u('root', [
+        u('footnoteDefinition', {identifier: 'a', label: 'A'}, [
+          u('paragraph', [
+            u('text', 'Text with '),
+            u('emphasis', [u('text', 'markup')]),
+            u('text', '.')
+          ])
         ])
       ])
     ),
@@ -371,11 +377,13 @@ test('serialize', (t) => {
 
   t.equal(
     p.stringify(
-      u('footnoteDefinition', {identifier: 'a'}, [
-        u('paragraph', [
-          u('text', 'Text with '),
-          u('emphasis', [u('text', 'markup')]),
-          u('text', '.')
+      u('root', [
+        u('footnoteDefinition', {identifier: 'a'}, [
+          u('paragraph', [
+            u('text', 'Text with '),
+            u('emphasis', [u('text', 'markup')]),
+            u('text', '.')
+          ])
         ])
       ])
     ),
@@ -385,10 +393,13 @@ test('serialize', (t) => {
 
   t.equal(
     p.stringify(
-      u('footnoteDefinition', {identifier: 'a'}, [
-        u('heading', {depth: 1}, [u('text', 'Heading')]),
-        u('blockquote', [u('paragraph', [u('text', 'Block quote.')])]),
-        u('code', 'console.log(1)\n\nconsole.log(2)')
+      // @ts-expect-error: TS can’t infer `depth`.
+      u('root', [
+        u('footnoteDefinition', {identifier: 'a'}, [
+          u('heading', {depth: 1}, [u('text', 'Heading')]),
+          u('blockquote', [u('paragraph', [u('text', 'Block quote.')])]),
+          u('code', 'console.log(1)\n\nconsole.log(2)')
+        ])
       ])
     ),
     '[^a]: # Heading\n\n    > Block quote.\n\n        console.log(1)\n\n        console.log(2)\n',
@@ -469,13 +480,14 @@ test('fixtures', (t) => {
       .use(remarkParse)
       .use(remarkStringify)
       .use(remarkFootnotes, {inlineNotes: true})
+    /** @type {string|undefined} */
     let expected
 
     const tree = processor.parse(input)
 
     try {
       expected = JSON.parse(
-        readSync({dirname: base, basename: name, extname: '.json'})
+        String(readSync({dirname: base, basename: name, extname: '.json'}))
       )
     } catch {}
 

tsconfig.json

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