Refactor code-style

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

Author: wooorm

lib/index.js

@@ -1,39 +1,65 @@
 /**
- * @typedef Options
- *   Configuration (optional).
- * @property {Test} [ignore]
- *   `unist-util-is` test used to assert parents
- *
+ * @typedef {import('mdast').Parent} MdastParent
  * @typedef {import('mdast').Root} Root
  * @typedef {import('mdast').Content} Content
  * @typedef {import('mdast').PhrasingContent} PhrasingContent
  * @typedef {import('mdast').Text} Text
- * @typedef {Content|Root} Node
- * @typedef {Exclude<Extract<Node, import('mdast').Parent>, Root>} Parent
- *
  * @typedef {import('unist-util-visit-parents').Test} Test
  * @typedef {import('unist-util-visit-parents').VisitorResult} VisitorResult
+ */
+
+/**
+ * @typedef {Content | Root} Node
+ * @typedef {Extract<Node, MdastParent>} Parent
+ * @typedef {Exclude<Parent, Root>} ContentParent
  *
  * @typedef RegExpMatchObject
+ *   Info on the match.
  * @property {number} index
+ *   The index of the search at which the result was found.
  * @property {string} input
- * @property {[Root, ...Array<Parent>, Text]} stack
+ *   A copy of the search string in the text node.
+ * @property {[Root, ...Array<ContentParent>, Text]} stack
+ *   All ancestors of the text node, where the last node is the text itself.
  *
- * @typedef {string|RegExp} Find
- * @typedef {string|ReplaceFunction} Replace
+ * @callback ReplaceFunction
+ *   Callback called when a search matches.
+ * @param {...any} parameters
+ *   The parameters are the result of corresponding search expression:
  *
- * @typedef {[Find, Replace]} FindAndReplaceTuple
- * @typedef {Record<string, Replace>} FindAndReplaceSchema
- * @typedef {Array<FindAndReplaceTuple>} FindAndReplaceList
+ *   * `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}
+ *   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
- */
-
-/**
- * @callback ReplaceFunction
- * @param {...any} parameters
- * @returns {Array<PhrasingContent>|PhrasingContent|string|false|undefined|null}
+ *   All find and replaced.
+ *
+ * @typedef Options
+ *   Configuration.
+ * @property {Test | null | undefined} [ignore]
+ *   Test for which nodes to ignore.
  */
 
 import escape from 'escape-string-regexp'
@@ -43,31 +69,42 @@ import {convert} from 'unist-util-is'
 const own = {}.hasOwnProperty
 
 /**
- * @param tree mdast tree
- * @param find Value to find and remove. When `string`, escaped and made into a global `RegExp`
- * @param [replace] Value to insert.
- *   * When `string`, turned into a Text node.
- *   * When `Function`, called with the results of calling `RegExp.exec` as
- *     arguments, in which case it can return a single or a list of `Node`,
- *     a `string` (which is wrapped in a `Text` node), or `false` to not replace
- * @param [options] Configuration.
+ * Find patterns in a tree and replace them.
+ *
+ * The algorithm searches the tree in *preorder* for complete values in `Text`
+ * nodes.
+ * Partial matches are not supported.
+ *
+ * @param tree
+ *   Tree to change.
+ * @param find
+ *   Patterns to find.
+ * @param replace
+ *   Things to replace with (when `find` is `Find`) or configuration.
+ * @param options
+ *   Configuration (when `find` is not `Find`).
+ * @returns
+ *   Given, modified, tree.
  */
+// To do: next major: remove `find` & `replace` combo, remove schema.
 export const findAndReplace =
   /**
    * @type {(
-   *   ((tree: Node, find: Find, replace?: Replace, options?: Options) => Node) &
-   *   ((tree: Node, schema: FindAndReplaceSchema|FindAndReplaceList, options?: Options) => Node)
+   *   (<Tree extends Node>(tree: Tree, find: Find, replace?: Replace | null | undefined, options?: Options | null | undefined) => Tree) &
+   *   (<Tree extends Node>(tree: Tree, schema: FindAndReplaceSchema | FindAndReplaceList, options?: Options | null | undefined) => Tree)
    * )}
    **/
   (
     /**
-     * @param {Node} tree
-     * @param {Find|FindAndReplaceSchema|FindAndReplaceList} find
-     * @param {Replace|Options} [replace]
-     * @param {Options} [options]
+     * @template {Node} Tree
+     * @param {Tree} tree
+     * @param {Find | FindAndReplaceSchema | FindAndReplaceList} find
+     * @param {Replace | Options | null | undefined} [replace]
+     * @param {Options | null | undefined} [options]
+     * @returns {Tree}
      */
     function (tree, find, replace, options) {
-      /** @type {Options|undefined} */
+      /** @type {Options | null | undefined} */
       let settings
       /** @type {FindAndReplaceSchema|FindAndReplaceList} */
       let schema
@@ -94,21 +131,22 @@ export const findAndReplace =
         visitParents(tree, 'text', visitor)
       }
 
+      // To do next major: don’t return the given tree.
       return tree
 
       /** @type {import('unist-util-visit-parents/complex-types.js').BuildVisitor<Root, 'text'>} */
       function visitor(node, parents) {
         let index = -1
-        /** @type {Parent|undefined} */
+        /** @type {Parent | undefined} */
         let grandparent
 
         while (++index < parents.length) {
-          const parent = /** @type {Parent} */ (parents[index])
+          const parent = parents[index]
 
           if (
             ignored(
               parent,
-              // @ts-expect-error mdast vs. unist parent.
+              // @ts-expect-error: TS doesn’t understand but it’s perfect.
               grandparent ? grandparent.children.indexOf(parent) : undefined,
               grandparent
             )
@@ -120,15 +158,19 @@ export const findAndReplace =
         }
 
         if (grandparent) {
-          // @ts-expect-error: stack is fine.
           return handler(node, parents)
         }
       }
 
       /**
+       * Handle a text node which is not in an ignored parent.
+       *
        * @param {Text} node
-       * @param {[Root, ...Array<Parent>]} parents
+       *   Text node.
+       * @param {Array<Parent>} parents
+       *   Parents.
        * @returns {VisitorResult}
+       *   Result.
        */
       function handler(node, parents) {
         const parent = parents[parents.length - 1]
@@ -140,19 +182,18 @@ export const findAndReplace =
         let change = false
         /** @type {Array<PhrasingContent>} */
         let nodes = []
-        /** @type {number|undefined} */
-        let position
 
         find.lastIndex = 0
 
         let match = find.exec(node.value)
 
         while (match) {
-          position = match.index
+          const position = match.index
           /** @type {RegExpMatchObject} */
           const matchObject = {
             index: match.index,
             input: match.input,
+            // @ts-expect-error: stack is fine.
             stack: [...parents, node]
           }
           let value = replace(...match, matchObject)
@@ -161,6 +202,7 @@ export const findAndReplace =
             value = value.length > 0 ? {type: 'text', value} : undefined
           }
 
+          // It wasn’t a match after all.
           if (value !== false) {
             if (start !== position) {
               nodes.push({
@@ -202,8 +244,12 @@ export const findAndReplace =
   )
 
 /**
- * @param {FindAndReplaceSchema|FindAndReplaceList} schema
+ * Turn a schema into pairs.
+ *
+ * @param {FindAndReplaceSchema | FindAndReplaceList} schema
+ *   Schema.
  * @returns {Pairs}
+ *   Clean pairs.
  */
 function toPairs(schema) {
   /** @type {Pairs} */
@@ -237,16 +283,24 @@ function toPairs(schema) {
 }
 
 /**
+ * Turn a find into an expression.
+ *
  * @param {Find} find
+ *   Find.
  * @returns {RegExp}
+ *   Expression.
  */
 function toExpression(find) {
   return typeof find === 'string' ? new RegExp(escape(find), 'g') : find
 }
 
 /**
+ * Turn a replace into a function.
+ *
  * @param {Replace} replace
+ *   Replace.
  * @returns {ReplaceFunction}
+ *   Function.
  */
 function toFunction(replace) {
   return typeof replace === 'function' ? replace : () => replace

package.json

@@ -33,6 +33,7 @@
     "index.js"
   ],
   "dependencies": {
+    "@types/mdast": "^3.0.0",
     "escape-string-regexp": "^5.0.0",
     "unist-util-is": "^5.0.0",
     "unist-util-visit-parents": "^5.0.0"