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

Author: wooorm

index.js

@@ -1,12 +1,11 @@
 /**
- * @typedef {import('./lib/index.js').Options} Options
  * @typedef {import('./lib/index.js').Find} Find
+ * @typedef {import('./lib/index.js').FindAndReplaceList} FindAndReplaceList
+ * @typedef {import('./lib/index.js').FindAndReplaceTuple} FindAndReplaceTuple
+ * @typedef {import('./lib/index.js').Options} Options
  * @typedef {import('./lib/index.js').Replace} Replace
  * @typedef {import('./lib/index.js').ReplaceFunction} ReplaceFunction
  * @typedef {import('./lib/index.js').RegExpMatchObject} RegExpMatchObject
- * @typedef {import('./lib/index.js').FindAndReplaceTuple} FindAndReplaceTuple
- * @typedef {import('./lib/index.js').FindAndReplaceSchema} FindAndReplaceSchema
- * @typedef {import('./lib/index.js').FindAndReplaceList} FindAndReplaceList
  */
 
 export {defaultIgnore, findAndReplace} from './lib/index.js'

lib/index.js

@@ -17,10 +17,7 @@
  * @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 RegExpMatchObject
@@ -32,7 +29,7 @@
  * @property {[...Array<Parents>, Text]} stack
  *   All ancestors of the text node, where the last node is the text itself.
  *
- * @typedef {ReplaceFunction | string} Replace
+ * @typedef {ReplaceFunction | string | null | undefined} Replace
  *   Thing to replace with.
  *
  * @callback ReplaceFunction
@@ -66,7 +63,8 @@ import {visitParents} from 'unist-util-visit-parents'
 import {convertElement} from 'hast-util-is-element'
 import escape from 'escape-string-regexp'
 
-const own = {}.hasOwnProperty
+/** @type {Options} */
+const emptyOptions = {}
 
 /**
  * Default tag names to ignore.
@@ -84,52 +82,19 @@ export const defaultIgnore = ['math', 'script', 'style', 'svg', 'title']
  * 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
- *   Patterns to find.
- * @param {Options | Replace | null | undefined} [replace]
- *   Things to replace with (when `find` is `Find`) or configuration.
- * @param {Options | null | undefined} [options]
+ * @param {FindAndReplaceList | FindAndReplaceTuple} list
+ *   One or more find-and-replace pairs.
+ * @param {Readonly<Options> | null | undefined} [options]
  *   Configuration (when `find` is not `Find`).
  * @returns {undefined}
  *   Nothing.
  */
-export function findAndReplace(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
-  }
-
-  if (!settings) {
-    settings = {}
-  }
-
+export function findAndReplace(tree, list, options) {
+  const settings = options || emptyOptions
   const ignored = convertElement(settings.ignore || defaultIgnore)
-  const pairs = toPairs(schema)
+  const pairs = toPairs(list)
   let pairIndex = -1
 
   while (++pairIndex < pairs.length) {
@@ -243,39 +208,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

@@ -18,10 +18,9 @@
 *   [Use](#use)
 *   [API](#api)
     *   [`defaultIgnore`](#defaultignore)
-    *   [`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)
@@ -137,30 +136,21 @@ Default tag names to ignore (`Array<string>`).
 
 The defaults are `math`, `script`, `style`, `svg`, and `title`.
 
-### `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-find-and-replace-schema] or
-    [`FindAndReplaceList`][api-find-and-replace-list])
-    — several find and replaces
+*   `list` ([`FindAndReplaceList`][api-find-and-replace-list] or
+    [`FindAndReplaceTuple`][api-find-and-replace-tuple])
+    — one or more find-and-replace pairs
 *   `options` ([`Options`][api-options])
     — configuration
 
@@ -192,26 +182,14 @@ type FindAndReplaceList = Array<FindAndReplaceTuple>
 
 See [`FindAndReplaceTuple`][api-find-and-replace-tuple].
 
-### `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].
@@ -245,7 +223,7 @@ Thing to replace with (TypeScript type).
 ###### Type
 
 ```ts
-type Replace = ReplaceFunction | string
+type Replace = ReplaceFunction | string | null | undefined
 ```
 
 See [`ReplaceFunction`][api-replace-function].
@@ -279,7 +257,6 @@ Thing to replace with:
 This package is fully typed with [TypeScript][].
 It exports the additional types [`Find`][api-find],
 [`FindAndReplaceList`][api-find-and-replace-list],
-[`FindAndReplaceSchema`][api-find-and-replace-schema],
 [`FindAndReplaceTuple`][api-find-and-replace-tuple],
 [`Options`][api-options],
 [`RegExpMatchObject`][api-regexp-match-object],
@@ -406,7 +383,7 @@ abide by its terms.
 
 [api-default-ignore]: #defaultignore
 
-[api-find-and-replace]: #findandreplacetree-find-replace-options
+[api-find-and-replace]: #findandreplacetree-list-options
 
 [api-options]: #options
 
@@ -418,8 +395,6 @@ abide by its terms.
 
 [api-find-and-replace-list]: #findandreplacelist
 
-[api-find-and-replace-schema]: #findandreplaceschema
-
 [api-find-and-replace-tuple]: #findandreplacetuple
 
 [api-regexp-match-object]: #regexpmatchobject