`consistent-observable`

Little framework for simplifying reaction to values changing over time.

Install

NPM package:
```
npm install -S consistent-observable
```
Bower package
```
bower install -S consistent-observable
```
Manual download: consistent-observable and dependency one-time-event

Together with its dependency, consistent-observable requires the following ES2015 features:

So if you want to support old browsers you may need a polyfill, for example babel-polyfill.

Usage

If no CommonJS or AMD module loader is available, the module is exposed globally as consistentObservable.

var co = window.consistentObservable;

// CommonJS
var co = require('consistent-observable');

A “consistent observable” is an object which represents a value which may change over time. There are currently two types of consistent observables:

IndependentObservable: Stores the value like a box. Exhibits a set method to change the value.

var task = co.newIndependent('6 * 7');
var solution = co.newIndependent('42');

console.log(task.peek()); // Logs '6 * 7'

ComputedObservable: Depends on other consistent observables. The value is computed when it is accessed (and has not been computed before). If a dependency changes, the value of the ComputedObservable changes, too.
```
var equation = co.newComputed(function (r) {
  return r(task) + ' == ' + r(solution);
});

console.log(equation.peek()); // Logs '6 * 7 == 42'
```
Note the recording function r. It is required because the ComputedObservable needs to track which consistent observable it depends on.

Futhermore there are Actions, which—like ComputedObservables—depend on any amount of consistent observables, but Actions are no observables themselves. They can be used to align some external state according to their dependencies.

var logger = co.newAction(function (r) {
  console.log('This is true: ' + r(equation));
}); // Logs 'This is true: 6 * 7 == 42'.

Changing values can be performed in the following way:

co.inTransition(function(tr) {
  task.set('7 * 8', tr);
  end.set('56', tr);
}); // Logs 'This is true: 7 * 8 == 56'

These two set operations are performed inside a “transition”. This means that all updates caused by the changes are propagated only at the end of the inTransition call. This avoids that 'This is true: 7 * 8 == 42' is logged. Transitions should not be confused with transactions as they do not support rollbacks.

After an Action is stopped, it does not react to dependency changes anymore:

logger.close();

One target of the implementation of consistent-observable has been to minimize the count of executed computations so that unnecessary updates are avoided. It was primarily developed for UI coordination but it is purpose neutral.

Contributing

Use Yarn for reproducible builds.

Build command: npm run rebuild (or yarn run rebuild)

Test command: npm run test (or yarn run test)

Coverage command: npm run coverage (or yarn run coverage)

https://github.com/c7hm4r/consistent-observable

Similar projects

mobx is a faster implementation then consistentObservable (see comparison). However, the runtime complexity of both packages seems to be the same. mobx it is larger (144KB minified) than consistentObservable (9KB minified, inclusive one-time-event).

License

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.