# detokenizer

> Replace tokens in a string.

Latest version **1.0.2** (published 2021-09-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install detokenizer
pnpm add detokenizer
yarn add detokenizer
bun add detokenizer
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2021-09-04 |
| First published | 2021-05-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 11.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | tomasklaen |
| Maintainers | tomasklaen |
| Keywords | string, replace, token |

## Links

- npm: https://www.npmjs.com/package/detokenizer
- Repository: https://github.com/tomasklaen/detokenizer
- Homepage: https://github.com/tomasklaen/detokenizer#readme
- Issues: https://github.com/tomasklaen/detokenizer/issues
- npm.io page: https://npm.io/package/detokenizer

## 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.0.2 (latest) — 2021-09-04
- 1.0.1 — 2021-05-07
- 1.0.0 — 2021-05-07

## README

# detokenizer

Replace tokens in a string based on token value map.

Supports dynamic tokens (regular expressions), and sync & async replacer functions.

## Install

```
npm install detokenizer
```

### Examples

Basic:

```ts
const {detokenize} = require('detokenizer');

detokenize('Hello {name}!', {'{name}': 'John'});
// => 'Hello John!'
```

Dynamic tokens:

```ts
detokenize('Hello {name}! Your email is {emoji:envelope} {email}.', [
  ['{name}', 'John'],
  ['{email}', 'john@example.com'],
  [/{emoji:(?<id>[a-z0-9]+)}/i, (token, match) => match.groups.id === 'envelope' ? '✉️' : '']
]);
// => 'Hello John! Your email is ✉️ john@example.com.'
```

Async:

```ts
const {detokenizeAsync} = require('detokenizer');

// Transform issue ids into anchor links with titles
await detokenizeAsync('Issue #42', [
  [
    /#(?<id>\d+)/,
    async (token, match) => {
      const issueTitle = await retrieveIssueTitle(match.groups.id);
      return `<a href="..." title="${issueTitle}">#${match.groups.id}</a>`;
    }
  ]
]);
// => 'Issue <a href="..." title="Issue title">#42</a>'
```

Token escaping:

*Add escape sequences to be replaced out as last tokens. (use dynamic tokens (regular expressions) for more advanced replacing)*

```ts
detokenize('\{foo\} value is {foo}', {
  '{foo}': 'bar',
  '\\{': '{',
  '\\}': '}',
});
// => '{foo} value is bar'
```

### Regular expressions

When using regular expressions as tokens to match against, **DO NOT** use the `g` (global) flag, or it'll break tokenizing.

## API

Exports:

### `detokenize(input, values)`

Parameters:

#### `input: string`

A string to run the replacer on.

#### `values: Record<string, string | number | Replacer> | Array<[string | RegExp, string | number | Replacer]>`

Values to substitute tokens with.

It can either be a basic `key: value` object:

```ts
detokenize('...', {
  foo: 'value',
  bar: (token) => `you used ${token} token`
});
```

Or if you want the dynamic tokens support, an array of map like entries:

```ts
detokenize('...', [
  ['foo', 'value'],
  [/bar/i, (token, match) => `you used ${match[0]} token`]
]);
```

##### `Replacer`

If assigned to a string token, replacer is:

```ts
(token: string) => string | number;
```

If assigned to a RegExp token, it is:

```ts
(token: RegExp, match: RegExpExecArray) => string | number;
```

Example.

```ts
const emojis = {
  envelope: '✉️',
  // ...
}

const emojiToken = /{emoji:(?<id>[a-z0-9]+)}/i;

function emojiReplacer(token, match) {
  return emojis[match.groups.id] || '';
}

detokenize('{emoji:envelope}', [[emojiToken, emojiReplacer]]);
```

### `detokenizeAsync(input, values): Promise<string>`

Same API as sync version, but `Replacer` can return a promise that resolves with a `string` or a `number`.

```ts
// Transform issue ids into anchor links with titles
await detokenizeAsync('Issue #42', [
  [
    /#(?<id>\d+)/,
    async (token, match) => {
      const issueTitle = await retrieveIssueTitle(match.groups.id);
      return `<a href="..." title="${issueTitle}">#${match.groups.id}</a>`;
    }
  ]
]);
// => 'Issue <a href="..." title="Issue title">#42</a>'
```

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