Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,7 +1,20 @@
+/**
+ * @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: 'mdxFlowExpression', data: {estree?: Estree}}} MDXFlowExpression
+ * @typedef {Literal & {type: 'mdxSpanExpression', data: {estree?: Estree}}} MDXSpanExpression
+ */
+
 import stripIndent from 'strip-indent'
 
 const eol = /\r?\n|\r/g
 
+/** @type {FromMarkdownExtension} */
 export const mdxExpressionFromMarkdown = {
   enter: {
     mdxFlowExpression: enterMdxFlowExpression,
@@ -15,6 +28,7 @@ export const mdxExpressionFromMarkdown = {
   }
 }
 
+/** @type {ToMarkdownExtension} */
 export const mdxExpressionToMarkdown = {
   handlers: {
     mdxFlowExpression: handleMdxExpression,
@@ -26,37 +40,53 @@ export const mdxExpressionToMarkdown = {
   ]
 }
 
+/** @type {FromMarkdownHandle} */
 function enterMdxFlowExpression(token) {
+  // @ts-expect-error: fine.
   this.enter({type: 'mdxFlowExpression', value: ''}, token)
   this.buffer()
 }
 
+/** @type {FromMarkdownHandle} */
 function enterMdxTextExpression(token) {
+  // @ts-expect-error: fine.
   this.enter({type: 'mdxTextExpression', value: ''}, token)
   this.buffer()
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMdxExpression(token) {
   const value = this.resume()
   const node = this.exit(token)
 
   node.value = token.type === 'mdxFlowExpression' ? dedent(value) : value
 
+  // @ts-expect-error: estree.
   if (token.estree) {
+    // @ts-expect-error: estree.
     node.data = {estree: token.estree}
   }
 }
 
+/** @type {FromMarkdownHandle} */
 function exitMdxExpressionData(token) {
   this.config.enter.data.call(this, token)
   this.config.exit.data.call(this, token)
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {MDXFlowExpression|MDXSpanExpression} node
+ */
 function handleMdxExpression(node) {
   const value = node.value || ''
   return '{' + (node.type === 'mdxFlowExpression' ? indent(value) : value) + '}'
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 function dedent(value) {
   const firstLineEnding = /\r?\n|\r/.exec(value)
   const position = firstLineEnding
@@ -70,10 +100,16 @@ function dedent(value) {
   return value
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 function indent(value) {
+  /** @type {Array.<string>} */
   const result = []
   let start = 0
   let line = 0
+  /** @type {RegExpExecArray|null} */
   let match
 
   while ((match = eol.exec(value))) {
@@ -87,6 +123,10 @@ function indent(value) {
 
   return result.join('')
 
+  /**
+   * @param {string} slice
+   * @returns {void}
+   */
   function one(slice) {
     result.push((line && slice ? '  ' : '') + slice)
   }

package.json

@@ -29,30 +29,39 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/estree-jsx": "^0.0.1",
     "strip-indent": "^4.0.0"
   },
   "devDependencies": {
+    "@types/acorn": "^4.0.5",
+    "@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-mdx-expression": "^0.3.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "mdast-util-to-markdown": "^1.0.0",
+    "micromark-extension-mdx-expression": "^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,
@@ -69,5 +78,11 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

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 mdxExpression from 'micromark-extension-mdx-expression'
+import {mdxExpression} from 'micromark-extension-mdx-expression'
 import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from './index.js'
 
 test('markdown -> mdast', (t) => {
@@ -156,13 +156,18 @@ test('markdown -> mdast', (t) => {
         mdastExtensions: [mdxExpressionFromMarkdown]
       }),
       true
-    ).children[0],
+    ),
     {
-      type: 'paragraph',
+      type: 'root',
       children: [
-        {type: 'text', value: 'a '},
-        {type: 'mdxTextExpression', value: '\t \n'},
-        {type: 'text', value: ' c'}
+        {
+          type: 'paragraph',
+          children: [
+            {type: 'text', value: 'a '},
+            {type: 'mdxTextExpression', value: '\t \n'},
+            {type: 'text', value: ' c'}
+          ]
+        }
       ]
     },
     'should support an empty text expression (agnostic)'
@@ -175,12 +180,17 @@ test('markdown -> mdast', (t) => {
         mdastExtensions: [mdxExpressionFromMarkdown]
       }),
       true
-    ).children[0],
+    ),
     {
-      type: 'paragraph',
+      type: 'root',
       children: [
-        {type: 'mdxTextExpression', value: ' a { b } c '},
-        {type: 'text', value: '.'}
+        {
+          type: 'paragraph',
+          children: [
+            {type: 'mdxTextExpression', value: ' a { b } c '},
+            {type: 'text', value: '.'}
+          ]
+        }
       ]
     },
     'should support an balanced braces in a flow expression (agnostic)'
@@ -193,12 +203,17 @@ test('markdown -> mdast', (t) => {
         mdastExtensions: [mdxExpressionFromMarkdown]
       }),
       true
-    ).children[0],
+    ),
     {
-      type: 'paragraph',
+      type: 'root',
       children: [
-        {type: 'mdxTextExpression', value: ' a /* { */ '},
-        {type: 'text', value: '.'}
+        {
+          type: 'paragraph',
+          children: [
+            {type: 'mdxTextExpression', value: ' a /* { */ '},
+            {type: 'text', value: '.'}
+          ]
+        }
       ]
     },
     'should support a commented-out unbalanced brace in a flow expression (gnostic)'

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