Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,10 +1,22 @@
+/**
+ * @typedef {import('mdast').Footnote} Footnote
+ * @typedef {import('mdast').FootnoteReference} FootnoteReference
+ * @typedef {import('mdast').FootnoteDefinition} FootnoteDefinition
+ * @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').Map} Map
+ */
+
 import {normalizeIdentifier} from 'micromark-util-normalize-identifier'
-import association from 'mdast-util-to-markdown/lib/util/association.js'
-import phrasing from 'mdast-util-to-markdown/lib/util/container-phrasing.js'
-import flow from 'mdast-util-to-markdown/lib/util/container-flow.js'
-import indentLines from 'mdast-util-to-markdown/lib/util/indent-lines.js'
-import safe from 'mdast-util-to-markdown/lib/util/safe.js'
+import {association} from 'mdast-util-to-markdown/lib/util/association.js'
+import {containerPhrasing} from 'mdast-util-to-markdown/lib/util/container-phrasing.js'
+import {containerFlow} from 'mdast-util-to-markdown/lib/util/container-flow.js'
+import {indentLines} from 'mdast-util-to-markdown/lib/util/indent-lines.js'
+import {safe} from 'mdast-util-to-markdown/lib/util/safe.js'
 
+/** @type {FromMarkdownExtension} */
 export const footnoteFromMarkdown = {
   canContainEols: ['footnote'],
   enter: {
@@ -23,6 +35,7 @@ export const footnoteFromMarkdown = {
   }
 }
 
+/** @type {ToMarkdownExtension} */
 export const footnoteToMarkdown = {
   // This is on by default already.
   unsafe: [{character: '[', inConstruct: ['phrasing', 'label', 'reference']}],
@@ -32,17 +45,20 @@ export const footnoteToMarkdown = {
 footnoteReference.peek = footnoteReferencePeek
 footnote.peek = footnotePeek
 
+/** @type {FromMarkdownHandle} */
 function enterFootnoteDefinition(token) {
   this.enter(
     {type: 'footnoteDefinition', identifier: '', label: '', children: []},
     token
   )
 }
 
+/** @type {FromMarkdownHandle} */
 function enterFootnoteDefinitionLabelString() {
   this.buffer()
 }
 
+/** @type {FromMarkdownHandle} */
 function exitFootnoteDefinitionLabelString(token) {
   const label = this.resume()
   this.stack[this.stack.length - 1].label = label
@@ -51,18 +67,22 @@ function exitFootnoteDefinitionLabelString(token) {
   ).toLowerCase()
 }
 
+/** @type {FromMarkdownHandle} */
 function exitFootnoteDefinition(token) {
   this.exit(token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterFootnoteCall(token) {
   this.enter({type: 'footnoteReference', identifier: '', label: ''}, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterFootnoteCallString() {
   this.buffer()
 }
 
+/** @type {FromMarkdownHandle} */
 function exitFootnoteCallString(token) {
   const label = this.resume()
   this.stack[this.stack.length - 1].label = label
@@ -71,18 +91,25 @@ function exitFootnoteCallString(token) {
   ).toLowerCase()
 }
 
+/** @type {FromMarkdownHandle} */
 function exitFootnoteCall(token) {
   this.exit(token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterNote(token) {
   this.enter({type: 'footnote', children: []}, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function exitNote(token) {
   this.exit(token)
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {FootnoteReference} node
+ */
 function footnoteReference(node, _, context) {
   const exit = context.enter('footnoteReference')
   const subexit = context.enter('reference')
@@ -92,34 +119,46 @@ function footnoteReference(node, _, context) {
   return '[^' + reference + ']'
 }
 
+/** @type {ToMarkdownHandle} */
 function footnoteReferencePeek() {
   return '['
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {Footnote} node
+ */
 function footnote(node, _, context) {
   const exit = context.enter('footnote')
   const subexit = context.enter('label')
-  const value = '^[' + phrasing(node, context, {before: '[', after: ']'}) + ']'
+  const value =
+    '^[' + containerPhrasing(node, context, {before: '[', after: ']'}) + ']'
   subexit()
   exit()
   return value
 }
 
+/** @type {ToMarkdownHandle} */
 function footnotePeek() {
   return '^'
 }
 
+/**
+ * @type {ToMarkdownHandle}
+ * @param {FootnoteDefinition} node
+ */
 function footnoteDefinition(node, _, context) {
   const exit = context.enter('footnoteDefinition')
   const subexit = context.enter('label')
   const label =
     '[^' + safe(context, association(node), {before: '^', after: ']'}) + ']:'
   subexit()
-  const value = indentLines(flow(node, context), map)
+  const value = indentLines(containerFlow(node, context), map)
   exit()
 
   return value
 
+  /** @type {Map} */
   function map(line, index, blank) {
     if (index) {
       return (blank ? '' : '    ') + line

package.json

@@ -28,28 +28,36 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
-    "mdast-util-to-markdown": "^0.6.0",
-    "micromark-util-normalize-identifier": "^1.0.0-alpha.3"
+    "@types/mdast": "^3.0.0",
+    "mdast-util-to-markdown": "^1.0.0",
+    "micromark-util-normalize-identifier": "^1.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
-    "mdast-util-from-markdown": "^0.8.0",
-    "micromark-extension-footnote": "~0.3.0",
+    "mdast-util-from-markdown": "^1.0.0",
+    "micromark-extension-footnote": "^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,
@@ -66,5 +74,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 footnote from 'micromark-extension-footnote'
+import {fromMarkdown} from 'mdast-util-from-markdown'
+import {toMarkdown} from 'mdast-util-to-markdown'
+import {footnote} from 'micromark-extension-footnote'
 import {footnoteFromMarkdown, footnoteToMarkdown} 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
+  }
+}