can-compute

Compose observables.

• can-compute function
  • compute( getterSetter[, context] )
  • compute( initialValue [, settings] )
  • compute( initialValue, setter(newVal,oldVal) )
  • compute( object, propertyName [, eventName] )
    • compute( [newVal] )
    • compute.async(initialValue, computed(currentValue, setValue(newValue) )
    • asyncComputer function(lastSetValue, setVal)
    • computeSettings Object

API

can-compute function

Create an observable value.

compute( getterSetter[, context] )

Create a compute that derives its value from [can-map]s and other computes.

var age = compute(32);

var nameAndAge = compute(function(){
    return "Matthew - " + age();
});

console.log(nameAndAge()); // -> Matthew - 32

age(33);

console.log(nameAndAge()); // -> Matthew - 33

1. getterSetter {function(newVal, oldVal)}: A function that gets and optionally sets the value of the compute. When called with no parameters, getterSetter should return the current value of the compute. When called with a single parameter, getterSetter should arrange things so that the next read of the compute produces that value. This compute will automatically update its value when any [can.Map observable] values are read via [can-map.prototype.attr].

2. context {Object}: The this to use when calling the getterSetter function.

• returns {compute(newVal)}: A new compute.

compute( initialValue [, settings] )

Creates a compute from a value and optionally specifies how to read, update, and listen to changes in dependent values. This form of compute can be used to create a compute that derives its value from any source.

1. initialValue {*}: The initial value of the compute. If settings is not provided, the compute simply updates its value to whatever the first argument to the compute is.

   var age = compute(30); age() //-> 30 age(31) //-> fires a "change" event

2. settings {computeSettings}:

Configures all behaviors of the compute. The following cross binds an input element to a compute:

  var input = document.getElementById("age")
  var value = compute("",{
      get: function(){
          return input.value;
      },
      set: function(newVal){
          input.value = newVal;
      },
      on: function(updated){
          input.addEventListener("change", updated, false);
      },
      off: function(updated){
          input.removeEventListener("change", updated, false);
      }
  })

• returns {compute(newVal)}: The new compute.

compute( initialValue, setter(newVal,oldVal) )

Create a compute that has a setter that can adjust incoming new values.

var age = compute(6,function(newVal, oldVal){
  if(!isNaN(+newVal)){
    return +newVal;
  } else {
    return oldVal;
  }
})

1. initialValue {*}:

The initial value of the compute.

1. setter {function(newVal, oldVal)}:

A function that is called when a compute is called with an argument. The function is passed the first argumented passed to compute and the current value. If set returns a value, it is used to compare to the current value of the compute. Otherwise, get is called to get the current value of the compute and that value is used to determine if the compute has changed values.

• returns {compute(newVal)}: A new compute.

compute( object, propertyName [, eventName] )

Create a compute from an object's property value. This short-cut signature lets you create a compute on objects that have events that can be listened to with [can.bind].

var input = document.getElementById('age')
var age = compute(input,"value","change");

var me = new Map({name: "Justin"});
var name = compute(me,"name")

1. object {Object}: An object that either has a bind method or a has events dispatched on it via [can.trigger].

2. propertyName {String}: The property value to read on object. The property will be read via object.attr(propertyName) or object[propertyame].

3. eventName {String}: Specifies the event name to listen to on object for propertyName updates.

• returns {compute(newVal)}: A new compute.

compute( [newVal] )

1. newVal {*}: If compute is called with an argument, the first argument is used to set the compute to a new value. This may trigger a "change" event that can be listened for with [can.computed.bind].

If the compute is called without any arguments (compute()), it simply returns the current value of the compute.

• returns {*}: The current value of the compute.

compute.async(initialValue, computed(currentValue, setValue(newValue) )

1. The {*}: initial value of the compute.

2. computed {asyncComputer(lastSetValue, setVal)}: A function that returns the current value of the compute and can optionally later call its setValue callback to update the value.

• returns {compute(newVal)}: Returns a compute, but a compute that will possibly not have the correct value unless it is bound to.

asyncComputer {function(lastSetValue, setVal)}

A function that determines a value for an async compute.

function(lastSetValue, setVal)

The function callback to async that determines the value of the compute.

1. lastSetValue {*}: The last set value of the compute. This should be returned if you are doing an in-place compute.

2. setVal {function(newVal)}: Called to update the value of the compute at a later time.

• returns {*}: If a setVal argument is not provided, the return value is set as the current value of the compute. If setVal is provided and undefined is returned, the current value remains until setVal is called.

computeSettings {Object}

Object

• get {function}: A function that retrieves and returns the current value of the compute.

• set {function(newVal, oldVal)}: A function that is used when setting a new value of the compute.

  A function that is called when a compute is called with an argument. The function is passed the first argumented passed to [can.computed compute] and the current value. If set returns a value, it is used to compare to the current value of the compute. Otherwise, get is called to get the current value of the compute and that value is used to determine if the compute has changed values.

  newVal is the value being set, while oldVal is the previous value in the compute.

• on {function(updated)}: Called to setup binding to dependency events. Call updated when the compute's value needs to be updated.

• off {function(function)}: Called to teardown binding.

Contributing

Making a Build

To make a build of the distributables into dist/ in the cloned repository run

npm install
node build

Running the tests

Tests can run in the browser by opening a webserver and visiting the test.html page. Automated tests that run the tests from the command line in Firefox can be run with

npm test