📇 strif
Utility for interpolating strings from a template with some data.
Features
- ✔︎ Simple
- ✔︎ Expandable/Configurable
- ✔︎ Type Checking
- ✔︎ No Dependencies
Introduction
Strif was initially created for one of my other libraries Loggin'JS which needed some features I could not find in other libraries and decided to do it myself.
What I needed was to be able to process a string in segments, and apply some format to each segment, with the option to enable/disable which parts are formatted and which parts are not.
For example:
- Formating log messages, where some part need to be colored, some need to be converted to a specific date format. Etc...
- Filling in a string with any data
Most simple example, so you get an idea:
const githubRepoLink = strif
.template('https://github.com/{owner}/{repo}')
.compile({ owner: 'loggin-js', repo: 'strif' });
console.log(githubRepoLink);The above example would output the following:
Table Of Content
- Introduction
- Installation
- Importing
- Usage
- Examples
- Api
- Found a bug or have a feature request
- Contributing
Installation
Install from npm:
$ npm install strif
Importing
With require:
const strif = require('strif');With ES6 import:
import strif from 'strif';In the browser:
<script src="node_modules/strif/dist/strif.dist.js"></script>! NOTICE: Plugins currently don't work in browser, woking on it. PRs Welcome
Usage
Using in Node
Using strif is actually pretty easy, you can use the default formatter under strif. This formatter contains a set of predefined formatters (if you want to add you custom formatters, see the next point)
let template = strif.template('{time} {user} {message}');
template.compile(data);
// Or
strif.compile('{time} {user} {message}', data);or create a custom one by using strif.create(opts), you can pass a set of transformers, plugins and other options
const formatter = strif.create({
transformers: {
date: s => new Date(s),
lds: d => d.toLocaleString()
}
});
let template = formatter
.template('{time} {user} {message}')
.prop('time', { transformers: [`date`] });
let formatterString =
template.compile({
time: 11223322,
message: 'This is a super long message ',
user: { name: 'Bob' }
});
console.log(formatterString);Using in Browser
Using strif in the browser is as simple as in node, just import the script strif/dist/strif.dist.js
<html lang="en">
<head>
<script src="node_modules/strif/dist/strif.dist.js"></script>
</head>
<body>
<script>
strif.create(); // strif is available
</script>
</body>
</html>! NOTICE: Plugins currently don't work in browser, woking on it. PRs Welcome
Examples
I think looking at an example will help understand what strif does better than words:
Fill slug with data
const githubRepoLink = strif
.template('https://github.com/{owner}/{repo}')
.compile({ owner: 'loggin-js', repo: 'strif' });
console.log(githubRepoLink);The above example would output the following:
Formatting a log message
const template = strif
.template('[{time}] {user} - {message}', {
props: {
// `time` will be treated as a date, and apply the "lds" (toLocaleString) transformer
time: { transformers: [`date`, `lds`] },
// `user` specifies the dot notation path to the data ('user.name')
// transformers can also be functions
user: { transformers: [(c) => c.toUpperCase()], accessor: 'user.name' },
}
})
// props can be defined after creating the template, and can also define a type
.prop('message', { type: 'string' });
// If we want to apply data to the template, we do it by using the `compile()` method
const logMessage = template.compile({
time: Date.now(),
user: { name: 'Manolo' },
message: 'This is the message',
});The above example would output the following:
Api
strif
Exported members from strif.
interface strif {
create(opts: strif.StrifOptions): void;
Formatter: strif.Formatter;
}strif.Formatter
interface strif.Formatter {
constructor(opts: strif.FormatterOptions);
template(template: string, options: strif.TemplateOptions): strif.Template;
fromFile(path: string, options: strif.TemplateOptions): strif.Template;
}strif.Template
interface strif.Template {
constructor(template: string, transformers: { [key: string]: (v) => v }, options: strif.TemplateOptions);
prop(name: string, options: strif.PropOptions): this;
print(): void;
compile(data: object, options: { ignoreTransformers: string[] }): string;
}strif.Prop
interface strif.Prop {
constructor(name, opts: strif.PropOptions);
getFromObject(obj: object): any;
}strif.PropOptions
interface strif.PropOptions {
accessor: string;
type: string;
transformers: string[];
}strif.TemplateOptions
interface strif.TemplateOptions {
props: strif.StrifProp[];
}strif.FormatterOptions
interface strif.FormatterOptions {
transformers: { [key: string]: (v) => v };
plugins: string[];
}Transformers
Transformers are functions that are used to process some segment of the template,
they will receive a value and they must also return a value, here are some example:
{
transformers: {
date: s => new Date(s),
lds: d => d.toLocaleString()
}
}Plugins
I added a little bit of plugin support, what a plugin actually is, is an object (for now) wich contains transformers (also for now), and will be attached to any template generated by that transformer. Here are some example:
const chalk = require('chalk');
module.exports = {
transformers: {
blue: s => chalk.blue(s),
gray: s => chalk.gray(s),
green: s => chalk.green(s),
}
};Check this demo for another example.
Found a bug or have a feature request
If you found a bug or have a feature request please dont hesitate on leaving a issue
Contributing
If you would like to collaborate please check CONTRIBUTING.md for more details.
Considerations
This project was in some way inspired by @davidchambers/string-format, at least in the sense of the transformers concept.