Change API to accept only a tuple, or list of tuples

Author: wooorm

index.js

@@ -4,9 +4,8 @@
  * @typedef {import('./lib/index.js').Find} Find
  * @typedef {import('./lib/index.js').Replace} Replace
  * @typedef {import('./lib/index.js').ReplaceFunction} ReplaceFunction
- * @typedef {import('./lib/index.js').FindAndReplaceTuple} FindAndReplaceTuple
- * @typedef {import('./lib/index.js').FindAndReplaceSchema} FindAndReplaceSchema
  * @typedef {import('./lib/index.js').FindAndReplaceList} FindAndReplaceList
+ * @typedef {import('./lib/index.js').FindAndReplaceTuple} FindAndReplaceTuple
  */
 
 export {findAndReplace} from './lib/index.js'

lib/index.js

@@ -26,13 +26,10 @@
  * @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 {[Find, Replace?]} FindAndReplaceTuple
  *   Find and replace in tuple form.
  *
- * @typedef {ReplaceFunction | string} Replace
+ * @typedef {ReplaceFunction | string | null | undefined} Replace
  *   Thing to replace with.
  *
  * @callback ReplaceFunction
@@ -67,62 +64,26 @@ import escape from 'escape-string-regexp'
 import {visitParents} from 'unist-util-visit-parents'
 import {convert} from 'unist-util-is'
 
-const own = {}.hasOwnProperty
-
 /**
  * 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.
  *
- * @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 | FindAndReplaceList | FindAndReplaceSchema} find
+ * @param {FindAndReplaceList | FindAndReplaceTuple} list
  *   Patterns to find.
- * @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 {undefined}
  *   Nothing.
  */
-// To do: next major: remove `find` & `replace` combo, remove schema.
-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 = {}
-  }
-
+export function findAndReplace(tree, list, options) {
+  const settings = options || {}
   const ignored = convert(settings.ignore || [])
-  const pairs = toPairs(schema)
+  const pairs = toPairs(list)
   let pairIndex = -1
 
   while (++pairIndex < pairs.length) {
@@ -239,39 +200,33 @@ export function findAndReplace(tree, find, replace, options) {
 }
 
 /**
- * Turn a schema into pairs.
+ * Turn a tuple or a list of tuples into pairs.
  *
- * @param {FindAndReplaceList | FindAndReplaceSchema} schema
+ * @param {FindAndReplaceList | FindAndReplaceTuple} tupleOrList
  *   Schema.
  * @returns {Pairs}
  *   Clean pairs.
  */
-function toPairs(schema) {
+function toPairs(tupleOrList) {
   /** @type {Pairs} */
   const result = []
 
-  if (typeof schema !== 'object') {
-    throw new TypeError('Expected array or object as schema')
+  if (!Array.isArray(tupleOrList)) {
+    throw new TypeError('Expected find and replace tuple or list of tuples')
   }
 
-  if (Array.isArray(schema)) {
-    let index = -1
+  /** @type {FindAndReplaceList} */
+  // @ts-expect-error: correct.
+  const list =
+    !tupleOrList[0] || Array.isArray(tupleOrList[0])
+      ? tupleOrList
+      : [tupleOrList]
 
-    while (++index < schema.length) {
-      result.push([
-        toExpression(schema[index][0]),
-        toFunction(schema[index][1])
-      ])
-    }
-  } else {
-    /** @type {string} */
-    let key
+  let index = -1
 
-    for (key in schema) {
-      if (own.call(schema, key)) {
-        result.push([toExpression(key), toFunction(schema[key])])
-      }
-    }
+  while (++index < list.length) {
+    const tuple = list[index]
+    result.push([toExpression(tuple[0]), toFunction(tuple[1])])
   }
 
   return result

readme.md

@@ -17,10 +17,9 @@
 *   [Install](#install)
 *   [Use](#use)
 *   [API](#api)
-    *   [`findAndReplace(tree, find, replace[, options])`](#findandreplacetree-find-replace-options)
+    *   [`findAndReplace(tree, list[, options])`](#findandreplacetree-list-options)
     *   [`Find`](#find)
     *   [`FindAndReplaceList`](#findandreplacelist)
-    *   [`FindAndReplaceSchema`](#findandreplaceschema)
     *   [`FindAndReplaceTuple`](#findandreplacetuple)
     *   [`Options`](#options)
     *   [`RegExpMatchObject`](#regexpmatchobject)
@@ -123,30 +122,21 @@ paragraph[8]
 This package exports the identifier [`findAndReplace`][api-findandreplace].
 There is no default export.
 
-### `findAndReplace(tree, find, replace[, options])`
+### `findAndReplace(tree, list[, options])`
 
 Find patterns in a tree and replace them.
 
 The algorithm searches the tree in *[preorder][]* for complete values in
 [`Text`][text] nodes.
 Partial matches are not supported.
 
-###### Signatures
-
-*   `findAndReplace(tree, find, replace[, options])`
-*   `findAndReplace(tree, search[, options])`
-
 ###### Parameters
 
 *   `tree` ([`Node`][node])
     — 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
+*   `list` ([`FindAndReplaceList`][api-findandreplacelist] or
+    [`FindAndReplaceTuple`][api-findandreplacetuple])
+    — one or more find-and-replace pairs
 *   `options` ([`Options`][api-options])
     — configuration
 
@@ -178,26 +168,14 @@ 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]
+type FindAndReplaceTuple = [Find, Replace?]
 ```
 
 See [`Find`][api-find] and [`Replace`][api-replace].
@@ -265,7 +243,6 @@ Thing to replace with:
 This package is fully typed with [TypeScript][].
 It exports the additional types [`Find`][api-find],
 [`FindAndReplaceList`][api-findandreplacelist],
-[`FindAndReplaceSchema`][api-findandreplaceschema],
 [`FindAndReplaceTuple`][api-findandreplacetuple],
 [`Options`][api-options],
 [`RegExpMatchObject`][api-regexpmatchobject],
@@ -371,7 +348,7 @@ abide by its terms.
 
 [hast-util-find-and-replace]: https://github.com/syntax-tree/hast-util-find-and-replace
 
-[api-findandreplace]: #findandreplacetree-find-replace-options
+[api-findandreplace]: #findandreplacetree-list-options
 
 [api-options]: #options
 
@@ -383,8 +360,6 @@ abide by its terms.
 
 [api-findandreplacelist]: #findandreplacelist
 
-[api-findandreplaceschema]: #findandreplaceschema
-
 [api-findandreplacetuple]: #findandreplacetuple
 
 [api-regexpmatchobject]: #regexpmatchobject