# subslate

> configurable template string replacement

Latest version **1.0.0** (published 2021-03-03) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 40/100 (D)** — status: abandoned.

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

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2021-03-03 |
| First published | 2021-03-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 10.14.2 |
| Dependencies | 0 |
| Unpacked size | 197.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Maintainers | joshhemphill |
| Keywords | string, formatting, template, parser, object, format, interpolate, interpolation, templating, parsing, configurable, custom, expand, simple, replace, placeholders, values, transform, light |

## Links

- npm: https://www.npmjs.com/package/subslate
- Repository: https://github.com/josh-hemphill/subslate
- Homepage: https://github.com/josh-hemphill/subslate#readme
- Issues: https://github.com/josh-hemphill/subslate/issues
- npm.io page: https://npm.io/package/subslate

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2021-03-03
- 1.0.0-alpha.3 (alpha) — 2021-03-04
- 1.0.0-alpha.2 — 2021-03-04
- 1.0.0-alpha.1 — 2021-03-03

## README

# subslate

A configurable template string replacement

<br />

<!-- cspell: disable bracketsstartstop -->

[![version](https://img.shields.io/github/v/tag/josh-hemphill/subslate?sort=semver&style=flat-square)](https://github.com/josh-hemphill/subslate/releases)
[![NPM](https://img.shields.io/static/v1?label=&message=NPM&color=informational&style=flat-square)](https://npmjs.org/package/subslate)
[![Deno](https://img.shields.io/static/v1?label=&message=Deno&color=informational&style=flat-square)](https://deno.land/x/subslate/mod.ts)
[![API doc](https://img.shields.io/static/v1?label=Deno&message=API-Doc&color=informational&style=flat-square)](https://doc.deno.land/https/deno.land/x/subslate/mod.ts)
<!-- [![docs](https://img.shields.io/static/v1?label=&message=Docs&color=informational&style=flat-square)](https://josh-hemphill.github.io/subslate/#/) -->
[![Build Status](https://img.shields.io/travis/josh-hemphill/subslate.svg?style=flat-square)](https://travis-ci.org/josh-hemphill/subslate)
[![Codecov](https://img.shields.io/codecov/c/github/josh-hemphill/subslate.svg?style=flat-square)](https://codecov.io/gh/josh-hemphill/subslate)
[![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/subslate?label=Deps&style=flat-square)](https://libraries.io/npm/subslate)
[![Rate on Openbase](https://badges.openbase.io/js/rating/subslate.svg)](https://openbase.io/js/subslate?utm_source=embedded&utm_medium=badge&utm_campaign=rate-badge)

## Install

### Node.js & Browser

```bash
npm install subslate
```

```js
/* ES Module / Typescript */ import { subslate } from "subslate";
/* CommonJS */ const { subslate } = require("subslate");
```

### Deno

```js
import subslate from "https://deno.land/x/subslate/mod.ts"
```

### Import in HTML

```html
<script type="text/javascript" src="dist/subslate.js"></script> <!-- For UMD module -->
<script type="text/javascript" src="dist/subslate.poly.iife.js"></script> <!-- For global IIFE with polyfills -->
<script type="module" src="dist/subslate.esm.js"></script> <!-- For ES Module -->
```

### From CDN

```html
<script type="text/javascript" src="https://unpkg.com/subslate"></script>
```

## Examples

For a full list see the [examples directory](./example/) (coming)

### Play with it

[CodePen (suggested)](##) (coming soon)

[JSFiddle](##) (coming soon)

## Usage

Create a template with any kind of start and stop characters and configurable object path indicators; or by default just use JS style template characters (don't forget to escape them in a JS template if you want them there to replace later)

### Basic Usage

```js
import { subslate } from "subslate";

const template = '${A} world ${x["y"].0.z}'

const context = {A: 'hi', x:{y:[{z:', hello'}]}}

const compiled = subslate(template,context)

compiled === 'hi world, hello'
```

## Options

`subslate(template,context,options)`

  - [`options.startStopPairs`: `string | (string | [string, string])[]`](#with-custom-bracketsstartstop)
  - [`options.escapeSep`: `{[K in 'json' | 'html' | 'url' | 'js']?: boolean`](#with-escaped-object-property-indicators)
  - [`options.allowUnquotedProps`: `boolean`](#with-root-and-unquoted-brackets)
  - [`options.allowRootBracket`: `boolean`](#with-root-and-unquoted-brackets)
  - [`options.sanitizer`: `(v: SanitizerOptions) => string`](#with-sanitizer)
  - `options.maxNameLength`: `number` (maximum character length between start and stop)

### With Custom Brackets/Start-Stop

```js
import { subslate } from "subslate";

const template = `
SELECT * FROM ![tables.table]
`
const context = {tables: {table: 'myTable'}}

const compiled = subslate(template,context,{
  startStopPairs: ['![',']']
  // startStopPairs gets normalized to an array of pairs, so
  // ['![',']'] gets turned into [['![',']']]
  // and '||' would get turned into [['||','||']]
  // or even mixed ['||',['${','}']] = [['||','||'],['${','}']]
})
compiled === `
SELECT * FROM myTable
`
```

### With Escaped Object Property Indicators

```js
import { subslate } from "subslate";

const template = `
<p>
  <% x%5B%22y%22%5D\\u2E0&period;z %>
</p>
`

const context = {x:{y:[{z:'hello'}]}}

const compiled = subslate(template,context,{
  startStopPairs: ['<%','%>'],
  escapeSep: {
    json: true
    html: true
    url: true
    js: true
  }
})
compiled === `
<p>
  hello
</p>
`
```

### With Sanitizer

The sanitizer recieves all errors and empty fields as well as successful values. So you have a chance to to correct how you want the final string to be injected. A sanitizer must allways return a string, otherwise the library throws an error.

```ts
import { subslate } from "subslate";

const template = 'SELECT * FROM ${myTable}${blabla}'
const context = {myTable:'hello'}

type SanitizerOptions = {
  // If there was no characters between the start and stop
  isEmpty: boolean,

  // The full id that was between start and stop
  id: string,

  // The index in the id where parsing stopped if there was a problem
  at?: number,

  // The value that was successfully found for a givin id
  value?: unknown,
}

function sanitizer: string (opts: SanitizerOptions) {
  if (opts.isEmpty || opts.at !== undefined) return ''; // to silence errors from resulting in the stringified "undefined" being injected.
  return opts.value;
}

const compiled = subslate(template,context,{sanitizer})
compiled === 'SELECT * FROM hello'
```

### With Root and Unquoted Brackets

```js
import { subslate } from "subslate";

const template = `
<p>
  <% [x].y %>
</p>
`

const context = {x:{y:'hello'}}

const compiled = subslate(template,context,{
  startStopPairs: ['<%','%>'],
  allowUnquotedProps: true
  allowRootBracket: true
})
compiled === `
<p>
  hello
</p>
`
```

<!-- markdownlint-disable-next-line-->
## Reademe rewrite in progress...

## Contributors

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- ALL-CONTRIBUTORS-LIST:END -->

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