@zuze/interpolate

A tiny library for performing simple (and complex) interpolations and their reverse operations

Usage no npm install needed!

<script type="module">
  import zuzeInterpolate from 'https://cdn.skypack.dev/@zuze/interpolate';
</script>

README

interpolate

npm version Coverage Status Build Status Bundle Phobia install size

Interpolate is used to perform simple interpolations and (as best possible) their reverse operations.

import { interpolate, unterpolate } from '@zuze/interpolate';

const template = '{year}-{month}-{day}';
const interpolated = '2019-10-01';

unterpolate(template, interpolated) 
/*
{
    year:'2019',
    month:'10',
    day:'01'
}
*/

interpolate(template, {
    year: '2019',
    month: '10',
    day: '01'
});

// '2019-10-01'

Installation

Same as usual, npm:

npm install @zuze/interpolate

or yarn:

yarn add @zuze/interpolate

You can also use it directly in the browser by doing:

<script src="https://unpkg.com/@zuze/interpolate"></script>
<script>
 // creates a global variable ZInterpolate
 const { unterpolate, interpolate, get, set, parts } = ZInterpolate;
</script>

Usage

Interpolations are ubiquitous, from the first templating engines, to internationalization, etc.

Interpolations don't have to just work for creating strings, however. With the right tools, it can be used to create more complex data transformations, which is the purpose of interpolate.

Deeply Nested Objects

In addition to simple string mapping (see the first unterpolate example) interpolate supports transformations to/from deeply nested objects:

import { unterpolate, interpolate } from '@zuze/interpolate';


const template = '{first.second}-{first.third}-something-{first.fifth[0]}';
const interpolated = '2019-10-something-01';

interpolate(template,interpolated) 

/*
{
    first: {
        second:'2019',
        third:'10',
        fifth:['01']
    }
}
*/

unterpolate(template,{
    first: {
        second:'2019',
        third:'10',
        fifth:['01','02','03','04'] // extraneous values will be ignored
    }
});

// '2019-10-something-01'

NOTE: interpolate also accepts a function:


import { unterpolate, interpolate } from '@zuze/interpolate';

const template = '{year}-{month}-{day}';
const first = {
    year: '2019',
    month: '09',
    day: '01',
};

const second = {
    year: '2020',
    month: '10',
    day: '15',
};

const replacer = replaceWhat => replaceWhat === 'year' ? second[replaceWhat] : first[replaceWhat];
interpolate(template,replacer); //2020-09-01

complex object/array mapping

We don't only interpolate an object's values to a string, we can interpolate them into a complex structure:

interpolated value is an array

const template = ['{first}','{second.first}','{third}-something'];
const interpolated = [['an','array'],20,'somestring-something'];

unterpolate(template,interpolated);
/*
{
    first: ['an','array'],
    second: {
        first:20
    },
    third: 'somestring'
}
*/

// and magically...

interpolate(template, {
    first: {
        first: 'a',
        second: 'b',
    },
    second: {
        first: [ 'an', 'array' ]
    },
    third: 'must be a string'
});

/*
[
    {
        first:'a',
        second:'b'
    },
    ['an','array'],
    'must be a string-something'
]
*/

interpolated value is an object

const template = {
    first: '{someKey}',
    second: {
        third: '{first.first.0}'
    },
    fourth: [
        'key1', // no { }
        '{key1}',
        '{first.second}'
    ]
}

const interpolated = {
    first: 'something',
    second: {
        third: ['joe']
    },
    fourth: [
        'key1',
        'tom',
        'bill'
    ]
}

unterpolate(template,interpolated);
/*
{
    someKey:'something',
    first: {
        first:['joe'],
        second:'bill'
    },
    key1:'tom',
}
*/

in/unterpolating using a function

Truth be told, unterpolate was created to be able to do transformations through configuration which, under the circumstances in which it was developed, generally meant "through strings".

For full flexibility, interpolate does support using a function to perform interpolations and their reverse operations.

The function receives the the value being in/unterpolated and the options given to the unterpolate/interpolate function with a key of how whose value is either unterpolate or interpolate.

Note: If unterpolate the return value from the function must be false-y or an object - anything else will throw an error.

import { interpolate, unterpolate } from '@zuze/interpolate';

const template = {
    first: (val, opts) => opts.how === 'interpolate' ? { prop: val / 2 } : val['prop'] * 2
};

const value = {
    first: 20,
};

const expected = {
    prop: 10,
};

unterpolate(template,value); // { prop: 10 }
interpolate(template,expected); // { first: 20 }

match regexp

The default RegExp that determines what is an interpolation is /\{(.+?)\}/g - or anything enclosed in curly braces - i.e. {first}.

An object is created out of the matched strings which is then unflattened to create non-trivial structures.

You can pass a different match regexp, if it suits your purposes, to unterpolate and interpolate like so:


const template = '$year$-$month$-$day


to(template,'2019-10-01',{match:/\$(.+?)\$/g})

/*
{
    year:'2019',
    month:'10',
    day:'01'
}
*/

Dynamic Array Mapping

A difficult problem is dynamically uninterpolating complex arrays to the appropriate object structure.

const template = {
    options: [
        { keyToMapBy: 'a', value: '{fieldA}' },
        { keyToMapBy: 'b', value: '{fieldB}' },
        { keyToMapBy: 'c', value: '{fieldC}' },
    ],
}

const interpolated = {
    options: [
        { keyToMapBy: 'a', value: 'some val a' },
        { keyToMapBy: 'c', value: 'some val c' },
        { keyToMapBy: 'b', value: 'some val b' },
    ],  
}


to(template,interpolated);

/*
by default this would happen:
{
    fieldA: 'some val a',
    fieldB: 'some val c', 
    fieldC: 'some val b'    
}
*/

This can be solved by supplying the mapper option to unterpolate:

const template = {
    options: [
        { keyToMapBy: 'a', value: '{fieldA}' },
        { keyToMapBy: 'b', value: '{fieldB}' },
        { keyToMapBy: 'c', value: '{fieldC}' },
    ],
}

const interpolated = {
    options: [
        { keyToMapBy: 'a', value: 'some val a' },
        { keyToMapBy: 'c', value: 'some val c' },
        { keyToMapBy: 'b', value: 'some val b' },
    ],  
}


to(template,interpolated, { 
    mapper: { 
        // [`key of field that we are mapping`]: 'keyToBeCompared'
        options: 'keyToMapBy' 
    }
});

/*
destructured correctly:
{
    fieldA: 'some val a',
    fieldB: 'some val b', 
    fieldC: 'some val c'    
}
*/

You can also pass a plain function that accepts the array item in the template, the array of the value and the index:

const template = {
    options: [
        { keyToMapBy: 'a', value: '{fieldA}' },
        { keyToMapBy: 'b', value: '{fieldB}' },
        { keyToMapBy: 'c', value: '{fieldC}' },
    ],
}

const interpolated = {
    options: [
        { keyToMapBy: 'a', value: 'some val a' },
        { keyToMapBy: 'c', value: 'some val c' },
        { keyToMapBy: 'b', value: 'some val b' },
    ],  
}


to(template,interpolated, { 
    mapper: { 
        // the default array uninterpolater looks exactly like this:
        options: (template,arr = [],idx) => arr[idx]
    }
});

API

unterpolate(template: string | function | object | array, value: any, options: {match: RegExp, mapper: Mapper}): Uninterpolated Object

The unterpolate method is what creates the uninterpolated object from the template and value.

The mapper option is used to dynamically uninterpolate arrays:

type MappingFunction = (template: any, arr: T[], idx: number) => T | undefined;
type Mapper = { [key: string]: string | MappingFunction } | MappingFunction;

interpolate(template: string | function | object | array, value: object | (key: string) => any, options: {match: RegExp}): Interpolated Value

The interpolate method is what creates the interpolated value from an object (or replacer function that can provide the values for interpolate)

Additional Methods

This package exposes some additional methods that are useful:

keyMapper(key: string, comparator?: (a,b) => a === b)

When a string is given as a mapper, a keyMapper is used to compare array items. A custom comparator option can be given to it as an argument.

Comparing array items at object keys is highly useful, but ff this won't suffice for your needs, you'll probably want to just define your own MappingFunction.

get(object: object, path: string, default?: any): any

Equivalent to lodash get.

set(object: object, path: string, value: any, immutable?: boolean = false): any

Equivalent to lodash set with optional parameter to immutably set the property.

parts(path: string): string[]

Parses a path like first[1].second.third.9 into parts: ['first', '1', 'second', 'third', '9'].

unflatten(object: object): object

Like unflatten method in flat.