fix(orderByFilter): throw error if input is not array-like

nhodges · gkalpak · commit 2a85a634f86c · 2015-10-31T02:52:03.000+02:00
BREAKING CHANGE: Previously, an non array-like input would pass through the orderBy filter unchanged. Now, an error is thrown. This can be worked around by converting an object to an array, either manually or using a filter such as https://github.com/petebacondarwin/angular-toArrayFilter. (`null` and `undefined` still pass through without an error, in order to support asynchronous loading of resources.) Closes angular#11255 Closes angular#11719
diff --git a/docs/content/error/orderBy/notarray.ngdoc b/docs/content/error/orderBy/notarray.ngdoc
@@ -0,0 +1,52 @@
+@ngdoc error
+@name orderBy:notarray
+@fullName Value is not array-like
+@description
+
+This error occurs when {@link ng.orderBy orderBy} is not passed an array-like value:
+```html
+<div ng-repeat="(key, value) in myObj | orderBy:someProp">
+  {{ key }} : {{ value }}
+</div>
+```
+
+`orderBy` must be used with an array-like value so a subset of items can be returned.
+The array can be initialized asynchronously and therefore `null` or `undefined` won't throw this error.
+
+To use `orderBy` to order the properties of an object, you can create your own array based on that object:
+```js
+angular.module('aModule', [])
+  .controller('aController', function($scope) {
+    var myObj = {
+      one: {id: 1, name: 'Some thing'},
+      two: {id: 2, name: 'Another thing'},
+      three: {id: 3, name: 'A third thing'}
+    };
+
+    $scope.arrFromMyObj = Object.keys(myObj).map(function(key) {
+      return myObj[key];
+    });
+  });
+```
+That can be used as:
+```html
+<label>
+  Order by:
+  <select ng-model="orderProp" ng-options="prop for prop in ['id', 'name']"></select>
+</label>
+<div ng-repeat="item in arrFromMyObj | orderBy:orderProp">
+  [{{ item.id }}] {{ item.name }}
+</div>
+```
+
+You could as well convert the object to an array using a filter such as
+[toArrayFilter](https://github.com/petebacondarwin/angular-toArrayFilter):
+```html
+<label>
+  Order by:
+  <select ng-model="orderProp" ng-options="prop for prop in ['id', 'name']"></select>
+</label>
+<div ng-repeat="item in myObj | toArray:false | orderBy:orderProp">
+  [{{ item.id }}] {{ item.name }}
+</div>
+```
diff --git a/src/ng/filter/orderBy.js b/src/ng/filter/orderBy.js
@@ -9,8 +9,9 @@
  * Orders a specified `array` by the `expression` predicate. It is ordered alphabetically
  * for strings and numerically for numbers. Note: if you notice numbers are not being sorted
  * as expected, make sure they are actually being saved as numbers and not strings.
+ * Array-like values (e.g. NodeLists, jQuery objects, TypedArrays, Strings, etc) are also supported.
  *
- * @param {Array} array The array to sort.
+ * @param {Array} array The array (or array-like object) to sort.
  * @param {function(*)|string|Array.<(function(*)|string)>=} expression A predicate to be
  *    used by the comparator to determine the order of elements.
  *
@@ -177,7 +178,10 @@ orderByFilter.$inject = ['$parse'];
 function orderByFilter($parse) {
   return function(array, sortPredicate, reverseOrder) {
 
-    if (!(isArrayLike(array))) return array;
+    if (array == null) return array;
+    if (!isArrayLike(array)) {
+      throw minErr('orderBy')('notarray', 'Expected array but received: {0}', array);
+    }
 
     if (!isArray(sortPredicate)) { sortPredicate = [sortPredicate]; }
     if (sortPredicate.length === 0) { sortPredicate = ['+']; }
diff --git a/test/ng/filter/orderBySpec.js b/test/ng/filter/orderBySpec.js
@@ -8,6 +8,20 @@ describe('Filter: orderBy', function() {
 
 
   describe('(Arrays)', function() {
+    it('should throw an exception if no array-like object is provided', function() {
+      expect(function() { orderBy({}); }).
+        toThrowMinErr('orderBy', 'notarray', 'Expected array but received: {}');
+    });
+
+    it('should not throw an exception if a null or undefined value is provided', function() {
+      expect(orderBy(null)).toEqual(null);
+      expect(orderBy(undefined)).toEqual(undefined);
+    });
+
+    it('should not throw an exception if an array-like object is provided', function() {
+      expect(orderBy('cba')).toEqual(['a', 'b', 'c']);
+    });
+
     it('should return sorted array if predicate is not provided', function() {
       expect(orderBy([2, 1, 3])).toEqual([1, 2, 3]);
 
