Functional Reactive Bindings (frb): A CommonJS package that includes functional and generic building blocks to help incrementally ensure consistent state.
In their simplest form, bindings provide the illusion that two objects have the same property. Changing the property on one object causes the same change in the other. This is useful for coordinating state between views and models, among other entangled objects. For example, if you enter text into a text field, the same text might be added to the corresponding database record.
bind(object, "a.b", {"": "c.d"});
Functional Reactive Bindings go farther. They can gracefully bind long property paths and the contents of collections. They can also incrementally update the results of chains of queries including maps, flattened arrays, sums, and averages. They can also add and remove elements from sets based on the changes to a flag. FRB makes it easy to incrementally ensure consistent state.
bind(company, "payroll", {"FRB is built from a combination of powerful functional and generic building blocks, making it reliable, easy to extend, and easy to maintain.
Getting Started
frbis a CommonJS package, with JavaScript modules suitable for use with Node.js on the server side or Mr on the client side.❯ npm install frbTutorial
In this example, we bind
model.contenttodocument.body.innerHTML.var bind = require("frb/bind"); var model = {content: "Hello, World!"}; var cancelBinding = bind(document, "body.innerHTML", { "When a source property is bound to a target property, the target gets reassigned to the source any time the source changes.
model.content = "Farewell."; expect(document.body.innerHTML).toBe("Farewell.");Bindings can be recursively detached from the objects they observe with the returned cancel function.
cancelBinding(); model.content = "Hello again!"; // doesn't take expect(document.body.innerHTML).toBe("Farewell.");Two-way Bindings
Bindings can go one way or in both directions. Declare one-way bindings with the
property, and two-way bindings with the property.In this example, the "foo" and "bar" properties of an object will be inexorably intertwined.
var object = {}; var cancel = bind(object, "foo", {"": "bar"});// object.foo = 20; expect(object.bar).toBe(20);
Right-to-left
Note that even with a two-way binding, the right-to-left binding precedes the left-to-right. In this example, "foo" and "bar" are bound together, but both have initial values.
var object = {foo: 10, bar: 20}; var cancel = bind(object, "foo", {"": "bar"}); expect(object.foo).toBe(20); expect(object.bar).toBe(20);The right-to-left assignment of
bartofoohappens first, so the initial value offoogets lost.Properties
Bindings can follow deeply nested chains, on both the left and the right side.
In this example, we have two object graphs,
foo, andbar, with the same structure and initial values. This bindsbar.a.btofoo.a.band also the other way around.var foo = {a: {b: 10}}; var bar = {a: {b: 10}}; var cancel = bind(foo, "a.b", { "": "a.b", source: bar }); // foo.a.b = 30; expect(bar.a.b).toBe(30);Structure changes
Changes to the structure of either side of the binding are no matter. All of the orphaned event listeners will automatically be canceled, and the binders and observers will reattach to the new object graph.
Continuing from the previous example, we store and replace the
aobject from one side of the binding. The oldbproperty is now orphaned, and the oldbproperty adopted in its place.var a = foo.a; expect(a.b).toBe(30); // from beforefoo.a = {}; // orphan a and replace foo.a.b = 40; // -> expect(bar.a.b).toBe(40); // updated
bar.a.b = 50; //
Strings
String concatenation is straightforward.
var object = {name: "world"}; bind(object, "greeting", {"Sum
Some advanced queries are possible with one-way bindings from collections. FRB updates sums incrementally. When values are added or removed from the array, the sum of only those values is taken and added or removed from the last known sum.
var object = {array: [1, 2, 3]}; bind(object, "sum", {"Average
The arithmetic mean of a collection can be updated incrementally. Each time the array changes, the added and removed values adjust the last known sum and count of values in the array.
var object = {array: [1, 2, 3]}; bind(object, "average", {"Rounding
The
round,floor, andceilmethods operate on numbers and return the nearest integer, the nearest integer toward -infinity, and the nearest integer toward infinity respectively.var object = {number: -0.5}; Bindings.defineBindings(object, { "round": {"Last
FRB provides an operator for watching the last value in an Array.
var array = [1, 2, 3]; var object = {array: array, last: null}; Bindings.defineBinding(object, "last", {"When the dust settles,
array.last()is equivalent toarray[array.length - 1], but thelastobserver guarantees that it will not jitter between the ultimate value and null or the penultimate value of the collection. Witharray[array.length], the underlying may not change its content and length atomically.var changed = jasmine.createSpy(); PropertyChanges.addOwnPropertyChangeListener(object, "last", changed); array.unshift(0); array.splice(3, 0, 3.5); expect(object.last).toBe(4); expect(changed).not.toHaveBeenCalled();array.pop(); expect(object.last).toBe(3);
array.clear(); expect(object.last).toBe(null);
Only
FRB provides an
onlyoperator, which can either observe or bind the only element of a collection. Theonlyobserver watches a collection for when there is only one value in that collection and emits that value.. If there are multiple values, it emits null.var object = {array: [], only: null}; Bindings.defineBindings(object, { only: {"": "array.only()"} });object.array = [1]; expect(object.only).toBe(1);
object.array.pop(); expect(object.only).toBe(undefined);
object.array = [1, 2, 3]; expect(object.only).toBe(undefined);
The
onlybinder watches a value. When the value is null, it does nothing. Otherwise, it will update the bound collection such that it only contains that value. If the collection was empty, it adds the value. Otherwise, if the collection did not have the value, it replaces the collection's content with the one value. Otherwise, it removes everything but the value it already contains. Regardless of the means, the end result is the same. If the value is non-null, it will be the only value in the collection.object.only = 2; expect(object.array.slice()).toEqual([2]); // Note that slice() is necessary only because the testing scaffold // does not consider an observable array equivalent to a plain array // with the same contentobject.only = null; object.array.push(3); expect(object.array.slice()).toEqual([2, 3]);
One
Like the
onlyoperator, there is also aoneoperator. Theoneoperator will observe one value from a collection, whatever value is easiest to obtain. For an array, it's the first value; for a sorted set, it's whatever value was most recently found or added; for a heap, it's whatever is on top. However, if the collection is null, undefined, or empty, the result isundefined.var object = {array: [], one: null}; Bindings.defineBindings(object, { one: {"Unlike
only,oneis not bindable.Map
You can also create mappings from one array to a new array and an expression to evaluate on each value. The mapped array is bound once, and all changes to the source array are incrementally updated in the target array.
var object = {objects: [ {number: 10}, {number: 20}, {number: 30} ]}; bind(object, "numbers", {"Any function, like
sumoraverage, can be applied to the result of a mapping. The straight-forward path would beobjects.map{number}.sum(), but you can use a block with any function as a short hand,objects.sum{number}.Filter
A filter block generates an incrementally updated array filter. The resulting array will contain only those elements from the source array that pass the test deescribed in the block. As values of the source array are added, removed, or changed such that they go from passing to failing or failing to passing, the filtered array gets incrementally updated to include or exclude those values in their proper positions, as if the whole array were regenerated with
array.filterby brute force.var object = {numbers: [1, 2, 3, 4, 5, 6]}; bind(object, "evens", {"Scope
In a binding, there is always a value in scope. It is the implicit value for looking up properties and for applying operators, like methods. The value in scope can be called out explicitly as
this. On the left side, the value in scope is called the target, on the right it is called the source.Each scope has a
thisvalue and may have a parent scope. Inside a map block, like thenumberinnumbers.map{number}, the value in scope is one of the numbers, and the value in the parent scope is an object with anumbersproperty. To access the value in a parent scope, use the parent scope operator,^.Suppose you have an object with
numbersandmaxNumberproperties. In this example, we bind a property,smallNumbersto an array of all thenumbersless than or equal to themaxNumber.var object = Bindings.defineBindings({ numbers: [1, 2, 3, 4, 5], maxNumber: 3 }, { smallNumbers: { "Keywords like
thisoverlap with the notation normally used for properties ofthis. If an object has athisproperty, you may use the notation.this,this.this, orthis['this']..thisis the normal form.var object = Bindings.defineBindings({ "this": 10 }, { that: {"The only other FRB keywords that collide with propery names are
true,false, andnull, and the same technique for disambiguation applies.Some and Every
A
someblock incrementally tracks whether some of the values in a collection meet a criterion.var object = Bindings.defineBindings({ options: [ {checked: true}, {checked: false}, {checked: false} ] }, { anyChecked: { "An
everyblock incrementally tracks whether all of the values in a collection meet a criterion.var object = Bindings.defineBindings({ options: [ {checked: true}, {checked: false}, {checked: false} ] }, { allChecked: { "You can use a two-way binding on
someandeveryblocks.var object = Bindings.defineBindings({ options: [ {checked: true}, {checked: false}, {checked: false} ] }, { allChecked: { "": "options.every{checked}" }, noneChecked: { "": "!options.some{checked}" } });object.noneChecked = true; expect(object.options.every(function (option) { return !option.checked }));
object.allChecked = true; expect(object.noneChecked).toBe(false);
The caveat of an
equalsbinding applies. If the condition for every element of the collection is set to true, the condition will be bound incrementally to true on each element. When the condition is set to false, the binding will simply be canceled.object.allChecked = false; expect(object.options.every(function (option) { return option.checked; // still checked }));Sorted
A sorted block generates an incrementally updated sorted array. The resulting array will contain all of the values from the source except in sorted order.
var object = {numbers: [5, 2, 7, 3, 8, 1, 6, 4]}; bind(object, "sorted", {"The block may specify a property or expression by which to compare values.
var object = {arrays: [[1, 2, 3], [1, 2], [], [1, 2, 3, 4], [1]]}; bind(object, "sorted", {"The sorted binding responds to changes to the sorted property by removing them at their former place and adding them back at their new position.
object.arrays[0].push(4, 5); expect(object.sorted.map(function (array) { return array.slice(); // to clone })).toEqual([ [1, 2, 3, 4, 5], // new [1, 2, 3, 4], // old [1, 2], [1], [] ]);Unique and Sorted
FRB can create a sorted index of unique values using
sortedSetblocks.var object = Bindings.defineBindings({ folks: [ {id: 4, name: "Bob"}, {id: 2, name: "Alice"}, {id: 3, name: "Bob"}, {id: 1, name: "Alice"}, {id: 1, name: "Alice"} // redundant ] }, { inOrder: {"The outcome is a
SortedSetdata structure, not anArray. The sorted set is useful for fast lookups, inserts, and deletes on sorted, unique data. If you would prefer a sorted array of unique values, you can combine other operators to the same effect.var object = Bindings.defineBindings({ folks: [ {id: 4, name: "Bob"}, {id: 2, name: "Alice"}, {id: 3, name: "Bob"}, {id: 1, name: "Alice"}, {id: 1, name: "Alice"} // redundant ] }, { index: {"Min and Max
A binding can observe the minimum or maximum of a collection. FRB uses a binary heap internally to incrementally track the minimum or maximum value of the collection.
var object = Bindings.defineBindings({}, { min: {"Min and max blocks accept an expression on which to compare values from the collection.
var object = Bindings.defineBindings({}, { loser: {"Group
FRB can incrementally track equivalence classes within in a collection. The group block accepts an expression that determines the equivalence class for each object in a collection. The result is a nested data structure: an array of [key, class] pairs, where each class is itself an array of all members of the collection that have the corresponding key.
var store = Bindings.defineBindings({}, { "clothingByColor": {"Tracking the positions of every key and every value in its equivalence class can be expensive. Internally,
groupblocks are implemented with agroupMapblock followed by anentries()observer. ThegroupMapproduces aMapdata structure and does not waste any time, but does not produce range change events. Theentries()observer projects the map of classes into the nested array data structure.You can use the
groupMapblock directly.Bindings.cancelBinding(store, "clothingByColor"); Bindings.defineBindings(store, { "clothingByColor": {"The
groupandgroupMapblocks both respect the type of the source collection. If instead of an array you were to use aSortedSet, the equivalence classes would each be sorted sets. This is useful because replacing values in a sorted set can be performed with much less waste than with a large array.View
Suppose that your source is a large data store, like a
SortedSetfrom the Collections package. You might need to view a sliding window from that collection as an array. Theviewbinding reacts to changes to the collection and the position and length of the window.var SortedSet = require("collections/sorted-set"); var controller = { index: SortedSet([1, 2, 3, 4, 5, 6, 7, 8]), start: 2, length: 4 }; var cancel = bind(controller, "view", { "Enumerate
An enumeration observer produces
[index, value]pairs. You can bind to the index or the value in subsequent stages. The prefix dot distinguishes the zeroeth property from the literal zero.var object = {letters: ['a', 'b', 'c', 'd']}; bind(object, "lettersAtEvenIndexes", { "Range
A range observes a given length and produces and incrementally updates an array of consecutive integers starting with zero with that given length.
var object = Bindings.defineBinding({}, "stack", { "Flatten
You can flatten nested arrays. In this example, we have an array of arrays and bind it to a flat array.
var arrays = [[1, 2, 3], [4, 5, 6]]; var object = {}; bind(object, "flat", { "Note that changes to the inner and outer arrays are both projected into the flattened array.
arrays.push([7, 8, 9]); arrays[0].unshift(0); expect(object.flat).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);Also, as with all other bindings that produce arrays, the flattened array is never replaced, just incrementally updated.
var flat = object.flat; arrays.splice(0, arrays.length); expect(object.flat).toBe(flat); // === same objectConcat
You can observe the concatenation of collection of dynamic arrays.
var object = Bindings.defineBinding({ head: 10, tail: [20, 30] }, "flat", { "The underlying mechanism is equivalent to
[[head], tail].flatten().Reversed
You can bind the reversal of an array.
var object = {forward: [1, 2, 3]}; bind(object, "backward", { "": "forward.reversed()" }); expect(object.backward.slice()).toEqual([3, 2, 1]); object.forward.push(4); expect(object.forward.slice()).toEqual([1, 2, 3, 4]); expect(object.backward.slice()).toEqual([4, 3, 2, 1]);Note that you can do two-way bindings,
with reversed arrays. Changes to either side are updated to the opposite side.object.backward.pop(); expect(object.backward.slice()).toEqual([4, 3, 2]); expect(object.forward.slice()).toEqual([2, 3, 4]);Has
You can bind a property to always reflect whether a collection contains a particular value.
var object = { haystack: [1, 2, 3], needle: 3 }; bind(object, "hasNeedle", {"The binding also reacts to changes to the value you seek.
// Continued from above... object.needle = 2; expect(object.hasNeedle).toBe(true);hasbindings are not incremental, but with the right data-structure, updates are cheap. The Collections package contains Lists, Sets, and OrderedSets that all can send ranged content change notifications and thus can be bound.// Continued from above... var Set = require("collections/set"); object.haystack = new Set([1, 2, 3]); expect(object.hasNeedle).toBe(true);Likewise, Maps implement
addMapChangeListener, so you can use ahasbinding to observe whether an entry exists with the given key.// Continued from above... var Map = require("collections/map"); object.haystack = new Map([[1, "a"], [2, "b"]]); object.needle = 2; expect(object.hasNeedle).toBe(true); object.needle = 3; expect(object.hasNeedle).toBe(false);hasbindings can also be left-to-right and bi-directional.bind(object, "hasNeedle", {"": "haystack.has(needle)"}); object.hasNeedle = false; expect(object.haystack.has(2)).toBe(false);The collection on the left-hand-side must implement
hasorcontains,add, anddeleteorremove. FRB shimsArrayto havehas,add, anddelete, just like all the collections in Collections. It happens that theclassListproperties of DOM elements, when they are supported, implementadd,remove, andcontains.var model = {darkMode: false}; bind(document.body, "classList.has('dark')", { "The DOM
classListdoes not however implementaddRangeChangeListenerorremoveRangeChangeListener, so it cannot be used on the right-hand-side of a binding, and such bindings cannot be bidirectional. With some DOM Mutation Observers, you might be able to help FRB overcome this limitation in the future.Get
A binding can observe changes in key-to-value mappings in arrays and map Collections.
var object = { array: [1, 2, 3], second: null }; var cancel = bind(object, "second", { "": "array.get(1)" }); expect(object.array.slice()).toEqual([1, 2, 3]); expect(object.second).toBe(2);object.array.shift(); expect(object.array.slice()).toEqual([2, 3]); expect(object.second).toBe(3);
object.second = 4; expect(object.array.slice()).toEqual([2, 4]);
cancel(); object.array.shift(); expect(object.second).toBe(4); // still
The source collection can be a Map, Dict, MultiMap, SortedMap, SortedArrayMap, or anything that implements
getandaddMapChangeListeneras specified in Collections. The key can also be a variable.var Map = require("collections/map"); var a = {id: 0}, b = {id: 1}; var object = { source: new Map([[a, 10], [b, 20]]), key: null, selected: null };var cancel = bind(object, "selected", { "
You can also bind the entire content of a map-like collection to the content of another. Bear in mind that the content of the source replaces the content of the target initially.
var Map = require("collections/map"); var object = { a: new Map({a: 10}), b: new Map() }; var cancel = bind(object, "a.mapContent()", {"": "b.mapContent()"}); expect(object.a.toObject()).toEqual({}); expect(object.b.toObject()).toEqual({});object.a.set('a', 10); expect(object.a.toObject()).toEqual({a: 10}); expect(object.b.toObject()).toEqual({a: 10});
object.b.set('b', 20); expect(object.a.toObject()).toEqual({a: 10, b: 20}); expect(object.b.toObject()).toEqual({a: 10, b: 20});
In this case, the source of the binding is a different object than the target, so the binding descriptor specifies the alternate source.
Keys, Values, Entries
If the source of a binding is a map, FRB can also translate changes to the map into changes on an array. The
keys,values, andentriesobservers produce incrementally updated projections of the key-value-mappings onto an array.var Map = require("collections/map"); var object = Bindings.defineBindings({}, { keys: {"Coerce to Map
Records (Objects with a fixed shape), arrays of entries, and Maps themselves can be coerced to an incrementally updated
Mapwith thetoMapoperator.var object = Bindings.defineBindings({}, { map: {"The
toMapobserver maintains the insertion order of the keys.// Continued... object.entries = [['b', 20], ['c', 30]]; expect(map.keysArray()).toEqual(['b', 'c']);object.entries.push(object.entries.shift()); expect(map.keysArray()).toEqual(['c', 'b']);
If the entries do not have unique keys, the last entry wins. This is managed internally by observing,
entries.group{.0}.map{.1.last()}.// Continued... object.entries = [['a', 10], ['a', 20]]; expect(map.get('a')).toEqual(20); object.entries.pop(); expect(map.get('a')).toEqual(10);toMapbinds the content of the output map to the content of the input map and will clear and repopulate the output map if the input map is replaced.// Continued... object.entries = new Map({a: 10}); expect(map.keysArray()).toEqual(['a']);Equals
You can bind to whether expressions are equal.
var fruit = {apples: 1, oranges: 2}; bind(fruit, "equal", {"Equality can be bound both directions. In this example, we do a two-way binding between whether a radio button is checked and a corresponding value in our model.
var component = { orangeElement: {checked: false}, appleElement: {checked: true} }; Bindings.defineBindings(component, { "orangeElement.checked": {"": "fruit == 'orange'"}, "appleElement.checked": {"": "fruit == 'apple'"}, });component.orangeElement.checked = true; expect(component.fruit).toEqual("orange");
component.appleElement.checked = true; expect(component.fruit).toEqual("apple");
Because equality and assignment are interchanged in this language, you can use either
=or==.FRB also supports a comparison operator,
<=>, which usesObject.compareto determines how two operands should be sorted in relation to each other.Array and Map Content
In JavaScript, arrays behave both like objects (in the sense that every index is a property, but also like a map collection of index-to-value pairs. The Collections package goes so far as to patch up the
Arrayprototype so arrays can masquerade as maps, with the caveat thatdelete(value)behaves like a Set instead of a Map.This duplicity is reflected in FRB. You can access the values in an array using the object property notation or the mapped key notation.
var object = { array: [1, 2, 3] }; Bindings.defineBindings(object, { first: {"To distinguish a numeric property of the source from a number literal, use a dot. To distingish a mapped index from an array literal, use an empty expression.
var array = [1, 2, 3]; var object = {}; Bindings.defineBindings(object, { first: { "Unlike property notation, map notation can observe a variable index.
var object = { array: [1, 2, 3], index: 0 }; Bindings.defineBinding(object, "last", { "You can also bind all of the content of an array by range or by mapping. The notation for binding ranged content is
rangeContent(). Every change to an Array or SortedSet dispatches range changes and any collection that implementsspliceandswapcan be a target for such changes.var SortedSet = require("collections/sorted-set"); var object = { set: SortedSet(), array: [] }; Bindings.defineBindings(object, { "array.rangeContent()": {"The notation for binding the content of any mapping collection using map changes is
mapContent(). On the target of a binding, this will note when values are added or removed on each key of the source collection and apply the same change to the target. The target and source can be arrays or map collections.var Map = require("collections/map"); var object = { map: new Map(), array: [] }; Bindings.defineBinding(object, "map.mapContent()", { "Value
A note about the source value: an empty path implies the source value. Using empty paths and empty expressions is useful in some situations.
If a value is ommitted on either side of an operator, it implies the source value. The expression
sorted{}indicates a sorted array, where each value is sorted by its own numeric value. The expressionfilter{!!}would filter falsy values. The operand is implied. Similarly,filter{!(%2)}produces only even values.This is why you can use
.0to get the zeroth property of an array, to distingiush the form from0which would be a numeric literal, and why you can use()[0]to map the zeroeth key of a map or array, to distinguish the form from[0]which would be an array literal.With Context Value
Expressions can be evaluated in the context of another value using a variant of property notation. A parenthesized expression can follow a path.
var object = { context: {a: 10, b: 20} }; Bindings.defineBinding(object, "sum", { "To observe a constructed array or object literal, the expression does not need parentheses.
var object = { context: {a: 10, b: 20} }; Bindings.defineBindings(object, { "duple": {"Operators
FRB can also recognize many operators. These are in order of precedence unary
-negation,+numeric coercion, and!logical negation and then binary**power,//root,%%logarithm,*,/,%modulo,%%remainder,+,-,<,>,<=,>=,=or==,!=,&&and||.var object = {height: 10}; bind(object, "heightPx", {"The unary
+operator coerces a value to a number. It is handy for binding a string to a number.var object = { number: null, string: null, }; Bindings.defineBinding(object, "+number", { "Functions
FRB supports some common functions.
startsWith,endsWith, andcontainsall operate on strings.joinconcatenates an array of strings with a given delimiter (or empty string).splitbreaks a string between every delimiter (or just between every character).joinandsplitare algebraic and can be bound as well as observed.Conditional
FRB supports the ternary conditional operator, if
?then:else.var object = Bindings.defineBindings({ condition: null, consequent: 10, alternate: 20 }, { choice: {"": "condition ? consequent : alternate"} });expect(object.choice).toBe(undefined); // no choice made
object.condition = true; expect(object.choice).toBe(10);
object.condition = false; expect(object.choice).toBe(20);
The ternary operator can bind in both directions.
object.choice = 30; expect(object.alternate).toBe(30);object.condition = true; object.choice = 40; expect(object.consequent).toBe(40);
And
The logical and operator,
&&, observes either the left or right argument depending on whether the first argument is both defined and true. If the first argument is null, undefined, or false, it will stand for the whole expression. Otherwise, the second argument will stand for the whole expression.If we assume that the first and second argument are always defined and either true or false, the and operator serves strictly as a logical combinator. However, with bindings, it is common for a value to at least initially be null or undefined. Logical operators are the exception to the rule that an expression will necessarily terminate if any operand is null or undefined.
In this example, the left and right sides are initially undefined. We set the right operand to
10and the bound value remains undefined.var object = Bindings.defineBindings({ left: undefined, right: undefined }, { and: {"We set the left operand to
20. The bound value becomes the value of the right operand,10.// Continued... object.left = 20; expect(object.and).toBe(10);
Interestingly, logical and is bindable. The objective of the binding is to do whatever is necessary, if possible, to make the logical expression equal the bound value.
Supposing that both the left and right operands are false, and the result is or becomes true, to satisfy the equality
left && right == true, both left and right must be set and bound totrue.var object = Bindings.defineBindings({}, { "left && right": { "As with the equals binder, logic bindings will prefer to alter the left operand if altering either operand would suffice to validate the expression. So, if the expression then becomes false, it is sufficient to set the left side to false to satisfy the equality.
// Continued... object.leftAndRight = false; expect(object.left).toBe(false); expect(object.right).toBe(true);This can facilitate some interesting, tri-state logic. For example, if you have a checkbox that can be checked, unchecked, or disabled, and you want it to be unchecked if it is disabled, you can use logic bindings to ensure this.
var controller = Bindings.defineBindings({ checkbox: { checked: false, disabled: false }, model: { expanded: false, children: [1, 2, 3] } }, { "checkbox.checked": {"": "model.expanded && expandable"}, "checkbox.disabled": {" 0"} });expect(controller.checkbox.checked).toBe(false); expect(controller.checkbox.disabled).toBe(false);
// check the checkbox controller.checkbox.checked = true; expect(controller.model.expanded).toBe(true);
// alter the model such that the checkbox is unchecked and disabled controller.model.children.clear(); expect(controller.checkbox.checked).toBe(false); expect(controller.checkbox.disabled).toBe(true);
Or
As with the and operator, the logical or is an exception to the rule that an expression is null, undefined, or empty if any of the operands are null or undefined. If both operands are defined and boolean, or expressions behave strictly within the realm of logic. However, if the values are non-boolean or even non-values, they serve to select either the left or right side based on whether the left side is defined and true.
If the first argument is undefined or false, the aggregate expression will evaluate to the second argument, even if that argument is null or undefined.
Suppose we bind
ortoleft || righton some object.orwill beundefinedinitially, but if we set therightto10,orwill become10, bypassing the still undefined left side.var object = Bindings.defineBindings({ left: undefined, right: undefined }, { or: {"However, the left hand side takes precedence over the right if it is defined and true.
// Continued... object.left = 20; expect(object.or).toBe(20);And it will remain bound, even if the right hand side becomes undefined.
object.right = undefined; expect(object.or).toBe(20);Aside: JavaScript’s
deleteoperator performs a configuration change, and desugars toObject.defineProperty, and is not interceptable with an ES5 setter. So, don't use it on any property that is involved in a binding. Setting to null or undefined should suffice.
Logical or is bindable. As with logical and, the binding performs the minimum operation necessary to ensure that the expression is equal. If the expression becomes true, and either of the operands are true, the nothing needs to change. If the expression becomes false, however, both operands must be bound to false. If the expression becomes true again, it is sufficient to bind the left operand to true to ensure that the expression as a whole is true. Rather than belabor the point, I leave as an exercise to the reader to apply DeMorgan’s Theorem to the documentation for logical and bindings.
Default
The default operator,
??, is similar to the or,||operator, except that it decides whether to use the left or right solely based on whether the left is defined. If the left is null or undefined, the aggregate expression will evaluate to the right expression. If the left is defined, even if it is false, the result will be the left expression.var object = Bindings.defineBindings({ left: undefined, right: undefined }, { or: {"The default operator is not bindable, but weirder things have happened.
Defined
The
defined()operator serves a similar role to the default operator. If the value in scope is null or undefined, it the result will be false, and otherwise it will be true. This will allow a term that may be undefined to propagate.var object = Bindings.defineBindings({}, { ready: { "The defined operator is also bindable. If the source is or becomes false, the target will be bound to
null. If the source is null or false, the binding has no effect.var object = Bindings.defineBindings({ value: 10, operational: true }, { "value.defined()": {"If the source becomes null or undefined, it will cancel the previous binding but does not set or restore the bound value. Vaguely becoming “defined” is not enough information to settle on a particular value.
object.operational = true; expect(object.value).toBe(undefined);However, another binding might settle the issue.
Bindings.defineBindings(object, { "value == 10": { "Algebra
FRB can automatically invert algebraic operators as long as they operate strictly on the left-most expressions on both the source and target are bindable properties.
In this example, the primary binding is
notToBe , and the inverse binding is automatically computedtoBe .var caesar = {toBe: false}; bind(caesar, "notToBe", {"": "!toBe"}); expect(caesar.toBe).toEqual(false); expect(caesar.notToBe).toEqual(true);caesar.notToBe = false; expect(caesar.toBe).toEqual(true);
FRB does algebra by rotating the expressions on one side of a binding to the other until only one independent property remains (the left most expression) on the target side of the equation.
convert: yconvert: yThe left-most independent variable on the right hand side becomes the dependent variable on the inverted binding. At present, this only works for numbers and when the left-most expression is a bindable property because it cannot assign a new value to the literal 10. For example, FRB cannot yet implicitly revert
y 10 + x.Literals
You may have noticed literals in the previous examples. String literals take the form of any characters between single quotes. Any character can be escaped with a back slash.
var object = {}; bind(object, "greeting", {"Number literals are digits with an optional mantissa.
bind(object, 'four', {"Tuples
Bindings can produce fixed-length arrays. These are most useful in conjunction with mappings. Tuples are comma-delimited and parantheses-enclosed.
var object = {array: [[1, 2, 3], [4, 5]]}; bind(object, "summary", {"Records
Bindings can also produce fixed-shape objects. The notation is comma-delimited, colon-separated entries, enclosed by curly-braces.
var object = {array: [[1, 2, 3], [4, 5]]}; bind(object, "summary", { "The left hand side of an entry in a record is any combination of letters or numbers. The right side is any expression.
Parameters
Bindings can also involve parameters. The source of parameters is by default the same as the source. The source, in turn, defaults to the same as the target object. It can be specified on the binding descriptor. Parameters are declared by any expression following a dollar sign.
var object = {a: 10, b: 20, c: 30}; bind(object, "foo", { "Bindings also react to changes to the parameters.
object.a = 0; object.b = 1; object.c = 2; expect(object.foo).toEqual([0, 1, 2]);The degenerate case of the property language is an empty string. This is a valid property path that observes the value itself. So, as an emergent pattern, a
$expression by itself corresponds to the whole parameters object.var object = {}; bind(object, "ten", {"Elements and Components
FRB provides a
#notation for reaching into the DOM for an element. This is handy for binding views and models on a controller object.The
defineBindingsmethod accepts an optional final argument,parameters, which is shared by all bindings (unless shadowed by a more specific parameters object on an individual descriptor).The
parameterscan include adocument. Thedocumentmay be any object that implementsgetElementById.Additionally, the
frb/domis an experiment that monkey-patches the DOM to make some properties of DOM elements observable, like thevalueorcheckedattribute of aninputortextarea element.var Bindings = require("frb"); require("frb/dom");var controller = Bindings.defineBindings({}, {
"fahrenheit": {"": "celsius * 1.8 + 32"}, "celsius": {"": "kelvin - 272.15"}, "#fahrenheit.value": {"": "+fahrenheit"}, "#celsius.value": {"": "+celsius"}, "#kelvin.value": {"": "+kelvin"}
}, { document: document });
controller.celsius = 0;
One caveat of this approach is that it can cause a lot of DOM repaint and reflow events. The Montage framework uses a synchronized draw cycle and a component object model to minimize the cost of computing CSS properties on the DOM and performing repaints and reflows, deferring such operations to individual animation frames.
For a future release of Montage, FRB provides an alternate notation for reaching into the component object model, using its deserializer. The
@prefix refers to another component by its label. Instead of providing adocument, Montage provides aserialization, which in turn implementsgetObjectForLabel.var Bindings = require("frb");var controller = Bindings.defineBindings({}, {
"fahrenheit": {"": "celsius * 1.8 + 32"}, "celsius": {"": "kelvin - 272.15"}, "@fahrenheit.value": {"": "+fahrenheit"}, "@celsius.value": {"": "+celsius"}, "@kelvin.value": {"": "+kelvin"}
}, { serializer: serializer });
controller.celsius = 0;
Observers
FRB’s bindings use observers and binders internally. You can create an observer from a property path with the
observefunction exported by thefrb/observemodule.var results = []; var object = {foo: {bar: 10}}; var cancel = observe(object, "foo.bar", function (value) { results.push(value); });object.foo.bar = 10; expect(results).toEqual([10]);
object.foo.bar = 20; expect(results).toEqual([10, 20]);
For more complex cases, you can specify a descriptor instead of the callback. For example, to observe a property’s value before it changes, you can use the
beforeChangeflag.var results = []; var object = {foo: {bar: 10}}; var cancel = observe(object, "foo.bar", { change: function (value) { results.push(value); }, beforeChange: true });expect(results).toEqual([10]);
object.foo.bar = 20; expect(results).toEqual([10, 10]);
object.foo.bar = 30; expect(results).toEqual([10, 10, 20]);
If the product of an observer is an array, that array is always updated incrementally. It will only get emitted once. If you want it to get emitted every time its content changes, you can use the
contentChangeflag.var lastResult; var array = [[1, 2, 3], [4, 5, 6]]; observe(array, "map{sum()}", { change: function (sums) { lastResult = sums.slice(); // 1. [6, 15] // 2. [6, 15, 0] // 3. [10, 15, 0] }, contentChange: true });expect(lastResult).toEqual([6, 15]);
array.push([0]); expect(lastResult).toEqual([6, 15, 0]);
array[0].push(4); expect(lastResult).toEqual([10, 15, 0]);
Nested Observers
To get the same effect as the previous example, you would have to nest your own content change observer.
var i = 0; var array = [[1, 2, 3], [4, 5, 6]]; var cancel = observe(array, "map{sum()}", function (array) { function contentChange() { if (i === 0) { expect(array.slice()).toEqual([6, 15]); } else if (i === 1) { expect(array.slice()).toEqual([6, 15, 0]); } else if (i === 2) { expect(array.slice()).toEqual([10, 15, 0]); } i++; } contentChange(); array.addRangeChangeListener(contentChange); return function cancelRangeChange() { array.removeRangeChangeListener(contentChange); }; }); array.push([0]); array[0].push(4); cancel();This illustrates one crucial aspect of the architecture. Observers return cancelation functions. You can also return a cancelation function inside a callback observer. That canceler will get called each time a new value is observed, or when the parent observer is canceled. This makes it possible to nest observers.
var object = {foo: {bar: 10}}; var cancel = observe(object, "foo", function (foo) { return observe(foo, "bar", function (bar) { expect(bar).toBe(10); }); });Bindings
FRB provides utilities for declaraing and managing multiple bindings on objects. The
frb(frb/bindings) module exports this interface.var Bindings = require("frb");The
Bindingsmodule providesdefineBindingsandcancelBindings,defineBindingandcancelBinding, as well as binding inspector methodsgetBindingsandgetBinding. All of these take a target object as the first argument.The
Bindings.defineBinding(target, descriptors)method returns the target object for convenience.var target = Bindings.defineBindings({}, { "fahrenheit": {"": "celsius * 1.8 + 32"}, "celsius": {"": "kelvin - 272.15"} }); target.celsius = 0; expect(target.fahrenheit).toEqual(32); expect(target.kelvin).toEqual(272.15);Bindings.getBindingsin that case would return an object withfahrenheitandcelsiuskeys. The values would be identical to the given binding descriptor objects, like{"": "kelvin - 272.15"}, but it also gets annotated with acancelfunction and the default values for any ommitted properties likesource(same astarget),parameters(same assource), and others.Bindings.cancelBindingscancels all bindings attached to an object and removes them from the bindings descriptors object.Bindings.cancelBindings(target); expect(Bindings.getBindings(object)).toEqual({});Binding Descriptors
Binding descriptors describe the source of a binding and additional parameters.
Bindings.defineBindingscan set up bindings (or ), computed (compute) properties, and falls back to defining ES5 properties with permissive defaults (enumerable,writable, andconfigurableall on by default).If a descriptor has a
or , it is a binding descriptor. FRB creates a binding, adds the canceler to the descriptor, and adds the descriptor to an internal table that tracks all of the bindings defined on that object.var object = Bindings.defineBindings({ darkMode: false, document: document }, { "document.body.classList.has('dark')": { "You can get all the binding descriptors with
Bindings.getBindings, or a single binding descriptor withBindings.getBinding.Bindings.cancelcancels all the bindings to an object andBindings.cancelBindingwill cancel just one.// Continued from above... var bindings = Bindings.getBindings(object); var descriptor = Bindings.getBinding(object, "document.body.classList.has('dark')"); Bindings.cancelBinding(object, "document.body.classList.has('dark')"); Bindings.cancelBindings(object); expect(Object.keys(bindings)).toEqual([]);Converters
A binding descriptor can have a
convertfunction, arevertfunction, or alternately aconverterobject. Converters are useful for transformations that cannot be expressed in the property language, or are not reversible in the property language.In this example,
aandbare synchronized such thatais always half ofb, regardless of which property gets updated.var object = Bindings.defineBindings({ a: 10 }, { b: { "": "a", convert: function (a) { return a * 2; }, revert: function (b) { return b / 2; } } }); expect(object.b).toEqual(20);object.b = 10; expect(object.a).toEqual(5);
Converter objects are useful for reusable or modular converter types and converters that track additional state.
function Multiplier(factor) { this.factor = factor; } Multiplier.prototype.convert = function (value) { return value * this.factor; }; Multiplier.prototype.revert = function (value) { return value / this.factor; };var doubler = new Multiplier(2);
var object = Bindings.defineBindings({ a: 10 }, { b: { "": "a", converter: doubler } }); expect(object.b).toEqual(20);
object.b = 10; expect(object.a).toEqual(5);
Reusable converters have an implied direction, from some source type to a particular target type. Sometimes the types on your binding are the other way around. For that case, you can use the converter as a reverter. This merely swaps the
convertandrevertmethods.var uriConverter = { convert: encodeURI, revert: decodeURI }; var model = Bindings.defineBindings({}, { "title": { "": "location", reverter: uriConverter } });model.title = "Hello, World!"; expect(model.location).toEqual("Hello,%20World!");
model.location = "Hello,%20Dave."; expect(model.title).toEqual("Hello, Dave.");
Computed Properties
A computed property is one that gets updated with a function call when one of its arguments changes. Like a converter, it is useful in cases where a transformation or computation cannot be expressed in the property language, but can additionally accept multiple arguments as input. A computed property can be used as the source for another binding.
In this example, we create an object as the root of multiple bindings. The object synchronizes the properties of a "form" object with the window’s search string, effectively navigating to a new page whenever the "q" or "charset" values of the form change.
Bindings.defineBindings({ window: window, form: { q: "", charset: "utf-8" } }, { queryString: { args: ["form.q", "form.charset"], compute: function (q, charset) { return "?" + QS.stringify({ q: q, charset: charset }); } }, "window.location.search": { "Debugging with Traces
A binding can be configured to log when it changes and why. The
traceproperty on a descriptor instructs the binder to log changes to the console.Bindings.defineBindings({ a: 10 }, { b: { "Polymorphic Extensibility
Bindings support three levels of polymorphic extensibility depending on the needs of a method that FRB does not anticipate.
If an operator is pure, meaning that all of its operands are value types that will necessarily need to be replaced outright if they every change, meaning that they are all effectively stateless, and if all of the operands must be defined in order for the output to be defined, it is sufficient to just use a plain JavaScript method. For example,
string.toUpperCase()will work fine.If an operator responds to state changes of its one and only operand, an object may implement an observer method. If the operator is
fooin FRB, the JavaScript method isobserveFoo(emit). The observer must return a cancel function if it will emit new values after it returns, or if it uses observers itself. It must stop emitting new values if FRB calls its canceler. The emitter may return a canceler itself, and the observer must call that canceler before it emits a new value.This is an example of a clock. The
clock.time()is an observable operator of the clock in FRB, implemented byobserveTime. It will emit a new value once a second.function Clock() { }Clock.prototype.observeTime = function (emit) { var cancel, timeoutHandle; function tick() { if (cancel) { cancel(); } cancel = emit(Date.now()); timeoutHandle = setTimeout(tick, 1000); } tick(); return function cancelTimeObserver() { clearTimeout(timeoutHandle); if (cancel) { cancel(); } }; };
var object = Bindings.defineBindings({ clock: new Clock() }, { "time": {"
If an operator responds to state changes of its operands, you will need to implement an observer maker. An observer maker is a function that returns an observer function, and accepts observer functions for all of the arguments you are expected to observe. The observer must also handle a scope argument, usually just passing it on at run-time,
observe(emit, scope). Otherwise it is much the same.FRB would delegate to
makeTimeObserver(observeResolution)for aclock.time(ms)FRB expression.This is an updated rendition of the clock example except that it will observe changes to a resolution operand and adjust its tick frequency accordingly.
function Clock() { }Clock.prototype.observeTime = function (emit, resolution) { var cancel, timeoutHandle; function tick() { if (cancel) { cancel(); } cancel = emit(Date.now()); timeoutHandle = setTimeout(tick, resolution); } tick(); return function cancelTimeObserver() { clearTimeout(timeoutHandle); if (cancel) { cancel(); } }; };
Clock.prototype.makeTimeObserver = function (observeResolution) { var self = this; return function observeTime(emit, scope) { return observeResolution(function replaceResolution(resolution) { return self.observeTime(emit, resolution); }, scope); }; };
var object = Bindings.defineBindings({ clock: new Clock() }, { "time": {"
Polymorphic binders are not strictly impossible, but you would be mad to try them.
Reference
Functional Reactive Bindings is an implementation of synchronous, incremental object-property and collection-content bindings for JavaScript. It was ripped from the heart of the Montage web application framework and beaten into this new, slightly magical form. It must prove itself worthy before it can return.
addRangeChangeListener, so any object can implement the same interface and be used in a binding.
map,
reversed,
flatten,
sum, and
averageobservers. It can also incrementally update
hasbindings.
Object.definePropertymethod. For arrays, this involves replacing all of the mutation methods, like
pushand
pop, with variants that dispatch change notifications. The methods are either replaced by swapping the
__proto__or adding the methods to the instance with
Object.defineProperties. These techniques should [work]Define Property starting in Internet Explorer 9, Firefox 4, Safari 5, Chrome 7, and Opera 12.
setmethod on Arrays to dispatch property and content change events. Does not work in older Internet Explorers since they support neither prototype assignment or ES5 property setters.
The highest level interface for FRB resembles the ES5 Object constructor and can be used to declare objects and define and cancel bindings on them with extended property descriptors.
var Bindings = require("frb");// create an object var object = Bindings.defineBindings({ foo: 0, graph: [ {numbers: [1,2,3]}, {numbers: [4,5,6]} ] }, { bar: {"": "foo", enumerable: false}, numbers: {"
Bindings.defineBindings(object, name, descriptor)
Bindings.defineBinding(object, name, descriptor)
Bindings.getBindings(object)
Bindings.getBinding(object, name)
Bindings.cancelBindings(object)
Bindings.cancelBinding(object, name)
A binding descriptor contains:
target: the
targetPath: the target
targetSyntax: the syntax tree for the target path
source: the source object, which defaults to
target
sourcePath: the source path, from either
or
sourceSyntax: the syntax tree for the source path
twoWay: whether the binding goes in both directions, if was the source path.
parameters: the parameters, which default to
source.
convert: a function that converts the source value to the target value, useful for coercing strings to dates, for example.
revert: a function that converts the target value to the source value, useful for two-way bindings.
converter: an object with
convertand optionally also a
revertmethod. The implementation binds these methods to their converter and stores them in
covertand
revert.
serializable: a note from the Montage Deserializer, to the Montage Serializer, indicating that the binding came from a serialization, and to a serialization it must return.
cancel: a function to cancel the binding
The
bindmodule provides direct access to the
bindfunction.
var bind = require("frb/bind");var source = [{numbers: [1,2,3]}, {numbers: [4,5,6]}]; var target = {}; var cancel = bind(target, "summary", { "
bindis built on top ofparse,compileBinder, andcompileObserver.Compute
The
computemodule provides direct access to thecomputefunction, used byBindingsto make computed properties.var compute = require("frb/compute");var source = {operands: [10, 20]}; var target = {}; var cancel = compute(target, "sum", { source: source, args: ["operands.0", "operands.1"], compute: function (a, b) { return a + b; } });
expect(target.sum).toEqual(30);
// change one operand source.operands.set(1, 30); // needed to dispatch change notification expect(target.sum).toEqual(40);
Observe
The
observemodules provides direct access to theobservefunction.observeis built on top ofparseandcompileObserver.compileObservercreates a tree of observers using the methods in theobserversmodule.var observe = require("frb/observe");var source = [1, 2, 3]; var sum; var cancel = observe(source, "sum()", function (newSum) { sum = newSum; });
expect(sum).toBe(6);
source.push(4); expect(sum).toBe(10);
source.unshift(0); // no change expect(sum).toBe(10);
cancel(); source.splice(0, source.length); // would change expect(sum).toBe(10);
observeproduces a cancelation hierarchy. Each time a value is removed from an array, the underlying observers are canceled. Each time a property is replaced, the underlying observer is canceled. When new values are added or replaced, the observer produces a new canceler. The cancel function returned byobservecommands the entire underlying tree.Observers also optional accept a descriptor argument in place of a callback.
set: the change handler, receives
valuefor most observers, but also
keyand
objectfor property changes.
parameters: the value for
$expressions.
beforeChange: instructs an observer to emit the previous value before a change occurs.
contentChange: instructs an observer to emit an array every time its content changes. By default, arrays are only emitted once.
var object = {}; var cancel = observe(object, "array", { change: function (value) { // may return a cancel function for a nested observer }, parameters: {}, beforeChange: false, contentChange: true });object.array = []; // emits [] object.array.push(10); // emits [10]
The
compile-evaluatormodule returns a function that accepts a syntax tree and returns an evaluator function. The evaluator accepts a scope (which may include a value, parent scope, parameters, a document, and components) and returns the corresponding value without all the cost or benefit of setting up incremental observers.
var parse = require("frb/parse"); var compile = require("frb/compile-evaluator"); var Scope = require("frb/scope");var syntax = parse("a.b"); var evaluate = compile(syntax); var c = evaluate(new Scope({a: {b: 10}})) expect(c).toBe(10);
The
evaluatemodule returns a function that accepts a path or syntax tree, a source value, and parameters and returns the corresponding value.
var evaluate = require("frb/evaluate"); var c = evaluate("a.b", {a: {b: 10}}) expect(c).toBe(10);
The
stringifymodule returns a function that accepts a syntax tree and returns the corresponding path in normal form.
var stringify = require("frb/stringify");var syntax = {type: "and", args: [ {type: "property", args: [ {type: "value"}, {type: "literal", value: "a"} ]}, {type: "property", args: [ {type: "value"}, {type: "literal", value: "b"} ]} ]};
var path = stringify(syntax); expect(path).toBe("a && b");
The grammar is expressed succinctly in
grammar.pegjsand is subject to ammendment.
An expression is observed with a source value and emits a target one or more times. All expressions emit an initial value. Array targets are always updated incrementally. Numbers and boolean are emited anew each time their value changes.
If any operand is
nullor
undefine, a binding will not emit an update. Thus, if a binding’s source becomes invalid, it does not corrupt its target but waits until a valid replacement becomes available.
Object.addPropertyChangeListener.
#prefix) uses the
documentproperty of the
parametersobject and emits
document.getElementById(id), or dies trying. Changes to the document are not observed.
@prefix) uses the
serializationproperty of
parametersobject and emits
serialization.getObjectForLable(label), or dies trying. Changes to the serialization are not observed. This syntax exists to support Montage serializations.
^observes the given expression in the context of the current scope's parent.
context.(expression), observes the given expression in a new scope that uses the
contextas its value and the current scope as its parent.
addRangeChangeListener. Each element of the target array corresponds to the observed value of the block expression using the respective element in the source array as the source value.
SortedSetvalue exactly once. If the input is or becomes invalid, the sorted set is cleared, not replaced. The sorted set will always contain the last of each group of equivalant values from the input.
addRangeChangeListener. The target array will always contain the concatenation of all of the source arrays. Changes to the inner and outer source arrays are reflected with incremental splices to the target array in their corresponding positions.
0.5toward infinity.
Unary operators:
Binary operators:
remcan produce negative numbers.
Object.compare(left, right) < 0.
Object.compare(left, right) <= 0.
Object.compare(left, right) > 0.
Object.compare(left, right) >= 0.
Object.compare(left, right).
Object.equals(left, right).
!=operator gets converted into a "not" node around an "equals" node.
Ternary operator:
?). If the expression is true, the result observes the consequent expression (second argument, between the question mark and the colon), and if it is false, the result observes the alternate (the third argument, after the colon). If the condition is null or undefined, the result is null or undefined.
On the left hand side of a binding, the last term has alternate semantics. Binders receive a target as well as a source.
collection.set(key, value). This is suitable for arrays and custom map Collections.
addmethod of the collection (provided by a shim for arrays) to make it true that the collection contains the sought value. When the value is false and the value does appear in the collection one or more times, the binder uses the
deleteor
removemethod of the collection to remove all occurrences of the sought value.
hasand
swap) or it may have the set collection interface (
has,
clear, and
add), and the binder prefers the former if both are supported because it results in a single range change dispatch on the target collection.
var parse = require("frb/parse"); var compileObserver = require("frb/compile-observer"); var compileBinder = require("frb/compile-binder");
parse(text)returns a syntax tree.
compileObserver(syntax)returns an observer function of the form
observe(callback, source, parameters)which in turn returns a
cancel()function.
compileObservervisits the syntax tree and creates functions for each node, using the
observersmodule.
compileBinder(syntax)returns a binder function of the form
bind(observeValue, source, target, parameters)which in turn returns a
cancel()function.
compileBindervisits the root node of the syntax tree and delegates to
compileObserverfor its terms. The root node must be a
propertyat this time, but could conceivably be any function with a clear inverse operation like
mapand
reversed.
The syntax tree is JSON serializable and has a "type" property. Nodes have the following types:
valuecorresponds to observing the source value
parameterscorresponds to observing the parameters object
literalhas a
valueproperty and observes that value
elementhas an
idproperty and observes an element from the
parameters.document, by way of
getElementById.
componenthas a
labelproperty and observes a component from the
parameters.serialization, by way of
getObjectForLabel. This feature support's Montage’s serialization format.
All other node types have an "args" property that is an array of syntax nodes (or an "args" object for
record).
property: corresponds to observing a property named by the right argument of the left argument.
get: corresponds to observing the value for a key (second argument) in a collection (first argument).
with: corresponds to observing the right expression using the left expression as the source.
parent: corresponds to observing the given expression (only argument) in the parent scope.
has: corresponds to whether the key (second argument) exists within a collection (first argument)
mapBlock: the left is the input, the right is an expression to observe on each element of the input.
filterBlock: the left is the input, the right is an expression to determine whether the result is included in the output.
someBlock: the left is the input, the right is a criterion.
everyBlock: the left is the input, the right is a criterion.
sortedBlock: the left is the input, the right is a relation on each value of the input on which to compare to determine the order.
sortedSetBlock: differs only in semantics from
sortedBlock.
minBlock: the left is the input, the right is a relation on each value of the input by which to compare the value to others.
maxBlock: the left is the input, the right is a relation on each value of the input by which to compare the value to others.
groupBlock: the left is the input, the right is an expression that provides the key for an equivalence class for each value in the input. The output is an array of entries,
[key, class], with the shared key of every value in the equivalence class.
groupMapBlock: has the same input semantics as
groupBlock, but the output is a
Mapinstance instead of an array of entries.
tuple: has any number of arguments, each an expression to observe in terms of the source value.
record: as an args object. The keys are property names for the resulting object, and the values are the corresponding syntax nodes for the values.
view: the arguments are the input, the start position, and the length of the sliding window to view from the input. The input may correspond to any ranged content collection, like an array or sorted set.
rangeContent: corresponds to the content of an ordered collection that can dispatch indexed range changes like an array or sorted set. This indicates to a binder that it should replace the content of the target instead of replacing the target property with the observed content of the source. A range content node has no effect on the source.
mapContent: corresponds to the content of a map-like collection including arrays and all map Collections. These collections dispatch map changes, which create, read, update, or delete key-to-value pairs. This indicates to a binder to replace the content of the target map-like collection with the observed content of the source, instead of replacing the target collection. A map change node on the source side just passes the collection forward without alteration.
For all operators, the "args" property are operands. The node types for unary operators are:
+:
number, arithmetic coercion
-:
neg, arithmetic negation
!:
not, logical negation
For all binary operators, the node types are:
**:
pow, exponential power
//:
root, of 2 square root, of 3 cube root, etc
%%:
log, logarithm with base
*:
mul, multiplication
/:
div, division
%:
mod, modulo (toward negative infinity, always positive)
rem:
rem, remainder (toward zero, negative if negative)
+:
add, addition
-:
sub, subtraction
<:
lt, less than
<=:
le, less than or equal
>:
gt, greater than
>=:
ge, greater than or equal
<=>:
compare
==:
equals, equality comparison and assignment
!=produces unary negation and equality comparison or assignment so does not have a corresponding node type. The simplification makes it easier to rotate the syntax tree algebraically.
&&,
and, logical and
||,
or, logical or
??,
default
For the ternary operator:
?and
::
if, ternary conditional
For all function calls, the right hand side is a tuple of arguments.
reversed()
enumerate()
flatten()
sum()
average()
last()
only()
one()
startsWith(other)
endsWith(other)
contains(other)
join(delimiter)
split(delimiter)
concat(...arrays)
range()
keysArray()
valuesArray()
entriesArray()
defined()
round()
floor()
ceil()
The
observersmodule contains functions for making all of the different types of observers, and utilities for creating new ones. All of these functions are or return an observer function of the form
observe(emit, value, parameters)which in turn returns
cancel().
observeValue
observeParameters
makeLiteralObserver(value)
makeElementObserver(id)
makeComponentObserver(label)
makeRelationObserver(callback, thisp)is unavailable through the property binding language, translates a value through a JavaScript function.
makeComputerObserver(observeArgs, compute, thisp)applies arguments to the computation function to get a new value.
makeConverterObserver(observeValue, convert, thisp)calls the converter function to transform a value to a converted value.
makePropertyObserver(observeObject, observeKey)
makeGetObserver(observeCollection, observeKey)
makeMapFunctionObserver(observeArray, observeFunction)
makeMapBlockObserver(observeArray, observeRelation)
makeFilterBlockObserver(observeArray, observePredicate)
makeSortedBlockObserver(observeArray, observeRelation)
makeEnumerationObserver(observeArray)
makeFlattenObserver(observeOuterArray)
makeTupleObserver(...observers)
makeObserversObserver(observers)
makeReversedObserver(observeArrayh)
makeWindowObserveris not presently available through the language and is subject to change. It is for watching a length from an array starting at an observable index.
makeSumObserver(observeArray)
makeAverageObserver(observeArray)
makeParentObserver(observeExpression)
These are utilities for making observer functions.
makeNonReplacing(observe)accepts an array observer (the emitted values must be arrays) and returns an array observer that will only emit the target once and then incrementally update that target. All array observers use this decorator to handle the case where the source value gets replaced.
makeArrayObserverMaker(setup)generates an observer that uses an array as its source and then incrementally updates a target value, like
sumand
average. The
setup(source, emit)function must return an object of the form
{contentChange, cancel}and arrange for
emitto be called with new values when
contentChange(plus, minus, index)receives incremental updates.
makeUniq(callback)wraps an emitter callback such that it only forwards new values. So, if a value is repeated, subsequent calls are ignored.
autoCancelPrevious(callback)accepts an observer callback and returns an observer callback. Observer callbacks may return cancelation functions, so this decorator arranges for the previous canceler to be called before producing a new one, and arranges for the last canceler to be called when the whole tree is done.
once(callback)accepts a canceler function and ensures that the cancelation routine is only called once.
The
bindersmodule contains similar functions for binding an observed value to a bound value. All binders are of the form
bind(observeValue, source, target, parameters)and return a
cancel()function.
makePropertyBinder(observeObject, observeKey)
makeGetBinder(observeCollection, observeKey)
makeHasBinder(observeCollection, observeValue)
makeEqualityBinder(observeLeft, observeRight)
makeRangeContentBinder(observeTarget)
makeMapContentBinder(observeTarget)
makeReversedBinder(observeTarget)
This documentation of the internal observer and binder functions is not exhaustive.