Neanderthals Paint Mammals

    filly
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    npm version

    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.

    Install

    npm i filly

    DownloadsWeekly Downloads

    6

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    12.9 kB

    Total Files

    7

    Last publish

    Collaborators

    • zaneh