Refactor code-style

Author: wooorm

lib/index.js

@@ -1,64 +1,66 @@
 /**
+ * @typedef {import('hast').Comment} Comment
+ * @typedef {import('hast').Doctype} Doctype
+ * @typedef {import('hast').Element} Element
+ * @typedef {import('hast').Nodes} Nodes
+ * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').RootContent} RootContent
+ * @typedef {import('hast').Text} Text
+ *
+ * @typedef {import('mdast-util-to-hast').Raw} Raw
+ *
  * @typedef {import('parse5').DefaultTreeAdapterMap} DefaultTreeAdapterMap
+ * @typedef {import('parse5').ParserOptions<DefaultTreeAdapterMap>} ParserOptions
  * @typedef {import('parse5').Token.CharacterToken} CharacterToken
  * @typedef {import('parse5').Token.CommentToken} CommentToken
  * @typedef {import('parse5').Token.DoctypeToken} DoctypeToken
- * @typedef {import('parse5').Token.TagToken} TagToken
  * @typedef {import('parse5').Token.Location} Location
- * @typedef {import('parse5').ParserOptions<DefaultTreeAdapterMap>} ParserOptions
- *
- * @typedef {import('vfile').VFile} VFile
+ * @typedef {import('parse5').Token.TagToken} TagToken
  *
  * @typedef {import('unist').Point} Point
  *
- * @typedef {import('hast').Root} Root
- * @typedef {import('hast').Doctype} Doctype
- * @typedef {import('hast').Element} Element
- * @typedef {import('hast').Text} Text
- * @typedef {import('hast').Comment} Comment
- * @typedef {import('hast').RootContent} RootContent
- * @typedef {import('hast').Nodes} Nodes
- *
- * @typedef {import('mdast-util-to-hast').Raw} Raw
+ * @typedef {import('vfile').VFile} VFile
  */
 
 /**
- * @typedef {{type: 'comment', value: {stitch: Nodes}}} Stitch
- *
  * @typedef Options
  *   Configuration.
+ * @property {VFile | null | undefined} [file]
+ *   Corresponding virtual file representing the input document (optional).
  * @property {Array<string> | null | undefined} [passThrough]
- *   List of custom hast node types to pass through (keep).
+ *   List of custom hast node types to pass through (as in, keep) (optional).
  *
  *   If the passed through nodes have children, those children are expected to
  *   be hast again and will be handled.
- * @property {VFile | null | undefined} [file]
- *   Corresponding virtual file representing the input document.
  *
  * @typedef State
  *   Info passed around about the current state.
+ * @property {(node: Nodes) => undefined} handle
+ *   Add a hast node to the parser.
+ * @property {Options} options
+ *   User configuration.
  * @property {Parser<DefaultTreeAdapterMap>} parser
  *   Current parser.
- * @property {(node: Nodes) => void} handle
- *   Add a hast node to the parser.
  * @property {boolean} stitches
  *   Whether there are stitches.
- * @property {Options} options
- *   User configuration.
+ *
+ * @typedef {{type: 'comment', value: {stitch: Nodes}}} Stitch
+ *   Custom comment-like value we pass through parse5, which contains a
+ *   replacement node that we’ll swap back in afterwards.
  */
 
 import extend from 'extend'
 import {fromParse5} from 'hast-util-from-parse5'
 import {toParse5} from 'hast-util-to-parse5'
 import {htmlVoidElements} from 'html-void-elements'
 import {Parser, Token, TokenizerMode, html} from 'parse5'
-import {pointStart, pointEnd} from 'unist-util-position'
+import {pointEnd, pointStart} from 'unist-util-position'
 import {visit} from 'unist-util-visit'
-import {zwitch} from 'zwitch'
 import {webNamespaces} from 'web-namespaces'
+import {zwitch} from 'zwitch'
 
 // Node types associated with MDX.
-// <https://github.com/mdx-js/mdx/blob/641eb91/packages/mdx/lib/node-types.js>
+// <https://github.com/mdx-js/mdx/blob/8a56312/packages/mdx/lib/node-types.js>
 const knownMdxNames = new Set([
   'mdxFlowExpression',
   'mdxJsxFlowElement',
@@ -77,13 +79,13 @@ const parseOptions = {sourceCodeLocationInfo: true, scriptingEnabled: false}
  * @param {Nodes} tree
  *   Original hast tree to transform.
  * @param {Options | null | undefined} [options]
- *   Configuration.
+ *   Configuration (optional).
  * @returns {Nodes}
  *   Parsed again tree.
  */
 export function raw(tree, options) {
   const document = documentMode(tree)
-  /** @type {(node: Nodes, state: State) => void} */
+  /** @type {(node: Nodes, state: State) => undefined} */
   const one = zwitch('type', {
     handlers: {root, element, text, comment, doctype, raw: handleRaw},
     unknown
@@ -93,7 +95,7 @@ export function raw(tree, options) {
   const state = {
     parser: document
       ? new Parser(parseOptions)
-      : Parser.getFragmentParser(null, parseOptions),
+      : Parser.getFragmentParser(undefined, parseOptions),
     handle(node) {
       one(node, state)
     },
@@ -111,11 +113,13 @@ export function raw(tree, options) {
   })
 
   if (state.stitches) {
-    visit(result, 'comment', (node, index, parent) => {
+    visit(result, 'comment', function (node, index, parent) {
       const stitch = /** @type {Stitch} */ (/** @type {unknown} */ (node))
-      if (stitch.value.stitch && parent !== null && index !== null) {
+      if (stitch.value.stitch && parent && index !== undefined) {
+        /** @type {Array<RootContent>} */
+        const siblings = parent.children
         // @ts-expect-error: assume the stitch is allowed.
-        parent.children[index] = stitch.value.stitch
+        siblings[index] = stitch.value.stitch
         return index
       }
     })
@@ -140,7 +144,7 @@ export function raw(tree, options) {
  *   hast content.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function all(nodes, state) {
@@ -161,7 +165,7 @@ function all(nodes, state) {
  *   hast root node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function root(node, state) {
@@ -175,7 +179,7 @@ function root(node, state) {
  *   hast element node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function element(node, state) {
@@ -193,7 +197,7 @@ function element(node, state) {
  *   hast text node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function text(node, state) {
@@ -220,7 +224,7 @@ function text(node, state) {
  *   hast doctype node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function doctype(node, state) {
@@ -250,7 +254,7 @@ function doctype(node, state) {
  *   unknown node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function stitch(node, state) {
@@ -263,8 +267,10 @@ 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.options)
-    // @ts-expect-error Assume a given parent yields a parent.
+    // Root in root out.
+    const fakeRoot = /** @type {Root} */ (
+      raw({type: 'root', children: node.children}, state.options)
+    )
     clone.children = fakeRoot.children
   }
 
@@ -281,12 +287,12 @@ function stitch(node, state) {
  *   hast comment node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function comment(node, state) {
   /** @type {string} */
-  // @ts-expect-error: yeah, we’re passing stiches through.
+  // @ts-expect-error: we pass stitches through.
   const data = node.value
 
   /** @type {CommentToken} */
@@ -311,12 +317,12 @@ function comment(node, state) {
  *   hast raw node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function handleRaw(node, state) {
   // Reset preprocessor:
-  // See: <https://github.com/inikulin/parse5/blob/8e22fe4/packages/parse5/lib/tokenizer/preprocessor.ts#L18-L31>.
+  // See: <https://github.com/inikulin/parse5/blob/6f7ca60/packages/parse5/lib/tokenizer/preprocessor.ts#L18-L31>.
   state.parser.tokenizer.preprocessor.html = ''
   // @ts-expect-error: private.
   // type-coverage:ignore-next-line
@@ -353,6 +359,8 @@ function handleRaw(node, state) {
 
   // Note: `State` is not exposed by `parse5`, so these numbers are fragile.
   // See: <https://github.com/inikulin/parse5/blob/46cba43/packages/parse5/lib/tokenizer/index.ts#L58>
+  // Note: a change to `parse5`, which breaks this, was merged but not released.
+  // Investigate when it is.
   if (
     state.parser.tokenizer.state === 72 /* NAMED_CHARACTER_REFERENCE */ ||
     state.parser.tokenizer.state === 78 /* NUMERIC_CHARACTER_REFERENCE_END */
@@ -377,7 +385,7 @@ function handleRaw(node, state) {
  *   unknown node.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Never.
  */
 function unknown(node_, state) {
@@ -407,7 +415,7 @@ function unknown(node_, state) {
  *   Info passed around about the current state.
  * @param {Point | undefined} point
  *   Point.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function resetTokenizer(state, point) {
@@ -480,7 +488,7 @@ function resetTokenizer(state, point) {
  *   Info passed around about the current state.
  * @param {Point | undefined} point
  *   Point.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function setPoint(state, point) {
@@ -513,7 +521,7 @@ function setPoint(state, point) {
  *   Element.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function startTag(node, state) {
@@ -578,7 +586,7 @@ function startTag(node, state) {
  *   Element.
  * @param {State} state
  *   Info passed around about the current state.
- * @returns {void}
+ * @returns {undefined}
  *   Nothing.
  */
 function endTag(node, state) {
@@ -663,23 +671,30 @@ function documentMode(node) {
  *   `parse5` location.
  */
 function createParse5Location(node) {
-  const start = pointStart(node)
-  const end = pointEnd(node)
-
-  return {
-    // @ts-expect-error: could be `undefined` in hast, which `parse5` types don’t want.
-    startLine: start?.line,
-    // @ts-expect-error: could be `undefined` in hast, which `parse5` types don’t want.
-    startCol: start?.column,
-    // @ts-expect-error: could be `undefined` in hast, which `parse5` types don’t want.
-    startOffset: start?.offset,
-    // @ts-expect-error: could be `undefined` in hast, which `parse5` types don’t want.
-    endLine: end?.line,
-    // @ts-expect-error: could be `undefined` in hast, which `parse5` types don’t want.
-    endCol: end?.column,
-    // @ts-expect-error: could be `undefined` in hast, which `parse5` types don’t want.
-    endOffset: end?.offset
+  const start = pointStart(node) || {
+    line: undefined,
+    column: undefined,
+    offset: undefined
+  }
+  const end = pointEnd(node) || {
+    line: undefined,
+    column: undefined,
+    offset: undefined
   }
+
+  /** @type {Record<keyof Location, number | undefined>} */
+  const location = {
+    startLine: start.line,
+    startCol: start.column,
+    startOffset: start.offset,
+    endLine: end.line,
+    endCol: end.column,
+    endOffset: end.offset
+  }
+
+  // @ts-expect-error: unist point values can be `undefined` in hast, which
+  // `parse5` types don’t want.
+  return location
 }
 
 /**

package.json

@@ -89,6 +89,16 @@
     "strict": true
   },
   "xo": {
+    "overrides": [
+      {
+        "files": [
+          "**/*.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/consistent-type-definitions": "off"
+        }
+      }
+    ],
     "prettier": true
   }
 }

readme.md

@@ -181,7 +181,7 @@ import {visit} from 'unist-util-visit'
 /** @type {import('hast').Root} */
 const tree = getHastNodeSomeHow()
 
-visit(tree, (node) => {
+visit(tree, function (node) {
   // `node` can now be a `raw` node.
 })
 ```

test-types.d.ts

@@ -1,7 +1,5 @@
 import type {Parent, Literal} from 'hast'
 
-/* eslint-disable @typescript-eslint/consistent-type-definitions */
-
 export interface CustomParent extends Parent {
   type: 'customParent'
 }
@@ -26,5 +24,3 @@ declare module 'hast' {
     customParent: CustomParent
   }
 }
-
-/* eslint-enable @typescript-eslint/consistent-type-definitions */