Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,20 +1,44 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('hast-util-sanitize').Schema} Schema
+ * @typedef {import('mdast-util-to-hast').Handlers} Handlers
+ *
+ * @typedef Options
+ *   Configuration.
+ * @property {boolean|Schema|null} [sanitize]
+ *   How to sanitize the output.
+ * @property {Handlers} [handlers={}]
+ *   Object mapping mdast nodes to functions handling them.
+ */
+
 import {toHtml} from 'hast-util-to-html'
 import {sanitize} from 'hast-util-sanitize'
 import {toHast} from 'mdast-util-to-hast'
 
+/**
+ * Plugin to serialize markdown as HTML.
+ *
+ * @type {import('unified').Plugin<[Options?]|void[], Root, string>}
+ */
 export default function remarkHtml(options = {}) {
   const handlers = options.handlers || {}
   const schema =
     options.sanitize && typeof options.sanitize === 'object'
       ? options.sanitize
-      : null
+      : undefined
 
   Object.assign(this, {Compiler: compiler})
 
+  /**
+   * @type {import('unified').CompilerFunction<Root, string>}
+   */
   function compiler(node, file) {
     const hast = toHast(node, {allowDangerousHtml: !options.sanitize, handlers})
+    // @ts-expect-error: assume root.
+    const cleanHast = options.sanitize ? sanitize(hast, schema) : hast
     const result = toHtml(
-      options.sanitize ? sanitize(hast, schema) : hast,
+      // @ts-expect-error: assume root.
+      cleanHast,
       Object.assign({}, options, {allowDangerousHtml: !options.sanitize})
     )
 

package.json

@@ -31,15 +31,20 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.0",
     "hast-util-sanitize": "^4.0.0",
     "hast-util-to-html": "^8.0.0",
-    "mdast-util-to-hast": "^11.0.0"
+    "mdast-util-to-hast": "^11.0.0",
+    "unified": "^10.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "commonmark.json": "^0.30.0",
     "is-hidden": "^2.0.0",
@@ -55,16 +60,19 @@
     "remark-preset-wooorm": "^8.0.0",
     "remark-slug": "^6.0.0",
     "remark-toc": "^7.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
     "to-vfile": "^7.0.0",
-    "unified": "^10.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
+    "build": "rimraf \"test/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo --ignore-pattern test/ && 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 npm run test-api",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -75,14 +83,17 @@
     "trailingComma": "none"
   },
   "xo": {
-    "prettier": true,
-    "ignores": [
-      "types/"
-    ]
+    "prettier": true
   },
   "remarkConfig": {
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

test/index.js

@@ -1,3 +1,10 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('mdast').Paragraph} Paragraph
+ * @typedef {import('vfile').VFile} VFile
+ * @typedef {import('../index.js').Options} Options
+ */
+
 import path from 'path'
 import fs from 'fs'
 import test from 'tape'
@@ -19,8 +26,6 @@ import rehypeStringify from 'rehype-stringify'
 import remarkHtml from '../index.js'
 
 test('remarkHtml', (t) => {
-  let processor
-
   t.doesNotThrow(() => {
     remark().use(remarkHtml).freeze()
   }, 'should not throw if not passed options')
@@ -29,22 +34,25 @@ test('remarkHtml', (t) => {
     () => {
       remark()
         .use(remarkHtml)
+        // @ts-expect-error: not a node.
         .stringify({type: 'root', children: [{value: 'baz'}]})
     },
     /Expected node, got `\[object Object]`/,
     'should throw when not given a node'
   )
 
-  processor = remark().use(remarkHtml)
+  let processor = remark().use(remarkHtml)
 
   t.equal(
+    // @ts-expect-error: unknown node.
     processor.stringify({type: 'alpha'}),
     '<div></div>',
     'should stringify unknown nodes'
   )
 
   t.equal(
     processor.stringify({
+      // @ts-expect-error: unknown node.
       type: 'alpha',
       children: [{type: 'strong', children: [{type: 'text', value: 'bravo'}]}]
     }),
@@ -54,6 +62,7 @@ test('remarkHtml', (t) => {
 
   t.equal(
     processor.stringify({
+      // @ts-expect-error: unknown node.
       type: 'alpha',
       children: [{type: 'text', value: 'bravo'}],
       data: {
@@ -68,8 +77,14 @@ test('remarkHtml', (t) => {
 
   processor = remark().use(remarkHtml, {
     handlers: {
+      /** @param {Paragraph} node */
       paragraph(h, node) {
-        node.children[0].value = 'changed'
+        const head = node.children[0]
+
+        if (head.type === 'text') {
+          head.value = 'changed'
+        }
+
         return h(node, 'p', all(h, node))
       }
     }
@@ -82,13 +97,15 @@ test('remarkHtml', (t) => {
   )
 
   processor = remark()
-    .use(() => {
-      return function (ast) {
+    .use(
+      /** @type {import('unified').Plugin<void[], Root>} */
+      () => (ast) => {
+        // @ts-expect-error: assume it exists.
         ast.children[0].children[0].data = {
           hProperties: {title: 'overwrite'}
         }
       }
-    })
+    )
     .use(remarkHtml)
 
   t.equal(
@@ -98,11 +115,13 @@ test('remarkHtml', (t) => {
   )
 
   processor = remark()
-    .use(() => {
-      return function (ast) {
+    .use(
+      /** @type {import('unified').Plugin<void[], Root>} */
+      () => (ast) => {
+        // @ts-expect-error: assume it exists.
         ast.children[0].children[0].data = {hName: 'b'}
       }
-    })
+    )
     .use(remarkHtml)
 
   t.equal(
@@ -112,8 +131,10 @@ test('remarkHtml', (t) => {
   )
 
   processor = remark()
-    .use(() => {
-      return function (ast) {
+    .use(
+      /** @type {import('unified').Plugin<void[], Root>} */
+      () => (ast) => {
+        // @ts-expect-error: assume it exists.
         const code = ast.children[0].children[0]
 
         code.data = {
@@ -127,7 +148,7 @@ test('remarkHtml', (t) => {
           ]
         }
       }
-    })
+    )
     .use(remarkHtml)
 
   t.equal(
@@ -137,8 +158,10 @@ test('remarkHtml', (t) => {
   )
 
   processor = remark()
-    .use(() => {
-      return function (ast) {
+    .use(
+      /** @type {import('unified').Plugin<void[], Root>} */
+      () => (ast) => {
+        // @ts-expect-error: assume it exists.
         const code = ast.children[0].children[0]
 
         code.data = {
@@ -152,7 +175,7 @@ test('remarkHtml', (t) => {
           ]
         }
       }
-    })
+    )
     .use(remarkHtml, {sanitize: true})
 
   t.equal(
@@ -162,13 +185,14 @@ test('remarkHtml', (t) => {
   )
 
   processor = remark()
-    .use(() => {
-      return function (ast) {
+    .use(
+      /** @type {import('unified').Plugin<void[], Root>} */
+      () => (ast) => {
         ast.children[0].data = {
           hProperties: {className: 'foo'}
         }
       }
-    })
+    )
     .use(remarkHtml)
 
   t.equal(
@@ -242,7 +266,9 @@ test('Fixtures', (t) => {
     let config = {}
 
     try {
-      config = JSON.parse(fs.readFileSync(path.join(base, name, 'config.json')))
+      config = JSON.parse(
+        String(fs.readFileSync(path.join(base, name, 'config.json')))
+      )
     } catch {}
 
     const result = processSync(file, config)
@@ -256,6 +282,7 @@ test('Fixtures', (t) => {
 test('CommonMark', (t) => {
   let start = 0
   let index = -1
+  /** @type {string|undefined} */
   let section
 
   while (++index < commonmark.length) {
@@ -296,7 +323,7 @@ test('Integrations', (t) => {
     toc: [remarkSlug, remarkToc]
   }
   const base = path.join('test', 'integrations')
-  const files = fs.readdirSync(base)
+  const files = /** @type {(keyof integrationMap)[]} */ (fs.readdirSync(base))
   let index = -1
 
   while (++index < files.length) {
@@ -308,6 +335,7 @@ test('Integrations', (t) => {
     const input = String(fs.readFileSync(path.join(base, name, 'input.md')))
     const file = toVFile({path: name + '.md', value: input})
     const result = remark()
+      // @ts-expect-error: fine.
       .use(integrationMap[name])
       .use(remarkHtml)
       .processSync(file)
@@ -319,6 +347,10 @@ test('Integrations', (t) => {
   t.end()
 })
 
+/**
+ * @param {VFile} file
+ * @param {Options} [config]
+ */
 function processSync(file, config) {
   return remark().use(remarkHtml, config).processSync(file).toString()
 }

tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "include": ["test/**/*.js", "*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "strict": true
+  }
+}