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']?: booleanoptions.allowUnquotedProps:booleanoptions.allowRootBracket:booleanoptions.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.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>
`