/**
@module ember
@submodule ember-runtime
*/
// ..........................................................
// HELPERS
//
import { symbol } from 'ember-utils';
import { peekMeta } from 'ember-metal';
import Ember, { // ES6TODO: Ember.A
get,
computed,
cacheFor,
isNone,
Mixin,
propertyWillChange,
propertyDidChange,
addListener,
removeListener,
sendEvent,
hasListeners,
deprecate,
isFeatureEnabled
} from 'ember-metal';
import Enumerable from './enumerable';
import EachProxy from '../system/each_proxy';
function arrayObserversHelper(obj, target, opts, operation, notify) {
let willChange = (opts && opts.willChange) || 'arrayWillChange';
let didChange = (opts && opts.didChange) || 'arrayDidChange';
let hasObservers = get(obj, 'hasArrayObservers');
if (hasObservers === notify) {
propertyWillChange(obj, 'hasArrayObservers');
}
operation(obj, '@array:before', target, willChange);
operation(obj, '@array:change', target, didChange);
if (hasObservers === notify) {
propertyDidChange(obj, 'hasArrayObservers');
}
return obj;
}
export function addArrayObserver(array, target, opts) {
return arrayObserversHelper(array, target, opts, addListener, false);
}
export function removeArrayObserver(array, target, opts) {
return arrayObserversHelper(array, target, opts, removeListener, true);
}
export function objectAt(content, idx) {
if (content.objectAt) {
return content.objectAt(idx);
}
return content[idx];
}
export function arrayContentWillChange(array, startIdx, removeAmt, addAmt) {
let removing, lim;
// if no args are passed assume everything changes
if (startIdx === undefined) {
startIdx = 0;
removeAmt = addAmt = -1;
} else {
if (removeAmt === undefined) {
removeAmt = -1;
}
if (addAmt === undefined) {
addAmt = -1;
}
}
if (array.__each) {
array.__each.arrayWillChange(array, startIdx, removeAmt, addAmt);
}
sendEvent(array, '@array:before', [array, startIdx, removeAmt, addAmt]);
if (startIdx >= 0 && removeAmt >= 0 && get(array, 'hasEnumerableObservers')) {
removing = [];
lim = startIdx + removeAmt;
for (let idx = startIdx; idx < lim; idx++) {
removing.push(objectAt(array, idx));
}
} else {
removing = removeAmt;
}
array.enumerableContentWillChange(removing, addAmt);
return array;
}
export function arrayContentDidChange(array, startIdx, removeAmt, addAmt) {
// if no args are passed assume everything changes
if (startIdx === undefined) {
startIdx = 0;
removeAmt = addAmt = -1;
} else {
if (removeAmt === undefined) {
removeAmt = -1;
}
if (addAmt === undefined) {
addAmt = -1;
}
}
let adding;
if (startIdx >= 0 && addAmt >= 0 && get(array, 'hasEnumerableObservers')) {
adding = [];
let lim = startIdx + addAmt;
for (let idx = startIdx; idx < lim; idx++) {
adding.push(objectAt(array, idx));
}
} else {
adding = addAmt;
}
array.enumerableContentDidChange(removeAmt, adding);
if (array.__each) {
array.__each.arrayDidChange(array, startIdx, removeAmt, addAmt);
}
sendEvent(array, '@array:change', [array, startIdx, removeAmt, addAmt]);
let meta = peekMeta(array);
let cache = meta && meta.readableCache();
if (cache) {
if (cache.firstObject !== undefined &&
objectAt(array, 0) !== cacheFor.get(cache, 'firstObject')) {
propertyWillChange(array, 'firstObject');
propertyDidChange(array, 'firstObject');
}
if (cache.lastObject !== undefined &&
objectAt(array, get(array, 'length') - 1) !== cacheFor.get(cache, 'lastObject')) {
propertyWillChange(array, 'lastObject');
propertyDidChange(array, 'lastObject');
}
}
return array;
}
const EMBER_ARRAY = symbol('EMBER_ARRAY');
export function isEmberArray(obj) {
return obj && !!obj[EMBER_ARRAY];
}
// ..........................................................
// ARRAY
//
/**
This mixin implements Observer-friendly Array-like behavior. It is not a
concrete implementation, but it can be used up by other classes that want
to appear like arrays.
For example, ArrayProxy is a concrete classes that can
be instantiated to implement array-like behavior. Both of these classes use
the Array Mixin by way of the MutableArray mixin, which allows observable
changes to be made to the underlying array.
Unlike `Ember.Enumerable,` this mixin defines methods specifically for
collections that provide index-ordered access to their contents. When you
are designing code that needs to accept any kind of Array-like object, you
should use these methods instead of Array primitives because these will
properly notify observers of changes to the array.
Although these methods are efficient, they do add a layer of indirection to
your application so it is a good idea to use them only when you need the
flexibility of using both true JavaScript arrays and "virtual" arrays such
as controllers and collections.
You can use the methods defined in this module to access and modify array
contents in a KVO-friendly way. You can also be notified whenever the
membership of an array changes by using `.observes('myArray.[]')`.
To support `Ember.Array` in your own class, you must override two
primitives to use it: `length()` and `objectAt()`.
Note that the Ember.Array mixin also incorporates the `Ember.Enumerable`
mixin. All `Ember.Array`-like objects are also enumerable.
@class Array
@namespace Ember
@uses Ember.Enumerable
@since Ember 0.9.0
@public
*/
const ArrayMixin = Mixin.create(Enumerable, {
[EMBER_ARRAY]: true,
/**
__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
@public
*/
length: null,
/**
Returns the object at the given `index`. If the given `index` is negative
or is greater or equal than the array length, returns `undefined`.
This is one of the primitives you must implement to support `Ember.Array`.
If your object supports retrieving the value of an array item using `get()`
(i.e. `myArray.get(0)`), then you do not need to implement this method
yourself.
```javascript
let arr = ['a', 'b', 'c', 'd'];
arr.objectAt(0); // 'a'
arr.objectAt(3); // 'd'
arr.objectAt(-1); // undefined
arr.objectAt(4); // undefined
arr.objectAt(5); // undefined
```
@method objectAt
@param {Number} idx The index of the item to return.
@return {*} item at index or undefined
@public
*/
objectAt(idx) {
if (idx < 0 || idx >= get(this, 'length')) {
return undefined;
}
return get(this, idx);
},
/**
This returns the objects at the specified indexes, using `objectAt`.
```javascript
let arr = ['a', 'b', 'c', 'd'];
arr.objectsAt([0, 1, 2]); // ['a', 'b', 'c']
arr.objectsAt([2, 3, 4]); // ['c', 'd', undefined]
```
@method objectsAt
@param {Array} indexes An array of indexes of items to return.
@return {Array}
@public
*/
objectsAt(indexes) {
return indexes.map(idx => objectAt(this, idx));
},
// overrides Ember.Enumerable version
nextObject(idx) {
return objectAt(this, idx);
},
/**
This is the handler for the special array content property. If you get
this property, it will return this. If you set this property to a new
array, it will replace the current content.
This property overrides the default property defined in `Ember.Enumerable`.
@property []
@return this
@public
*/
'[]': computed({
get(key) {
return this;
},
set(key, value) {
this.replace(0, get(this, 'length'), value);
return this;
}
}),
firstObject: computed(function() {
return objectAt(this, 0);
}).readOnly(),
lastObject: computed(function() {
return objectAt(this, get(this, 'length') - 1);
}).readOnly(),
// optimized version from Enumerable
contains(obj) {
if (isFeatureEnabled('ember-runtime-enumerable-includes')) {
deprecate(
'`Enumerable#contains` is deprecated, use `Enumerable#includes` instead.',
false,
{ id: 'ember-runtime.enumerable-contains', until: '3.0.0', url: 'http://emberjs.com/deprecations/v2.x#toc_enumerable-contains' }
);
}
return this.indexOf(obj) >= 0;
},
// Add any extra methods to Ember.Array that are native to the built-in Array.
/**
Returns a new array that is a slice of the receiver. This implementation
uses the observable array methods to retrieve the objects for the new
slice.
```javascript
let arr = ['red', 'green', 'blue'];
arr.slice(0); // ['red', 'green', 'blue']
arr.slice(0, 2); // ['red', 'green']
arr.slice(1, 100); // ['green', 'blue']
```
@method slice
@param {Number} beginIndex (Optional) index to begin slicing from.
@param {Number} endIndex (Optional) index to end the slice at (but not included).
@return {Array} New array with specified slice
@public
*/
slice(beginIndex, endIndex) {
let ret = Ember.A();
let length = get(this, 'length');
if (isNone(beginIndex)) {
beginIndex = 0;
}
if (isNone(endIndex) || (endIndex > length)) {
endIndex = length;
}
if (beginIndex < 0) {
beginIndex = length + beginIndex;
}
if (endIndex < 0) {
endIndex = length + endIndex;
}
while (beginIndex < endIndex) {
ret[ret.length] = objectAt(this, beginIndex++);
}
return ret;
},
/**
Returns the index of the given object's first occurrence.
If no `startAt` argument is given, the starting location to
search is 0. If it's negative, will count backward from
the end of the array. Returns -1 if no match is found.
```javascript
let arr = ['a', 'b', 'c', 'd', 'a'];
arr.indexOf('a'); // 0
arr.indexOf('z'); // -1
arr.indexOf('a', 2); // 4
arr.indexOf('a', -1); // 4
arr.indexOf('b', 3); // -1
arr.indexOf('a', 100); // -1
```
@method indexOf
@param {Object} object the item to search for
@param {Number} startAt optional starting location to search, default 0
@return {Number} index or -1 if not found
@public
*/
indexOf(object, startAt) {
let len = get(this, 'length');
if (startAt === undefined) {
startAt = 0;
}
if (startAt < 0) {
startAt += len;
}
for (let idx = startAt; idx < len; idx++) {
if (objectAt(this, idx) === object) {
return idx;
}
}
return -1;
},
/**
Returns the index of the given object's last occurrence.
If no `startAt` argument is given, the search starts from
the last position. If it's negative, will count backward
from the end of the array. Returns -1 if no match is found.
```javascript
let arr = ['a', 'b', 'c', 'd', 'a'];
arr.lastIndexOf('a'); // 4
arr.lastIndexOf('z'); // -1
arr.lastIndexOf('a', 2); // 0
arr.lastIndexOf('a', -1); // 4
arr.lastIndexOf('b', 3); // 1
arr.lastIndexOf('a', 100); // 4
```
@method lastIndexOf
@param {Object} object the item to search for
@param {Number} startAt optional starting location to search, default 0
@return {Number} index or -1 if not found
@public
*/
lastIndexOf(object, startAt) {
let len = get(this, 'length');
if (startAt === undefined || startAt >= len) {
startAt = len - 1;
}
if (startAt < 0) {
startAt += len;
}
for (let idx = startAt; idx >= 0; idx--) {
if (objectAt(this, idx) === object) {
return idx;
}
}
return -1;
},
// ..........................................................
// ARRAY OBSERVERS
//
/**
Adds an array observer to the receiving array. The array observer object
normally must implement two methods:
* `arrayWillChange(observedObj, start, removeCount, addCount)` - This method will be
called just before the array is modified.
* `arrayDidChange(observedObj, start, removeCount, addCount)` - This method will be
called just after the array is modified.
Both callbacks will be passed the observed object, starting index of the
change as well as a count of the items to be removed and added. You can use
these callbacks to optionally inspect the array during the change, clear
caches, or do any other bookkeeping necessary.
In addition to passing a target, you can also include an options hash
which you can use to override the method names that will be invoked on the
target.
@method addArrayObserver
@param {Object} target The observer object.
@param {Object} opts Optional hash of configuration options including
`willChange` and `didChange` option.
@return {Ember.Array} receiver
@public
*/
addArrayObserver(target, opts) {
return addArrayObserver(this, target, opts);
},
/**
Removes an array observer from the object if the observer is current
registered. Calling this method multiple times with the same object will
have no effect.
@method removeArrayObserver
@param {Object} target The object observing the array.
@param {Object} opts Optional hash of configuration options including
`willChange` and `didChange` option.
@return {Ember.Array} receiver
@public
*/
removeArrayObserver(target, opts) {
return removeArrayObserver(this, target, opts);
},
/**
Becomes true whenever the array currently has observers watching changes
on the array.
@property {Boolean} hasArrayObservers
@public
*/
hasArrayObservers: computed(function() {
return hasListeners(this, '@array:change') || hasListeners(this, '@array:before');
}),
/**
If you are implementing an object that supports `Ember.Array`, call this
method just before the array content changes to notify any observers and
invalidate any related properties. Pass the starting index of the change
as well as a delta of the amounts to change.
@method arrayContentWillChange
@param {Number} startIdx The starting index in the array that will change.
@param {Number} removeAmt The number of items that will be removed. If you
pass `null` assumes 0
@param {Number} addAmt The number of items that will be added. If you
pass `null` assumes 0.
@return {Ember.Array} receiver
@public
*/
arrayContentWillChange(startIdx, removeAmt, addAmt) {
return arrayContentWillChange(this, startIdx, removeAmt, addAmt);
},
/**
If you are implementing an object that supports `Ember.Array`, call this
method just after the array content changes to notify any observers and
invalidate any related properties. Pass the starting index of the change
as well as a delta of the amounts to change.
@method arrayContentDidChange
@param {Number} startIdx The starting index in the array that did change.
@param {Number} removeAmt The number of items that were removed. If you
pass `null` assumes 0
@param {Number} addAmt The number of items that were added. If you
pass `null` assumes 0.
@return {Ember.Array} receiver
@public
*/
arrayContentDidChange(startIdx, removeAmt, addAmt) {
return arrayContentDidChange(this, startIdx, removeAmt, addAmt);
},
/**
Returns a special object that can be used to observe individual properties
on the array. Just get an equivalent property on this object and it will
return an enumerable that maps automatically to the named key on the
member objects.
`@each` should only be used in a non-terminal context. Example:
```javascript
myMethod: computed('posts.@each.author', function(){
...
});
```
If you merely want to watch for the array being changed, like an object being
replaced, added or removed, use `[]` instead of `@each`.
```javascript
myMethod: computed('posts.[]', function(){
...
});
```
@property @each
@public
*/
'@each': computed(function() {
// TODO use Symbol or add to meta
if (!this.__each) {
this.__each = new EachProxy(this);
}
return this.__each;
}).volatile().readOnly()
});
if (isFeatureEnabled('ember-runtime-enumerable-includes')) {
ArrayMixin.reopen({
/**
Returns `true` if the passed object can be found in the array.
This method is a Polyfill for ES 2016 Array.includes.
If no `startAt` argument is given, the starting location to
search is 0. If it's negative, searches from the index of
`this.length + startAt` by asc.
```javascript
[1, 2, 3].includes(2); // true
[1, 2, 3].includes(4); // false
[1, 2, 3].includes(3, 2); // true
[1, 2, 3].includes(3, 3); // false
[1, 2, 3].includes(3, -1); // true
[1, 2, 3].includes(1, -1); // false
[1, 2, 3].includes(1, -4); // true
[1, 2, NaN].includes(NaN); // true
```
@method includes
@param {Object} obj The object to search for.
@param {Number} startAt optional starting location to search, default 0
@return {Boolean} `true` if object is found in the array.
@public
*/
includes(obj, startAt) {
let len = get(this, 'length');
if (startAt === undefined) {
startAt = 0;
}
if (startAt < 0) {
startAt += len;
}
for (let idx = startAt; idx < len; idx++) {
let currentObj = objectAt(this, idx);
// SameValueZero comparison (NaN !== NaN)
if (obj === currentObj || (obj !== obj && currentObj !== currentObj)) {
return true;
}
}
return false;
}
});
}
export default ArrayMixin;