Add JSDoc based types

.gitignore

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

index.js

@@ -1,17 +1,37 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('micromark-extension-frontmatter').Options} Options
+ */
+
 import {frontmatter} from 'micromark-extension-frontmatter'
 import {
   frontmatterFromMarkdown,
   frontmatterToMarkdown
 } from 'mdast-util-frontmatter'
 
-export default function remarkFrontmatter(options) {
+/**
+ * Plugin to add support for frontmatter.
+ *
+ * @type {import('unified').Plugin<[Options?]|void[], Root>}
+ */
+export default function remarkFrontmatter(options = 'yaml') {
   const data = this.data()
+
   add('micromarkExtensions', frontmatter(options))
   add('fromMarkdownExtensions', frontmatterFromMarkdown(options))
   add('toMarkdownExtensions', frontmatterToMarkdown(options))
+
+  /**
+   * @param {string} field
+   * @param {unknown} value
+   */
   function add(field, value) {
-    /* istanbul ignore if - other extensions. */
-    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

@@ -29,30 +29,38 @@
   "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-frontmatter": "^1.0.0",
-    "micromark-extension-frontmatter": "^1.0.0"
+    "micromark-extension-frontmatter": "^1.0.0",
+    "unified": "^10.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "is-hidden": "^2.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",
     "to-vfile": "^7.0.0",
-    "unified": "^10.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "build": "rimraf \"test/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo --ignore-pattern test/ && 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,
@@ -79,5 +87,11 @@
       ],
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

test/index.js

@@ -1,17 +1,18 @@
+/**
+ * @typedef {import('vfile').VFile} VFile
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('../index.js').Options} Options
+ */
+
 import fs from 'fs'
 import path from 'path'
 import test from 'tape'
-import {readSync} from 'to-vfile'
+import {readSync, writeSync} from 'to-vfile'
 import {unified} from 'unified'
 import {remark} from 'remark'
 import {isHidden} from 'is-hidden'
 import remarkFrontmatter from '../index.js'
 
-const join = path.join
-const read = fs.readFileSync
-const write = fs.writeFileSync
-const dir = fs.readdirSync
-
 test('remarkFrontmatter', (t) => {
   t.doesNotThrow(() => {
     remark().use(remarkFrontmatter).freeze()
@@ -23,6 +24,7 @@ test('remarkFrontmatter', (t) => {
 
   t.throws(
     () => {
+      // @ts-expect-error: invalid input.
       unified().use(remarkFrontmatter, [1]).freeze()
     },
     /^Error: Expected matter to be an object, not `1`/,
@@ -31,6 +33,7 @@ test('remarkFrontmatter', (t) => {
 
   t.throws(
     () => {
+      // @ts-expect-error: invalid input.
       unified().use(remarkFrontmatter, ['jsonml']).freeze()
     },
     /^Error: Missing matter definition for `jsonml`/,
@@ -40,6 +43,7 @@ test('remarkFrontmatter', (t) => {
   t.throws(
     () => {
       unified()
+        // @ts-expect-error: invalid input.
         .use(remarkFrontmatter, [{marker: '*'}])
         .freeze()
     },
@@ -50,6 +54,7 @@ test('remarkFrontmatter', (t) => {
   t.throws(
     () => {
       unified()
+        // @ts-expect-error: invalid input.
         .use(remarkFrontmatter, [{type: 'jsonml'}])
         .freeze()
     },
@@ -61,45 +66,53 @@ test('remarkFrontmatter', (t) => {
 })
 
 test('fixtures', (t) => {
-  const base = join('test', 'fixtures')
-  const entries = dir(base).filter((d) => !isHidden(d))
+  const base = path.join('test', 'fixtures')
+  const entries = fs.readdirSync(base).filter((d) => !isHidden(d))
   let index = -1
 
   t.plan(entries.length)
 
   while (++index < entries.length) {
     const fixture = entries[index]
     t.test(fixture, (st) => {
-      const input = readSync(join(base, fixture, 'input.md'))
-      const treePath = join(base, fixture, 'tree.json')
-      const outputPath = join(base, fixture, 'output.md')
+      const input = readSync(path.join(base, fixture, 'input.md'))
+      const treePath = path.join(base, fixture, 'tree.json')
+      const outputPath = path.join(base, fixture, 'output.md')
+      /** @type {VFile} */
       let output
+      /** @type {Root} */
       let expected
+      /** @type {Options|undefined} */
       let config
 
       try {
-        config = JSON.parse(read(join(base, fixture, 'config.json')))
+        config = JSON.parse(
+          String(readSync(path.join(base, fixture, 'config.json')))
+        )
       } catch {}
 
       const proc = remark().use(remarkFrontmatter, config)
-      const actual = JSON.parse(JSON.stringify(proc.parse(input)))
+      const actual = proc.parse(input)
 
       try {
-        output = read(outputPath, 'utf8')
+        output = readSync(outputPath)
       } catch {
-        output = String(input)
+        output = input
       }
 
       try {
-        expected = JSON.parse(read(treePath))
+        expected = JSON.parse(String(readSync(treePath)))
       } catch {
         // New fixture.
-        write(treePath, JSON.stringify(actual, 0, 2) + '\n')
+        writeSync({
+          path: treePath,
+          value: JSON.stringify(actual, null, 2) + '\n'
+        })
         expected = actual
       }
 
       st.deepEqual(actual, expected, 'tree')
-      st.equal(String(proc.processSync(input)), output, 'process')
+      st.equal(String(proc.processSync(input)), String(output), 'process')
       st.end()
     })
   }

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