Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,6 +1,18 @@
+/**
+ * @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').Options} ToMarkdownExtension
+ * @typedef {import('mdast-util-to-markdown').Handle} ToMarkdownHandle
+ *
+ * @typedef {Literal & {type: 'math', lang?: string|null, meta?: string|null}} Math
+ * @typedef {Literal & {type: 'inlineMath'}} InlineMath
+ */
+
 import {longestStreak} from 'longest-streak'
-import safe from 'mdast-util-to-markdown/lib/util/safe.js'
+import {safe} from 'mdast-util-to-markdown/lib/util/safe.js'
 
+/** @type {FromMarkdownExtension} */
 export const mathFromMarkdown = {
   enter: {
     mathFlow: enterMathFlow,
@@ -17,6 +29,7 @@ export const mathFromMarkdown = {
   }
 }
 
+/** @type {ToMarkdownExtension} */
 export const mathToMarkdown = {
   unsafe: [
     {character: '\r', inConstruct: ['mathFlowMeta']},
@@ -29,79 +42,94 @@ export const mathToMarkdown = {
 
 inlineMath.peek = inlineMathPeek
 
+/** @type {FromMarkdownHandle} */
 function enterMathFlow(token) {
-  this.enter(
-    {
-      type: 'math',
-      meta: null,
-      value: '',
-      data: {
-        hName: 'div',
-        hProperties: {className: ['math', 'math-display']},
-        hChildren: [{type: 'text', value: ''}]
-      }
-    },
-    token
-  )
+  /** @type {Math} */
+  const node = {
+    type: 'math',
+    meta: null,
+    value: '',
+    data: {
+      hName: 'div',
+      hProperties: {className: ['math', 'math-display']},
+      hChildren: [{type: 'text', value: ''}]
+    }
+  }
+  // @ts-expect-error: custom node.
+  this.enter(node, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterMathFlowMeta() {
   this.buffer()
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMathFlowMeta() {
   const data = this.resume()
   this.stack[this.stack.length - 1].meta = data
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMathFlowFence() {
   // Exit if this is the closing fence.
   if (this.getData('mathFlowInside')) return
   this.buffer()
   this.setData('mathFlowInside', true)
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMathFlow(token) {
   const data = this.resume().replace(/^(\r?\n|\r)|(\r?\n|\r)$/g, '')
   const node = this.exit(token)
   node.value = data
+  // @ts-expect-error: we defined it.
   node.data.hChildren[0].value = data
   this.setData('mathFlowInside')
 }
 
+/** @type {FromMarkdownHandle} */
 function enterMathText(token) {
-  this.enter(
-    {
-      type: 'inlineMath',
-      value: '',
-      data: {
-        hName: 'span',
-        hProperties: {className: ['math', 'math-inline']},
-        hChildren: [{type: 'text', value: ''}]
-      }
-    },
-    token
-  )
+  /** @type {InlineMath} */
+  const node = {
+    type: 'inlineMath',
+    value: '',
+    data: {
+      hName: 'span',
+      hProperties: {className: ['math', 'math-inline']},
+      hChildren: [{type: 'text', value: ''}]
+    }
+  }
+  // @ts-expect-error: custom node.
+  this.enter(node, token)
   this.buffer()
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMathText(token) {
   const data = this.resume()
   const node = this.exit(token)
   node.value = data
+  // @ts-expect-error: we defined it.
   node.data.hChildren[0].value = data
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMathData(token) {
   this.config.enter.data.call(this, token)
   this.config.exit.data.call(this, token)
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {Math} node
+ */
 function math(node, _, context) {
   const raw = node.value || ''
   const fence = '$'.repeat(Math.max(longestStreak(raw, '$') + 1, 2))
   const exit = context.enter('mathFlow')
   let value = fence
+  /** @type {ReturnType<context['enter']>} */
   let subexit
 
   if (node.meta) {
@@ -121,6 +149,10 @@ function math(node, _, context) {
   return value
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {InlineMath} node
+ */
 function inlineMath(node) {
   const value = node.value || ''
   let size = 1
@@ -147,6 +179,7 @@ function inlineMath(node) {
   return sequence + pad + value + pad + sequence
 }
 
+/** @type {ToMarkdownHandle} */
 function inlineMathPeek() {
   return '$'
 }

package.json

@@ -29,28 +29,36 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.0",
     "longest-streak": "^3.0.0",
-    "mdast-util-to-markdown": "^0.6.0"
+    "mdast-util-to-markdown": "^1.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
-    "mdast-util-from-markdown": "^0.8.0",
-    "micromark-extension-math": "^0.1.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "micromark-extension-math": "^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",
     "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 +75,11 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

test.js

@@ -1,7 +1,7 @@
 import test from 'tape'
-import fromMarkdown from 'mdast-util-from-markdown'
-import toMarkdown from 'mdast-util-to-markdown'
-import math from 'micromark-extension-math'
+import {fromMarkdown} from 'mdast-util-from-markdown'
+import {toMarkdown} from 'mdast-util-to-markdown'
+import {math} from 'micromark-extension-math'
 import {mathFromMarkdown, mathToMarkdown} from './index.js'
 
 test('markdown -> mdast', (t) => {

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