https://github.com/josh-hemphill/subslate
A configurable template string replacement library for Node.js, web, and Deno
https://github.com/josh-hemphill/subslate
deno nodejs parser string-manipulation template
Last synced: 12 months ago
JSON representation
A configurable template string replacement library for Node.js, web, and Deno
- Host: GitHub
- URL: https://github.com/josh-hemphill/subslate
- Owner: josh-hemphill
- License: mit
- Created: 2021-01-29T04:37:19.000Z (over 5 years ago)
- Default Branch: latest
- Last Pushed: 2025-01-31T20:50:32.000Z (over 1 year ago)
- Last Synced: 2025-06-15T22:07:45.716Z (about 1 year ago)
- Topics: deno, nodejs, parser, string-manipulation, template
- Language: TypeScript
- Homepage:
- Size: 278 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# subslate
A configurable template string replacement library for Node.js, web, and Deno
[](https://github.com/josh-hemphill/subslate/releases)
[](https://npmjs.org/package/subslate)
[](https://deno.land/x/subslate/mod.ts)
[](https://doc.deno.land/https/deno.land/x/subslate/mod.ts)
[](https://travis-ci.org/josh-hemphill/subslate)
[](https://codecov.io/gh/josh-hemphill/subslate)
[](https://libraries.io/npm/subslate)
[](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
```
### From CDN
```html
```
## 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 = `
<% x%5B%22y%22%5D\\u2E0.z %>
`
const context = {x:{y:[{z:'hello'}]}}
const compiled = subslate(template,context,{
startStopPairs: ['<%','%>'],
escapeSep: {
json: true
html: true
url: true
js: true
}
})
compiled === `
hello
`
```
### 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 = `
<% [x].y %>
`
const context = {x:{y:'hello'}}
const compiled = subslate(template,context,{
startStopPairs: ['<%','%>'],
allowUnquotedProps: true
allowRootBracket: true
})
compiled === `
hello
`
```
## Reademe rewrite in progress...
## Contributors