Quick Take

import { strict as assert } from "assert";
import { er } from "easy-replace";

assert.equal(
  er(
    "&nBsp; NBsp &nbSP NbsP;",
    {
      leftOutsideNot: "",
      leftOutside: "",
      leftMaybe: ["&", "&"],
      searchFor: "nbsp",
      rightMaybe: ";",
      rightOutside: "",
      rightOutsideNot: "",
      i: {
        searchFor: true,
      },
    },
    " "
  ),
  "       "
);

Purpose

It's an alternative to JS regexes.

API

er(
  source_string,
  options_object,
  replacement_string
)

In other words, it's a "string-in, string-out" function with three input arguments, see them below.

API - Input

Input argument Type Obligatory? Description
source_string String yes Original string
options_object Plain Object yes Settings
replacement_string String no Replace all the findings with this. If missing, library runs on delete-only mode, it won't replace, just delete.

Options object:

Options object's key Type Obligatory? Description
leftOutsideNot String/Array of strings no Equivalent of regex negative lookbehind. This/these string(s) must not be present to the left of searchFor (plus any "maybe's" strings, see below), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
leftOutside String/Array of strings no Equivalent of regex positive lookbehind. This/these string(s) must be present to the left of searchFor (plus any "maybe's" strings, see below), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
leftMaybe String/Array no If this is present on the left side of the searchFor, replace/delete it together with searchFor, but don't fret if it's not found.
searchFor String only yes The keyword to look for in the source_string
rightMaybe String/Array of strings no If this is present on the right side of the searchFor, replace/delete it together with searchFor, but don't fret if it's not found.
rightOutside String/Array of strings no Equivalent of regex positive lookahead. This/these string(s) must be present to the right of searchFor (plus any "maybe's" strings, see higher), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
rightOutsideNot String/Array of strings no Equivalent of regex negative lookahead. This/these string(s) must not be present to the right of searchFor (plus any "maybe's" strings, see higher), in order for searchFor to be counted as "found". This input's contents are not replaced/deleted.
i Plain object no Each key mentioned above can be set to a Boolean true/false to optionally be case-insensitive. Same thing as i flag in regexes.

API - Output

Type Description
String String with things replaced

Examples

Simple replace:

  • Example replacement recipe in words — replace all instances of x with 🦄.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"a x c x d",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "x",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
},
"🦄"
);
console.log(res);
//=> 'a 🦄 c 🦄 d'

Case insensitive setting — set each and every key you want to ignore the case via opts.i:

const er = require("easy-replace");
const res = er(
"a X c x d",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "x",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
i: {
searchFor: true,
},
},
"🦄"
);
console.log(res);
//=> 'a 🦄 c 🦄 d'

"Maybes" — optional surrounding strings to be replaced as well

  • Example replacement recipe in words — Replace all instances of i. If there are 🐴 or 🦄 characters on the left, count them as part of found i and replace together as one thing. If there are 🐴 or 🦄 characters on the right, count them as part of found i and replace together as one thing.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"🐴i🦄 🐴i i🦄 i",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: ["🐴", "🦄"],
searchFor: "i",
rightMaybe: ["🐴", "🦄"],
rightOutside: "",
rightOutsideNot: "",
},
"x"
);
console.log(res);
//=> 'x x x x'

By the way, notice, how the values can be strings or arrays! The easy-replace doesn't accept array only for searchFor values — create a loop from the outside of this library, then call this library many times if you want to search for multiple values.

Case-insensitive setting will cover more surroundings' cases:

const er = require("easy-replace");
const res = er(
"Ai ib Aib i",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: ["a", "z"],
searchFor: "i",
rightMaybe: ["y", "b"],
rightOutside: "",
rightOutsideNot: "",
i: {
leftMaybe: true,
},
},
"x"
);
console.log(res);
//=> 'x x x x'

Negative lookahead - if you want to match something not followed by something else

  • Example replacement recipe in words — Replace all instances of 🦄, but only ones that don't have c or d on the right.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"a🦄c x🦄x",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "🦄",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: ["c", "d"],
},
"🐴"
);
console.log(res);
//=> 'a🦄c x🐴x'

Case insensitive setting will narrow-down the amount of findings/replacements:

const er = require("easy-replace");
const res = er(
"a🦄C x🦄x",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "",
searchFor: "🦄",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: ["c", "d"],
i: {
rightOutsideNot: true,
},
},
"🐴"
);
console.log(res);
//=> 'a🦄c x🐴x'

Positive lookbehind - if you want to match something that is preceded by something else

For example, search for space characters that have another space right to their left, and delete them

  • Example replacement recipe in words — Replace all occurencies of space character, but only those that have another space character in front of them.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"zzzzz zzzzzz zzzzzz",
{
leftOutsideNot: "",
leftOutside: " ", // <- space
leftMaybe: "",
searchFor: " ", // <- space
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
},
"" // <- empty string
);
console.log(res);
//=> 'zzzzz zzzzzz zzzzzz'

Negative lookbehind - if you want to match something that is NOT preceded by something else

For example, our <br /> sometimes look like <br/>. Replace all occurencies of /> with {{space character}}/> (disregard curly braces, it's only to make it more visible here) if they are not preceded with space already:

  • Example replacement recipe in words — Add missing spaces before closing slashes on tags. Do not add spaces where they exist already.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"<br /><br/><br />",
{
leftOutsideNot: " ",
leftOutside: "",
leftMaybe: "",
searchFor: "/>",
rightMaybe: "",
rightOutside: "",
rightOutsideNot: "",
},
" />"
);
console.log(res);
//=> '<br /><br /><br />'

Real life scenario

  • Example replacement recipe in words — Add a missing semicolon and/or ampersand on &nbsp;, but only where they are missing.

  • Solution using this library::

const er = require("easy-replace");
const res = er(
"&nbsp; nbsp &nbsp nbsp;",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "&",
searchFor: "nbsp",
rightMaybe: ";",
rightOutside: "",
rightOutsideNot: "",
},
"&nbsp;"
);
console.log(res);
//=> '&nbsp; &nbsp; &nbsp; &nbsp;'

If you want to cover cases of random letter capitalisation of n, b, s and p, just set case-insensitive flag for searchFor:

const er = require("easy-replace");
const res = er(
"&nBsp; NBsp &nbSP NbsP;",
{
leftOutsideNot: "",
leftOutside: "",
leftMaybe: "&",
searchFor: "nbsp",
rightMaybe: ";",
rightOutside: "",
rightOutsideNot: "",
i: {
searchFor: true,
},
},
"&nbsp;"
);
console.log(res);
//=> '&nbsp; &nbsp; &nbsp; &nbsp;'

Changelog

See it in the monorepo opens in a new tab, on GitHub.

Contributing

To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.

Licence

MIT opens in a new tab

Copyright © 2010–2021 Roy Revelt and other contributors

Related packages:

📦 edit-package-json 0.5.1
Edit package.json without parsing, as string, to keep the formatting intact
📦 str-indexes-of-plus 4.0.1
Like indexOf but returns array and counts per-grapheme
📦 email-all-chars-within-ascii 4.0.1
Scans all characters within a string and checks are they within ASCII range
📦 js-row-num 5.0.1
Update all row numbers in all console.logs in JS code
📦 line-column-mini 2.0.1
Convert string index to line-column position