find-replace

Replace or remove multiple items in an array.

Similar to array.prototype.splice() with the following differences:

• splice only operates on one item at a time requiring you to know its index. find-replace will operate on every item satisfying the find function.
• If a function is passed as a replaceWith argument, find-replace will invoke it to compute the replacement value.

Synopsis

import findReplace from 'find-replace'

const colours = ['red', 'white', 'blue', 'white']

const result = findReplace(
  colours,
  colour => colour === 'white',
  'gold'
)

console.log(result)
// [ 'red', 'gold', 'blue', 'gold' ]

If the replaceWith value is a function, it will be invoked with the found item and its result used as the replace value. For example:

const colours = ['red', 'white', 'blue', 'white']

const result = findReplace(
  colours,
  colour => colour === 'red',
  colour => colour.split('')
)

console.log(result)
// [ 'r', 'e', 'd', 'white', 'blue', 'white' ]

Real world examples

Replace with an array of strings

This example explodes combined (-vrf) into individual flags (-v -r -f).

import findReplace from 'find-replace'

const argv = ['-vrf', 'file1.js', 'file2.js']
const combinedShortOptionRe = /^-[^\d-]{2,}$/

const result = findReplace(
  argv,
  arg => combinedShortOptionRe.test(arg),
  arg => {
    return arg
      .slice(1) /* remove initial hypen */
      .split('')
      .map(letter => '-' + letter)
  }
)

console.log(result)

Output:

$ node example/argv.mjs
[ '-v', '-r', '-f', 'file1.js', 'file2.js' ]

Delete found items

If you omit the third replaceWith argument, all found items will be deleted.

import findReplace from 'find-replace'

const fruits = ['apple', 'pear', 'nectarine', 'pineapple', 'peach']
const bad = ['pear', 'pineapple']

const result = findReplace(
  fruits,
  fruit => bad.includes(fruit)
)

console.log(result)

Output:

$ node example/delete.mjs
[ 'apple', 'nectarine', 'peach' ]

API Reference

{{>main}}

Load anywhere

This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.

Node.js (CommonJS):

const findReplace = require('find-replace')

Node.js (ECMAScript Module):

import findReplace from 'find-replace'

Modern browser (ECMAScript Module):

import findReplace from './node_modules/find-replace/dist/index.mjs'

Old browser (adds window.findReplace):

<script nomodule src="./node_modules/find-replace/dist/index.js"></script>

© 2015-25 Lloyd Brookes <[email protected]>.

Test suite by test-runner. Documented by jsdoc-to-markdown.