custom-interpolator v1.0.0

custom-interpolator

An interpolation library that interpolates values and object properties using custom interpolation rules.

Supported browsers

es5 compliant browsers with Array#find and Symbol polyfills.

Installing

When using yarn:

yarn add custom-interpolator

When using npm:

npm install custom-interpolator

When using a script tag:

<script src="custom-interpolator.js"></script>

Importing

When using TypeScript or es2015 modules:

import * as customInterpolator from "custom-interpolator";

// or

import { create } from "custom-interpolator";

When using CommonJS:

const customInterpolator = require("custom-interpolator");

When using AMD:

define(["custom-interpolator"], (customInterpolator) => {
  // ...
});

Creating

const interpolator = customInterpolator.create();

Interpolation

Interpolation is based on rules. Each time values are passed to any of the interpolation methods, a suitable rule is matched, based on type of these values.

Builtin rules:

• number, that interpolates from the source to the target number,
• relative string, that interpolates from the source number to the source number plus the value of the relative string.

Interpolation methods return an interpolation function that has this signature: (progress: number) => sourceValue.

Interpolating single values

Interpolation of single values is performed by the interpolate method.

Interpolating numeric values

const interpolationFunc = interpolator.interpolate(0, 100);

interpolationFunc(0); // 0
interpolationFunc(0.5); // 50
interpolationFunc(1); // 100

Interpolating relative values

Positive relative values:

const interpolationFunc = interpolator.interpolate(50, "+100");

interpolationFunc(0); // 50
interpolationFunc(0.5); // 100
interpolationFunc(1); // 150

Negative relative values:

const interpolationFunc = interpolator.interpolate(50, "-100");

interpolationFunc(0); // 50
interpolationFunc(0.5); // 0
interpolationFunc(1); // -50

Errors

interpolate throws an error when given values, for which no matching rules exist.

Interpolating object properties

Interpolation of object properties is performed by the interpolateObject method. Properties from the source object that should be interpolated, must be defined in the target object. Interpolation rules are then matched based on values of each property and the property name.

const source = { prop1: 0, prop2: 0, prop3: 0 };
const target = { prop1: 100, prop2: "-10" };
const interpolationFunc = interpolator.interpolateObject(source, target);

interpolationFunc(0); // { prop1: 0, prop2: 0, prop3: 0 }
interpolationFunc(0.5); // { prop1: 50, prop2: -5, prop3: 0 }
interpolationFunc(1); // { prop1: 100, prop2: -10, prop3: 0 }

Custom interpolation rules

Rule definition

Rules consist of two functions:

• supports(source: any, target: any, propName?: string), which decides what value types or property names does this rule support,
• prepare(source: any, target: any), which prepares and returns an interpolation function for this rule.

For example, the snippet below defines a rule, that will interpolate values in an object under the property named prop1, using the interpolation function returned by prepare.

import { InterpolationRule } from "custom-interpolator";

const rule: InterpolationRule<number, string> = {
  supports(source: any, target: any, propName: string) {
    return propName === "prop1";
  },

  prepare(source: number, target: string) {
    return progress => progress * source;
  },
};

Rule registering

Custom rules are registered, by passing them as options to the create factory function.

import { create } from "custom-interpolator";

const interpolator = create({
  rules: [rule],
});

License

This project is licensed under the MIT License - see the LICENSE.md file for details.