Remove support for file as parameter

Please pass it in `options` instead.

Author: wooorm

lib/index.js

@@ -28,11 +28,13 @@
  *
  * @typedef Options
  *   Configuration.
- * @property {Array<string>} [passThrough]
+ * @property {Array<string> | null | undefined} [passThrough]
  *   List of custom hast node types to pass through (keep) in hast.
  *
  *   If the passed through nodes have children, those children are expected to
- *   be hast and will be handled.
+ *   be hast again and will be handled.
+ * @property {VFile | null | undefined} [file]
+ *   Corresponding virtual file.
  *
  * @typedef State
  *   Info passed around about the current state.
@@ -42,8 +44,6 @@
  *   Add a hast node to the parser.
  * @property {boolean} stitches
  *   Whether there are stitches.
- * @property {VFile | undefined} file
- *   Virtual file.
  * @property {Options} options
  *   User configuration.
  */
@@ -61,88 +61,67 @@ import {zwitch} from 'zwitch'
 const parseOptions = {sourceCodeLocationInfo: true, scriptingEnabled: false}
 
 /**
- * Given a hast tree and an optional vfile (for positional info), return a new
- * parsed-again hast tree.
+ * Pass a hast tree through an HTML parser, which will fix nesting, and
+ * turn raw nodes into actual nodes.
  *
- * @param tree
- *   Original hast tree.
- * @param file
- *   Virtual file for positional info, optional.
- * @param options
+ * @param {Node} tree
+ *   Original hast tree to transform.
+ * @param {Options | null | undefined} [options]
  *   Configuration.
+ * @returns {Node}
+ *   Parsed again tree.
  */
-// To do: remove support for overload.
-export const raw =
-  /**
-   * @type {(
-   *   ((tree: Node, file: VFile | null | undefined, options?: Options) => Node) &
-   *   ((tree: Node, options?: Options) => Node)
-   * )}
-   */
-  (
-    /**
-     * @param {Node} tree
-     * @param {VFile | Options | null | undefined} [file]
-     * @param {Options | null | undefined} [options]
-     */
-    function (tree, file, options) {
-      if (isOptions(file)) {
-        options = file
-        file = undefined
-      }
-
-      const document = documentMode(tree)
-      /** @type {(node: Node, state: State) => void} */
-      const one = zwitch('type', {
-        handlers: {root, element, text, comment, doctype, raw: handleRaw},
-        unknown
-      })
-
-      /** @type {State} */
-      const state = {
-        parser: document
-          ? new Parser(parseOptions)
-          : Parser.getFragmentParser(null, parseOptions),
-        handle(node) {
-          one(node, state)
-        },
-        stitches: false,
-        file: file || undefined,
-        options: options || {}
-      }
+export function raw(tree, options) {
+  const document = documentMode(tree)
+  /** @type {(node: Node, state: State) => void} */
+  const one = zwitch('type', {
+    handlers: {root, element, text, comment, doctype, raw: handleRaw},
+    unknown
+  })
+
+  /** @type {State} */
+  const state = {
+    parser: document
+      ? new Parser(parseOptions)
+      : Parser.getFragmentParser(null, parseOptions),
+    handle(node) {
+      one(node, state)
+    },
+    stitches: false,
+    options: options || {}
+  }
 
-      one(tree, state)
-      resetTokenizer(state, pointStart())
-
-      const p5 = document ? state.parser.document : state.parser.getFragment()
-      const result = fromParse5(p5, {
-        // To do: support `space`?
-        file
-      })
-
-      if (state.stitches) {
-        visit(result, 'comment', (node, index, parent) => {
-          const stitch = /** @type {Stitch} */ (/** @type {unknown} */ (node))
-          if (stitch.value.stitch && parent !== null && index !== null) {
-            // @ts-expect-error: assume the stitch is allowed.
-            parent.children[index] = stitch.value.stitch
-            return index
-          }
-        })
+  one(tree, state)
+  resetTokenizer(state, pointStart())
+
+  const p5 = document ? state.parser.document : state.parser.getFragment()
+  const result = fromParse5(p5, {
+    // To do: support `space`?
+    file: state.options.file
+  })
+
+  if (state.stitches) {
+    visit(result, 'comment', (node, index, parent) => {
+      const stitch = /** @type {Stitch} */ (/** @type {unknown} */ (node))
+      if (stitch.value.stitch && parent !== null && index !== null) {
+        // @ts-expect-error: assume the stitch is allowed.
+        parent.children[index] = stitch.value.stitch
+        return index
       }
+    })
+  }
 
-      // Unpack if possible and when not given a `root`.
-      if (
-        tree.type !== 'root' &&
-        result.type === 'root' &&
-        result.children.length === 1
-      ) {
-        return result.children[0]
-      }
+  // Unpack if possible and when not given a `root`.
+  if (
+    tree.type !== 'root' &&
+    result.type === 'root' &&
+    result.children.length === 1
+  ) {
+    return result.children[0]
+  }
 
-      return result
-    }
-  )
+  return result
+}
 
 /**
  * Transform all nodes
@@ -288,11 +267,7 @@ function stitch(node, state) {
   // Recurse, because to somewhat handle `[<x>]</x>` (where `[]` denotes the
   // passed through node).
   if ('children' in node && 'children' in clone) {
-    const fakeRoot = raw(
-      {type: 'root', children: node.children},
-      state.file,
-      state.options
-    )
+    const fakeRoot = raw({type: 'root', children: node.children}, state.options)
     // @ts-expect-error Assume a given parent yields a parent.
     clone.children = fakeRoot.children
   }
@@ -626,18 +601,6 @@ function createParse5Location(node) {
   }
 }
 
-/**
- * Check if `value` is an options object.
- *
- * @param {VFile | Options | null | undefined} value
- *   Thing.
- * @return {value is Options}
- *   Whether `value` is an options object.
- */
-function isOptions(value) {
-  return Boolean(value && !('message' in value && 'messages' in value))
-}
-
 /**
  * @template {Node} NodeType
  *   Node type.

test.js

@@ -337,7 +337,7 @@ test('integration', () => {
   const mdast = fromMarkdown(doc)
   const hast = toHast(mdast, {allowDangerousHtml: true})
   assert(hast, 'should transform to hast')
-  const hast2 = raw(hast, new VFile(doc))
+  const hast2 = raw(hast, {file: new VFile(doc)})
 
   assert.deepEqual(
     hast2,