Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,31 +1,55 @@
+/**
+ * @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 {import('estree-jsx').Program} Estree
+ *
+ * @typedef {Literal & {type: 'mdxjsEsm', data: {estree?: Estree}}} MDXJSEsm
+ */
+
+/** @type {FromMarkdownExtension} */
 export const mdxjsEsmFromMarkdown = {
   enter: {mdxjsEsm: enterMdxjsEsm},
   exit: {mdxjsEsm: exitMdxjsEsm, mdxjsEsmData: exitMdxjsEsmData}
 }
 
+/** @type {ToMarkdownExtension} */
 export const mdxjsEsmToMarkdown = {handlers: {mdxjsEsm: handleMdxjsEsm}}
 
+/** @type {FromMarkdownHandle} */
 function enterMdxjsEsm(token) {
+  // @ts-expect-error: custom.
   this.enter({type: 'mdxjsEsm', value: ''}, token)
   this.buffer() // Capture EOLs
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMdxjsEsm(token) {
   const value = this.resume()
   const node = this.exit(token)
+  /** @type {Estree?} */
+  // @ts-expect-error: custom.
+  const estree = token.estree
 
   node.value = value
 
-  if (token.estree) {
-    node.data = {estree: token.estree}
+  if (estree) {
+    node.data = {estree}
   }
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMdxjsEsmData(token) {
   this.config.enter.data.call(this, token)
   this.config.exit.data.call(this, token)
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {MDXJSEsm} node
+ */
 function handleMdxjsEsm(node) {
   return node.value || ''
 }

package.json

@@ -31,27 +31,38 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
+  "dependencies": {
+    "@types/estree-jsx": "^0.0.1",
+    "@types/mdast": "^3.0.0"
+  },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "acorn": "^8.0.0",
     "c8": "^7.0.0",
-    "mdast-util-from-markdown": "^0.8.0",
-    "mdast-util-to-markdown": "^0.6.0",
-    "micromark-extension-mdxjs-esm": "^0.3.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "mdast-util-to-markdown": "^1.0.0",
+    "micromark-extension-mdxjs-esm": "^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,
@@ -68,5 +79,11 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

readme.md

@@ -50,7 +50,7 @@ import fs from 'fs'
 import * as acorn from 'acorn'
 import {fromMarkdown} from 'mdast-util-from-markdown'
 import {toMarkdown} from 'mdast-util-to-markdown'
-import mdxjsEsm from 'micromark-extension-mdxjs-esm'
+import {mdxjsEsm} from 'micromark-extension-mdxjs-esm'
 import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'mdast-util-mdxjs-esm'
 
 const doc = fs.readFileSync('example.mdx')

test.js

@@ -1,9 +1,9 @@
 import test from 'tape'
 import * as acorn from 'acorn'
-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 mdxjsEsm from 'micromark-extension-mdxjs-esm'
+import {mdxjsEsm} from 'micromark-extension-mdxjs-esm'
 import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} 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
+  }
+}