Add JSDoc based types

Author: wooorm

.gitignore

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

index.d.ts

@@ -0,0 +1,15 @@
+import type {Root} from 'mdast'
+import type {ReactElement} from 'react'
+import type {Plugin} from 'unified'
+import type {Options} from './lib/index.js'
+
+/**
+ * Plugin to compile to React
+ *
+ * @param options
+ *   Configuration.
+ */
+// Note: defining all react nodes as result value seems to trip TS up.
+const remarkReact: Plugin<[Options], Root, ReactElement<unknown>>
+export default remarkReact
+export type {Options}

index.js

@@ -1,61 +1,3 @@
-import {toHast} from 'mdast-util-to-hast'
-import {sanitize} from 'hast-util-sanitize'
-import {toH} from 'hast-to-hyperscript'
-import tableCellStyle from '@mapbox/hast-util-table-cell-style'
+import remarkReact from './lib/index.js'
 
-const own = {}.hasOwnProperty
-
-const tableElements = new Set(['table', 'thead', 'tbody', 'tfoot', 'tr'])
-
-export default function remarkReact(options) {
-  const settings = options || {}
-  const createElement = settings.createElement
-  const Fragment = settings.Fragment || settings.fragment
-  const clean = settings.sanitize !== false
-  const scheme =
-    clean && typeof settings.sanitize !== 'boolean' ? settings.sanitize : null
-  const toHastOptions = settings.toHast || {}
-  const components = settings.remarkReactComponents || {}
-
-  this.Compiler = compile
-
-  // Wrapper around `createElement` to pass components in.
-  function h(name, props, children) {
-    // Currently, React issues a warning for *any* white space in tables.
-    // So we remove the pretty lines for now.
-    // See: <https://github.com/facebook/react/pull/7081>.
-    // See: <https://github.com/facebook/react/pull/7515>.
-    // See: <https://github.com/remarkjs/remark-react/issues/64>.
-    /* istanbul ignore next - still works but need to publish `remark-gfm`
-     * first. */
-    if (children && tableElements.has(name)) {
-      children = children.filter((child) => {
-        return child !== '\n'
-      })
-    }
-
-    return createElement(
-      own.call(components, name) ? components[name] : name,
-      props,
-      children
-    )
-  }
-
-  // Compile mdast to React.
-  function compile(node) {
-    let tree = toHast(node, toHastOptions)
-
-    if (clean) {
-      tree = sanitize(tree, scheme)
-    }
-
-    let root = toH(h, tableCellStyle(tree), settings.prefix)
-
-    // If this compiled to a `<div>`, but fragment are possible, use those.
-    if (root.type === 'div' && Fragment) {
-      root = createElement(Fragment, {}, root.props.children)
-    }
-
-    return root
-  }
-}
+export default remarkReact

lib/index.js

@@ -0,0 +1,119 @@
+/**
+ * @typedef {import('mdast').Root} Root
+ * @typedef {import('hast-util-sanitize').Schema} Schema
+ * @typedef {import('mdast-util-to-hast').Options} ToHastOptions
+ * @typedef {import('react').ReactNode} ReactNode
+ * @typedef {import('react').ReactElement<unknown>} ReactElement
+ *
+ * @callback CreateElementLike
+ * @param {any} name
+ * @param {any} props
+ * @param {...ReactNode} children
+ * @returns {ReactNode}
+ *
+ * @typedef Options
+ * @property {CreateElementLike} createElement
+ *   How to create elements or components.
+ *   You should typically pass `React.createElement`.
+ * @property {((props: any) => ReactNode)|undefined} [Fragment]
+ *   Create fragments instead of an outer `<div>` if available.
+ *   You should typically pass `React.Fragment`.
+ * @property {string|undefined} [prefix='h-']
+ *   React key prefix
+ * @property {boolean|Schema} [sanitize]
+ *   Options for `hast-util-sanitize`.
+ * @property {ToHastOptions} [toHast={}]
+ *   Options for `mdast-util-to-hast`.
+ * @property {Partial<{[TagName in keyof JSX.IntrinsicElements]: string|((props: JSX.IntrinsicElements[TagName]) => ReactNode)}>} [remarkReactComponents]
+ *   Override default elements (such as `<a>`, `<p>`, etcetera) by passing an
+ *   object mapping tag names to components.
+ */
+
+import {toHast} from 'mdast-util-to-hast'
+import {sanitize} from 'hast-util-sanitize'
+import {toH} from 'hast-to-hyperscript'
+// @ts-expect-error: untyped.
+import tableCellStyle from '@mapbox/hast-util-table-cell-style'
+
+const own = {}.hasOwnProperty
+const tableElements = new Set(['table', 'thead', 'tbody', 'tfoot', 'tr'])
+
+/**
+ * Plugin to transform markdown to React.
+ *
+ * @type {import('unified').Plugin<[Options], Root, ReactElement>}
+ */
+export default function remarkReact(options) {
+  if (!options || !options.createElement) {
+    throw new Error('Missing `createElement` in `options`')
+  }
+
+  const createElement = options.createElement
+  /** @type {Options['Fragment']} */
+  // @ts-expect-error: to do: deprecate `fragment`.
+  const Fragment = options.Fragment || options.fragment
+  const clean = options.sanitize !== false
+  const scheme =
+    clean && typeof options.sanitize !== 'boolean' ? options.sanitize : null
+  const toHastOptions = options.toHast || {}
+  const components = options.remarkReactComponents || {}
+
+  Object.assign(this, {Compiler: compile})
+
+  /**
+   * @param {keyof JSX.IntrinsicElements} name
+   * @param {Record<string, unknown>} props
+   * @param {unknown[]} [children]
+   * @returns {ReactNode}
+   */
+  function h(name, props, children) {
+    // Currently, React issues a warning for *any* white space in tables.
+    // So we remove the pretty lines for now.
+    // See: <https://github.com/facebook/react/pull/7081>.
+    // See: <https://github.com/facebook/react/pull/7515>.
+    // See: <https://github.com/remarkjs/remark-react/issues/64>.
+    /* istanbul ignore next - still works but need to publish `remark-gfm`
+     * first. */
+    if (children && tableElements.has(name)) {
+      children = children.filter((child) => {
+        return child !== '\n'
+      })
+    }
+
+    return createElement(
+      own.call(components, name) ? components[name] : name,
+      props,
+      children
+    )
+  }
+
+  // Compile mdast to React.
+  /** @type {import('unified').CompilerFunction<Root, ReactNode>} */
+  function compile(node) {
+    let tree = toHast(node, toHastOptions)
+
+    if (clean && tree) {
+      tree = sanitize(tree, scheme || undefined)
+    }
+
+    /** @type {ReactNode} */
+    // @ts-expect-error: assume `name` is a known element.
+    let result = toH(h, tableCellStyle(tree), options.prefix)
+
+    // If this compiled to a `<div>`, but fragment are possible, use those.
+    if (
+      result &&
+      typeof result === 'object' &&
+      'type' in result &&
+      result.type === 'div' &&
+      'props' in result &&
+      Fragment
+    ) {
+      // `children` does exist.
+      // type-coverage:ignore-next-line
+      result = createElement(Fragment, {}, result.props.children)
+    }
+
+    return result
+  }
+}

package.json

@@ -40,16 +40,24 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "lib/",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
     "@mapbox/hast-util-table-cell-style": "^0.2.0",
+    "@types/mdast": "^3.0.0",
+    "@types/react": "^17.0.0",
     "hast-to-hyperscript": "^10.0.0",
     "hast-util-sanitize": "^4.0.0",
-    "mdast-util-to-hast": "^11.0.0"
+    "mdast-util-to-hast": "^11.0.0",
+    "unified": "^10.0.0"
   },
   "devDependencies": {
+    "@types/react-dom": "^17.0.0",
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "is-hidden": "^2.0.0",
     "prettier": "^2.0.0",
@@ -60,16 +68,19 @@
     "remark-footnotes": "^4.0.0",
     "remark-frontmatter": "^4.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",
     "vfile": "^5.0.0",
     "xo": "^0.39.0"
   },
   "scripts": {
-    "sub-install": "cd test/react/v17 && npm install && cd ../..",
+    "build": "rimraf \"lib/**/*.d.ts\" \"test/**/*.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 npm run test-api",
-    "test": "npm run sub-install && npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -86,5 +97,15 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true,
+    "#": "needed `any`s",
+    "ignoreFiles": [
+      "lib/index.d.ts"
+    ]
   }
 }

test/index.js

@@ -1,3 +1,9 @@
+/**
+ * @typedef {import('mdast').Image} Image
+ * @typedef {import('react').ReactNode} ReactNode
+ * @typedef {import('react').ReactElement<unknown>} ReactElement
+ */
+
 import path from 'path'
 import fs from 'fs'
 import test from 'tape'
@@ -12,9 +18,14 @@ import {renderToStaticMarkup} from 'react-dom/server.js'
 import remarkReact from '../index.js'
 
 test('React ' + React.version, (t) => {
-  t.doesNotThrow(() => {
-    remark().use(remarkReact).freeze()
-  }, 'should not throw if not passed options')
+  t.throws(
+    () => {
+      // @ts-expect-error: Options missing.
+      remark().use(remarkReact).freeze()
+    },
+    /Missing `createElement` in `options`/,
+    'should throw if not passed options'
+  )
 
   t.test('should use consistent keys on multiple renders', (st) => {
     const markdown = '# A **bold** heading'
@@ -23,6 +34,9 @@ test('React ' + React.version, (t) => {
 
     st.end()
 
+    /**
+     * @param {string} text
+     */
     function reactKeys(text) {
       return extractKeys(
         remark()
@@ -31,14 +45,29 @@ test('React ' + React.version, (t) => {
       )
     }
 
+    /**
+     * @param {ReactElement} reactElement
+     * @returns {Array.<string|number>}
+     */
     function extractKeys(reactElement) {
+      /** @type {Array.<string|number>} */
       const keys = []
 
       if (reactElement.key !== undefined && reactElement.key !== null) {
         keys.push(reactElement.key)
       }
 
-      if (reactElement.props !== undefined && reactElement.props !== null) {
+      if (
+        reactElement.props &&
+        typeof reactElement.props === 'object' &&
+        // `children` does exist.
+        // @ts-expect-error
+        // type-coverage:ignore-next-line
+        reactElement.props.children
+      ) {
+        // `children` does exist.
+        // @ts-expect-error
+        // type-coverage:ignore-next-line
         React.Children.forEach(reactElement.props.children, (child) => {
           keys.push(...extractKeys(child))
         })
@@ -97,12 +126,17 @@ test('React ' + React.version, (t) => {
       remark()
         .use(remarkReact, {
           createElement: React.createElement,
-          toHast: {commonmark: true}
+          toHast: {
+            handlers: {
+              image(_, /** @type {Image} */ node) {
+                return {type: 'text', value: node.alt || ''}
+              }
+            }
+          }
         })
-        .processSync('[reference]\n\n[reference]: a.com\n[reference]: b.com')
-        .result
+        .processSync('![a]()').result
     ),
-    '<p><a href="a.com">reference</a></p>',
+    '<p>a</p>',
     'passes toHast options to inner toHast() function'
   )
 
@@ -121,7 +155,9 @@ test('React ' + React.version, (t) => {
     let config = {}
 
     try {
-      config = JSON.parse(fs.readFileSync(path.join(base, 'config.json')))
+      config = JSON.parse(
+        String(fs.readFileSync(path.join(base, 'config.json')))
+      )
     } catch {}
 
     config.createElement = React.createElement

tsconfig.json

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