Enumerables

In order for Ember to observe when you make a change to an enumerable, you need to use special methods that MutableArray provides. For example, if you add an element to an array using the standard JavaScript method push(), Ember will not be able to observe the change, but if you use the enumerable method pushObject(), the change will propagate throughout your application.

Here is a list of standard JavaScript array methods and their observable enumerable equivalents:

Additionally, to retrieve the first and last objects in an array in an observable fashion, you should use myArray.get('firstObject') and myArray.get('lastObject'), respectively.

In the rest of this guide, we'll explore some of the most common enumerable conveniences. For the full list, please see the MutableArray API reference documentation.

To enumerate all the values of an enumerable object, use the forEach() method:

let food = ['Poi', 'Ono', 'Adobo Chicken'];

food.forEach((item, index) => {
  console.log(`Menu Item ${index+1}: ${item}`);
});

// Menu Item 1: Poi
// Menu Item 2: Ono
// Menu Item 3: Adobo Chicken

All enumerables expose firstObject and lastObject properties that you can bind to.

import { A } from '@ember/array';

let animals = A(['rooster', 'pig']);

animals.get('lastObject');
//=> "pig"

animals.pushObject('peacock');

animals.get('lastObject');
//=> "peacock"

You can easily transform each item in an enumerable using the map() method, which creates a new array with results of calling a function on each item in the enumerable.

let words = ['goodbye', 'cruel', 'world'];

let emphaticWords = words.map(item => `${item}!`);
//=> ["goodbye!", "cruel!", "world!"]

If your enumerable is composed of objects, there is a mapBy() method that will extract the named property from each of those objects in turn and return a new array:

import { A } from '@ember/array';
import EmberObject from '@ember/object';

let hawaii = EmberObject.create({
  capital: 'Honolulu'
});

let california = EmberObject.create({
  capital: 'Sacramento'
});

let states = A([hawaii, california]);

states.mapBy('capital');
//=> ["Honolulu", "Sacramento"]

Another common task to perform on an enumerable is to take the enumerable as input, and return an Array after filtering it based on some criteria.

For arbitrary filtering, use the filter() method. The filter method expects the callback to return true if Ember should include it in the final Array, and false or undefined if Ember should not.

let arr = [1, 2, 3, 4, 5];

arr.filter((item, index, self) => item < 4);

//=> [1, 2, 3]

When working with a collection of Ember objects, you will often want to filter a set of objects based upon the value of some property. The filterBy() method provides a shortcut.

import { A } from '@ember/array';
import EmberObject from '@ember/object';

Todo = EmberObject.extend({
  title: null,
  isDone: false
});

let todos = A([
  Todo.create({ title: 'Write code', isDone: true }),
  Todo.create({ title: 'Go to sleep' })
]);

todos.filterBy('isDone', true);

// returns an Array containing only items with `isDone == true`

If you only want to return the first matched value, rather than an Array containing all of the matched values, you can use find() and findBy(), which work like filter() and filterBy(), but return only one item.

To find out whether every item in an enumerable matches some condition, you can use the every() method:

import { A } from '@ember/array';
import EmberObject from '@ember/object';

Person = EmberObject.extend({
  name: null,
  isHappy: false
});

let people = A([
  Person.create({ name: 'Yehuda', isHappy: true }),
  Person.create({ name: 'Majd', isHappy: false })
]);

people.every((person, index, self) => person.get('isHappy'));

//=> false

To find out whether at least one item in an enumerable matches some condition, you can use the any() method:

people.any((person, index, self) => person.get('isHappy'));

//=> true

Like the filtering methods, the every() and any() methods have analogous isEvery() and isAny() methods.

people.isEvery('isHappy', true); // false
people.isAny('isHappy', true);  // true