filly

Small, extensible, Angular-style string templating

Features

• Angular-style pipes and params
  • Built-in substr and slice pipes
  • Optionally add your own custom pipes
• Support multiple brace depths
• Set default options (presets)
• Zero runtime dependencies

Usage

Basic Fill:

filly('Hello {foo}, I am {bar|slice:1:-1}!', { foo: 'friend', bar: '"filly"' });
// Output: 'Hello friend, I am filly!'

Custom presets:

const myfilly = filly({
	pipes: {
    lower: (val) => val.toLowerCase(),
    upper: (val) => val.toUpperCase(),
  },
});

myfilly('{foo|upper} - {bar|lower}', { foo: 'big', bar: 'SMALL' });
// Output: 'BIG - small'

See API for more details and examples.

API

filly

filly(template: string, source: object | Function, options?: Options): string;

filly(options: Options): (template: string, source: object | Function, options?: Options) => string;

Name | Type | Description --- | --- | --- template | string | The template to fill source | object | Function | The source object or callback from which to obtain values. If an object is passed, nested properties are supported. See SourceFunc for info on passing a callback function. options | object | Configurable options for the fill function. See Options

Options

Name | Type | Default value | Description --- | --- | --- | --- pipes | object | {} | A string-keyed object containing callbacks to be used for custom pipes. Pipes take the form (value: string, ...params: string[]) => string transform | Function | undefined | An additional transformation to perform on values after any pipes have executed. See TransformFunc for details. notFoundValue | string | Function | '' | The value to insert when the placeholder key is not found. If source is a function, this option is ignored. A callback function may also be supplied which takes the same form as SourceFunc

SourceFunc

(key: string, info: { pipe: string, params: string[], depth: number }) => string

Name | Description --- | --- key | The name (first part) of the placeholder info | Additional information about the placeholder info.pipe | The name of the pipe in the placeholder, if any info.params | A copy of the additional parameters to be passed to the pipe, if any info.depth | The number of braces used to enclose the placeholder. See also Gotcha: Asymmetric Braces

Example:

Template:  '{{nickName|foo:bar:baz}}'
Values passed to SourceFunc:
  ('nickName', { pipe: 'foo', params: ['bar', 'baz'], depth: 2 })

TransformFunc

(value: string, info?: { key: string, pipe: string, params: string[], depth: number }) => string

Name | Description --- | --- value | The current value of the placeholder info | Additional information about the placeholder info.key | The name (first part) of the placeholder info.pipe | The name of the pipe in the placeholder, if any info.params | A copy of the additional parameters to be passed to the pipe, if any info.depth | The number of braces used to enclose the placeholder. See also Gotcha: Asymmetric Braces

Gotchas

Asymmetric Braces

If the number of braces on one side of a placeholder is different from the other (such as due to a typographical error), the depth will be the lower of the two numbers. However, all braces will still be removed from both sides of the placeholder upon replacement.

Example | Depth --- | --- {foo}} | 1 {{{{bar}}} | 3

filly('This placeholder has a depth of {{foo}}}', (key, info) => {
  return String(info.depth);
});
// Output: 'This placeholder has a depth of 2'
// Note that all 3 braces were removed from the right side.

Params are immutable

The info.params arrays passed to source and tranform callbacks are copies of the array used internally by filly, so changes to their values will not affect other callbacks, pipes, or the final replacement value, making the params effectively immutable from the perspective of the user. This was done to ward against unintended side effects.

Contributing

Contributions and feedback are welcome and appreciated! Please visit the GitHub repo to submit an issue or pull request.

Recognition

Thanks to the Angular Team and sindresorhus (author of pupa), whose work contributed greatly to the inspiration of filly.