interpolatable
v1.3.2
Published
Fast memoization for interpolatable entities
Downloads
9
Readme
interpolatable
A super tiny ( < 600 bytes minzipped) package that allows you to quickly (⚡) interpolate any values into any other value!
Installation
npm install interpolatable
## or
yarn add interpolatable
Or directly via the browser:
<script src="https://cdn.jsdelivr.net/npm/interpolatable"></script>
<script>
const descriptor = 'Hello {{user}}!';
const interpolate = interpolatable(descriptor);
const interpolated = interpolate({ user: 'Joe' });
// Hello Joe!
</script>
Usage
import interpolatable from 'interpolatable';
const interpolate = interpolatable({
weather: {
params: {
query: '{{city}}',
appId: '{{apiKey}}',
units: '{{units}}',
},
path: 'main.temp',
is: {
type: 'number',
minimum: '{{hotTemp}}',
},
},
});
const result = interpolate({
city: 'Halifax',
apiKey: 'XXX',
units: 'metric',
minimum: 20,
});
/*
{
weather: {
params: {
query: 'Halifax',
appId: 'XXX',
units: 'metric',
},
path: 'main.temp',
is: {
type: 'number',
minimum: 20,
},
},
}
*/
What in the heck is this good for?
Two things:
- Interpolating complex objects
- Doing 1 fast ⚡ (while maintaining referential integrity)
Referential Integrity
The "dependencies" of some nested structure to be interpolated are, in the below descriptor, defined by strings like: {{city}}
const descriptor = {
weather: {
params: {
query: '{{city}}',
appId: '{{apiKey}}',
units: '{{units}}',
},
path: 'main.temp',
is: {
type: 'number',
minimum: '{{hotTemp}}',
},
},
};
Rather than parse the entire structure every time it needs to be interpolated, which is expensive, we check at each node to see if the dependencies of that node (if there are any) have changed since the last run. If they haven't, then we return the last object and we can skip the expensive parsing operation.
The dependencies of the root node are: city
, apiKey
, units
, and hotTemp
. But if only hotTemp
changes between interpolations, we don't need to re-evaluate weather.params
because it's dependencies - city
, apiKey
, and units
haven't changed. So:
const interpolate = interpolatable(descriptor);
const first = interpolate({
city: 'Halifax',
apiKey: 'XXX',
units: 'metric',
minimum: 20,
});
const second = interpolate({
city: 'Halifax',
apiKey: 'XXX',
units: 'metric',
minimum: 25,
});
console.log(first === second); // false
console.log(first.weather.params === second.weather.params); // same object! dependencies didn't change between runs
API
function interpolatable<T = string | Record<string, unknown> | unknown[]>(
subject: T,
options?: Options<R>,
): <R>(context: R) => T;
type Options<R> = {
pattern?: RegExp | null;
resolver?: Resolver<R>;
skip?: RegExp;
};
type Resolver<R = unknown> = (context: R, subject: string) => unknown;
Pass a subject (any interpolatable string, object, or array) to the default export, and optionally options and it returns an interpolation function which accepts a data source to interpolate from.
Options
pattern: RegExp = /\{\{\s*(.+?)\s*\}\}/g
The default interpolation pattern is a RegExp that matches a string between {{ }}
- some_string
in {{some_string}}
. You can pass in a custom pattern if you like:
const interpolate = interpolatable(
{
foo: '<%= bar %> qux',
},
{
pattern: /<%=\s*(.+?)\s*%>/g,
},
);
const result = interpolate({ bar: 'baz' });
/*
{ foo: 'baz qux' }
*/
Note: pattern
can also be null
. If pattern is passed as null
, interpolatable
will return a function that always returns your unaltered subject.
resolver: (context: R, subject: string) => unknown
A resolver is a function that accepts a context and interpolated string and synchronously returns any value, it doesn't have to be a primitive.
The default resolver returns the value from the context indexed by the string:
const DEFAULT_RESOLVER = (c, k) => c[k];
Other good resolvers are lodash's get or property-expr, or jsonpointer.
import expr from 'property-expr';
const interpolate = interpolatable(
{
foo: '{{bar.baz}}',
},
{
resolver: (context, subject) => expr.getter(subject)(context),
},
);
const result = interpolate({
bar: {
baz: 'qux',
},
});
/*
{ foo: 'qux' }
*/
skip: RegExp
Sometimes we want to interpolate a very large deeply nested object. Traversing the entire object is often unnecessary and can be very expensive. This is where skip
comes in. When skip
is defined, all paths, while traversing the subject, will be tested against it. If the path matches the skip
RegExp, anything beneath it will not be traversed.
const interpolate = interpolatable(
{
foo: '{{someString}}',
bar: {
some: {
deeply: {
nested: {
expensive_to_traverse: {
object: []
}
}
}
}
}
},
{
skip: /bar/
}
)
delimieter: string = '.'
The delimiter is the thing that joins path segments and defaults to a .
. Useful to configure if you're skip RegExp is restrictive.
import { get } from 'json-pointer';
const interpolate = interpolatable(
{
foo: '{{/bar/baz}}',
},
{
resolver: get,
},
);
const result = interpolate({
bar: {
baz: 'qux',
},
});
/*
{ foo: 'qux' }
*/
Other Cool Stuff
Check out json-schema-rules-engine or json-modifiable for a more practical application.
License
Contributing
PRs welcome!