Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,8 +1,27 @@
-import matters from 'micromark-extension-frontmatter/lib/matters.js'
+/**
+ * @typedef {import('mdast').Literal} Literal
+ * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
+ * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Options} ToMarkdownExtension
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Handle} ToMarkdownHandle
+ * @typedef {import('mdast-util-to-markdown/lib/util/indent-lines.js').Map} Map
+ *
+ * @typedef {import('micromark-extension-frontmatter/matters.js').Options} Options
+ * @typedef {import('micromark-extension-frontmatter/matters.js').Matter} Matter
+ * @typedef {import('micromark-extension-frontmatter/matters.js').Info} Info
+ */
 
+import {matters} from 'micromark-extension-frontmatter/matters.js'
+
+/**
+ * @param {Options} [options]
+ * @returns {FromMarkdownExtension}
+ */
 export function frontmatterFromMarkdown(options) {
   const settings = matters(options)
+  /** @type {FromMarkdownExtension['enter']} */
   const enter = {}
+  /** @type {FromMarkdownExtension['exit']} */
   const exit = {}
   let index = -1
 
@@ -16,27 +35,41 @@ export function frontmatterFromMarkdown(options) {
   return {enter, exit}
 }
 
+/**
+ * @param {Matter} matter
+ * @returns {FromMarkdownHandle} enter
+ */
 function opener(matter) {
   return open
+  /** @type {FromMarkdownHandle} */
   function open(token) {
+    // @ts-expect-error: custom.
     this.enter({type: matter.type, value: ''}, token)
     this.buffer()
   }
 }
 
+/** @type {FromMarkdownHandle} */
 function close(token) {
   const data = this.resume()
   // Remove the initial and final eol.
   this.exit(token).value = data.replace(/^(\r?\n|\r)|(\r?\n|\r)$/g, '')
 }
 
+/** @type {FromMarkdownHandle} */
 function value(token) {
   this.config.enter.data.call(this, token)
   this.config.exit.data.call(this, token)
 }
 
+/**
+ * @param {Options} [options]
+ * @returns {ToMarkdownExtension}
+ */
 export function frontmatterToMarkdown(options) {
+  /** @type {ToMarkdownExtension['unsafe']} */
   const unsafe = []
+  /** @type {ToMarkdownExtension['handlers']} */
   const handlers = {}
   const settings = matters(options)
   let index = -1
@@ -50,23 +83,42 @@ export function frontmatterToMarkdown(options) {
   return {unsafe, handlers}
 }
 
+/**
+ * @param {Matter} matter
+ * @returns {(node: Literal) => string} enter
+ */
 function handler(matter) {
   const open = fence(matter, 'open')
   const close = fence(matter, 'close')
 
   return handle
 
+  /**
+   * @type {ToMarkdownHandle}
+   * @param {Literal} node
+   */
   function handle(node) {
     return open + (node.value ? '\n' + node.value : '') + '\n' + close
   }
 }
 
+/**
+ * @param {Matter} matter
+ * @param {'open'|'close'} prop
+ * @returns {string}
+ */
 function fence(matter, prop) {
   return matter.marker
     ? pick(matter.marker, prop).repeat(3)
-    : pick(matter.fence, prop)
+    : // @ts-expect-error: They’re mutually exclusive.
+      pick(matter.fence, prop)
 }
 
+/**
+ * @param {Info|string} schema
+ * @param {'open'|'close'} prop
+ * @returns {string}
+ */
 function pick(schema, prop) {
   return typeof schema === 'string' ? schema : schema[prop]
 }

package.json

@@ -29,28 +29,35 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
-    "micromark-extension-frontmatter": "^0.2.0"
+    "micromark-extension-frontmatter": "^1.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
-    "mdast-util-from-markdown": "^0.8.0",
-    "mdast-util-to-markdown": "^0.6.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "mdast-util-to-markdown": "^1.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-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 node --conditions development test.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -67,5 +74,11 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

test.js

@@ -1,8 +1,8 @@
 import test from 'tape'
-import fromMarkdown from 'mdast-util-from-markdown'
-import toMarkdown from 'mdast-util-to-markdown'
+import {fromMarkdown} from 'mdast-util-from-markdown'
+import {toMarkdown} from 'mdast-util-to-markdown'
 import {removePosition} from 'unist-util-remove-position'
-import frontmatter from 'micromark-extension-frontmatter'
+import {frontmatter} from 'micromark-extension-frontmatter'
 import {frontmatterFromMarkdown, frontmatterToMarkdown} from './index.js'
 
 const custom = {type: 'custom', marker: {open: '<', close: '>'}}

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