# async-to-string

> Turn every (async or sync) value into a string

Latest version **1.1.0** (published 2022-09-08) · MIT license · 0 weekly downloads

## Install

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

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2022-09-08 |
| First published | 2022-09-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 19 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Han Dijk |
| Maintainers | handijk |
| Keywords | async, async-iterable, method, string, to-string, javascript |

## Links

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

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2022-09-08
- 1.0.0 — 2022-09-08

## README

# async-to-string

Turn every (async or sync) value into a string by calling `asyncToString` or by creating a tag function.

- [Installation](#installation)
- [Method usage](#method usage)
- [Tag usage](#tag usage)

## Installation

```
npm i async-to-string
```

## Method usage

Any value passed into the `asyncToString` method will be converted into a string.

```js
import { asyncToString } from 'async-to-string';

console.log(await asyncToString(1)); // -> '1'
console.log(await asyncToString(null)); // -> ''
```

Promise values will be awaited and the result will be passed into the `asyncToString` method and returned.

```js
import { asyncToString } from 'async-to-string';

console.log(await asyncToString(Promise.resolve(1))); // -> '1'
```

Async iterables will be looped and the last yield will be passed into the `asyncToString` method and returned.

```js
import { asyncToString } from 'async-to-string';

async function* generate() {
  yield 1;
  yield 2;
  yield 3;
}

console.log(await asyncToString(generate())); // -> '3'
```

Iterables will be joined together after every value was be passed into the `asyncToString` method.

```js
import { asyncToString } from 'async-to-string';

async function* generate() {
  yield 1;
  yield 2;
  yield 3;
}

const list = [1, Promise.resolve(2), generate()];

console.log(await asyncToString(list)); // -> '123'
```

Even methods can be passed in, they will be called and their return value will be passed into the `asyncToString` method before being returned.

```js
import { asyncToString } from 'async-to-string';

async function* generate() {
  yield 1;
  yield 2;
  yield 3;
}

console.log(await asyncToString(generate)); // -> '3'
```

An optional `args` iterable can be provided in the second options argument, it's items will be used as the arguments for calling any methods.

```js
import { asyncToString } from 'async-to-string';

console.log(await asyncToString((x, y) => x + y, { args: [6, 3] })); // -> '9'
```

Values will be passed on recursively so deeply nested hierarchies will all be turned into a single string.

```js
import { asyncToString } from 'async-to-string';

console.log(
  await asyncToString(
    [
      Promise.resolve(1),
      [(x, y) => x + y, Promise.resolve(['string', (x, y) => x - y])],
    ],
    { args: [6, 3] }
  )
); // -> '19string3'
```

If string encoding is required an `encode` option can be provided as method for instance to generate html safe strings.

```js
import { asyncToString } from 'async-to-string';
import { encode } from 'html-entities';

console.log(await asyncToString('< > " \' &', { encode })); // -> '&lt; &gt; &quot; &apos; &amp;'
```

To exclude a string from being encoded it can be marked as "safe".

```js
import { asyncToString, safeString } from 'async-to-string';
import { encode } from 'html-entities';

console.log(
    await asyncToString([
      '< > " \' &',
      safeString('< > " \' &'),
    ]
    { encode }
  )
); // -> '&lt; &gt; &quot; &apos; &amp;< > " \' &'
```

# Tag usage

The tag function `tagAsyncToString` returns a method that can be called with the options argument of the `asyncToString` method.

```js
import { tagAsyncToString } from 'async-to-string';

const template = tagAsyncToString`This is some string with an ${Promise.resolve('async replacement')}`;

console.log(
  await template({ /* asyncToString options can be provided here */ })
)
); // -> 'This is some string with an async replacement'
```

All values that `asyncToString` will convert to strings can be used as placeholders

```js
import { tagAsyncToString } from 'async-to-string';

const template = tagAsyncToString`This is some string with an ${Promise.resolve(
  'async replacement'
)}
Just showing off: ${[
  (x, y) => x + y,
  Promise.resolve(['string', (x, y) => x - y]),
]}`;

console.log(await template({ args: [6, 3] }));
// -> 'This is some string with an async replacement
// -> 'Just showing off: 19string3'
```

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