Refactor code-style

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

Author: wooorm

lib/index.js

@@ -1,13 +1,27 @@
 /**
  * @typedef {import('hast').Root} Root
  * @typedef {import('vfile').VFileCompatible} VFileCompatible
- * @typedef {Pick<import('hast-util-from-parse5').Options, 'space'|'verbose'>} FromParse5Options
+ */
+
+/**
+ * @typedef {Pick<import('hast-util-from-parse5').Options, 'space' | 'verbose'>} FromParse5Options
  *
  * @typedef {keyof errors} ErrorCode
- * @typedef {0|1|2|boolean|null|undefined} ErrorSeverity
- * @typedef {Partial<Record<ErrorCode, ErrorSeverity>>} ErrorFields
+ *   Known names of parse errors.
+ * @typedef {0 | 1 | 2 | boolean} ErrorSeverity
+ *   Error severity:
+ *
+ *   * `0` or `false`
+ *     — turn the parse error off
+ *   * `1` or `true`
+ *     — turn the parse error into a warning
+ *   * `2`
+ *     — turn the parse error into an actual error: processing stops.
+ * @typedef {Partial<Record<ErrorCode, ErrorSeverity | null | undefined>>} ErrorFields
+ *   Error configuration.
  *
  * @typedef Error
+ *   Error from `parse5`.
  * @property {string} code
  * @property {number} startLine
  * @property {number} startCol
@@ -17,27 +31,34 @@
  * @property {number} endOffset
  *
  * @callback OnError
+ *   Handle errors.
  * @param {VFileMessage} error
+ *   Message.
  * @returns {void}
+ *   Nothing.
  *
  * @typedef ParseFields
- * @property {boolean|undefined} [fragment=false]
+ * @property {boolean | null | undefined} [fragment=false]
  *   Specify whether to parse a fragment, instead of a complete document.
+ *
  *   In document mode, unopened `html`, `head`, and `body` elements are opened
  *   in just the right places.
- * @property {OnError|undefined} [onerror=false]
+ * @property {OnError | null | undefined} [onerror]
+ *   Call `onerror` with parse errors while parsing.
+ *
  *   > 👉 **Note**: parse errors are currently being added to HTML.
  *   > Not all errors emitted by parse5 (or us) are specced yet.
  *   > Some documentation may still be missing.
  *
- *   Call `onerror` with parse errors while parsing.
- *
  *   Specific rules can be turned off by setting them to `false` (or `0`).
  *   The default, when `emitParseErrors: true`, is `true` (or `1`), and means
  *   that rules emit as warnings.
  *   Rules can also be configured with `2`, to turn them into fatal errors.
- *
+ */
+
+/**
  * @typedef {FromParse5Options & ParseFields & ErrorFields} Options
+ *   Configuration.
  */
 
 import {parse, parseFragment} from 'parse5'
@@ -51,27 +72,33 @@ const base = 'https://html.spec.whatwg.org/multipage/parsing.html#parse-error-'
 const fatalities = {2: true, 1: false, 0: null}
 
 /**
+ * Turn serialized HTML into a hast tree.
+ *
  * @param {VFileCompatible} value
- * @param {Options} [options={}]
+ *   Serialized HTML to parse.
+ * @param {Options | null | undefined} [options={}]
+ *   Configuration (optional).
  * @returns {Root}
+ *   Tree.
  */
-export function fromHtml(value, options = {}) {
-  const warn = options.onerror || null
+export function fromHtml(value, options) {
+  const settings = options || {}
+  const warn = settings.onerror || null
   const file = value instanceof VFile ? value : new VFile(value)
-  const fn = options.fragment ? parseFragment : parse
+  const fn = settings.fragment ? parseFragment : parse
   const doc = String(file)
   const p5doc = fn(doc, {
     sourceCodeLocationInfo: true,
-    onParseError: options.onerror ? onerror : null,
+    onParseError: settings.onerror ? onerror : null,
     scriptingEnabled: false
   })
 
   // @ts-expect-error: `parse5` returns document or fragment, which are always
   // mapped to roots.
   return fromParse5(p5doc, {
     file,
-    space: options.space,
-    verbose: options.verbose
+    space: settings.space,
+    verbose: settings.verbose
   })
 
   /**
@@ -80,7 +107,7 @@ export function fromHtml(value, options = {}) {
   function onerror(error) {
     const code = error.code
     const name = camelcase(code)
-    const setting = options[name]
+    const setting = settings[name]
     const config = setting === undefined || setting === null ? true : setting
     const level = typeof config === 'number' ? config : config ? 1 : 0
     const start = {

test/index.js

@@ -3,7 +3,6 @@
  */
 
 import fs from 'node:fs/promises'
-import path from 'node:path'
 import test from 'tape'
 import {VFile} from 'vfile'
 import {toVFile, read} from 'to-vfile'
@@ -321,7 +320,7 @@ test('parse errors: coverage', async (t) => {
 
 test('parse-errors: working', async (t) => {
   let index = -1
-  const root = path.join('test', 'parse-error')
+  const root = new URL('parse-error/', import.meta.url)
   const fixtures = await fs.readdir(root)
 
   t.test('surrogate-in-input-stream', (t) => {
@@ -379,15 +378,13 @@ test('parse-errors: working', async (t) => {
       return
     }
 
-    const fp = path.join(root, fixture)
-
     setImmediate(next) // Queue next.
 
     t.test(fixture, async (t) => {
-      const file = await read(path.join(fp, 'index.html'), 'utf8')
+      const file = await read(new URL(fixture + '/index.html', root), 'utf8')
       /** @type {Array<Error>} */
       const messages = JSON.parse(
-        String(await fs.readFile(path.join(fp, 'messages.json')))
+        String(await fs.readFile(new URL(fixture + '/messages.json', root)))
       )
 
       file.dirname = ''