Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

lib/index.js

@@ -1,8 +1,11 @@
 /**
  * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
  * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
- *
+ */
+
+/**
  * @typedef {import('mdast-util-gfm-table').Options} Options
+ *   Configuration.
  */
 
 import {
@@ -24,7 +27,12 @@ import {
 } from 'mdast-util-gfm-task-list-item'
 
 /**
+ * Create an extension for `mdast-util-from-markdown` to enable GFM (autolink
+ * literals, footnotes, strikethrough, tables, tasklists).
+ *
  * @returns {Array<FromMarkdownExtension>}
+ *   Extension for `mdast-util-from-markdown` to enable GFM (autolink literals,
+ *   footnotes, strikethrough, tables, tasklists).
  */
 export function gfmFromMarkdown() {
   return [
@@ -37,8 +45,14 @@ export function gfmFromMarkdown() {
 }
 
 /**
- * @param {Options} [options]
+ * Create an extension for `mdast-util-to-markdown` to enable GFM (autolink
+ * literals, footnotes, strikethrough, tables, tasklists).
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration.
  * @returns {ToMarkdownExtension}
+ *   Extension for `mdast-util-to-markdown` to enable GFM (autolink literals,
+ *   footnotes, strikethrough, tables, tasklists).
  */
 export function gfmToMarkdown(options) {
   return {

package.json

@@ -82,11 +82,19 @@
     "trailingComma": "none"
   },
   "xo": {
-    "prettier": true
+    "prettier": true,
+    "overrides": [
+      {
+        "files": "test/**/*.js",
+        "rules": {
+          "no-await-in-loop": "off"
+        }
+      }
+    ]
   },
   "remarkConfig": {
     "plugins": [
-      "preset-wooorm"
+      "remark-preset-wooorm"
     ]
   },
   "typeCoverage": {

script/crawl-tests.js

@@ -1,11 +1,12 @@
 import assert from 'node:assert/strict'
 import fs from 'node:fs'
-import path from 'node:path'
 import fetch from 'node-fetch'
 
 const response = await fetch(
   'https://api.github.com/repos/micromark/micromark-extension-gfm/contents/test/spec.js',
   {headers: {Accept: 'application/vnd.github.v3.raw'}}
 )
 assert(response.body, 'expected body')
-response.body.pipe(fs.createWriteStream(path.join('test', 'spec.js')))
+response.body.pipe(
+  fs.createWriteStream(new URL('../test/spec.js', import.meta.url))
+)

test/index.js

@@ -1,6 +1,5 @@
 import assert from 'node:assert/strict'
-import fs from 'node:fs'
-import path from 'node:path'
+import fs from 'node:fs/promises'
 import test from 'tape'
 import {slug} from 'github-slugger'
 import {toHast} from 'mdast-util-to-hast'
@@ -11,55 +10,60 @@ import {gfm} from 'micromark-extension-gfm'
 import {gfmFromMarkdown, gfmToMarkdown} from '../index.js'
 import {spec} from './spec.js'
 
-test('markdown -> mdast', (t) => {
+test('markdown -> mdast', async (t) => {
   const files = spec.filter(
     (example) => !/disallowed raw html/i.test(example.category)
   )
   let index = -1
 
   while (++index < files.length) {
     const example = files[index]
-    const category = slug(example.category)
-    const name = index + '-' + category
-    const fixtureHtmlPath = path.join('test', name + '.html')
-    const fixtureMarkdownPath = path.join('test', name + '.md')
-
+    const name = index + '-' + slug(example.category)
     const mdast = fromMarkdown(example.input, {
       extensions: [gfm()],
       mdastExtensions: [gfmFromMarkdown()]
     })
 
     const hast = toHast(mdast, {allowDangerousHtml: true})
     assert(hast, 'expected node')
-
-    const html = toHtml(hast, {
+    const actualHtml = toHtml(hast, {
       allowDangerousHtml: true,
       entities: {useNamedReferences: true},
       closeSelfClosing: true
     })
 
     /** @type {string} */
-    let fixtureHtml
+    let expectedHtml
     /** @type {string} */
-    let fixtureMarkdown
+    let expectedMarkdown
+    const expectedUrl = new URL(name + '.html', import.meta.url)
+    const inputUrl = new URL(name + '.md', import.meta.url)
 
     try {
-      fixtureHtml = String(fs.readFileSync(fixtureHtmlPath))
+      expectedHtml = String(await fs.readFile(expectedUrl))
     } catch {
-      fixtureHtml = example.output.slice(0, -1)
+      expectedHtml = example.output.slice(0, -1)
     }
 
-    const md = toMarkdown(mdast, {extensions: [gfmToMarkdown()]})
+    const actualMarkdown = toMarkdown(mdast, {extensions: [gfmToMarkdown()]})
 
     try {
-      fixtureMarkdown = String(fs.readFileSync(fixtureMarkdownPath))
+      expectedMarkdown = String(await fs.readFile(inputUrl))
     } catch {
-      fixtureMarkdown = md
-      fs.writeFileSync(fixtureMarkdownPath, fixtureMarkdown)
+      expectedMarkdown = actualMarkdown
+      await fs.writeFile(inputUrl, expectedMarkdown)
     }
 
-    t.deepEqual(html, fixtureHtml, category + ' (' + index + ') -> html')
-    t.equal(md, fixtureMarkdown, category + ' (' + index + ') -> md')
+    t.deepEqual(
+      actualHtml,
+      expectedHtml,
+      example.category + ' (' + index + ') -> html'
+    )
+    t.equal(
+      actualMarkdown,
+      expectedMarkdown,
+      example.category + ' (' + index + ') -> md'
+    )
   }
 
   t.end()