Customizable String Formatter
npm install custom-string-formatterts
import {createFormatter, IFormatter} from 'custom-string-formatter';
class BaseFormatter implements IFormatter {
format(value: any): string {
// your own value formatting here;
return (value ?? 'null').toString();
}
}
// creating a reusable formatting function:
const format = createFormatter(new BaseFormatter());
// formatting a string with values from an object:
const s = format('Hello ${title} ${name}!', {title: 'Mr.', name: 'Foreman'});
console.log(s); //=> Hello Mr. Foreman!
`
And because the above is based on interfaces, you can simplify it to just:
`ts
const format = createFormatter({
format: (value: any) => (value ?? 'null').toString()
});
`
Installation
`sh
$ npm i custom-string-formatter
`
Current GitHub CI is set up for just NodeJS v18-v24, but it works in all browsers the same.
Variable Syntax
Basic variable syntax is as below:
* ${propertyName}
* $(propertyName)
* $
The extra syntax is for cases like combining it with ES6 Template Literals, etc.
Property names follow a simple JavaScript variable notation: the name can contain letters (case-sensitive),
digits, $, _ (underscore) and . for nested properties. For array access, like prop[123].value,
use prop.123.value syntax instead, for the fastest possible value resolution that avoids performance-expensive
property tokenization.
You can use a combination of the above inside one string, but you cannot combine opener-closer pairs, i.e.
something like ${propertyName) is invalid, and won't be recognized as a variable.
Full Syntax:
Full variable syntax supports a chain of nested properties, plus optional filters with arguments:
* ${prop1.prop2.prop3 | filter1 | filter2 | filter3 : arg1 : arg2}.
All spaces in between are ignored, i.e. ${ prop | filter : arg } works the same as ${prop|filter:arg}.
See the chapters below for further details.
Formatting Filters
Formatting filters can be appended to the property name after | separator, for value transformation, in the form
of ${propertyName | filter1 | filter2 | filter3}.
Filter names follow a simple JavaScript variable notation: the name can contain letters (case-sensitive),
digits, $ and _ (underscore).
Filters perform value transformation in the same order in which they are specified, as a pipeline, with the
output from the last filter going to the formatter, to be converted into a string (if needed).
Example of using formatting filters:
`ts
import {createFormatter, IFormatter, IFilter} from 'custom-string-formatter';
import dayjs from 'dayjs';
class JsonFilter implements IFilter {
transform(value: any): any {
return JSON.stringify(value); // transform into a JSON string
}
}
type DateInput = Date | number | string; // inputs that dayjs supports
class DateFilter implements IFilter {
transform(value: DateInput, args: string[]): string {
return dayjs(value).format(args[0]); // use dayjs to format the date
}
}
class BaseFormatter implements IFormatter {
format(value: any): string {
return (value ?? 'null').toString();
}
// name->object map of all our filters:
filters = {
date: new DateFilter(),
json: new JsonFilter()
};
}
const format = createFormatter(new BaseFormatter());
const s = format('${title} ${name} address: ${address | json}, updated: ${updated | date : DD-MM-YYYY}', {
title: 'Mr.',
name: 'Foreman',
address: {street: 'Springfield', house: 10},
updated: new Date()
});
console.log(s); //=> Mr. Foreman address: {"street":"Springfield","house":10}, updated: 09-11-2025
`
For more, see Examples in the WiKi.
$3
You can pass optional arguments into a filter after : symbol:
`
${propertyName | filterName : -123.45 : Hello World!}
`
For the example above, method transform will receive args set to ['-123.45', 'Hello World!'].
Passing in empty arguments like filter:::Hello World! or filter : : : Hello World! will produce a list of arguments
set to ['', '', 'Hello World!'].
IMPORTANT ☝
> Filter arguments cannot contain symbols |:{}<>(), as they would conflict with the variable syntax.
> To pass those in, you need to sanitize them (HTML-encode), as shown below.
Filter arguments are automatically HTML-decoded (unless [decodeArguments] override is present):
* € => €: decimal symbol codes (1–6 digits)
* 😊 => 😊: hexadecimal symbol codes (1–5 hex digits, case-insensitive)
---
List of symbols that must be encoded.
| symbol | decimal | hexadecimal |
|:------:|:--------:|:-----------:|
| \| | | | | |
| : | : | : |
| { | { | { |
| } | } | } |
| < | < | < |
| > | > | > |
| ( | ( | ( |
| ) | ) | ) |
---
You can use function [sanitizeFilterArgs] to encode all such special symbols automatically.
For manual conversion, use the table above or check out the
online helper.
You can also override method [decodeArguments], for the following purposes:
* to let the filter control individual argument decoding
* to optimize the filter's performance by not decoding some or all arguments
* to also remove accents (diacritical marks), supported by [decodeFilterArg]
Self-Reference
When a property chain starts with this (case-sensitive), the parser treats it as the reference to the parameter object
itself. It is to avoid wrapping the parameter object into another object when you want to format that parameter object
itself.
For the above example with the filter, we can use it like this:
`ts
const s = format('Address: ${this | json}', {street: 'Springfield', house: 10});
console.log(s); //=> Address: {"street":"Springfield","house":10}
`
Above, we referenced the parameter object itself, and then forwarded formatting into our json filter.
Because this references the parameter object, its use with nested properties is also valid - ${this.prop1.prop2},
though it may not have a practical need (use of this in this case is superfluous), but just for logical consistency.
Input Analysis
If you need to verify an input string for the variable references it has, this library offers three global
functions to help you with that:
| Function | Description |
|------------------|-----------------------------------------------------|
| [hasVariables] | A fast check if a string has valid variables in it. |
| [countVariables] | A fast count of valid variables in a string. |
| [enumVariables] | Enumerates and parses variables from a string. |
Example:
`ts
import {enumVariables} from 'custom-string-formatter';
enumVariables('${title} ${name} address: ${address | json}');
// ==>
[
{match: '${title}', property: 'title', filters: []},
{match: '${name}', property: 'name', filters: []},
{
match: '${address | json}',
property: 'address',
filters: [{name: 'json', args: []}]
}
]
`
Safety Checks
$3
The parser requires that any referenced property exists, or else it will throw Property "propName" does not exist.
This is to help with detection of invalid property names.
If a property is missing, it must be set to undefined before it can be referenced from a string, to avoid the error.
You can override such behavior by implementing [getDefaultValue] function inside [IFormatter] and return
a default value whenever the property cannot be resolved. This is, however, not the safest approach when no error is thrown,
as invalid property names can be easily missed.
$3
When using an unknown filter, the parser will throw Filter "filterName" not recognized`, to help with detection