Reactively computed field for Meteor

Reactively computed field for Meteor provides an easy way to define a reactive variable
which gets value from another reactive function. This allows you to minimize propagation of a reactive change
because if the reactive function returns the value equal to the previous value, reactively computed field
will not invalidate reactive contexts where it is used.

var field = new ComputedField(function () {
  var sum = 0;
  collection.find({}, {fields: {value: 1}}).forEach(function (doc) {
    sum += doc.value;
  });
  return sum;
});
console.log(field());

You get current value by calling the field as a function. A reactive dependency is then registered.
This is useful when you are assigning them to objects because they behave like object methods. You can also access
them in Blaze Components template by simply doing
{{field}} when they are assigned to the component.

When computed field is created inside a Blaze template (in onCreated or onRendered) it will automatically detect this
and allow use of Template.instance() and Template.currentData() inside a function.

Optionally, you can pass a custom equality function:

new ComputedField(reactiveFunction, function (a, b) {return a === b});

Adding this package to your Meteor application adds the ComputedField constructor into
the global scope.

Both client and server side.

Installation

meteor add peerlibrary:computed-field

Arguments

ComputedField constructor accepts the following arguments:

reactiveFunction – a reactive function which should return a computed field’s value
equalityFunction – a function to compare the return value to see if it has changed and if the computed field
should be invalidated; by default it is equal to ReactiveVar._isEqual, which means that only primitive values are compared
by value, and all other are always different
dontStop – pass true to prevent computed field from automatically stopping internal autorun once the field is not used
anymore inside any reactive context (no reactive dependency has been registered on the computed field); sometimes
you do not want autorun to be stopped in this way because you are not using a computed field inside a reactive context at all

You can pass dontStop as a second argument as well, skipping the equalityFunction.

Extra field methods

The computed field is a function, but it has also two extra methods which you probably do not really need, because
computed field should do the right thing automatically.

`field.stop()`

Internally, computed field creates an autorun which should not run once it is not needed anymore.

If you create a computed field inside another autorun, then you do not have to worry and computed field’s autorun
will be stopped and cleaned automatically every time outside computation gets invalidated.

If you create a computed field outside an autorun, autorun will be automatically stopped when there will
be no reactive dependencies anymore on the computed field. So the previous example could be written as well as:

var result = new ComputedField(frequentlyInvalidatedButCheap);
Tracker.autorun(function () {
  expensiveComputation(result());
});

Moreover, if you create a computed field inside a Blaze template (in onCreated or onRendered) it will automatically
detect this and it will use template’s autorun which means that autorun will be stopped automatically when
template instance gets destroyed.

Despite all this, the stop() method is provided for you if you want to explicitly stop and clean the field. Remember,
getting a value again afterwards will start internal autorun again.

`field.flush()`

Sometimes you do not want to wait for global flush to happen to recompute the value. You can call flush() on the
field to force immediate recomputation. But the same happens when you access the field value. If the value is
invalidated, it will be automatically first recomputed and then returned. flush() is in this case called for you
before returning you the field value. In both cases, calling flush() directly or accessing the field value,
recomputation happens only if it is needed.

Examples

Computed field is useful if you want to minimize propagation of reactivity. For example:

Tracker.autorun(function () {
  var result = new ComputedField(frequentlyInvalidatedButCheap);
  expensiveComputation(result());
});

In this example frequentlyInvalidatedButCheap is a function which depends on reactive variables which frequently
change, but computing with them is cheap, and resulting value rarely changes. On the other hand,
expensiveComputation is a function which is expensive and should be called only when result value changes.
Example frequentlyInvalidatedButCheap could for example be determining if current mouse position is inside a
rectangle on canvas or outside. Every time mouse is moved, it should be recomputed, but result changes only when
mouse moves over the rectangle’s border. On the other hand, expensiveComputation could be an expensive drawing
operation which draws a rectangle differently if the mouse position is inside or outside of the rectangle. You do
not want to redraw on every mouse position change.

Even if you create a computed field outside an autorun, autorun will be automatically stopped when there will
be no reactive dependencies anymore on the computed field. So the previous example could be written as well as:

var result = new ComputedField(frequentlyInvalidatedButCheap);
Tracker.autorun(function () {
  expensiveComputation(result());
});

You can use computed field to attach a field to a Blaze Component:

class ExampleComponent extends BlazeComponent {
  onCreated() {
    super.onCreated();
    this.sum = new ComputedField(() => {
      let sum = 0;
      collection.find({}, {fields: {value: 1}}).forEach((doc) => {
        sum += doc.value;
      });
      return sum;
    });
  }
}
ExampleComponent.register('ExampleComponent');

And now you can access this field inside a component without knowing that it will change DOM only when the sum
itself changes, and not at every change of any document:

<template name="ExampleComponent">
  <p>{{sum}}</p>
</template>

meteor-isolate-value – an obsolete package with alternative way of
minimizing reactivity propagation
meteor-embox-value - more or less the same as computed
field, just different implementation, but embox-value does not stop autoruns automatically by default, only when run
lazily; computed field allows you to use instanceof ComputedField to determine if a field is a computed field;
embox-value package has special provisioning for better integration with Blaze templates, but computed field does
not need that because of the auto-stopping feature