Refactor code-style

Author: wooorm

lib/index.js

@@ -18,6 +18,23 @@
  * @property {[...Array<Parents>, Text]} stack
  *   All ancestors of the text node, where the last node is the text itself.
  *
+ * @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 {ReplaceFunction | string} Replace
+ *   Thing to replace with.
+ *
  * @callback ReplaceFunction
  *   Callback called when a search matches.
  * @param {...any} parameters
@@ -26,36 +43,24 @@
  *   * `value` (`string`) — whole match
  *   * `...capture` (`Array<string>`) — matches from regex capture groups
  *   * `match` (`RegExpMatchObject`) — info on the match
- * @returns {Array<PhrasingContent> | PhrasingContent | string | false | undefined | null}
+ * @returns {Array<PhrasingContent> | PhrasingContent | 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
  *   All find and replaced.
  *
  * @typedef Options
  *   Configuration.
  * @property {Test | null | undefined} [ignore]
- *   Test for which nodes to ignore.
+ *   Test for which nodes to ignore (optional).
  */
 
 import escape from 'escape-string-regexp'
@@ -71,176 +76,175 @@ const own = {}.hasOwnProperty
  * nodes.
  * Partial matches are not supported.
  *
- * @param 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
+ * @param {Find | FindAndReplaceList | FindAndReplaceSchema} find
  *   Patterns to find.
- * @param replace
+ * @param {Options | Replace | null | undefined} [replace]
  *   Things to replace with (when `find` is `Find`) or configuration.
- * @param options
+ * @param {Options | null | undefined} [options]
  *   Configuration (when `find` is not `Find`).
- * @returns
+ * @returns {undefined}
  *   Given, modified, tree.
  */
 // To do: next major: remove `find` & `replace` combo, remove schema.
-export const findAndReplace =
-  /**
-   * @type {(
-   *   ((tree: Nodes, find: Find, replace?: Replace | null | undefined, options?: Options | null | undefined) => undefined) &
-   *   ((tree: Nodes, schema: FindAndReplaceSchema | FindAndReplaceList, options?: Options | null | undefined) => undefined)
-   * )}
-   **/
-  (
-    /**
-     * @param {Nodes} tree
-     * @param {Find | FindAndReplaceSchema | FindAndReplaceList} find
-     * @param {Replace | Options | null | undefined} [replace]
-     * @param {Options | null | undefined} [options]
-     * @returns {undefined}
-     */
-    function (tree, find, replace, options) {
-      /** @type {Options | null | undefined} */
-      let settings
-      /** @type {FindAndReplaceSchema|FindAndReplaceList} */
-      let schema
-
-      if (typeof find === 'string' || find instanceof RegExp) {
-        // @ts-expect-error don’t expect options twice.
-        schema = [[find, replace]]
-        settings = options
-      } else {
-        schema = find
-        // @ts-expect-error don’t expect replace twice.
-        settings = replace
-      }
+export function findAndReplace(tree, find, replace, options) {
+  /** @type {Options | null | undefined} */
+  let settings
+  /** @type {FindAndReplaceList | FindAndReplaceSchema} */
+  let schema
+
+  if (typeof find === 'string' || find instanceof RegExp) {
+    // @ts-expect-error don’t expect options twice.
+    schema = [[find, replace]]
+    settings = options
+  } else {
+    schema = find
+    // @ts-expect-error don’t expect replace twice.
+    settings = replace
+  }
 
-      if (!settings) {
-        settings = {}
+  if (!settings) {
+    settings = {}
+  }
+
+  const ignored = convert(settings.ignore || [])
+  const pairs = toPairs(schema)
+  let pairIndex = -1
+
+  while (++pairIndex < pairs.length) {
+    visitParents(tree, 'text', visitor)
+  }
+
+  // @ts-expect-error: To do: remove.
+  return tree
+
+  /** @type {import('unist-util-visit-parents').BuildVisitor<Root, 'text'>} */
+  function visitor(node, parents) {
+    let index = -1
+    /** @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,
+          siblings ? siblings.indexOf(parent) : undefined,
+          grandparent
+        )
+      ) {
+        return
       }
 
-      const ignored = convert(settings.ignore || [])
-      const pairs = toPairs(schema)
-      let pairIndex = -1
+      grandparent = parent
+    }
+
+    if (grandparent) {
+      return handler(node, parents)
+    }
+  }
+
+  /**
+   * Handle a text node which is not in an ignored parent.
+   *
+   * @param {Text} node
+   *   Text node.
+   * @param {Array<Parents>} parents
+   *   Parents.
+   * @returns {VisitorResult}
+   *   Result.
+   */
+  function handler(node, parents) {
+    const parent = parents[parents.length - 1]
+    const find = pairs[pairIndex][0]
+    const replace = pairs[pairIndex][1]
+    let start = 0
+    /** @type {Array<Nodes>} */
+    const siblings = parent.children
+    const index = siblings.indexOf(node)
+    let change = false
+    /** @type {Array<PhrasingContent>} */
+    let nodes = []
+
+    find.lastIndex = 0
+
+    let match = find.exec(node.value)
+
+    while (match) {
+      const position = match.index
+      /** @type {RegExpMatchObject} */
+      const matchObject = {
+        index: match.index,
+        input: match.input,
+        stack: [...parents, node]
+      }
+      let value = replace(...match, matchObject)
 
-      while (++pairIndex < pairs.length) {
-        visitParents(tree, 'text', visitor)
+      if (typeof value === 'string') {
+        value = value.length > 0 ? {type: 'text', value} : undefined
       }
 
-      // @ts-expect-error: To do: remove.
-      return tree
-
-      /** @type {import('unist-util-visit-parents').BuildVisitor<Root, 'text'>} */
-      function visitor(node, parents) {
-        let index = -1
-        /** @type {Parents | undefined} */
-        let grandparent
-
-        while (++index < parents.length) {
-          const parent = parents[index]
-
-          if (
-            ignored(
-              parent,
-              // @ts-expect-error: TS doesn’t understand but it’s perfect.
-              grandparent ? grandparent.children.indexOf(parent) : undefined,
-              grandparent
-            )
-          ) {
-            return
-          }
-
-          grandparent = parent
+      // It wasn’t a match after all.
+      if (value !== false) {
+        if (start !== position) {
+          nodes.push({
+            type: 'text',
+            value: node.value.slice(start, position)
+          })
         }
 
-        if (grandparent) {
-          return handler(node, parents)
+        if (Array.isArray(value)) {
+          nodes.push(...value)
+        } else if (value) {
+          nodes.push(value)
         }
-      }
 
-      /**
-       * Handle a text node which is not in an ignored parent.
-       *
-       * @param {Text} node
-       *   Text node.
-       * @param {Array<Parents>} parents
-       *   Parents.
-       * @returns {VisitorResult}
-       *   Result.
-       */
-      function handler(node, parents) {
-        const parent = parents[parents.length - 1]
-        const find = pairs[pairIndex][0]
-        const replace = pairs[pairIndex][1]
-        let start = 0
-        // @ts-expect-error: TS is wrong, some of these children can be text.
-        const index = parent.children.indexOf(node)
-        let change = false
-        /** @type {Array<PhrasingContent>} */
-        let nodes = []
-
-        find.lastIndex = 0
-
-        let match = find.exec(node.value)
-
-        while (match) {
-          const position = match.index
-          /** @type {RegExpMatchObject} */
-          const matchObject = {
-            index: match.index,
-            input: match.input,
-            stack: [...parents, node]
-          }
-          let value = replace(...match, matchObject)
-
-          if (typeof value === 'string') {
-            value = value.length > 0 ? {type: 'text', value} : undefined
-          }
-
-          // It wasn’t a match after all.
-          if (value !== false) {
-            if (start !== position) {
-              nodes.push({
-                type: 'text',
-                value: node.value.slice(start, position)
-              })
-            }
-
-            if (Array.isArray(value)) {
-              nodes.push(...value)
-            } else if (value) {
-              nodes.push(value)
-            }
-
-            start = position + match[0].length
-            change = true
-          }
-
-          if (!find.global) {
-            break
-          }
-
-          match = find.exec(node.value)
-        }
+        start = position + match[0].length
+        change = true
+      }
 
-        if (change) {
-          if (start < node.value.length) {
-            nodes.push({type: 'text', value: node.value.slice(start)})
-          }
+      if (!find.global) {
+        break
+      }
 
-          parent.children.splice(index, 1, ...nodes)
-        } else {
-          nodes = [node]
-        }
+      match = find.exec(node.value)
+    }
 
-        return index + nodes.length
+    if (change) {
+      if (start < node.value.length) {
+        nodes.push({type: 'text', value: node.value.slice(start)})
       }
+
+      parent.children.splice(index, 1, ...nodes)
+    } else {
+      nodes = [node]
     }
-  )
+
+    return index + nodes.length
+  }
+}
 
 /**
  * Turn a schema into pairs.
  *
- * @param {FindAndReplaceSchema | FindAndReplaceList} schema
+ * @param {FindAndReplaceList | FindAndReplaceSchema} schema
  *   Schema.
  * @returns {Pairs}
  *   Clean pairs.
@@ -297,5 +301,9 @@ function toExpression(find) {
  *   Function.
  */
 function toFunction(replace) {
-  return typeof replace === 'function' ? replace : () => replace
+  return typeof replace === 'function'
+    ? replace
+    : function () {
+        return replace
+      }
 }