# object-placeholder

> It's a zero-dependency package that exports default function: ```text placeholder(, , ) ``` and function with named params: ```text placeholder.replace({ template, data, options }) ``` where: - `template` - some template ( [string

Latest version **0.2.3** (published 2022-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install object-placeholder
pnpm add object-placeholder
yarn add object-placeholder
bun add object-placeholder
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2022-11-19 |
| First published | 2022-11-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 36.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Taras Panasiuk |
| Maintainers | webdev-taras |
| Keywords | placeholder, replace, template, templates, mustache, object, string |

## Links

- npm: https://www.npmjs.com/package/object-placeholder
- Repository: https://github.com/webdev-taras/object-placeholder
- Homepage: https://github.com/webdev-taras/object-placeholder#readme
- Issues: https://github.com/webdev-taras/object-placeholder/issues
- npm.io page: https://npm.io/package/object-placeholder

## 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.2.3 (latest) — 2022-11-19
- 0.2.2 — 2022-11-13
- 0.2.1 — 2022-11-08
- 0.2.0 — 2022-11-06
- 0.1.1 — 2022-11-05
- 0.1.0 — 2022-11-03
- 0.0.2 — 2022-11-03
- 0.0.1 — 2022-11-02

## README

# object-placeholder

It's a zero-dependency package that exports default function:
```text
placeholder(<template>, <data>, <options>)
```
and function with named params:
```text
placeholder.replace({ template, data, options })
```
where:
- `template` - some template ( [string](#string-template), [object](#object-template), [array](#array-template) )
- `data` - object with values to replace
- `options` - { [error, clone, stringify](#options) }

This function allows you to substitute ['mustache' like](#syntax) `{{<template>}}` by values in `<data>` param including all nested properties of object or array template.

## Usage

```javascript
const placeholder = require('object-placeholder')
// or
const { replace } = require('object-placeholder')
```

### `String` template:
```javascript
const template = '{{user.name}}, {{user.email}}, {{user.id}}'
const data = {
  user: {
    id: 1985,
    name: 'John Connor',
    email: 'john.connor@test.com'
  }
}

const result = placeholder(template, data)
// or
const result = replace({ template, data })
// result = 'John Connor, john.connor@test.com, 1985'
```

### `Object` template:
```javascript
const template = {
  target: {
    uuid: '&{{user.id}}',
    user: '{{user.name}}',
  },
  mailto: 'mailto:{{user.email}}',
}
const data = {
  user: {
    id: 1985,
    name: 'John Connor',
    email: 'john.connor@test.com'
  }
}
const result = placeholder(template, data)
/*
result = {
  target: { uuid: 1985, user: 'John Connor' },
  mailto: 'mailto:john.connor@test.com'
}
*/
```

### `Array` template:
```javascript
const template = {
  title: '{{ service.id }}',
  admin: '{{ service.members[0].id }}', // get first element of 'service.members'
  mailto: '{{service.members.0.email}}',
  emails: [
    '@{{ service.members | member }}', // for each item of 'service.members'
    '{{ @.member.email }}', // '@.member' - current item
  ],
  users: '&{{ service.members }}',
}
const data = {
  service: {
    id: 'SOME_IT_SERVICE',
    members: [
      { id: 'user1', email: 'user1@test.com' },
      { id: 'user2', email: 'user2@test.com' },
      { id: 'user3', email: 'user3@test.com' },
    ],
  },
}
const result = placeholder(template, data)
/*
result = {
  title: 'SOME_IT_SERVICE',
  admin: 'user1',
  mailto: 'user1@test.com',
  emails: [ 'user1@test.com', 'user2@test.com', 'user3@test.com' ],
  users: [
    { id: 'user1', email: 'user1@test.com' },
    { id: 'user2', email: 'user2@test.com' },
    { id: 'user3', email: 'user3@test.com' }
  ]
}
*/
```

[All examples](examples).

## Syntax

### 1. String value syntax

Returns the value converted to 'string' type
```text
{{property}}
```
Path can also be dot-separated:
```text
{{user.name}} {{user.email}} 
```

In this case `data` parameter should be the object:
```javascript
{
  property: 'blablabla',
  user: {
    name: 'John Connor',
    email: 'john.connor@test.com'
  }
}
```

### 2. Reference value syntax

Returns the value of original type
```text
&{{property}}
```

### 3. Loop syntax

Starts new loop for property of array type
```text
@{{ array | item }}
```

### 4. Item syntax

Returns the value of current item in a loop 
```text
{{@.item.property}}
```

## Options

By default
```javascript
options: {
  error: true,
  clone: true,
  stringify: true,
}
```

### `error`

Define how to manage the case when template was not resolved.\
If `true` then throw the Error immediately in place where value by specified path was not found.\
If `false` then just pass through this case and leave template string as is.\
If custom `function` passed then it will be used as error handler function.\
For more details see [test examples](test/error-option.test.js).

### `clone`

Clone the output value or not.\
If `true` then all properties of output object will be cloned.\
If `false` then 'object' type properties will refer to input data object properties.\
If custom `function` passed then it will be used as clone function.\
For more details see [test examples](test/clone-option.test.js).

### `stringify`

Stringify the value of non 'string' type.\
If `true` then `JSON.stringify()` will be used.\
If `false` then `value.toString()` will be used.\
If custom `function` passed then it will be used as stringify function.\
For more details see [test examples](test/stringify-option.test.js).

## Partial application

You can use partial application for `replace` function parameters in order to produce another function of smaller arguments i.e binding values to one or more of those arguments. For example:
```javascript
const { replace } = require('object-placeholder')

const template = '{{user.name}}, {{user.email}}, {{user.id}}'
const options = { clone: true }

const configured = replace({ template, options })

const result1 = configured({
  data: {
    user: {
      id: 1985,
      name: 'John Connor',
      email: 'john.connor@test.com'
    }
  }
})
// result1 = 'John Connor, john.connor@test.com, 1985'

const result2 = configured({
  data: {
    user: {
      id: 1965,
      name: 'Sarah Connor',
      email: 'sarah.connor@test.com'
    }
  }
})
// result2 = 'Sarah Connor, sarah.connor@test.com, 1965'

```

## Install

> Install on Node.JS with [npm](https://www.npmjs.com/)

```bash
$ npm install --save object-placeholder
```

## License

MIT © [Taras Panasyuk](webdev.taras@gmail.com)

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