Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,7 +1,26 @@
-import phrasing from 'mdast-util-to-markdown/lib/util/container-phrasing.js'
-import defaultInlineCode from 'mdast-util-to-markdown/lib/handle/inline-code.js'
+/**
+ * @typedef {import('mdast').Table} Table
+ * @typedef {import('mdast').TableRow} TableRow
+ * @typedef {import('mdast').TableCell} TableCell
+ * @typedef {import('mdast').InlineCode} InlineCode
+ * @typedef {import('markdown-table').MarkdownTableOptions} MarkdownTableOptions
+ * @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('mdast-util-to-markdown').Context} ToMarkdownContext
+ *
+ * @typedef Options
+ * @property {boolean} [tableCellPadding=true]
+ * @property {boolean} [tablePipeAlign=true]
+ * @property {MarkdownTableOptions['stringLength']} [stringLength]
+ */
+
+import {containerPhrasing} from 'mdast-util-to-markdown/lib/util/container-phrasing.js'
+import {inlineCode} from 'mdast-util-to-markdown/lib/handle/inline-code.js'
 import {markdownTable} from 'markdown-table'
 
+/** @type {FromMarkdownExtension} */
 export const gfmTableFromMarkdown = {
   enter: {
     table: enterTable,
@@ -18,30 +37,37 @@ export const gfmTableFromMarkdown = {
   }
 }
 
+/** @type {FromMarkdownHandle} */
 function enterTable(token) {
+  // @ts-expect-error: `align` is custom.
   this.enter({type: 'table', align: token._align, children: []}, token)
   this.setData('inTable', true)
 }
 
+/** @type {FromMarkdownHandle} */
 function exitTable(token) {
   this.exit(token)
   this.setData('inTable')
 }
 
+/** @type {FromMarkdownHandle} */
 function enterRow(token) {
   this.enter({type: 'tableRow', children: []}, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function exit(token) {
   this.exit(token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterCell(token) {
   this.enter({type: 'tableCell', children: []}, token)
 }
 
 // Overwrite the default code text data handler to unescape escaped pipes when
 // they are in tables.
+/** @type {FromMarkdownHandle} */
 function exitCodeText(token) {
   let value = this.resume()
 
@@ -53,11 +79,20 @@ function exitCodeText(token) {
   this.exit(token)
 }
 
+/**
+ * @param {string} $0
+ * @param {string} $1
+ * @returns {string}
+ */
 function replace($0, $1) {
   // Pipes work, backslashes don’t (but can’t escape pipes).
   return $1 === '|' ? $1 : $0
 }
 
+/**
+ * @param {Options} [options]
+ * @returns {ToMarkdownExtension}
+ */
 export function gfmTableToMarkdown(options) {
   const settings = options || {}
   const padding = settings.tableCellPadding
@@ -92,27 +127,48 @@ export function gfmTableToMarkdown(options) {
     }
   }
 
+  /**
+   * @type {ToMarkdownHandle}
+   * @param {Table} node
+   */
   function handleTable(node, _, context) {
+    // @ts-expect-error: fixed in `markdown-table@3.0.1`.
     return serializeData(handleTableAsData(node, context), node.align)
   }
 
-  // This function isn’t really used normally, because we handle rows at the
-  // table level.
-  // But, if someone passes in a table row, this ensures we make somewhat sense.
+  /**
+   * This function isn’t really used normally, because we handle rows at the
+   * table level.
+   * But, if someone passes in a table row, this ensures we make somewhat sense.
+   *
+   * @type {ToMarkdownHandle}
+   * @param {TableRow} node
+   */
   function handleTableRow(node, _, context) {
     const row = handleTableRowAsData(node, context)
     // `markdown-table` will always add an align row
     const value = serializeData([row])
     return value.slice(0, value.indexOf('\n'))
   }
 
+  /**
+   * @type {ToMarkdownHandle}
+   * @param {TableCell} node
+   */
   function handleTableCell(node, _, context) {
     const exit = context.enter('tableCell')
-    const value = phrasing(node, context, {before: around, after: around})
+    const value = containerPhrasing(node, context, {
+      before: around,
+      after: around
+    })
     exit()
     return value
   }
 
+  /**
+   * @param {Array.<Array.<string>>} matrix
+   * @param {Array.<string>} [align]
+   */
   function serializeData(matrix, align) {
     return markdownTable(matrix, {
       align,
@@ -122,14 +178,18 @@ export function gfmTableToMarkdown(options) {
     })
   }
 
+  /**
+   * @param {Table} node
+   * @param {ToMarkdownContext} context
+   */
   function handleTableAsData(node, context) {
     const children = node.children
     let index = -1
-    const length = children.length
+    /** @type {Array.<Array.<string>>} */
     const result = []
     const subexit = context.enter('table')
 
-    while (++index < length) {
+    while (++index < children.length) {
       result[index] = handleTableRowAsData(children[index], context)
     }
 
@@ -138,14 +198,18 @@ export function gfmTableToMarkdown(options) {
     return result
   }
 
+  /**
+   * @param {TableRow} node
+   * @param {ToMarkdownContext} context
+   */
   function handleTableRowAsData(node, context) {
     const children = node.children
     let index = -1
-    const length = children.length
+    /** @type {Array.<string>} */
     const result = []
     const subexit = context.enter('tableRow')
 
-    while (++index < length) {
+    while (++index < children.length) {
       result[index] = handleTableCell(children[index], node, context)
     }
 
@@ -154,8 +218,12 @@ export function gfmTableToMarkdown(options) {
     return result
   }
 
+  /**
+   * @type {ToMarkdownHandle}
+   * @param {InlineCode} node
+   */
   function inlineCodeWithTable(node, parent, context) {
-    let value = defaultInlineCode(node, parent, context)
+    let value = inlineCode(node, parent, context)
 
     if (context.stack.includes('tableCell')) {
       value = value.replace(/\|/g, '\\$&')

package.json

@@ -31,30 +31,37 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
     "markdown-table": "^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-gfm-table": "^0.4.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "micromark-extension-gfm-table": "^1.0.0",
     "prettier": "^2.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "string-width": "^5.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,
@@ -71,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 stringWidth from 'string-width'
-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 gfmTable from 'micromark-extension-gfm-table'
+import {gfmTable} from 'micromark-extension-gfm-table'
 import {gfmTableFromMarkdown, gfmTableToMarkdown} from './index.js'
 
 test('markdown -> mdast', (t) => {
@@ -67,15 +67,23 @@ test('markdown -> mdast', (t) => {
         mdastExtensions: [gfmTableFromMarkdown]
       }),
       true
-    ).children[0],
+    ),
     {
-      type: 'table',
-      align: [null],
+      type: 'root',
       children: [
         {
-          type: 'tableRow',
+          type: 'table',
+          align: [null],
           children: [
-            {type: 'tableCell', children: [{type: 'inlineCode', value: '|'}]}
+            {
+              type: 'tableRow',
+              children: [
+                {
+                  type: 'tableCell',
+                  children: [{type: 'inlineCode', value: '|'}]
+                }
+              ]
+            }
           ]
         }
       ]
@@ -90,8 +98,13 @@ test('markdown -> mdast', (t) => {
         mdastExtensions: [gfmTableFromMarkdown]
       }),
       true
-    ).children[0],
-    {type: 'paragraph', children: [{type: 'inlineCode', value: '\\|'}]},
+    ),
+    {
+      type: 'root',
+      children: [
+        {type: 'paragraph', children: [{type: 'inlineCode', value: '\\|'}]}
+      ]
+    },
     'should not support an escaped pipe in code *not* in a table cell'
   )
 
@@ -102,20 +115,25 @@ test('markdown -> mdast', (t) => {
         mdastExtensions: [gfmTableFromMarkdown]
       }),
       true
-    ).children[0],
+    ),
     {
-      type: 'table',
-      align: [null, null],
+      type: 'root',
       children: [
         {
-          type: 'tableRow',
+          type: 'table',
+          align: [null, null],
           children: [
-            {type: 'tableCell', children: [{type: 'text', value: '`\\'}]},
             {
-              type: 'tableCell',
+              type: 'tableRow',
               children: [
-                {type: 'inlineCode', value: '\\\\'},
-                {type: 'text', value: ' b'}
+                {type: 'tableCell', children: [{type: 'text', value: '`\\'}]},
+                {
+                  type: 'tableCell',
+                  children: [
+                    {type: 'inlineCode', value: '\\\\'},
+                    {type: 'text', value: ' b'}
+                  ]
+                }
               ]
             }
           ]

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