mdast-util-find-and-replace - npm Package Compare versions

Comparing version 2.2.1 to 2.2.2

lib/index.d.ts

 /**
- * @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.
  */
-export const findAndReplace: ((
-  tree: Node,
+export const findAndReplace: (<Tree extends Node>(
+  tree: Tree,
   find: Find,
-  replace?: Replace,
-  options?: Options
-) => Node) &
-  ((
-    tree: Node,
+  replace?: Replace | null | undefined,
+  options?: Options | null | undefined
+) => Tree) &
+  (<Tree_1 extends Node>(
+    tree: Tree_1,
     schema: FindAndReplaceSchema | FindAndReplaceList,
-    options?: Options
-  ) => Node)
-/**
- * Configuration (optional).
- */
-export type Options = {
-  /**
-   * `unist-util-is` test used to assert parents
-   */
-  ignore?: Test
-}
+    options?: Options | null | undefined
+  ) => Tree_1)
+export type MdastParent = import('mdast').Parent
 export type Root = import('mdast').Root
@@ -35,18 +35,27 @@ export type Content = import('mdast').Content
 export type Text = import('mdast').Text
-export type Node = Content | Root
-export type Parent = Exclude<Extract<Node, import('mdast').Parent>, Root>
 export type Test = import('unist-util-visit-parents').Test
 export type VisitorResult = import('unist-util-visit-parents').VisitorResult
+export type Node = Content | Root
+export type Parent = Extract<Node, MdastParent>
+export type ContentParent = Exclude<Parent, Root>
+/**
+ * Info on the match.
+ */
 export type RegExpMatchObject = {
+  /**
+   * The index of the search at which the result was found.
+   */
   index: number
+  /**
+   * A copy of the search string in the text node.
+   */
   input: string
-  stack: [Root, ...Array<Parent>, Text]
+  /**
+   * All ancestors of the text node, where the last node is the text itself.
+   */
+  stack: [Root, ...Array<ContentParent>, Text]
 }
-export type Find = string | RegExp
-export type Replace = string | ReplaceFunction
-export type FindAndReplaceTuple = [Find, Replace]
-export type FindAndReplaceSchema = Record<string, Replace>
-export type FindAndReplaceList = Array<[Find, Replace]>
-export type Pair = [RegExp, ReplaceFunction]
-export type Pairs = Array<[RegExp, ReplaceFunction]>
+/**
+ * Callback called when a search matches.
+ */
 export type ReplaceFunction = (
@@ -61,1 +70,40 @@ ...parameters: any[]
   | null
+/**
+ * Pattern to find.
+ *
+ * Strings are escaped and then turned into global expressions.
+ */
+export type Find = string | RegExp
+/**
+ * Several find and replaces, in array form.
+ */
+export type FindAndReplaceList = Array<[Find, Replace]>
+/**
+ * Several find and replaces, in object form.
+ */
+export type FindAndReplaceSchema = Record<string, Replace>
+/**
+ * Find and replace in tuple form.
+ */
+export type FindAndReplaceTuple = [Find, Replace]
+/**
+ * Thing to replace with.
+ */
+export type Replace = string | ReplaceFunction
+/**
+ * Normalized find and replace.
+ */
+export type Pair = [RegExp, ReplaceFunction]
+/**
+ * All find and replaced.
+ */
+export type Pairs = Array<[RegExp, ReplaceFunction]>
+/**
+ * Configuration.
+ */
+export type Options = {
+  /**
+   * Test for which nodes to ignore.
+   */
+  ignore?: Test | null | undefined
+}

lib/index.js

 /**
- * @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
@@ -11,30 +7,60 @@ * @typedef {import('mdast').Content} Content
  * @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:
  *
+ *   * `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
- * @typedef {Record<string, Replace>} FindAndReplaceSchema
- * @typedef {Array<FindAndReplaceTuple>} FindAndReplaceList
- *
+ *   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.
  */
 
-/**
- * @callback ReplaceFunction
- * @param {...any} parameters
- * @returns {Array<PhrasingContent>|PhrasingContent|string|false|undefined|null}
- */
-
 import escape from 'escape-string-regexp'
@@ -47,16 +73,25 @@ import {visitParents} from 'unist-util-visit-parents'
 /**
- * @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)
    * )}
@@ -66,9 +101,11 @@ **/
     /**
-     * @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
@@ -100,12 +137,13 @@ /** @type {FindAndReplaceSchema|FindAndReplaceList} */
 
+      // To do next major: don’t return the given tree.
       return tree
 
-      /** @type {import('unist-util-visit-parents/complex-types').BuildVisitor<Root, 'text'>} */
+      /** @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]
 
@@ -115,3 +153,3 @@ if (
               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,
@@ -128,3 +166,2 @@ grandparent
         if (grandparent) {
-          // @ts-expect-error: stack is fine.
           return handler(node, parents)
@@ -135,5 +172,10 @@ }
       /**
+       * 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.
        */
@@ -150,4 +192,2 @@ function handler(node, parents) {
         let nodes = []
-        /** @type {number|undefined} */
-        let position
 
@@ -159,3 +199,3 @@ find.lastIndex = 0
         while (match) {
-          position = match.index
+          const position = match.index
           /** @type {RegExpMatchObject} */
@@ -165,2 +205,3 @@ const matchObject = {
             input: match.input,
+            // @ts-expect-error: stack is fine.
             stack: [...parents, node]
@@ -174,2 +215,3 @@ }
 
+          // It wasn’t a match after all.
           if (value !== false) {
@@ -216,4 +258,8 @@ if (start !== position) {
 /**
- * @param {FindAndReplaceSchema|FindAndReplaceList} schema
+ * Turn a schema into pairs.
+ *
+ * @param {FindAndReplaceSchema | FindAndReplaceList} schema
+ *   Schema.
  * @returns {Pairs}
+ *   Clean pairs.
  */
@@ -252,4 +298,8 @@ function toPairs(schema) {
 /**
+ * Turn a find into an expression.
+ *
  * @param {Find} find
+ *   Find.
  * @returns {RegExp}
+ *   Expression.
  */
@@ -261,4 +311,8 @@ function toExpression(find) {
 /**
+ * Turn a replace into a function.
+ *
  * @param {Replace} replace
+ *   Replace.
  * @returns {ReplaceFunction}
+ *   Function.
  */
@@ -265,0 +319,0 @@ function toFunction(replace) {

package.json

 {
   "name": "mdast-util-find-and-replace",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "mdast utility to find and replace text in a tree",
@@ -36,2 +36,3 @@ "license": "MIT",
   "dependencies": {
+    "@types/mdast": "^3.0.0",
     "escape-string-regexp": "^5.0.0",
@@ -42,3 +43,3 @@ "unist-util-is": "^5.0.0",
   "devDependencies": {
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "c8": "^7.0.0",
@@ -48,12 +49,10 @@ "prettier": "^2.0.0",
     "remark-preset-wooorm": "^9.0.0",
-    "rimraf": "^3.0.0",
-    "tape": "^5.0.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
     "unist-builder": "^3.0.0",
-    "xo": "^0.50.0"
+    "xo": "^0.53.0"
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"lib/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
+    "build": "tsc --build --clean && tsc --build && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
@@ -60,0 +59,0 @@ "test-api": "node --conditions development test.js",

readme.md

@@ -21,2 +21,10 @@ # mdast-util-find-and-replace
     *   [`findAndReplace(tree, find, replace[, options])`](#findandreplacetree-find-replace-options)
+    *   [`Find`](#find)
+    *   [`FindAndReplaceList`](#findandreplacelist)
+    *   [`FindAndReplaceSchema`](#findandreplaceschema)
+    *   [`FindAndReplaceTuple`](#findandreplacetuple)
+    *   [`Options`](#options)
+    *   [`RegExpMatchObject`](#regexpmatchobject)
+    *   [`Replace`](#replace)
+    *   [`ReplaceFunction`](#replacefunction)
 *   [Types](#types)
@@ -46,3 +54,3 @@ *   [Compatibility](#compatibility)
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+In Node.js (version 14.14+ and or 16.0+), install with [npm][]:
 
@@ -117,3 +125,3 @@ ```sh
 
-This package exports the identifier `findAndReplace`.
+This package exports the identifier [`findAndReplace`][api-findandreplace].
 There is no default export.
@@ -124,2 +132,3 @@
 Find patterns in a tree and replace them.
+
 The algorithm searches the tree in *[preorder][]* for complete values in
@@ -137,29 +146,134 @@ [`Text`][text] nodes.
 *   `tree` ([`Node`][node])
-*   `find` (`string` or `RegExp`)
-    — value to find and remove (`string`s are escaped and turned into a global
-    `RegExp`)
-*   `replace` (`string` or `Function`)
-    — value to insert.
-    `string`s are turned into a [`Text`][text] node,
-    `Function`s are called with the results of calling `RegExp.exec` as
-    arguments, and they can return a [`Node`][node], a `string` (which is
-    wrapped in a [`Text`][text] node), or `false` to not replace
-*   `search` (`Array` or `Object`)
-    — perform multiple find-and-replaces.
-    Either an `Array` of tuples (`Array`s) with `find` (at `0`) and `replace`
-    (at `1`), or an `Object` where each key is `find` and each value is
-    the corresponding `replace`
-*   `options.ignore` (`Test`, default: `[]`)
-    — any [`unist-util-is`][test] compatible test.
+    — tree to change
+*   `find` ([`Find`][api-find])
+    — value to find and remove
+*   `replace` ([`Replace`][api-replace])
+    — thing to replace with
+*   `search` ([`FindAndReplaceSchema`][api-findandreplaceschema] or
+    [`FindAndReplaceList`][api-findandreplacelist])
+    — several find and replaces
+*   `options` ([`Options`][api-options])
+    — configuration
 
 ###### Returns
 
-The given `tree` ([`Node`][node]).
+Given, modified, tree ([`Node`][node]).
 
+### `Find`
+
+Pattern to find (TypeScript type).
+
+Strings are escaped and then turned into global expressions.
+
+###### Type
+
+```ts
+type Find = string | RegExp
+```
+
+### `FindAndReplaceList`
+
+Several find and replaces, in array form (TypeScript type).
+
+###### Type
+
+```ts
+type FindAndReplaceList = Array<FindAndReplaceTuple>
+```
+
+See [`FindAndReplaceTuple`][api-findandreplacetuple].
+
+### `FindAndReplaceSchema`
+
+Several find and replaces, in object form (TypeScript type).
+
+###### Type
+
+```ts
+type FindAndReplaceSchema = Record<string, Replace>
+```
+
+See [`Replace`][api-replace].
+
+### `FindAndReplaceTuple`
+
+Find and replace in tuple form (TypeScript type).
+
+###### Type
+
+```ts
+type FindAndReplaceTuple = [Find, Replace]
+```
+
+See [`Find`][api-find] and [`Replace`][api-replace].
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+*   `ignore` ([`Test`][test], optional)
+    — test for which elements to ignore
+
+### `RegExpMatchObject`
+
+Info on the match (TypeScript type).
+
+###### Fields
+
+*   `index` (`number`)
+    — the index of the search at which the result was found
+*   `input` (`string`)
+    — a copy of the search string in the text node
+*   `stack` ([`Array<Node>`][node])
+    — all ancestors of the text node, where the last node is the text itself
+
+### `Replace`
+
+Thing to replace with (TypeScript type).
+
+###### Type
+
+```ts
+type Replace = string | ReplaceFunction
+```
+
+See [`ReplaceFunction`][api-replacefunction].
+
+### `ReplaceFunction`
+
+Callback called when a search matches (TypeScript type).
+
+###### Parameters
+
+The parameters are the result of corresponding search expression:
+
+*   `value` (`string`)
+    — whole match
+*   `...capture` (`Array<string>`)
+    — matches from regex capture groups
+*   `match` ([`RegExpMatchObject`][api-regexpmatchobject])
+    — info on the match
+
+###### Returns
+
+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
+
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the types `Find`, `Replace`, `ReplaceFunction`,
-`FindAndReplaceTuple`, `FindAndReplaceSchema`, `FindAndReplaceList`,
-`RegExpMatchObject`, and `Options`.
+It exports the additional types [`Find`][api-find],
+[`FindAndReplaceList`][api-findandreplacelist],
+[`FindAndReplaceSchema`][api-findandreplaceschema],
+[`FindAndReplaceTuple`][api-findandreplacetuple],
+[`Options`][api-options],
+[`RegExpMatchObject`][api-regexpmatchobject],
+[`Replace`][api-replace], and
+[`ReplaceFunction`][api-replacefunction].
 
@@ -170,3 +284,3 @@ ## Compatibility
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+As of now, that is Node.js 14.14+ and 16.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
@@ -254,3 +368,3 @@
 
-[node]: https://github.com/syntax-tree/mdast#ndoes
+[node]: https://github.com/syntax-tree/mdast#nodes
 
@@ -266,1 +380,19 @@ [preorder]: https://github.com/syntax-tree/unist#preorder
 [hast-util-find-and-replace]: https://github.com/syntax-tree/hast-util-find-and-replace
+
+[api-findandreplace]: #findandreplacetree-find-replace-options
+
+[api-options]: #options
+
+[api-find]: #find
+
+[api-replace]: #replace
+
+[api-replacefunction]: #replacefunction
+
+[api-findandreplacelist]: #findandreplacelist
+
+[api-findandreplaceschema]: #findandreplaceschema
+
+[api-findandreplacetuple]: #findandreplacetuple
+
+[api-regexpmatchobject]: #regexpmatchobject

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

25596

increased by25.07%

Dev dependency count

9

decreased by-18.18%

Lines of code

399

increased by34.34%

Number of lines in readme file

391

increased by50.97%

Worsened metrics

Dependency count

4

increased by33.33%

Dependency changes

• + Added@types/mdast@^3.0.0

• + Added@types/mdast@3.0.15(transitive)