Class ComputedProperty

public

Defined in: packages/@ember/-internals/metal/lib/computed.ts:57

@computed is a decorator that turns a JavaScript getter and setter into a computed property, which is a cached, trackable value. By default the getter will only be called once and the result will be cached. You can specify various properties that your computed property depends on. This will force the cached result to be cleared if the dependencies are modified, and lazily recomputed the next time something asks for it.

In the following example we decorate a getter - fullName - by calling computed with the property dependencies (firstName and lastName) as arguments. The fullName getter will be called once (regardless of how many times it is accessed) as long as its dependencies do not change. Once firstName or lastName are updated any future calls to fullName will incorporate the new values, and any watchers of the value such as templates will be updated:

        
              import { computed, set } from '@ember/object';

class Person {
  constructor(firstName, lastName) {
    set(this, 'firstName', firstName);
    set(this, 'lastName', lastName);
  }

  @computed('firstName', 'lastName')
  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }
});

let tom = new Person('Tom', 'Dale');

tom.fullName; // 'Tom Dale'

You can also provide a setter, which will be used when updating the computed property. Ember's set function must be used to update the property since it will also notify observers of the property:

        
          
              
              import { computed, set } from '@ember/object';

class Person {
  constructor(firstName, lastName) {
    set(this, 'firstName', firstName);
    set(this, 'lastName', lastName);
  }

  @computed('firstName', 'lastName')
  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }

  set fullName(value) {
    let [firstName, lastName] = value.split(' ');

    set(this, 'firstName', firstName);
    set(this, 'lastName', lastName);
  }
});

let person = new Person();

set(person, 'fullName', 'Peter Wagenet');
person.firstName; // 'Peter'
person.lastName;  // 'Wagenet'
            

        
      

You can also pass a getter function or object with get and set functions as the last argument to the computed decorator. This allows you to define computed property macros:

        
              import { computed } from '@ember/object';

function join(...keys) {
  return computed(...keys, function() {
    return keys.map(key => this[key]).join(' ');
  });
}

class Person {
  @join('firstName', 'lastName')
  fullName;
}

Note that when defined this way, getters and setters receive the key of the property they are decorating as the first argument. Setters receive the value they are setting to as the second argument instead. Additionally, setters must return the value that should be cached:

        
          
              
              import { computed, set } from '@ember/object';

function fullNameMacro(firstNameKey, lastNameKey) {
  return computed(firstNameKey, lastNameKey, {
    get() {
      return `${this[firstNameKey]} ${this[lastNameKey]}`;
    }

    set(key, value) {
      let [firstName, lastName] = value.split(' ');

      set(this, firstNameKey, firstName);
      set(this, lastNameKey, lastName);

      return value;
    }
  });
}

class Person {
  constructor(firstName, lastName) {
    set(this, 'firstName', firstName);
    set(this, 'lastName', lastName);
  }

  @fullNameMacro('firstName', 'lastName') fullName;
});

let person = new Person();

set(person, 'fullName', 'Peter Wagenet');
person.firstName; // 'Peter'
person.lastName;  // 'Wagenet'
            

        
      

Computed properties can also be used in classic classes. To do this, we provide the getter and setter as the last argument like we would for a macro, and we assign it to a property on the class definition. This is an anonymous computed macro:

        
          
              
              import EmberObject, { computed, set } from '@ember/object';

let Person = EmberObject.extend({
  // these will be supplied by `create`
  firstName: null,
  lastName: null,

  fullName: computed('firstName', 'lastName', {
    get() {
      return `${this.firstName} ${this.lastName}`;
    }

    set(key, value) {
      let [firstName, lastName] = value.split(' ');

      set(this, 'firstName', firstName);
      set(this, 'lastName', lastName);

      return value;
    }
  })
});

let tom = Person.create({
  firstName: 'Tom',
  lastName: 'Dale'
});

tom.get('fullName') // 'Tom Dale'
            

        
      

You can overwrite computed property without setters with a normal property (no longer computed) that won't change if dependencies change. You can also mark computed property as .readOnly() and block all attempts to set it.

        
              import { computed, set } from '@ember/object';

class Person {
  constructor(firstName, lastName) {
    set(this, 'firstName', firstName);
    set(this, 'lastName', lastName);
  }

  @computed('firstName', 'lastName').readOnly()
  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }
});

let person = new Person();
person.set('fullName', 'Peter Wagenet'); // Uncaught Error: Cannot set read-only property "fullName" on object: <(...):emberXXX>

Additional resources:

Show: Inherited Protected Private Deprecated

meta (meta) public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/computed.ts:811

meta: Object

In some cases, you may want to annotate computed properties with additional metadata about how they function or what values they operate on. For example, computed property functions may close over variables that are then no longer available for introspection. You can pass a hash of these values to a computed property.

Example:

        
              import { computed } from '@ember/object';
import Person from 'my-app/utils/person';

class Store {
  @computed().meta({ type: Person })
  get person() {
    let personId = this.personId;
    return Person.create({ id: personId });
  }
}

Classic Class Example:

        
              import { computed } from '@ember/object';
import Person from 'my-app/utils/person';

const Store = EmberObject.extend({
  person: computed(function() {
    let personId = this.get('personId');
    return Person.create({ id: personId });
  }).meta({ type: Person })
});

The hash that you pass to the meta() function will be saved on the computed property descriptor under the _meta key. Ember runtime exposes a public API for retrieving these values from classes, via the metaForProperty() function.

readOnly ComputedProperty public

Module: @ember/object

Defined in packages/@ember/-internals/metal/lib/computed.ts:625

returns: ComputedProperty; this

Call on a computed property to set it into read-only mode. When in this mode the computed property will throw an error when set.

Example:

        
              import { computed, set } from '@ember/object';

class Person {
  @computed().readOnly()
  get guid() {
    return 'guid-guid-guid';
  }
}

let person = new Person();
set(person, 'guid', 'new-guid'); // will throw an exception

Classic Class Example:

        
              import EmberObject, { computed } from '@ember/object';

let Person = EmberObject.extend({
  guid: computed(function() {
    return 'guid-guid-guid';
  }).readOnly()
});

let person = Person.create();
person.set('guid', 'new-guid'); // will throw an exception