Refactor code-style

.gitignore

@@ -1,12 +1,8 @@
 coverage/
 node_modules/
-packages/rehype/*.d.ts
-packages/rehype-cli/*.d.ts
-packages/rehype-parse/lib/*.d.ts
-packages/rehype-stringify/lib/*.d.ts
-script/*.d.ts
-test/*.d.ts
-.DS_Store
+*.d.ts
 *.log
-tsconfig.tsbuildinfo
+.DS_Store
 yarn.lock
+!packages/rehype-parse/index.d.ts
+!packages/rehype-stringify/index.d.ts

package.json

@@ -18,19 +18,16 @@
   ],
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "bail": "^2.0.0",
     "c8": "^8.0.0",
     "hast-util-assert": "^4.0.0",
     "prettier": "^3.0.0",
     "remark-cli": "^11.0.0",
     "remark-preset-wooorm": "^9.0.0",
-    "to-vfile": "^8.0.0",
     "type-coverage": "^2.0.0",
-    "type-fest": "^4.0.0",
     "typescript": "^5.0.0",
     "unified": "^11.0.0",
-    "unist-builder": "^4.0.0",
     "unist-util-remove-position": "^5.0.0",
+    "vfile": "^6.0.0",
     "xo": "^0.56.0"
   },
   "scripts": {
@@ -61,6 +58,14 @@
   },
   "xo": {
     "overrides": [
+      {
+        "files": [
+          "test/**/*.js"
+        ],
+        "rules": {
+          "no-await-in-loop": "off"
+        }
+      },
       {
         "files": [
           "**/*.ts"
@@ -72,6 +77,7 @@
     ],
     "prettier": true,
     "rules": {
+      "unicorn/no-this-assignment": "off",
       "unicorn/prefer-code-point": "off",
       "unicorn/prefer-string-replace-all": "off"
     }

packages/rehype-cli/cli.js

@@ -2,9 +2,13 @@
 
 /**
  * @typedef Pack
+ *   Minimum `package.json`.
  * @property {string} name
+ *   Name.
  * @property {string} version
+ *   Version.
  * @property {string} description
+ *   Description.
  */
 
 import fs from 'node:fs/promises'
@@ -25,16 +29,16 @@ const cli = JSON.parse(
 )
 
 args({
-  processor: rehype,
-  name: proc.name,
   description: cli.description,
+  extensions: ['html', 'htm', 'xht', 'xhtml'],
+  ignoreName: '.' + proc.name + 'ignore',
+  name: proc.name,
+  packageField: proc.name,
+  pluginPrefix: proc.name,
+  processor: rehype,
+  rcName: '.' + proc.name + 'rc',
   version: [
     proc.name + ': ' + proc.version,
     cli.name + ': ' + cli.version
-  ].join(', '),
-  pluginPrefix: proc.name,
-  packageField: proc.name,
-  rcName: '.' + proc.name + 'rc',
-  ignoreName: '.' + proc.name + 'ignore',
-  extensions: ['html', 'htm', 'xht', 'xhtml']
+  ].join(', ')
 })

packages/rehype-parse/index.d.ts

@@ -1,10 +1,19 @@
-// This wrapper exists because JS in TS can’t export a `@type` of a function.
 import type {Root} from 'hast'
 import type {Plugin} from 'unified'
 import type {Options} from './lib/index.js'
 
 export type {ErrorCode, ErrorSeverity} from 'hast-util-from-html'
 export type {Options} from './lib/index.js'
 
+/**
+ * Plugin to add support for parsing from HTML.
+ *
+ * @this
+ *   Unified processor.
+ * @param
+ *   Configuration (optional).
+ * @returns
+ *   Nothing.
+ */
 declare const rehypeParse: Plugin<[(Options | null | undefined)?], string, Root>
 export default rehypeParse

packages/rehype-parse/index.js

@@ -1 +1,2 @@
+// Note: types exposed from `index.d.ts`.
 export {default} from './lib/index.js'

packages/rehype-parse/lib/index.js

@@ -1,11 +1,12 @@
 /**
  * @typedef {import('hast').Root} Root
  * @typedef {import('hast-util-from-html').Options} FromHtmlOptions
+ * @typedef {import('unified').Parser<Root>} Parser
  */
 
 /**
  * @typedef {Omit<FromHtmlOptions, 'onerror'> & RehypeParseFields} Options
- *   Options.
+ *   Configuration.
  *
  * @typedef RehypeParseFields
  *   Extra fields.
@@ -20,20 +21,29 @@
 import {fromHtml} from 'hast-util-from-html'
 
 /**
- * @this {import('unified').Processor}
- * @type {import('unified').Plugin<[(Options | null | undefined)?], string, Root>}
+ * Plugin to add support for parsing from HTML.
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {undefined}
+ *   Nothing.
  */
 export default function rehypeParse(options) {
-  const processorSettings = /** @type {Options} */ (this.data('settings'))
-  const settings = Object.assign({}, processorSettings, options)
+  /** @type {import('unified').Processor<Root>} */
+  // @ts-expect-error: TS in JSDoc generates wrong types if `this` is typed regularly.
+  const self = this
+  const processorSettings = /** @type {Options} */ (self.data('settings'))
+  const {emitParseErrors, ...settings} = {...processorSettings, ...options}
 
-  Object.assign(this, {Parser: parser})
+  self.parser = parser
 
-  /** @type {import('unified').Parser<Root>} */
+  /**
+   * @type {Parser}
+   */
   function parser(doc, file) {
     return fromHtml(doc, {
       ...settings,
-      onerror: settings.emitParseErrors
+      onerror: emitParseErrors
         ? function (message) {
             if (file.path) {
               message.name = file.path + ':' + message.name

packages/rehype-stringify/index.d.ts

@@ -1,11 +1,19 @@
-// This wrapper exists because JS in TS can’t export a `@type` of a function.
 import type {Root} from 'hast'
 import type {Plugin} from 'unified'
 import type {Options} from './lib/index.js'
 
 export type {Options} from './lib/index.js'
-// Note: defining all nodes here, such as with `Root | Element | ...` seems
-// to trip TS up.
+
+/**
+ * Plugin to add support for serializing as HTML.
+ *
+ * @this
+ *   Unified processor.
+ * @param
+ *   Configuration (optional).
+ * @returns
+ *   Nothing.
+ */
 declare const rehypeStringify: Plugin<
   [(Options | null | undefined)?],
   Root,

packages/rehype-stringify/index.js

@@ -1 +1,2 @@
+// Note: types exposed from `index.d.ts`.
 export {default} from './lib/index.js'

packages/rehype-stringify/lib/index.js

@@ -1,23 +1,30 @@
 /**
  * @typedef {import('hast').Root} Root
- * @typedef {Root|Root['children'][number]} Node
  * @typedef {import('hast-util-to-html').Options} Options
+ * @typedef {import('unified').Compiler<Root, string>} Compiler
  */
 
 import {toHtml} from 'hast-util-to-html'
 
 /**
- * @this {import('unified').Processor}
- * @type {import('unified').Plugin<[(Options | null | undefined)?], Node, string>}
+ * Plugin to add support for serializing as HTML.
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {undefined}
+ *   Nothing.
  */
-export default function rehypeStringify(config) {
-  const processorSettings = /** @type {Options} */ (this.data('settings'))
-  const settings = Object.assign({}, processorSettings, config)
+export default function rehypeStringify(options) {
+  /** @type {import('unified').Processor<undefined, undefined, undefined, Root, string>} */
+  // @ts-expect-error: TS in JSDoc generates wrong types if `this` is typed regularly.
+  const self = this
+  const processorSettings = /** @type {Options} */ (self.data('settings'))
+  const settings = {...processorSettings, ...options}
 
-  Object.assign(this, {Compiler: compiler})
+  self.compiler = compiler
 
   /**
-   * @type {import('unified').Compiler<Node, string>}
+   * @type {Compiler}
    */
   function compiler(tree) {
     return toHtml(tree, settings)

packages/rehype/index.js

@@ -1,5 +1,8 @@
-import {unified} from 'unified'
 import rehypeParse from 'rehype-parse'
 import rehypeStringify from 'rehype-stringify'
+import {unified} from 'unified'
 
+/**
+ * Processor for HTML.
+ */
 export const rehype = unified().use(rehypeParse).use(rehypeStringify).freeze()

packages/rehype/readme.md

@@ -147,7 +147,7 @@ main()
 
 async function main() {
   const file = await rehype()
-    .data('settings', {fragment: true, emitParseErrors: true, preferUnquoted: true})
+    .data('settings', {emitParseErrors: true, fragment: true, preferUnquoted: true})
     .process('<div title="a" title="b"></div>')
 
   console.error(reporter(file))

readme.md

@@ -78,8 +78,8 @@ import {visit} from 'unist-util-visit'
 
 /** @type {import('unified').Plugin<[], import('hast').Root>} */
 function myRehypePluginToIncreaseHeadings() {
-  return (tree) => {
-    visit(tree, 'element', (node) => {
+  return function (tree) {
+    visit(tree, 'element', function (node) {
       if (['h1', 'h2', 'h3', 'h4', 'h5'].includes(node.tagName)) {
         node.tagName = 'h' + (Number(node.tagName.charAt(1)) + 1)
       }