# stubber-interpolation-pkg

> This is the Stubber Interpolation Package, used by services to interpolate a `field`, specified as a string, from `data`, which is generally an object.

Latest version **1.13.3** (published 2024-10-24) · ISC license · 0 weekly downloads

## Install

```sh
npm install stubber-interpolation-pkg
pnpm add stubber-interpolation-pkg
yarn add stubber-interpolation-pkg
bun add stubber-interpolation-pkg
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.13.3 |
| Published | 2024-10-24 |
| First published | 2022-12-08 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 12 |
| Unpacked size | 42.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | ivanstubber, hansies, abriestubber, hassan-stubber, abrie-stubber, vincent_stubber.com, charlinm-stubber |

## Links

- npm: https://www.npmjs.com/package/stubber-interpolation-pkg
- Repository: https://github.com/stubber/stubber-interpolation-pkg
- Homepage: https://github.com/stubber/stubber-interpolation-pkg#readme
- Issues: https://github.com/stubber/stubber-interpolation-pkg/issues
- npm.io page: https://npm.io/package/stubber-interpolation-pkg

## Dependencies (12)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [marked](https://npm.io/package/marked.md) ^14.1.3
- [moment](https://npm.io/package/moment.md) ^2.29.4
- [jsonata](https://npm.io/package/jsonata.md) ^2.0.2
- [turndown](https://npm.io/package/turndown.md) ^7.2.0
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.7
- [sugar-date](https://npm.io/package/sugar-date.md) ^2.0.6
- [sync-fetch](https://npm.io/package/sync-fetch.md) ^0.5.2
- [require-dir](https://npm.io/package/require-dir.md) ^1.2.0
- [html-to-text](https://npm.io/package/html-to-text.md) ^9.0.5
- [simple-crypto-js](https://npm.io/package/simple-crypto-js.md) ^3.0.1
- [require-directory](https://npm.io/package/require-directory.md) ^2.1.1

## Recent versions

- 1.13.3 (latest) — 2024-10-24
- 1.13.1 — 2024-10-23
- 1.13.0 — 2024-10-22
- 1.12.1 — 2024-10-11
- 1.9.1 — 2024-08-15
- 1.12.0 — 2024-07-19
- 1.11.1 — 2024-06-27
- 1.11.0 — 2024-06-27
- 1.10.2 — 2024-06-21
- 1.10.1 — 2024-05-24
- 1.10.0 — 2024-04-10
- 1.9.8 — 2024-04-10
- 1.9.7 — 2024-04-10
- 1.9.6 — 2024-04-10
- 1.9.5 — 2024-04-09
- … 43 more at https://npm.io/package/stubber-interpolation-pkg/versions

## README

# stubber-interpolation-pkg

This is the Stubber Interpolation Package, used by services to interpolate a `field`, specified as a string, from `data`, which is generally an object.

[See the wiki page](https://wiki.stubber.zone:3443/en/concept/app/interpolation)

The package exports a function called `Plugin`. The `Plugin` function returns an object that contains a function called `process`. This `process` function takes two parameters, `field` and `data`. It then extract variables specified in `field` from `data`. See usage example in the **Usage** section

# Building

To update the npm package version, you have to run `npm version {{update_type}}`.
If the package version is `x.y.z` the following applies:

- `npm version major` updates `x`
- `npm version minor` updates `y`
- `npm version patch` updates `z`

> Take a look at [npm's semantic versioning](https://docs.npmjs.com/about-semantic-versioning#incrementing-semantic-versions-in-published-packages) to decide what update to apply.

The `npm version {{update_type}}` command creates a commit on the repo with the updated version number in the `package.json` file.
**REMEMBER** to push this commit to the repo, or the next person to run `npm publish` will get an error.

Then run `npm publish`, which will compress the project and publish it to npm. Files that should not be public should be placed in the `.npmigore` file.

In summary

```
npm version {{update_type}} # major, minor, patch
npm publish
git push
```

# Usage

Import the `Plugin` function, and then call it with the `sref_co_host` and `sref_cc_host` values to ensure that `stublinks` and `stuburls` point to live/dev.

```
import { Plugin } from "stubber-interpolation-pkg"

let interpolation = Plugin({
      sref_co_host: config.sref_co?.host,  // "http://sref.co" or http://dev.sref.co",
      sref_cc_host: config.sref_cc?.host, // "http://sref.cc" or http://dev.sref.cc",
      stubby_url_shortener_host: config.stubby_url_shortener?.host // "http://stub.by" or "http://dev.stub.by",
      stubby_url_shortener_security_token: config.stubby_url_shortener?.apikey,
    });

```

This interpolation can then be exported to use everywhere in the code. This is generally done as a plugin, which can be seen in the `stubber-core` project.

To use it:

```
interpolation.process(field, data)
```

## Local Development

The steps below walk through how you would add a new helper.

1. Open the [initHandlebars.js](./src/initHandlebars.js) file
1. Add a new file in the helpers directory
   - Use an existing helper as a starting point
1. Open the [interpolation.test.js](./test/interpolation.test.js) file and add at least one test for your helper
1. Run `npm run test` from the project directory to run the tests.
   - Ensure all tests pass
   - Remember to run `npm install` first if the run command fails.

## Result examples

eg:

```
"~~stub.number" -> "2022-12-07-1123"
"Hello {{name}}" -> "Hello Abrie"
```

Various field types are handled as follows:

- Pure strings - eg. `"some string"` Returned unchanged
- Strings starting with `~~` - eg `"~~stub.data.value"`, `value` are extracted from data as `stub.data.value`. This handles bracket notation as well, so the same value could also have been specified as `"~~stub[data][value]"`
- Integers and floats - eg `2` or `3.14` become strings `"2"` and `"3.14"`.
- Arrays - eg `["~~stub.data.value", "~~post.uuid"]` are run recursively, each element executes `interpolate` with the element as `field` and the same data as `data`. It then returns an array with each element interpolated `[stub_data_value, post_uuid]`
- Objects - eg `{stubnumber: "~~stub.number", d1:{d2:{d3:'~~d1.d2.d3'}}}` also run recursively, each nested value is interpolated and the result is returned as an object. `{stubnumber: "2022-12-07-1123", d1:{d2:{d3:'d3_value'}}}`

### Internal workings

The package uses the function `handleTildeNotation` to handle `fields` that starts with a double tilde ("`~~`").
The `handleHandlebarsTemplate` (lol) function is used to handle `fields` that contain plain strings or strings that contain `handlebar templates`, ie. anything with `{{}}` type syntax.

`Handlebar` `helpers` or `partials` are defined in the `src/initHandlebars.js` file.

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