From e2f38191b870760196311fb9f919dfc2cd9a5cad Mon Sep 17 00:00:00 2001
From: Peter Wagenet <peter.wagenet@gmail.com>
Date: Wed, 18 Mar 2015 19:49:28 -0700
Subject: [PATCH] Deprecate Ember.required

---
 packages/ember-application/lib/system/resolver.js  | 14 +++++++-------
 packages/ember-metal/lib/mixin.js                  |  5 ++++-
 packages/ember-metal/tests/mixin/required_test.js  | 10 ++++++----
 packages/ember-runtime/lib/mixins/array.js         |  9 ++++-----
 packages/ember-runtime/lib/mixins/comparable.js    |  9 ++++-----
 packages/ember-runtime/lib/mixins/copyable.js      |  6 ++++--
 packages/ember-runtime/lib/mixins/enumerable.js    |  5 +++--
 packages/ember-runtime/lib/mixins/mutable_array.js |  7 ++-----
 .../ember-runtime/lib/mixins/mutable_enumerable.js |  6 +++---
 packages/ember-runtime/lib/system/core_object.js   |  6 +++---
 packages/ember-runtime/tests/suites/copyable.js    |  9 ++++++---
 packages/ember-runtime/tests/suites/enumerable.js  |  9 ++++++---
 packages/ember-runtime/tests/suites/suite.js       |  8 ++++----
 .../tests/system/object/create_test.js             |  4 ++--
 14 files changed, 58 insertions(+), 49 deletions(-)

diff --git a/packages/ember-application/lib/system/resolver.js b/packages/ember-application/lib/system/resolver.js
index a7cc7acb9ea..82124ca3c9a 100644
--- a/packages/ember-application/lib/system/resolver.js
+++ b/packages/ember-application/lib/system/resolver.js
@@ -23,13 +23,13 @@ export var Resolver = EmberObject.extend({
     @property namespace
   */
   namespace: null,
-  normalize:         Ember.required(Function),
-  resolve:           Ember.required(Function),
-  parseName:         Ember.required(Function),
-  lookupDescription: Ember.required(Function),
-  makeToString:      Ember.required(Function),
-  resolveOther:      Ember.required(Function),
-  _logLookup:        Ember.required(Function)
+  normalize:         null, // required
+  resolve:           null, // required
+  parseName:         null, // required
+  lookupDescription: null, // required
+  makeToString:      null, // required
+  resolveOther:      null, // required
+  _logLookup:        null  // required
 });
 
 /**
diff --git a/packages/ember-metal/lib/mixin.js b/packages/ember-metal/lib/mixin.js
index 2e209f3d7f2..c375509507e 100644
--- a/packages/ember-metal/lib/mixin.js
+++ b/packages/ember-metal/lib/mixin.js
@@ -740,6 +740,7 @@ REQUIRED.toString = function() { return '(Required Property)'; };
   @for Ember
 */
 export function required() {
+  Ember.deprecate('Ember.required is deprecated as its behavior is inconsistent and unreliable.', false);
   return REQUIRED;
 }
 
@@ -937,5 +938,7 @@ export function beforeObserver(...args) {
 
 export {
   IS_BINDING,
-  Mixin
+  Mixin,
+  required,
+  REQUIRED
 };
diff --git a/packages/ember-metal/tests/mixin/required_test.js b/packages/ember-metal/tests/mixin/required_test.js
index fc88bea99a7..3728b6dbef4 100644
--- a/packages/ember-metal/tests/mixin/required_test.js
+++ b/packages/ember-metal/tests/mixin/required_test.js
@@ -9,10 +9,12 @@ var PartialMixin, FinalMixin, obj;
 
 QUnit.module('Module.required', {
   setup() {
-    PartialMixin = Mixin.create({
-      foo: required(),
-      bar: 'BAR'
-    });
+    expectDeprecation(function() {
+      PartialMixin = Mixin.create({
+        foo: required(),
+        bar: 'BAR'
+      });
+    }, "Ember.required is deprecated as its behavior is inconsistent and unreliable.");
 
     FinalMixin = Mixin.create({
       foo: 'FOO'
diff --git a/packages/ember-runtime/lib/mixins/array.js b/packages/ember-runtime/lib/mixins/array.js
index 0d1d0288a53..0eefa09c5ad 100644
--- a/packages/ember-runtime/lib/mixins/array.js
+++ b/packages/ember-runtime/lib/mixins/array.js
@@ -16,10 +16,7 @@ import {
 import isNone from 'ember-metal/is_none';
 import Enumerable from 'ember-runtime/mixins/enumerable';
 import { map } from 'ember-metal/enumerable_utils';
-import {
-  Mixin,
-  required
-} from 'ember-metal/mixin';
+import { Mixin } from 'ember-metal/mixin';
 import {
   propertyWillChange,
   propertyDidChange
@@ -93,12 +90,14 @@ function arrayObserversHelper(obj, target, opts, operation, notify) {
 export default Mixin.create(Enumerable, {
 
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Your array must support the `length` property. Your replace methods should
     set this property whenever it changes.
 
     @property {Number} length
   */
-  length: required(),
+  length: null,
 
   /**
     Returns the object at the given `index`. If the given `index` is negative
diff --git a/packages/ember-runtime/lib/mixins/comparable.js b/packages/ember-runtime/lib/mixins/comparable.js
index b71d42937e7..7fb98cb0618 100644
--- a/packages/ember-runtime/lib/mixins/comparable.js
+++ b/packages/ember-runtime/lib/mixins/comparable.js
@@ -1,7 +1,4 @@
-import {
-  Mixin,
-  required
-} from "ember-metal/mixin";
+import { Mixin } from "ember-metal/mixin";
 
 /**
 @module ember
@@ -21,6 +18,8 @@ import {
 export default Mixin.create({
 
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Override to return the result of the comparison of the two parameters. The
     compare method should return:
 
@@ -35,5 +34,5 @@ export default Mixin.create({
     @param b {Object} the second object to compare
     @return {Integer} the result of the comparison
   */
-  compare: required(Function)
+  compare: null
 });
diff --git a/packages/ember-runtime/lib/mixins/copyable.js b/packages/ember-runtime/lib/mixins/copyable.js
index ba19bf656b3..e2851f51243 100644
--- a/packages/ember-runtime/lib/mixins/copyable.js
+++ b/packages/ember-runtime/lib/mixins/copyable.js
@@ -5,7 +5,7 @@
 
 
 import { get } from "ember-metal/property_get";
-import { required, Mixin } from "ember-metal/mixin";
+import { Mixin } from "ember-metal/mixin";
 import { Freezable } from "ember-runtime/mixins/freezable";
 import { fmt } from "ember-runtime/system/string";
 import EmberError from 'ember-metal/error';
@@ -28,6 +28,8 @@ import EmberError from 'ember-metal/error';
 */
 export default Mixin.create({
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Override to return a copy of the receiver. Default implementation raises
     an exception.
 
@@ -35,7 +37,7 @@ export default Mixin.create({
     @param {Boolean} deep if `true`, a deep copy of the object should be made
     @return {Object} copy of receiver
   */
-  copy: required(Function),
+  copy: null,
 
   /**
     If the object implements `Ember.Freezable`, then this will return a new
diff --git a/packages/ember-runtime/lib/mixins/enumerable.js b/packages/ember-runtime/lib/mixins/enumerable.js
index cb58efca295..1757be0287b 100644
--- a/packages/ember-runtime/lib/mixins/enumerable.js
+++ b/packages/ember-runtime/lib/mixins/enumerable.js
@@ -12,7 +12,6 @@ import { get } from 'ember-metal/property_get';
 import { set } from 'ember-metal/property_set';
 import {
   Mixin,
-  required,
   aliasMethod
 } from 'ember-metal/mixin';
 import { indexOf } from 'ember-metal/enumerable_utils';
@@ -91,6 +90,8 @@ function iter(key, value) {
 export default Mixin.create({
 
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Implement this method to make your class enumerable.
 
     This method will be called repeatedly during enumeration. The index value
@@ -123,7 +124,7 @@ export default Mixin.create({
     @param {Object} context a context object you can use to maintain state.
     @return {Object} the next object in the iteration or undefined
   */
-  nextObject: required(Function),
+  nextObject: null,
 
   /**
     Helper method returns the first object from a collection. This is usually
diff --git a/packages/ember-runtime/lib/mixins/mutable_array.js b/packages/ember-runtime/lib/mixins/mutable_array.js
index 955446dc600..b3bef8daab0 100644
--- a/packages/ember-runtime/lib/mixins/mutable_array.js
+++ b/packages/ember-runtime/lib/mixins/mutable_array.js
@@ -21,10 +21,7 @@ var EMPTY = [];
 import { get } from "ember-metal/property_get";
 import { isArray } from "ember-metal/utils";
 import EmberError from "ember-metal/error";
-import {
-  Mixin,
-  required
-} from "ember-metal/mixin";
+import { Mixin } from "ember-metal/mixin";
 import EmberArray from "ember-runtime/mixins/array";
 import MutableEnumerable from "ember-runtime/mixins/mutable_enumerable";
 import Enumerable from "ember-runtime/mixins/enumerable";
@@ -65,7 +62,7 @@ export default Mixin.create(EmberArray, MutableEnumerable, {
     @param {Array} objects An array of zero or more objects that should be
       inserted into the array at *idx*
   */
-  replace: required(),
+  replace: null,
 
   /**
     Remove all elements from the array. This is useful if you
diff --git a/packages/ember-runtime/lib/mixins/mutable_enumerable.js b/packages/ember-runtime/lib/mixins/mutable_enumerable.js
index 2043acd6277..c36227ee96c 100644
--- a/packages/ember-runtime/lib/mixins/mutable_enumerable.js
+++ b/packages/ember-runtime/lib/mixins/mutable_enumerable.js
@@ -1,6 +1,6 @@
 import { forEach } from "ember-metal/enumerable_utils";
 import Enumerable from "ember-runtime/mixins/enumerable";
-import {Mixin, required} from "ember-metal/mixin";
+import { Mixin } from "ember-metal/mixin";
 import {beginPropertyChanges, endPropertyChanges} from "ember-metal/property_events";
 
 /**
@@ -63,7 +63,7 @@ export default Mixin.create(Enumerable, {
     @param {Object} object The object to add to the enumerable.
     @return {Object} the passed object
   */
-  addObject: required(Function),
+  addObject: null,
 
   /**
     Adds each object in the passed enumerable to the receiver.
@@ -93,7 +93,7 @@ export default Mixin.create(Enumerable, {
     @param {Object} object The object to remove from the enumerable.
     @return {Object} the passed object
   */
-  removeObject: required(Function),
+  removeObject: null,
 
 
   /**
diff --git a/packages/ember-runtime/lib/system/core_object.js b/packages/ember-runtime/lib/system/core_object.js
index 54493d39abf..5d3e7778c86 100644
--- a/packages/ember-runtime/lib/system/core_object.js
+++ b/packages/ember-runtime/lib/system/core_object.js
@@ -34,7 +34,7 @@ import { sendEvent } from "ember-metal/events";
 import {
   IS_BINDING,
   Mixin,
-  required
+  REQUIRED
 } from "ember-metal/mixin";
 import { indexOf } from "ember-metal/enumerable_utils";
 import EmberError from "ember-metal/error";
@@ -462,9 +462,9 @@ CoreObject.__super__ = null;
 
 var ClassMixinProps = {
 
-  ClassMixin: required(),
+  ClassMixin: REQUIRED,
 
-  PrototypeMixin: required(),
+  PrototypeMixin: REQUIRED,
 
   isClass: true,
 
diff --git a/packages/ember-runtime/tests/suites/copyable.js b/packages/ember-runtime/tests/suites/copyable.js
index d323a1caed2..01ff5539f2d 100644
--- a/packages/ember-runtime/tests/suites/copyable.js
+++ b/packages/ember-runtime/tests/suites/copyable.js
@@ -1,16 +1,19 @@
 import { Suite } from 'ember-runtime/tests/suites/suite';
-import {required} from "ember-metal/mixin";
 
 var CopyableTests = Suite.extend({
 
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Must be able to create a new object for testing.
 
     @returns {Object} object
   */
-  newObject: required(Function),
+  newObject: null,
 
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Compares the two passed in objects.  Returns true if the two objects
     are logically equivalent.
 
@@ -22,7 +25,7 @@ var CopyableTests = Suite.extend({
 
     @returns {Boolean}
   */
-  isEqual: required(Function),
+  isEqual: null,
 
   /**
     Set this to true if you expect the objects you test to be freezable.
diff --git a/packages/ember-runtime/tests/suites/enumerable.js b/packages/ember-runtime/tests/suites/enumerable.js
index ff70956ff66..b2ee7306bd5 100644
--- a/packages/ember-runtime/tests/suites/enumerable.js
+++ b/packages/ember-runtime/tests/suites/enumerable.js
@@ -1,6 +1,5 @@
 import { Suite } from 'ember-runtime/tests/suites/suite';
 import EmberObject from "ember-runtime/system/object";
-import {required} from "ember-metal/mixin";
 import {guidFor, generateGuid} from "ember-metal/utils";
 import {computed} from "ember-metal/computed";
 import {get} from "ember-metal/property_get";
@@ -161,6 +160,8 @@ var ObserverClass = EmberObject.extend({
 
 var EnumerableTests = Suite.extend({
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Implement to return a new enumerable object for testing.  Should accept
     either no parameters, a single number (indicating the desired length of
     the collection) or an array of objects.
@@ -170,7 +171,7 @@ var EnumerableTests = Suite.extend({
 
     @returns {Ember.Enumerable} a new enumerable
   */
-  newObject: required(Function),
+  newObject: null,
 
   /**
     Implement to return a set of new fixture strings that can be applied to
@@ -211,6 +212,8 @@ var EnumerableTests = Suite.extend({
   },
 
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Implement accept an instance of the enumerable and return an array
     containing the objects in the enumerable.  This is used only for testing
     so performance is not important.
@@ -220,7 +223,7 @@ var EnumerableTests = Suite.extend({
 
     @returns {Array} array of items
   */
-  toArray: required(Function),
+  toArray: null,
 
   /**
     Implement this method if your object can mutate internally (even if it
diff --git a/packages/ember-runtime/tests/suites/suite.js b/packages/ember-runtime/tests/suites/suite.js
index 647d03c2542..5a38ff2a1e3 100644
--- a/packages/ember-runtime/tests/suites/suite.js
+++ b/packages/ember-runtime/tests/suites/suite.js
@@ -1,5 +1,4 @@
 import EmberObject from "ember-runtime/system/object";
-import { required } from "ember-metal/mixin";
 import {
   guidFor
 } from "ember-metal/utils";
@@ -20,8 +19,7 @@ import { forEach } from "ember-metal/enumerable_utils";
   ## Defining a Callback API
 
   To define the callback API, just extend this class and add your properties
-  or methods that must be provided.  Use Ember.required() placeholders for
-  any properties that implementers must define themselves.
+  or methods that must be provided.
 
   ## Defining Unit Tests
 
@@ -41,11 +39,13 @@ import { forEach } from "ember-metal/enumerable_utils";
 var Suite = EmberObject.extend({
 
   /**
+    __Required.__ You must implement this method to apply this mixin.
+
     Define a name for these tests - all modules are prefixed w/ it.
 
     @type String
   */
-  name: required(String),
+  name: null,
 
   /**
     Invoked to actually run the test - overridden by mixins
diff --git a/packages/ember-runtime/tests/system/object/create_test.js b/packages/ember-runtime/tests/system/object/create_test.js
index 84c848c1e68..dc8b10353d2 100644
--- a/packages/ember-runtime/tests/system/object/create_test.js
+++ b/packages/ember-runtime/tests/system/object/create_test.js
@@ -3,7 +3,7 @@ import {get} from "ember-metal/property_get";
 import {set} from "ember-metal/property_set";
 import {guidFor} from "ember-metal/utils";
 import {computed} from "ember-metal/computed";
-import {required, Mixin, observer} from "ember-metal/mixin";
+import {Mixin, observer} from "ember-metal/mixin";
 import run from "ember-metal/run_loop";
 import {on} from "ember-metal/events";
 import EmberObject from "ember-runtime/system/object";
@@ -245,7 +245,7 @@ QUnit.test("Triggers init", function() {
 
 QUnit.test('creating an object with required properties', function() {
   var ClassA = EmberObject.extend({
-    foo: required()
+    foo: null // required
   });
 
   var obj = ClassA.createWithMixins({ foo: 'FOO' }); // should not throw