npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@zuze/interpolate

v7.0.0

Published

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

Downloads

87

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.