# interpolatr

> Parse any value in search of placeholders within strings and replace them accordingly.

Latest version **0.0.3** (published 2020-09-17) · GNU General Public License v3.0 license · 0 weekly downloads

## Install

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

## Health

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

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

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.3 |
| Published | 2020-09-17 |
| First published | 2020-08-08 |
| Weekly downloads | 0 |
| License | GNU General Public License v3.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 97 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Lazhar Ichir |
| Maintainers | lazharichir |
| Keywords | map, string interpolation, interpolation, deep, nested, pattern matching, deep map |

## Links

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

## Dependencies (10)

- [rfdc](https://npm.io/package/rfdc.md) ^1.1.4
- [picomatch](https://npm.io/package/picomatch.md) ^2.2.2
- [lodash.isnull](https://npm.io/package/lodash.isnull.md) ^3.0.0
- [lodash.isarray](https://npm.io/package/lodash.isarray.md) ^4.0.0
- [lodash.isnumber](https://npm.io/package/lodash.isnumber.md) ^3.0.3
- [lodash.isstring](https://npm.io/package/lodash.isstring.md) ^4.0.1
- [lodash.clonedeep](https://npm.io/package/lodash.clonedeep.md) ^4.5.0
- [lodash.isboolean](https://npm.io/package/lodash.isboolean.md) ^3.0.3
- [lodash.isundefined](https://npm.io/package/lodash.isundefined.md) ~3.0.1
- [lodash.isplainobject](https://npm.io/package/lodash.isplainobject.md) ^4.0.6

## 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

- 0.0.3 (latest) — 2020-09-17
- 0.0.2 — 2020-08-21
- 0.0.1 — 2020-08-08

## README

# Interpolatr

A string interpolator for deep, nested, complex structures. Pass any object and **Interpolatr** iteratess through every single property at any depth, including arrays. When a string value matches a `Pattern`, it is passed on to a `Resovler` that provides the replacement value.

Here is an example:

```ts
// Let's type the context object, if there's any
type Context = {
	name: string
}

/**
 * Create the handlers
 * `pattern` – the RegEx that will be used to test the string for our placeholder
 * `cleaner` – placeholders contain delimiters that we want to remove (e.g. `{{` and `}}`)
 * `resover` – returns the value to replace the placeholder with
 */
const handlers: Handlers<Context, string, string> = [
	// Matches pattern {{$.ctx.path.to.field.containing.the.data}}
	{
		id: `Context Replacer`,
		pattern: /{{(\$\.ctx\.[\s\S]+?)}}/g,
		cleaner: (placeholder: string) => placeholder.slice(2, -2),
		resolver: async (placeholder: string, context) => {
			if (placeholder.startsWith(`$.ctx.`)) {
				const value = get(context, placeholder.replace(`$.ctx.`, ``))
				return String(value)
			}
			return placeholder
		},
	},
	// Matches pattern {{$.fns.NAME_OF_FUNCTIN()}}
	{
		id: `Fns Replacers`,
		pattern: /{{(\$\.fns\.[\s\S]+?)}}/g,
		cleaner: (placeholder) => placeholder.slice(8, -2),
		resolver: async (placeholder, context) => {
			switch (placeholder) {
				case `now()`:
					return new Date().toISOString()
			}
			return placeholder
		},
	},
]

// Initialize the Interpolation, pass it the context data and the handlers
const interpolator = new Interpolation({ name: `John Dough` }, handlers)

// Interpolate the object
const result = await interpolator.interpolate({
	name: `{{$.ctx.name}}`,
	validUntil: `Around {{$.fns.now()}} :-)`,
})
```

The above gives `result.name` to equal `John Dough`.

## What for?

**Interpolatr** is useful when you have strings with placeholders (e.g. `{{name}}`). Such strings can be found in a very simple string, or as the value of a deeply nested object or array.

The library must be employed using `async/await` or `Promises`. This is useful when you need to perform asynchronous calls to perform an interpolation.

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