ember-source 3.28.5 → 4.0.0-beta.10

package/dist/packages/@ember/object/lib/computed/computed_macros.js

@@ -13,7 +13,7 @@ function expandPropertiesToArray(predicateName, properties) {
 
   for (let i = 0; i < properties.length; i++) {
     let property = properties[i];
-    assert(`Dependent keys passed to computed.${predicateName}() can't have spaces.`, property.indexOf(' ') < 0);
+    assert(`Dependent keys passed to \`${predicateName}\` computed macro can't have spaces.`, property.indexOf(' ') < 0);
     expandProperties(property, extractProperty);
   }
 
@@ -67,25 +67,6 @@ function generateComputedWithPredicate(name, predicate) {
   todoList.isDone; // true
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { empty } from '@ember/object/computed';
-
-  let ToDoList = EmberObject.extend({
-    isDone: empty('todos')
-  });
-
-  let todoList = ToDoList.create({
-    todos: ['Unit Test', 'Documentation', 'Release']
-  });
-
-  todoList.isDone; // false
-  set(todoList, 'todos', []);
-  todoList.isDone; // true
-  ```
-
   @since 1.6.0
   @method empty
   @static
@@ -132,25 +113,6 @@ export function empty(dependentKey) {
   hamster.hasStuff; // false
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { notEmpty } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    hasStuff: notEmpty('backpack')
-  });
-
-  let hamster = Hamster.create({
-    backpack: ['Food', 'Sleeping Bag', 'Tent']
-  });
-
-  hamster.hasStuff; // true
-  set(hamster, 'backpack', []);
-  hamster.hasStuff; // false
-  ```
-
   @method notEmpty
   @static
   @for @ember/object/computed
@@ -190,27 +152,6 @@ export function notEmpty(dependentKey) {
   hamster.isHungry; // true
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { none } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    isHungry: none('food')
-  });
-
-  let hamster = Hamster.create();
-
-  hamster.isHungry; // true
-
-  set(hamster, 'food', 'Banana');
-  hamster.isHungry; // false
-
-  set(hamster, 'food', null);
-  hamster.isHungry; // true
-  ```
-
   @method none
   @static
   @for @ember/object/computed
@@ -249,25 +190,6 @@ export function none(dependentKey) {
   user.isAnonymous; // false
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { not } from '@ember/object/computed';
-
-  let User = EmberObject.extend({
-    loggedIn: false,
-
-    isAnonymous: not('loggedIn')
-  });
-
-  let user = User.create();
-
-  user.isAnonymous; // true
-  set(user, 'loggedIn', true);
-  user.isAnonymous; // false
-  ```
-
   @method not
   @static
   @for @ember/object/computed
@@ -312,31 +234,6 @@ export function not(dependentKey) {
   hamster.hasBananas; // false
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { bool } from '@ember/object/computed';
-
-
-  let Hamster = EmberObject.extend({
-    hasBananas: bool('numBananas')
-  });
-
-  let hamster = Hamster.create();
-
-  hamster.hasBananas; // false
-
-  set(hamster, 'numBananas', 0);
-  hamster.hasBananas; // false
-
-  set(hamster, 'numBananas', 1);
-  hamster.hasBananas; // true
-
-  set(hamster, 'numBananas', null);
-  hamster.hasBananas; // false
-  ```
-
   @method bool
   @static
   @for @ember/object/computed
@@ -378,27 +275,6 @@ export function bool(dependentKey) {
   user.hasValidEmail; // true
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { match } from '@ember/object/computed';
-
-  let User = EmberObject.extend({
-    hasValidEmail: match('email', /^.+@.+\..+$/)
-  });
-
-  let user = User.create();
-
-  user.hasValidEmail; // false
-
-  set(user, 'email', '');
-  user.hasValidEmail; // false
-
-  set(user, 'email', 'ember_hamster@example.com');
-  user.hasValidEmail; // true
-  ```
-
   @method match
   @static
   @for @ember/object/computed
@@ -441,27 +317,6 @@ export function match(dependentKey, regexp) {
   hamster.satisfied; // false
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { equal } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    satisfied: equal('percentCarrotsEaten', 100)
-  });
-
-  let hamster = Hamster.create();
-
-  hamster.satisfied; // false
-
-  set(hamster, 'percentCarrotsEaten', 100);
-  hamster.satisfied; // true
-
-  set(hamster, 'percentCarrotsEaten', 50);
-  hamster.satisfied; // false
-  ```
-
   @method equal
   @static
   @for @ember/object/computed
@@ -503,27 +358,6 @@ export function equal(dependentKey, value) {
   hamster.hasTooManyBananas; // true
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { gt } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    hasTooManyBananas: gt('numBananas', 10)
-  });
-
-  let hamster = Hamster.create();
-
-  hamster.hasTooManyBananas; // false
-
-  set(hamster, 'numBananas', 3);
-  hamster.hasTooManyBananas; // false
-
-  set(hamster, 'numBananas', 11);
-  hamster.hasTooManyBananas; // true
-  ```
-
   @method gt
   @static
   @for @ember/object/computed
@@ -565,27 +399,6 @@ export function gt(dependentKey, value) {
   hamster.hasTooManyBananas; // true
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { gte } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    hasTooManyBananas: gte('numBananas', 10)
-  });
-
-  let hamster = Hamster.create();
-
-  hamster.hasTooManyBananas; // false
-
-  set(hamster, 'numBananas', 3);
-  hamster.hasTooManyBananas; // false
-
-  set(hamster, 'numBananas', 10);
-  hamster.hasTooManyBananas; // true
-  ```
-
   @method gte
   @static
   @for @ember/object/computed
@@ -627,27 +440,6 @@ export function gte(dependentKey, value) {
   hamster.needsMoreBananas; // true
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { lt } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    needsMoreBananas: lt('numBananas', 3)
-  });
-
-  let hamster = Hamster.create();
-
-  hamster.needsMoreBananas; // true
-
-  set(hamster, 'numBananas', 3);
-  hamster.needsMoreBananas; // false
-
-  set(hamster, 'numBananas', 2);
-  hamster.needsMoreBananas; // true
-  ```
-
   @method lt
   @static
   @for @ember/object/computed
@@ -689,27 +481,6 @@ export function lt(dependentKey, value) {
   hamster.needsMoreBananas; // true
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { lte } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    needsMoreBananas: lte('numBananas', 3)
-  });
-
-  let hamster = Hamster.create();
-
-  hamster.needsMoreBananas; // true
-
-  set(hamster, 'numBananas', 5);
-  hamster.needsMoreBananas; // false
-
-  set(hamster, 'numBananas', 3);
-  hamster.needsMoreBananas; // true
-  ```
-
   @method lte
   @static
   @for @ember/object/computed
@@ -762,34 +533,6 @@ export function lte(dependentKey, value) {
   tomster.readyForHike; // null
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { and } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    readyForCamp: and('hasTent', 'hasBackpack'),
-    readyForHike: and('hasWalkingStick', 'hasBackpack')
-  });
-
-  let tomster = Hamster.create();
-
-  tomster.readyForCamp; // false
-
-  set(tomster, 'hasTent', true);
-  tomster.readyForCamp; // false
-
-  set(tomster, 'hasBackpack', true);
-  tomster.readyForCamp; // true
-
-  set(tomster, 'hasBackpack', 'Yes');
-  tomster.readyForCamp; // 'Yes'
-
-  set(tomster, 'hasWalkingStick', null);
-  tomster.readyForHike; // null
-  ```
-
   @method and
   @static
   @for @ember/object/computed
@@ -833,31 +576,6 @@ export const and = generateComputedWithPredicate('and', value => value);
   tomster.readyForBeach; // 'Check'
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { or } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    readyForRain: or('hasJacket', 'hasUmbrella'),
-    readyForBeach: or('hasSunscreen', 'hasUmbrella')
-  });
-
-  let tomster = Hamster.create();
-
-  tomster.readyForRain; // undefined
-
-  set(tomster, 'hasUmbrella', true);
-  tomster.readyForRain; // true
-
-  set(tomster, 'hasJacket', 'Yes');
-  tomster.readyForRain; // 'Yes'
-
-  set(tomster, 'hasSunscreen', 'Check');
-  tomster.readyForBeach; // 'Check'
-  ```
-
   @method or
   @static
   @for @ember/object/computed
@@ -894,27 +612,6 @@ export const or = generateComputedWithPredicate('or', value => !value);
   alex.name;  // '@machty'
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { alias } from '@ember/object/computed';
-
-  let Person = EmberObject.extend({
-    name: 'Alex Matchneer',
-
-    nomen: alias('name')
-  });
-
-  let alex = Person.create();
-
-  alex.nomen; // 'Alex Matchneer'
-  alex.name;  // 'Alex Matchneer'
-
-  set(alex, 'nomen', '@machty');
-  alex.name;  // '@machty'
-  ```
-
   @method alias
   @static
   @for @ember/object/computed
@@ -925,11 +622,11 @@ export const or = generateComputedWithPredicate('or', value => !value);
 */
 
 /**
-  Where `computed.alias` aliases `get` and `set`, and allows for bidirectional
-  data flow, `computed.oneWay` only provides an aliased `get`. The `set` will
-  not mutate the upstream property, rather causes the current property to become
-  the value set. This causes the downstream property to permanently diverge from
-  the upstream property.
+  Where the `alias` computed macro aliases `get` and `set`, and allows for
+  bidirectional data flow, the `oneWay` computed macro only provides an aliased
+  `get`. The `set` will not mutate the upstream property, rather causes the
+  current property to become the value set. This causes the downstream property
+  to permanently diverge from the upstream property.
 
   Example:
 
@@ -955,31 +652,6 @@ export const or = generateComputedWithPredicate('or', value => !value);
   teddy.nickName; // 'TeddyBear'
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { oneWay } from '@ember/object/computed';
-
-  let User = EmberObject.extend({
-    firstName: null,
-    lastName: null,
-
-    nickName: oneWay('firstName')
-  });
-
-  let teddy = User.create({
-    firstName: 'Teddy',
-    lastName: 'Zeenny'
-  });
-
-  teddy.nickName; // 'Teddy'
-
-  set(teddy, 'nickName', 'TeddyBear'); // 'TeddyBear'
-  teddy.firstName; // 'Teddy'
-  teddy.nickName; // 'TeddyBear'
-  ```
-
   @method oneWay
   @static
   @for @ember/object/computed
@@ -994,8 +666,8 @@ export function oneWay(dependentKey) {
   return alias(dependentKey).oneWay();
 }
 /**
-  This is a more semantically meaningful alias of `computed.oneWay`, whose name
-  is somewhat ambiguous as to which direction the data flows.
+  This is a more semantically meaningful alias of the `oneWay` computed macro,
+  whose name is somewhat ambiguous as to which direction the data flows.
 
   @method reads
   @static
@@ -1007,9 +679,10 @@ export function oneWay(dependentKey) {
  */
 
 /**
-  Where `computed.oneWay` provides oneWay bindings, `computed.readOnly` provides
-  a readOnly one way binding. Very often when using `computed.oneWay` one does
-  not also want changes to propagate back up, as they will replace the value.
+  Where `oneWay` computed macro provides oneWay bindings, the `readOnly`
+  computed macro provides a readOnly one way binding. Very often when using
+  the `oneWay` macro one does not also want changes to propagate back up, as
+  they will replace the value.
 
   This prevents the reverse flow, and also throws an exception when it occurs.
 
@@ -1038,32 +711,6 @@ export function oneWay(dependentKey) {
   teddy.firstName; // 'Teddy'
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { readOnly } from '@ember/object/computed';
-
-  let User = EmberObject.extend({
-    firstName: null,
-    lastName: null,
-
-    nickName: readOnly('firstName')
-  });
-
-  let teddy = User.create({
-    firstName: 'Teddy',
-    lastName:  'Zeenny'
-  });
-
-  teddy.nickName; // 'Teddy'
-
-  set(teddy, 'nickName', 'TeddyBear'); // throws Exception
-  // throw new EmberError('Cannot Set: nickName on: <User:ember27288>' );`
-
-  teddy.firstName; // 'Teddy'
-  ```
-
   @method readOnly
   @static
   @for @ember/object/computed
@@ -1103,25 +750,6 @@ export function readOnly(dependentKey) {
   hamster.cavendishCount; // 5
   ```
 
-  Classic Class Example:
-
-  ```javascript
-  import EmberObject, { set } from '@ember/object';
-  import { deprecatingAlias } from '@ember/object/computed';
-
-  let Hamster = EmberObject.extend({
-    bananaCount: deprecatingAlias('cavendishCount', {
-      id: 'hamster.deprecate-banana',
-      until: '3.0.0'
-    })
-  });
-
-  let hamster = Hamster.create();
-
-  set(hamster, 'bananaCount', 5); // Prints a deprecation warning.
-  hamster.cavendishCount; // 5
-  ```
-
   @method deprecatingAlias
   @static
   @for @ember/object/computed