subslate

A configurable template string replacement

Install

Node.js & Browser

npm install subslate

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

Deno

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

Import in 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

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

Examples

For a full list see the examples directory (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

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])[]
options.escapeSep: {[K in 'json' | 'html' | 'url' | 'js']?: boolean
options.allowUnquotedProps: boolean
options.allowRootBracket: boolean
options.sanitizer: (v: SanitizerOptions) => string
options.maxNameLength: number (maximum character length between start and stop)

With Custom Brackets/Start-Stop

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

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.

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

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