rp (ReactiveProperty)

rp = value containers + computed values + automatic dependency tracking

• works well with objects and arrays
• including common computations

Basics

var rp = require("rp");

// Creating RPs
var x = rp.variable(1); // read/writable
var y = rp.const(2); // only readable

// Reading values
x() === 1
y() === 2
y.get() === 2 // y() is a shortcut for y.get()

// Computed RPs
var xy = rp.computed(function() {
	return x() + y(); // Dependencies
});

xy() === 3

// Writing values
x.set(5);
x() === 5

// Computed RPs are updated
xy() === 6

Reading operations

Shortcuts for common computations. They all return a RP so they are chainable.

var x = rp.variable(Math.PI);
var y = rp.variable(123);

x.computed(function(x) {
	return x * x + 2
}); // => 11.869...

x.inversed() // => false

x.asBool() // => true

x.asNumber() // => 3.14...

x.asString() // => "3.14..."

x.rounded() // => 3
x.floored() // => 3
x.ceiled() // => 4

x.plus(y) // => 126.14...
y.minus(x) // => 119.86...
y.dividedBy(x) // => 39.15...
x.multipliedBy(y) // => 386.41...
x.equals(y) // false
x.comparedTo(y) // -1
x.comparedTo(y, function(a,b) {...}) // -1
rp.variable("test123TEST").split(y.asString()) // => ["test", "TEST"]
rp.variable("[1,2]").parsed() // => [1,2]
rp.variable([1,2]).stringified() // => "[1,2]"

// Array operations
var z = rp.variable([1,2,3,4]);
var a = rp.variable(1);

z.map(function(item) {
	return item * (a() + 1);
}) // => [2, 4, 6, 8]

z.filter(function(item) {
	return item % 2 === a();
}) // => [1, 3]

z.reduce(function(a, b) {
	return a + b;
}) // => 10

z.slice(a, 2) // => [2, 3]

z.indexOf(a) // => 0

z.size() // => 4

Writing operations

var x = rp.variable(1);
var y = rp.variable(2);
var z = rp.variable([1,2,3]);

x.increment(); // x = x + 1
x.decrement(); // x = x - 1
x.add(3); // x = x + 3;
x.subtract(6); // x = x - 6;
x.multiply(10); // x = x * 10;
x.divide(y()); // x = x / y;

z.push(y());
z.unshift(y());
z.shift(); // => 2
z.pop(); // => 2
z.splice(1, 2, "test");
z(2).remove();

Helpers

var z = rp.variable([1,2,3]);

z.forEach(function(item, idx) {
	console.log("at " + idx + " is " + item());
});

z.log("z"); // logs all changes with the name "z"

z.readonly(); // readonly version of anything

z.fixed(); // cannot be updated, but elements and properties can be changed

z.fixedArray(); // cannot be updated, neither can elements be added or removed
				// But values can be changed

z.isConst() === false
rp.const([1,2,3]).map(function(i) { return i * i; }).isConst() === true
	// Returns true is the value is constant

Objects and Arrays

var o = rp.variable({a: {b: [{c: 1}, {d: 2}]}});

// Getting RP of properties and elements
var a = o("a");
var b = o("a", "b");
var c = a("b", 0, "c");
var d = o("a", "b", 1, "d");
var p = o("p", "p", "p");

c() === 1
d() === 2

// not existing properties are undefined
p() === undefined

// RP move with array modifications
b.shift();

//  d is now o("a", "b", 0, "d")
d() === 2

// removed elements become undefined
c() === undefined

// you get the same instance for a property or element
o("a", "b", 0, "d") === d

Memory management

// Every RP is only valid until the next tick
var x = rp.variable(1);
x() // fine
process.nextTick(function() {
	x() // :(
});

// To make them longer valid put them into a scope
var x = rp.variable(2).scope(); // into the global scope

// or into a private scope
var s = rp.scope(function() {
	var x = rp.variable(4).scope();
});

// continue to run code in this scope
s.run(function() {
	var y = rp.variable(6).scope();
	// nest scopes
	rp.scope(function() {
		var zz = rp.variable(8);
		var z = zz.plus(2).multipliedBy(7);

		// scope computed RPs,
		//  dependencies will stay too
		z.scope();
	});
});
s.scope(function() {
	var a = rp.const(1).plus(1).scope();
});

// Scope[ x, y, Scope[ z ], Scope[ a ] ]

// unref the scope anytime you want
// nested scopes are also removed
s.unref();

// Computed forms a scope too
//  but it's not part of the parent scope
// It's handled by the normal RP lifetime
var x = rp.computed(function() {
	var y = rp.variable().scope();
});
// x is valid until the next tick, so is y

Handled get

Read the value, but handle changes by some function.

rp.prototype.getHandled(changedHandler(value))

rp.prototype.getHandled(
	updatedHandler(value),
	addedHandler(idx, item),
	removedHandler(idx, item)
)

A handled get is active as long as the current scope is active.

Example: exchange the HTML code of a HTMLElement:

var x = rp.variable("Text");
var tag = rp.variable("div");
var html = x.computed(function(x) {
	return "<h1>" + x + "</h1>";
});
var element = rp.computed(function() {
	var element = document.createElement(tag());
	element.innerHTML = html.getHandled(function(html) {
		// Changes of html are handled here
		element.innerHTML = html;
	});
	return element;
});
var el1 = element();
x.set("New text");
element() === el1;
tag.set("pre");
element() !== el1;

Atomic

var x = rp.variable("test");
var counter = 0;
var y = x.computed(function(x) {
	return x + (++counter);
});
y() === "test1"

// atomic delay updates to the end of the block
// can boost performance for many changes
rp.atomic(function() {
	x.set("a");
	x.set("b");
	x.set("c");
});
y() === "c2"

Delegated

var a = rp.variable(1);
var b = rp.variable(2);
var which = rp.variable(false);

// while computed RPs provide only read access
var y = which.computed(function(which) {
	return which ? a() : b()
});

// delegated RPs can provide read/write access
//  to a dynamically choosen RP
var ref = which.computed(function(which) {
	return which ? a : b
});
var x = rp.delegated(ref);
// or: var x = ref.delegated();
// or: var x = rp.delegated(function() { return which() ? a : b; });

x() === 2
x.set(4);
b() === 4
which.set(true);
x() === 1
s.set(9);
a() === 9

Two-way computions

var x = rp.variable(1);
var y = x.computed(
	function(x) { return x * 2; },
	function(y) { return y / 2; }
);
y() === 2
y.set(5);
x() === 2.5
x.set(2);
y() === 4

Two-way operations

var x = rp.variable(123);
var str1 = x.asIntString();
var str2 = x.asFloatString();
str1() === "123"
str1.set("456");
x() === 456
x.set(789);
str1() === "789"
str2() === "789"
str2.set("1.23");
x() === 1.23

Attributes

Every RP can have attributes. One can use them to exchange user data. Each attribute is a rp.variable.

var x = rp.variable({ a: 1 });
function validate() {
	var a = x("a");
	a.attr("valid").set(a() % 2 === 0);
}
validate();
var aValid = x("a").attr("valid");
aValid() === false;
x("a").set(2);
aValid() === true;
x("a").hasAttr("valid") === true;
x.hasAttr("valid") === false;

Internals

All works with 5 events:

• changed: The value changed
• updated: The primitive value changed or the reference changed
• added: An item is added to the array
• removed: An item is removed from the array
• nested: A event occured on nested stuff

var a = rp.variable(/test/);
var b = rp.variable([1,2]);
var c = rp.variable({a: 1});
var d = rp.variable({a: {b: [1]}});

a.set(123);
// a updated(123, /test/)
// a changed()

a.set(123);
// no events

b.push(3);
// b added(2/*idx*/, 3/*value*/)
// b changed()

b.set([]);
// b updated([], [1,2,3])
// b changed

c("a").set(2);
// c nested("updated", ["a"], 2, 1);
// c changed

c.set({a: 2});
// c updated({a: 2}, {a: 2});
// c changed

d("a", "b").push(2);
// c nested("added", ["a", "b"], 2);
// d changed

d("a", "b", 1).set(3);
// c nested("updated", ["a", "b", 1], 3);
// d changed

The nested event is not used internally, can be used to capture all updates on objects and arrays.

Computed values listen on "changed", "updated", "added" and "removed" and update their values.

By design they could do this very clever:

var x = rp.variable([1,2,3,4]);
var y = x.filter(function(item) {
	return item % 2 === 0
}).map(function(item) {
	return item * item
});

// y() is now [4, 16]

x.push(5);
// no events for y

x.push(6)
// y added(2, 36)

But it's work on progress for some function. (They currently update the whole array, where a bunch of "added" or "removed" events would do it better.)

// You can listen on the events
x.onceChanged(function() {});
x.onChanged(function() {});
x.onUpdated(function() {});
x.onAdded(function() {});
x.onRemoved(function() {});
x.onceDisposed(function() {});

x.removeOnceChangedListener(fn);
x.removeChangedListener(fn);
// ...
x.removeDisposedListener(fn);

Internally each RP uses reference counting to know when to dispose itself. At creation they get one reference that is removed at nextTick. Disposing means to remove event listener from RPs it depend on.

With x.ref() and x.unref() you can add/remove references, but there is no need to do this if you don't want to write your own RP. Better use x.scope() and let the scope manage your RPs.

TODO

Test status

License

MIT