Update @types/hast, unified, utilities, etc

index.js

@@ -1,6 +1 @@
-/**
- * @typedef {import('./lib/index.js').Parser} Parser
- * @typedef {import('./lib/index.js').Processor} Processor
- */
-
 export {default} from './lib/index.js'

lib/index.js

@@ -1,10 +1,16 @@
 /**
- * @typedef {import('unist').Node} Node
  * @typedef {import('hast').Root} HastRoot
- * @typedef {import('hast-util-to-nlcst/lib/index.js').ParserInstance} ParserInstance
- * @typedef {import('hast-util-to-nlcst/lib/index.js').ParserConstructor} ParserConstructor
- * @typedef {import('unified').Processor<any, any, any, any>} Processor
- * @typedef {import('unified').Parser<any>} Parser
+ * @typedef {import('hast-util-to-nlcst').ParserConstructor} ParserConstructor
+ * @typedef {import('hast-util-to-nlcst').ParserInstance} ParserInstance
+ * @typedef {import('nlcst').Root} NlcstRoot
+ * @typedef {import('unified').Processor<NlcstRoot>} Processor
+ * @typedef {import('unified').Transformer<HastRoot>} TransformBridge
+ * @typedef {import('unified').Transformer<HastRoot, NlcstRoot>} TransformMutate
+ * @typedef {import('vfile').VFile} VFile
+ */
+
+/**
+ * @typedef {ParserConstructor | ParserInstance} ToNlcstParser
  */
 
 import {toNlcst} from 'hast-util-to-nlcst'
@@ -17,61 +23,67 @@ import {toNlcst} from 'hast-util-to-nlcst'
  * If a parser is given, returns the nlcst tree: further plugins run on that
  * tree (mutate-mode).
  *
- * @param options
- *   Either a processor (`unified().use(retextEnglish)…`) or a parser.
- */
-const rehypeRetext =
-  /**
-   * @type {(import('unified').Plugin<[Processor], HastRoot, HastRoot> & import('unified').Plugin<[Parser], HastRoot, Node>)}
-   */
-  (
-    /**
-     * @param {Processor|Parser} destination
-     */
-    function (destination) {
-      return destination && 'run' in destination
-        ? // @ts-expect-error: to do.
-          bridge(destination)
-        : // @ts-expect-error: to do.
-          mutate(destination)
-    }
-  )
-
-export default rehypeRetext
-
-/**
- * Mutate-mode.
- * Further transformers run on the nlcst tree.
+ * @overload
+ * @param {Processor} processor
+ * @returns {TransformBridge}
  *
- * @type {import('unified').Plugin<[Parser], HastRoot, Node>}
+ * @overload
+ * @param {ToNlcstParser} parser
+ * @returns {TransformMutate}
+ *
+ * @param {ToNlcstParser | Processor} options
+ *   Parser or processor.
+ * @returns {TransformBridge | TransformMutate}
+ *   Transform.
  */
-function mutate(parser) {
-  if (!parser) {
+export default function rehypeRetext(options) {
+  if (!options) {
     throw new Error(
-      'Expected `parser` (such as from `retext-english` or `parse-english`) or `processor` (a unified pipeline) as `options`'
+      'Expected `parser` (such as from `parse-english`) or `processor` (a unified pipeline) as `options`'
     )
   }
 
-  // Assume the parser is a retext parser.
-  const Parser = /** @type {ParserInstance|ParserConstructor} */ (parser)
-  return (node, file) => toNlcst(node, file, Parser)
-}
+  if ('run' in options) {
+    /**
+     * Bridge-mode.
+     *
+     * Runs the destination with the new nlcst tree.
+     * Discards result.
+     *
+     * @param {HastRoot} tree
+     *   Tree.
+     * @param {VFile} file
+     *   File.
+     * @returns {Promise<undefined>}
+     *   Nothing.
+     * @satisfies {TransformBridge}
+     */
+    return async function (tree, file) {
+      const frozen = options.freeze()
+      // @ts-expect-error: assume the parser is a retext parser.
+      const parser = /** @type {ParserConstructor | ParserInstance} */ (
+        frozen.parser || frozen.Parser
+      )
+      const nlcstTree = toNlcst(tree, file, parser)
 
-/**
- * Bridge-mode.
- * Runs the destination with the new nlcst tree.
- *
- * @type {import('unified').Plugin<[Processor], HastRoot>}
- */
-function bridge(destination) {
-  return (node, file, next) => {
-    // Assume the parser is a retext parser.
-    const Parser = /** @type {ParserInstance|ParserConstructor} */ (
-      destination.freeze().Parser
-    )
+      await options.run(nlcstTree, file)
+    }
+  }
 
-    destination.run(toNlcst(node, file, Parser), file, (error) => {
-      next(error)
-    })
+  /**
+   * Mutate-mode.
+   *
+   * Further transformers run on the nlcst tree.
+   *
+   * @param {HastRoot} tree
+   *   Tree.
+   * @param {VFile} file
+   *   File.
+   * @returns {NlcstRoot}
+   *   Nothing.
+   * @satisfies {TransformMutate}
+   */
+  return function (tree, file) {
+    return toNlcst(tree, file, options)
   }
 }

package.json

@@ -35,17 +35,19 @@
     "index.js"
   ],
   "dependencies": {
-    "@types/hast": "^2.0.0",
-    "@types/unist": "^2.0.0",
-    "hast-util-to-nlcst": "^2.0.0",
-    "unified": "^10.0.0"
+    "@types/hast": "^3.0.0",
+    "@types/nlcst": "^2.0.0",
+    "hast-util-to-nlcst": "^4.0.0",
+    "unified": "^11.0.0",
+    "vfile": "^6.0.0"
   },
   "devDependencies": {
     "@types/tape": "^5.0.0",
     "c8": "^8.0.0",
+    "parse-english": "^7.0.0",
     "prettier": "^3.0.0",
-    "rehype-parse": "^8.0.0",
-    "rehype-stringify": "^9.0.0",
+    "rehype-parse": "^9.0.0",
+    "rehype-stringify": "^10.0.0",
     "remark-cli": "^11.0.0",
     "remark-preset-wooorm": "^9.0.0",
     "retext-english": "^4.0.0",

test.js

@@ -1,7 +1,8 @@
 import test from 'tape'
 import {unified} from 'unified'
 import rehypeParse from 'rehype-parse'
-import retextEnglish, {Parser as RetextEnglish} from 'retext-english'
+import {ParseEnglish} from 'parse-english'
+import retextEnglish from 'retext-english'
 import rehypeStringify from 'rehype-stringify'
 import retextStringify from 'retext-stringify'
 import rehypeRetext from './index.js'
@@ -19,34 +20,37 @@ const doc = [
   '</html>'
 ].join('\n')
 
-test('rehypeRetext', (t) => {
+test('rehypeRetext', async (t) => {
   t.throws(
     () => {
       // @ts-expect-error: runtime.
       unified().use(rehypeRetext).freeze()
     },
-    /Expected `parser` \(such as from `retext-english` or `parse-english`\) or `processor` \(a unified pipeline\) as `options`/,
+    /Expected `parser` \(such as from `parse-english`\) or `processor` \(a unified pipeline\) as `options`/,
     'should throw when w/o parser or processor'
   )
 
   t.equal(
     unified()
       .use(rehypeParse, {fragment: true})
-      .use(rehypeRetext, RetextEnglish)
+      .use(rehypeRetext, ParseEnglish)
+      // @ts-expect-error: to do: remove this when `retext-stringify` is released.
       .use(retextStringify)
       .processSync(doc)
       .toString(),
     'Bravo',
     'should mutate'
   )
 
+  const file = await unified()
+    .use(rehypeParse)
+    // @ts-expect-error: to do: remove this when `retext-stringify` is released, hopefully.
+    .use(rehypeRetext, unified().use(retextEnglish))
+    .use(rehypeStringify)
+    .process(doc)
+
   t.equal(
-    unified()
-      .use(rehypeParse)
-      .use(rehypeRetext, unified().use(retextEnglish))
-      .use(rehypeStringify)
-      .processSync(doc)
-      .toString(),
+    file.toString(),
     [
       '<!doctype html><html><head>',
       '    <meta charset="utf8">',