Add JSDoc based types

Author: wooorm

.!42543!.editorconfig

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

.gitignore

@@ -1,11 +1,21 @@
+/**
+ * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
+ * @typedef {import('mdast-util-from-markdown').Transform} FromMarkdownTransform
+ * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
+ * @typedef {import('mdast-util-to-markdown/lib/types.js').Options} ToMarkdownExtension
+ * @typedef {import('mdast-util-find-and-replace').ReplaceFunction} ReplaceFunction
+ * @typedef {import('mdast-util-find-and-replace').RegExpMatchObject} RegExpMatchObject
+ * @typedef {import('mdast-util-find-and-replace').PhrasingContent} PhrasingContent
+ */
+
 import {ccount} from 'ccount'
 import {findAndReplace} from 'mdast-util-find-and-replace'
-import unicodePunctuation from 'micromark/dist/character/unicode-punctuation.js'
-import unicodeWhitespace from 'micromark/dist/character/unicode-whitespace.js'
+import {unicodePunctuation, unicodeWhitespace} from 'micromark-util-character'
 
 const inConstruct = 'phrasing'
 const notInConstruct = ['autolink', 'link', 'image', 'label']
 
+/** @type {FromMarkdownExtension} */
 export const gfmAutolinkLiteralFromMarkdown = {
   transforms: [transformGfmAutolinkLiterals],
   enter: {
@@ -22,6 +32,7 @@ export const gfmAutolinkLiteralFromMarkdown = {
   }
 }
 
+/** @type {ToMarkdownExtension} */
 export const gfmAutolinkLiteralToMarkdown = {
   unsafe: [
     {
@@ -42,31 +53,39 @@ export const gfmAutolinkLiteralToMarkdown = {
   ]
 }
 
+/** @type {FromMarkdownHandle} */
 function enterLiteralAutolink(token) {
+  // @ts-expect-error: `null` is fine.
   this.enter({type: 'link', title: null, url: '', children: []}, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function enterLiteralAutolinkValue(token) {
   this.config.enter.autolinkProtocol.call(this, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function exitLiteralAutolinkHttp(token) {
   this.config.exit.autolinkProtocol.call(this, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function exitLiteralAutolinkWww(token) {
   this.config.exit.data.call(this, token)
   this.stack[this.stack.length - 1].url = 'http://' + this.sliceSerialize(token)
 }
 
+/** @type {FromMarkdownHandle} */
 function exitLiteralAutolinkEmail(token) {
   this.config.exit.autolinkEmail.call(this, token)
 }
 
+/** @type {FromMarkdownHandle} */
 function exitLiteralAutolink(token) {
   this.exit(token)
 }
 
+/** @type {FromMarkdownTransform} */
 function transformGfmAutolinkLiterals(tree) {
   findAndReplace(
     tree,
@@ -78,8 +97,16 @@ function transformGfmAutolinkLiterals(tree) {
   )
 }
 
+/**
+ * @type {ReplaceFunction}
+ * @param {string} _
+ * @param {string} protocol
+ * @param {string} domain
+ * @param {string} path
+ * @param {RegExpMatchObject} match
+ */
 // eslint-disable-next-line max-params
-function findUrl($0, protocol, domain, path, match) {
+function findUrl(_, protocol, domain, path, match) {
   let prefix = ''
 
   // Not an expected previous character.
@@ -102,34 +129,48 @@ function findUrl($0, protocol, domain, path, match) {
 
   if (!parts[0]) return false
 
-  let result = {
+  /** @type {PhrasingContent} */
+  // @ts-expect-error: `null` is fine.
+  const result = {
     type: 'link',
     title: null,
     url: prefix + protocol + parts[0],
     children: [{type: 'text', value: protocol + parts[0]}]
   }
 
   if (parts[1]) {
-    result = [result, {type: 'text', value: parts[1]}]
+    return [result, {type: 'text', value: parts[1]}]
   }
 
   return result
 }
 
-function findEmail($0, atext, label, match) {
+/**
+ * @type {ReplaceFunction}
+ * @param {string} _
+ * @param {string} atext
+ * @param {string} label
+ * @param {RegExpMatchObject} match
+ */
+function findEmail(_, atext, label, match) {
   // Not an expected previous character.
   if (!previous(match, true) || /[_-]$/.test(label)) {
     return false
   }
 
   return {
     type: 'link',
+    // @ts-expect-error: `null` is fine.
     title: null,
     url: 'mailto:' + atext + '@' + label,
     children: [{type: 'text', value: atext + '@' + label}]
   }
 }
 
+/**
+ * @param {string} domain
+ * @returns {boolean}
+ */
 function isCorrectDomain(domain) {
   const parts = domain.split('.')
 
@@ -148,15 +189,24 @@ function isCorrectDomain(domain) {
   return true
 }
 
+/**
+ * @param {string} url
+ * @returns {[string, string|undefined]}
+ */
 function splitUrl(url) {
-  let trail = /[!"&'),.:;<>?\]}]+$/.exec(url)
+  const trailExec = /[!"&'),.:;<>?\]}]+$/.exec(url)
+  /** @type {number} */
   let closingParenIndex
+  /** @type {number} */
   let openingParens
+  /** @type {number} */
   let closingParens
+  /** @type {string|undefined} */
+  let trail
 
-  if (trail) {
-    url = url.slice(0, trail.index)
-    trail = trail[0]
+  if (trailExec) {
+    url = url.slice(0, trailExec.index)
+    trail = trailExec[0]
     closingParenIndex = trail.indexOf(')')
     openingParens = ccount(url, '(')
     closingParens = ccount(url, ')')
@@ -172,8 +222,14 @@ function splitUrl(url) {
   return [url, trail]
 }
 
+/**
+ * @param {RegExpMatchObject} match
+ * @param {boolean} [email=false]
+ * @returns {boolean}
+ */
 function previous(match, email) {
   const code = match.input.charCodeAt(match.index - 1)
+
   return (
     (match.index === 0 ||
       unicodeWhitespace(code) ||

index.js

@@ -32,32 +32,39 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
     "ccount": "^2.0.0",
     "mdast-util-find-and-replace": "^2.0.0",
-    "micromark": "^2.11.0"
+    "micromark-util-character": "^1.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "hast-util-to-html": "^8.0.0",
-    "mdast-util-from-markdown": "^0.8.0",
+    "mdast-util-from-markdown": "^1.0.0",
     "mdast-util-to-hast": "^11.0.0",
-    "mdast-util-to-markdown": "^0.6.0",
-    "micromark-extension-gfm-autolink-literal": "^0.5.6",
+    "mdast-util-to-markdown": "^1.0.0",
+    "micromark-extension-gfm-autolink-literal": "^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/index.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --conditions development test/index.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -74,5 +81,11 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

package.json

@@ -3,9 +3,9 @@ import path from 'path'
 import test from 'tape'
 import {toHtml} from 'hast-util-to-html'
 import {toHast} from 'mdast-util-to-hast'
-import fromMarkdown from 'mdast-util-from-markdown'
-import toMarkdown from 'mdast-util-to-markdown'
-import gfmAutolinkLiteral from 'micromark-extension-gfm-autolink-literal'
+import {fromMarkdown} from 'mdast-util-from-markdown'
+import {toMarkdown} from 'mdast-util-to-markdown'
+import {gfmAutolinkLiteral} from 'micromark-extension-gfm-autolink-literal'
 import {
   gfmAutolinkLiteralFromMarkdown,
   gfmAutolinkLiteralToMarkdown

test/index.js

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