This project is part of the @thi.ng/umbrella monorepo.
DAG resolution of vanilla objects & arrays with internally linked values. This is useful for expressing complex configurations with derived values or computing interrelated values without having to specify the order of computations.
TL;DR go check out the examples
It's common practice to use nested JS objects for configuration purposes. Frequently some values in the object are copies or derivatives of other values, which can lead to mistakes during refactoring and / or duplication of effort.
To avoid these issues, this library provides the ability to define single sources of truth, create references (links) to these values and provide a resolution mechanism to recursively expand their real values and / or compute derived values. Both absolute & relative references are supported.
Visits all key-value pairs or array items in depth-first order,
expands any reference values, mutates the original object and returns
it. Cyclic references are not allowed and will throw an error.
However, refs pointing to other refs are recursively resolved (again,
provided there are no cycles).
Reference values are special strings representing lookup paths of
other values in the object and are prefixed with @ for relative
refs or @/ for absolute refs and both using / as path separator
(Note: trailing slashes are NOT allowed!). Relative refs are resolved
from the currently visited object and support "../" prefixes to
access any parent levels. Absolute refs are always resolved from the
root level (the original object passed to this function).
// `c` references sibling `d`
// `d` references parent `a`
resolve({a: 1, b: {c: "@d", d: "@/a"} })
// { a: 1, b: { c: 1, d: 1 } }Any function values are called using two possible conventions:
- If the user function uses ES6 object destructuring for its first
argument, the given object keys are resolved prior to calling the
function and the resolved values provided as first argument (object)
and a general
resolvefunction as second argument. - If no de-structure form is found in the function's arguments, the
function is only called with
resolveas argument.
Important: ES6 destructuring can only be used for ES6 compile targets and will fail when transpiling to ES5. If you're not sure, use the 2nd (legacy) form. Also, since ES6 var names can't contain special characters, destructured keys can ALWAYS only be looked up as siblings of the currently processed key.
The resolve function provided as arg to the user function accepts a
path (without @ prefix) to look up any other values in the root
object.
// `c` uses ES6 destructuring form to look up `a` & `b` values
// `d` uses provided resolve fn arg `$` to look up `c`
resolve({a: 1, b: 2, c: ({a,b}) => a + b, d: ($) => $("c") })
// { a: 1, b: 2, c: 3, d: 3 }
// last item references item @ index = 2
resolve([1,2, ($) => $("0") + $("1"), "@2"])
// [1, 2, 3, 3]The return value of the user provided function is used as final value
for that key in the object. This mechanism can be used to compute
derived values of other values stored anywhere in the root object.
Function values will always be called only once. Therefore, in order
to associate a function as final value to a key, it MUST be wrapped with
an additional function, as shown for the e key in the example below.
Similarly, if an actual string value should happen to start with @, it
needs to be wrapped in a function (see f key below).
// `a` is derived from 1st array element in `b.d`
// `b.c` is looked up from `b.d[0]`
// `b.d[1]` is derived from calling `e(2)`
// `e` is a wrapped function
// `f` is wrapped to ignore `@` prefix
res = resolve({
a: ($) => $("b/c") * 100,
b: { c: "@d/0", d: [2, ($) => $("../../e")(2) ] },
e: () => (x) => x * 10,
f: () => "@foo",
})
// { a: 200, b: { c: 2, d: [ 2, 20 ] }, e: [Function], f: "@foo" }
res.e(2);
// 20yarn add @thi.ng/resolve-mapIn this example we construct a graph to compute a number of statistical properties for some numeric input array. The graph is a plain object of possibly dependent functions, which can be specified in any order. Each function uses ES6 object destructuring to look up and execute other computations in the graph. Each computation is only executed once.
import { resolve } from "@thi.ng/resolve-map";
import * as tx from "@thi.ng/transducers";
// define object of interrelated computations to be executed later
// the `src` key used by most functions is still missing here and
// will be injected later as well
const stats = {
// sequence average
mean: ({ src }) => tx.mean(src),
// sequence range
range: ({ min, max }) => max - min,
// computes sequence min val
min: ({ src }) => tx.min(src),
// computes sequence max val
max: ({ src }) => tx.max(src),
// sorted copy
sorted: ({ src }) => [...src].sort((a, b) => a - b),
// standard deviation
sd: ({ src, mean })=>
Math.sqrt(
tx.transduce(tx.map((x) => Math.pow(x - mean, 2)), tx.add(), src) /
(src.length - 1)),
// compute 10th - 90th percentiles
percentiles: ({ sorted }) => {
return tx.transduce(
tx.map((x) => sorted[Math.floor(x / 100 * sorted.length)]),
tx.push(),
tx.range(10, 100, 5)
);
}
};
// inject some source data to analyze
// Note: we wrap the data as function to avoid `resolve`
// attempting to resolve each array item as well. this is
// purely for performance reasons and would also work without
// wrapping.
// Note 2: If the `stats` graph is meant to be re-usable in
// the future you MUST use the spread operator to create a
// shallow copy, because `resolve` mutates the given object
resolve({...stats, src: () => [ 1, 6, 7, 2, 4, 11, -3 ]})
// {
// mean: 4,
// range: 14,
// min: -3,
// max: 11,
// sorted: [ -3, 1, 2, 4, 6, 7, 11 ],
// sd: 4.546060565661952,
// percentiles: [ -3, 1, 2, 2, 4, 6, 6, 7, 11 ],
// src: [ 1, 6, 7, 2, 4, 11, -3 ]
// }import { resolve } from "@thi.ng/resolve-map";
resolve({
colors: {
bg: "white",
text: "black",
selected: "red",
},
main: {
fontsizes: [12, 16, 20]
},
button: {
bg: "@/colors/text",
label: "@/colors/bg",
// resolve with abs path inside fn
fontsize: ($) => `${$("/main/fontsizes/0")}px`,
},
buttonPrimary: {
bg: "@/colors/selected",
label: "@/button/label",
// resolve with relative path inside fn
fontsize: ($) => `${$("../main/fontsizes/2")}px`,
}
});
// {
// colors: {
// bg: "white",
// text: "black",
// selected: "red"
// },
// main: {
// fontsizes: [ 12, 16, 20 ]
// },
// button: {
// "bg": "black",
// "label": "white",
// "fontsize": "12px"
// },
// buttonPrimary: {
// bg: "red",
// label: "black",
// fontsize: "20px"
// }
// }- Karsten Schmidt
© 2018 Karsten Schmidt // Apache Software License 2.0