Refactor code-style

Author: wooorm

lib/index.js

@@ -1,23 +1,40 @@
 /**
- * @typedef {import('hast').Text} Text
- * @typedef {import('hast').Root} Root
- * @typedef {import('hast').Element} Element
- * @typedef {import('hast').Content} Content
  * @typedef {import('hast').Nodes} Nodes
+ * @typedef {import('hast').Parents} Parents
+ * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').RootContent} RootContent
+ * @typedef {import('hast').Text} Text
  * @typedef {import('hast-util-is-element').Test} Test
  * @typedef {import('unist-util-visit-parents').VisitorResult} VisitorResult
  */
 
 /**
+ * @typedef {RegExp | string} Find
+ *   Pattern to find.
+ *
+ *   Strings are escaped and then turned into global expressions.
+ *
+ * @typedef {Array<FindAndReplaceTuple>} FindAndReplaceList
+ *   Several find and replaces, in array form.
+ *
+ * @typedef {Record<string, Replace>} FindAndReplaceSchema
+ *   Several find and replaces, in object form.
+ *
+ * @typedef {[Find, Replace]} FindAndReplaceTuple
+ *   Find and replace in tuple form.
+ *
  * @typedef RegExpMatchObject
  *   Info on the match.
  * @property {number} index
  *   The index of the search at which the result was found.
  * @property {string} input
  *   A copy of the search string in the text node.
- * @property {[Root, ...Array<Element>, Text]} stack
+ * @property {[...Array<Parents>, Text]} stack
  *   All ancestors of the text node, where the last node is the text itself.
  *
+ * @typedef {ReplaceFunction | string} Replace
+ *   Thing to replace with.
+ *
  * @callback ReplaceFunction
  *   Callback called when a search matches.
  * @param {...any} parameters
@@ -26,27 +43,14 @@
  *   * `value` (`string`) — whole match
  *   * `...capture` (`Array<string>`) — matches from regex capture groups
  *   * `match` (`RegExpMatchObject`) — info on the match
- * @returns {Array<Content> | Content | string | false | undefined | null}
+ * @returns {Array<RootContent> | RootContent | string | false | null | undefined}
  *   Thing to replace with.
  *
  *   * when `null`, `undefined`, `''`, remove the match
  *   * …or when `false`, do not replace at all
  *   * …or when `string`, replace with a text node of that value
  *   * …or when `Node` or `Array<Node>`, replace with those nodes
  *
- * @typedef {string | RegExp} Find
- *   Pattern to find.
- *
- *   Strings are escaped and then turned into global expressions.
- *
- * @typedef {Array<FindAndReplaceTuple>} FindAndReplaceList
- *   Several find and replaces, in array form.
- * @typedef {Record<string, Replace>} FindAndReplaceSchema
- *   Several find and replaces, in object form.
- * @typedef {[Find, Replace]} FindAndReplaceTuple
- *   Find and replace in tuple form.
- * @typedef {string | ReplaceFunction} Replace
- *   Thing to replace with.
  * @typedef {[RegExp, ReplaceFunction]} Pair
  *   Normalized find and replace.
  * @typedef {Array<Pair>} Pairs
@@ -55,7 +59,7 @@
  * @typedef Options
  *   Configuration.
  * @property {Test | null | undefined} [ignore]
- *   Test for which elements to ignore.
+ *   Test for which elements to ignore (optional).
  */
 
 import {visitParents} from 'unist-util-visit-parents'
@@ -80,18 +84,29 @@ export const defaultIgnore = ['math', 'script', 'style', 'svg', 'title']
  * nodes.
  * Partial matches are not supported.
  *
- * @template {Nodes} Tree
- *   Node type.
- * @param {Tree} tree
+ * @overload
+ * @param {Nodes} tree
+ * @param {Find} find
+ * @param {Replace | null | undefined} [replace]
+ * @param {Options | null | undefined} [options]
+ * @returns {undefined}
+ *
+ * @overload
+ * @param {Nodes} tree
+ * @param {FindAndReplaceSchema | FindAndReplaceList} schema
+ * @param {Options | null | undefined} [options]
+ * @returns {undefined}
+ *
+ * @param {Nodes} tree
  *   Tree to change.
- * @param {Find | FindAndReplaceSchema | FindAndReplaceList} find
+ * @param {Find | FindAndReplaceList | FindAndReplaceSchema} find
  *   Patterns to find.
- * @param {Replace | Options | null | undefined} [replace]
+ * @param {Options | Replace | null | undefined} [replace]
  *   Things to replace with (when `find` is `Find`) or configuration.
  * @param {Options | null | undefined} [options]
  *   Configuration (when `find` is not `Find`).
- * @returns {Tree}
- *   Given, modified, tree.
+ * @returns {undefined}
+ *   Nothing.
  */
 export function findAndReplace(tree, find, replace, options) {
   /** @type {Options | null | undefined} */
@@ -121,23 +136,24 @@ export function findAndReplace(tree, find, replace, options) {
     visitParents(tree, 'text', visitor)
   }
 
-  // To do next major: don’t return the given tree.
+  // @ts-expect-error: To do next major: don’t return the given tree.
   return tree
 
-  /** @type {import('unist-util-visit-parents').BuildVisitor<Nodes, 'text'>} */
+  /** @type {import('unist-util-visit-parents').BuildVisitor<Root, 'text'>} */
   function visitor(node, parents) {
     let index = -1
-    /** @type {Root | Element | undefined} */
+    /** @type {Parents | undefined} */
     let grandparent
 
     while (++index < parents.length) {
       const parent = parents[index]
+      /** @type {Array<Nodes> | undefined} */
+      const siblings = grandparent ? grandparent.children : undefined
 
       if (
         ignored(
           parent,
-          // @ts-expect-error: TS doesn’t understand but it’s perfect.
-          grandparent ? grandparent.children.indexOf(parent) : undefined,
+          siblings ? siblings.indexOf(parent) : undefined,
           grandparent
         )
       ) {
@@ -157,7 +173,7 @@ export function findAndReplace(tree, find, replace, options) {
    *
    * @param {Text} node
    *   Text node.
-   * @param {Array<Root | Element>} parents
+   * @param {Array<Parents>} parents
    *   Parents.
    * @returns {VisitorResult}
    *   Result.
@@ -167,9 +183,11 @@ export function findAndReplace(tree, find, replace, options) {
     const find = pairs[pairIndex][0]
     const replace = pairs[pairIndex][1]
     let start = 0
-    const index = parent.children.indexOf(node)
+    /** @type {Array<Nodes>} */
+    const siblings = parent.children
+    const index = siblings.indexOf(node)
     let change = false
-    /** @type {Array<Content>} */
+    /** @type {Array<RootContent>} */
     let nodes = []
 
     find.lastIndex = 0
@@ -182,7 +200,6 @@ export function findAndReplace(tree, find, replace, options) {
       const matchObject = {
         index: match.index,
         input: match.input,
-        // @ts-expect-error: stack is fine.
         stack: [...parents, node]
       }
       let value = replace(...match, matchObject)
@@ -231,7 +248,7 @@ export function findAndReplace(tree, find, replace, options) {
 /**
  * Turn a schema into pairs.
  *
- * @param {FindAndReplaceSchema | FindAndReplaceList} schema
+ * @param {FindAndReplaceList | FindAndReplaceSchema} schema
  *   Schema.
  * @returns {Pairs}
  *   Clean pairs.
@@ -288,5 +305,9 @@ function toExpression(find) {
  *   Function.
  */
 function toFunction(replace) {
-  return typeof replace === 'function' ? replace : () => replace
+  return typeof replace === 'function'
+    ? replace
+    : function () {
+        return replace
+      }
 }

readme.md

@@ -311,7 +311,9 @@ browser.
 ```js
 const tree = h('p', 'This and that.')
 
-findAndReplace(tree, 'and', () => h('script', 'alert(1)'))
+findAndReplace(tree, 'and', function () {
+  return h('script', 'alert(1)')
+})
 ```
 
 Yields: