# string-replace-async

> Asynchronous String.prototype.replace()

Latest version **3.0.2** (published 2021-09-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install string-replace-async
pnpm add string-replace-async
yarn add string-replace-async
bun add string-replace-async
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2021-09-10 |
| First published | 2016-01-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >= 14.0.0 |
| Dependencies | 0 |
| Unpacked size | 6.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 42 |
| Author | Dmitrii Sobolev |
| Maintainers | dsblv |
| Keywords | string, replace, regexp, match, async, asynchronous, promise, concurrent |

## Links

- npm: https://www.npmjs.com/package/string-replace-async
- Repository: https://github.com/dsblv/string-replace-async
- Homepage: https://github.com/dsblv/string-replace-async#readme
- Issues: https://github.com/dsblv/string-replace-async/issues
- npm.io page: https://npm.io/package/string-replace-async

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 3.0.2 (latest) — 2021-09-10
- 3.0.1 — 2021-08-27
- 3.0.0 — 2021-08-27
- 2.0.0 — 2020-07-01
- 1.2.1 — 2017-07-20
- 1.2.0 — 2016-02-02
- 1.1.0 — 2016-01-29
- 1.0.0 — 2016-01-29

## README

# string-replace-async

> A vesion of "string".replace() that knows how to wait

## Installation

```
$ npm install string-replace-async
```

**Note:** If you're using pre-14 version of Node or your node codebase isn't converted to [ES Modules](https://nodejs.org/api/esm.html#esm_introduction) yet, please use Version 2 specifically!

```
$ npm install string-replace-async@^2.0.0
```

## Usage

```js
import replaceAsync from "string-replace-async";

await replaceAsync("#rebeccapurple", /#(\w+)/g, async (match, name) => {
  let color = await getColorByName(name);
  return "#" + color + " (" + name + ")";
});
```

## The Why

Say you have a task of replacing color names with their respective hex codes.

```js
let spec = "I want background to be #papayawhip and borders #rebeccapurple.";
// make it "I want background to be #FFEFD5 (papayawhip) and borders #663399 (rebeccapurple).";
```

Luckily, strings in JavaScript have this handy `replace` method built in, so you use it.

```js
spec.replace(/#(\w+)/g, (match, name) => {
  let color = getColorByName(name);
  return "#" + color + " (" + name + ")";
});
```

Time passes, a new requirement emerges: now you have to query a database for custom colors. This is an async operation, so naturally you convert `getColorByName` into async function.

Turns out it has a cost: now all the code above should also be async. You try this:

```js
await spec.replace(/#(\w+)/g, async (match, name) => {
  let color = await getColorByName(name);
  return "#" + color + " (" + name + ")";
});
```

Unfortunately, this code doesn't work as you expect. **Built in menthod wasn't designed to work as async function.**

This is where `string-replace-async` comes in:

```js
await replaceAsync(spec, /#(\w+)/g, async (match, name) => {
  let color = await getColorByName(name);
  return "#" + color + " (" + name + ")";
});
```

Yay!

`string-replace-async` is nothing but direct `String.prototype.replace` replacement that awaits your function and returns a Promise for results.

## API

API is
[String.prototype.replace()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), except the first argument is a string itself.

### replaceAsync(string, searchValue, replace)

Runs `replace` and waits for it to resolve before replacing `searchValue` with results. If `searchValue` is a _global_ RegExp, `replace` will be called concurrently for every match.

#### string

Type: `string`  
_Required_

An input string.

#### searchValue

Type: `regexp`, `string`

An expression to match substrings to replace.

#### replace

Type: `function`, `string`

A `function` that takes [several arguments](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_function_as_a_parameter) and returns a `promise`. Resolved value will be used as _replacement substring_.

## A Note on Concurrency

Previously this module had an additional function `seq()` that ran `replace` functions one by one instead of all at once. We decided to remove it to narrow our scope. Here's a snippet that achieves the same effect:

```js
let sequence = Promise.resolve();
let seq = (fn) => (...args) => (sequence = sequence.then(() => fn(...args)));

await replaceAsync(
  "#rebeccapurple, #papayawhip",
  /#(\w+)/g,
  seq(async (match, name) => {
    let color = await getColorByName(name);
    return "#" + color + " (" + name + ")";
  })
);
```

## License

MIT © [Dmitrii Sobolev](http://github.com/dsblv)

---
_Source: https://npm.io/package/string-replace-async · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._