Refactor types

Author: wooorm

.gitignore

@@ -4,4 +4,6 @@
 coverage/
 node_modules/
 yarn.lock
-test/error-codes-from-p5.js
+/test/error-codes-from-p5.js
+!/lib/types.d.ts
+!/index.d.ts

index.d.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference -- needed to register data.
+/// <reference types="hast-util-from-parse5" />
+export {fromHtml} from './lib/index.js'
+export type {ErrorCode, ErrorSeverity, OnError, Options} from './lib/types.js'

index.js

@@ -1,10 +1,2 @@
-/**
- * @typedef {import('hast-util-from-parse5')} DoNotTouchItRegistersData
- *
- * @typedef {import('./lib/index.js').ErrorCode} ErrorCode
- * @typedef {import('./lib/index.js').ErrorSeverity} ErrorSeverity
- * @typedef {import('./lib/index.js').OnError} OnError
- * @typedef {import('./lib/index.js').Options} Options
- */
-
+// Note: types exposed from `index.d.ts`.
 export {fromHtml} from './lib/index.js'

lib/index.js

@@ -1,60 +1,8 @@
 /**
- * @typedef {import('hast').Root} Root
- * @typedef {import('parse5').ParserError} ParserError
- * @typedef {import('vfile').Value} Value
- */
-
-/**
- * @typedef {keyof errors} ErrorCode
- *   Known names of parse errors.
- *
- * @typedef {Partial<Record<ErrorCode, ErrorSeverity | null | undefined>>} ErrorOptions
- *   Options that define the severity of errors.
- *
- * @typedef {boolean | 0 | 1 | 2} 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 ExtraOptions
- *   Options that define how to parse HTML.
- * @property {boolean | null | undefined} [fragment=false]
- *   Specify whether to parse a fragment, instead of a complete document
- *   (default: `false`).
- *
- *   In document mode, unopened `html`, `head`, and `body` elements are opened
- *   in just the right places.
- * @property {OnError | null | undefined} [onerror]
- *   Call `onerror` with parse errors while parsing (optional).
- *
- *   > 👉 **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.
- *
- *   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 {Omit<import('hast-util-from-parse5').Options, 'file'>} FromParse5Options
- *   Options that can be passed through to `hast-util-from-parse5`.
- *
- * @callback OnError
- *   Handle parse errors.
- * @param {VFileMessage} error
- *   Message.
- * @returns {undefined | void}
- *   Nothing.
- *
- *   Note: `void` included until TS infers `undefined` nicely.
- *
- * @typedef {FromParse5Options & ErrorOptions & ExtraOptions} Options
- *   Configuration.
+ * @import {Root} from 'hast'
+ * @import {ParserError} from 'parse5'
+ * @import {Value} from 'vfile'
+ * @import {ErrorCode, Options} from './types.js'
  */
 
 import {ok as assert} from 'devlop'

lib/types.d.ts

@@ -0,0 +1,63 @@
+import type {VFileMessage} from 'vfile-message'
+import type {Options as FromParse5Options} from 'hast-util-from-parse5'
+import type {errors} from './errors.js'
+
+/**
+ * Known names of parse errors.
+ */
+export type ErrorCode = keyof typeof errors
+
+/**
+ * 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.
+ */
+export type ErrorSeverity = boolean | 0 | 1 | 2
+
+/**
+ * Handle parse errors.
+ */
+export type OnError = (error: VFileMessage) => undefined | void
+
+/**
+ * Options that define the severity of errors.
+ */
+export type ErrorOptions = Partial<
+  Record<ErrorCode, ErrorSeverity | null | undefined>
+>
+
+/**
+ * Configuration.
+ */
+export interface Options extends ErrorOptions, FromParse5Options {
+  /**
+   * The `file` field from `hast-util-from-parse5` is not supported.
+   */
+  file?: never
+  /**
+   * Specify whether to parse a fragment, instead of a complete document
+   * (default: `false`).
+   *
+   * In document mode, unopened `html`, `head`, and `body` elements are opened
+   * in just the right places.
+   */
+  fragment?: boolean | null | undefined
+  /**
+   * Call `onerror` with parse errors while parsing (optional).
+   *
+   * > 👉 **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.
+   *
+   * 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.
+   */
+  onerror?: OnError | null | undefined
+}

lib/types.js

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

script/parse-error.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import('mdast').Root} Root
- * @typedef {import('mdast').ListItem} ListItem
- * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ * @import {ListItem, PhrasingContent, Root} from 'mdast'
+ * @import {PackageJson} from 'type-fest'
+ * @import {Plugin} from 'unified'
  */
 
 import fs from 'node:fs/promises'
@@ -12,7 +12,7 @@ import {errors} from '../lib/errors.js'
 
 const own = {}.hasOwnProperty
 
-/** @type {import('type-fest').PackageJson} */
+/** @type {PackageJson} */
 const packageJson = JSON.parse(String(await fs.readFile('package.json')))
 
 const repo = packageJson.repository
@@ -26,7 +26,7 @@ const ignoreFixture = {
   surrogateInInputStream: true
 }
 
-/** @satisfies {import('unified').Plugin<[], Root>} */
+/** @satisfies {Plugin<[], Root>} */
 export default function remarkParseErrors() {
   /**
    * @param {Root} tree

test/index.js

@@ -1,7 +1,7 @@
 /* eslint-disable unicorn/prefer-structured-clone -- JSON is simplified */
 
 /**
- * @typedef {import('vfile-message').VFileMessage} VFileMessage
+ * @import {VFileMessage} from 'vfile-message'
  */
 
 import assert from 'node:assert/strict'

tsconfig.json

@@ -11,5 +11,5 @@
     "target": "es2022"
   },
   "exclude": ["coverage/", "node_modules/"],
-  "include": ["**/*.js"]
+  "include": ["**/*.js", "lib/types.d.ts", "index.d.ts"]
 }