/** @module liaison/ObservableArray */
define([
"requirejs-dplugins/has",
"./Observable"
], function (has, Observable) {
"use strict";
/**
* The same argument list of Array, taking the length of the new array or the initial list of array elements.
* @typedef {number|...Anything} module:liaison/ObservableArray~CtorArguments
*/
/**
* An observable array, working as a shim
* of {@link http://wiki.ecmascript.org/doku.php?id=harmony:observe ECMAScript Harmony Array.observe()}.
* @class
* @alias module:liaison/ObservableArray
* @augments module:decor/Observable
* @param {module:decor/ObservableArray~CtorArguments} [args]
* The length of the new array or the initial list of array elements.
*/
var ObservableArray,
augmentedMethods,
defineProperty = Object.defineProperty,
EMPTY_ARRAY = [],
REGEXP_GLOBAL_OBJECT = /\[\s*object\s+global\s*\]/i; // Global object in node.js
(function () {
var observableArrayMarker = "_observableArray";
if (has("object-observe-api")) {
// For useNative case, make ObservableArray an instance of Array instead of an inheritance,
// so that Array.observe() emits splices for .length update
ObservableArray = function (length) {
var self = [];
Observable.call(self);
// Make ObservableArray marker not enumerable, configurable or writable
defineProperty(self, observableArrayMarker, {value: 1});
defineProperty(self, "set", Object.getOwnPropertyDescriptor(Observable.prototype, "set"));
if (typeof length === "number" && arguments.length === 1) {
self.length = length;
} else {
EMPTY_ARRAY.push.apply(self, arguments);
}
return self;
};
} else {
// TODO(asudoh):
// Document that ObservableArray cannot be observed by Observable.observe()
// without "splice" in accept list.
// We need to create large amount of change records to do so,
// when splice happens with large amount of removals/adds
ObservableArray = function (length) {
var beingConstructed = this && !REGEXP_GLOBAL_OBJECT.test(this) && !this.hasOwnProperty("length"),
// If this is called as regular function (instead of constructor), work with a new instance
self = beingConstructed ? [] : new ObservableArray();
if (beingConstructed) {
Observable.call(self);
// Make ObservableArray marker not enumerable, configurable or writable
defineProperty(self, observableArrayMarker, {value: 1});
// Make those methods not enumerable
for (var s in augmentedMethods) {
defineProperty(self, s, {
value: augmentedMethods[s],
configurable: true,
writable: true
});
}
}
if (typeof length === "number" && arguments.length === 1) {
self.length = length;
} else {
EMPTY_ARRAY.push.apply(self, arguments);
}
return self;
};
}
/**
* @method module:liaison/ObservableArray.test
* @param {Array} a The array to test.
* @returns {boolean} true if o is an instance of {@link module:liaison/ObservableArray ObservableArray}.
*/
ObservableArray.test = function (a) {
return a && a[observableArrayMarker];
};
})();
/**
* @method module:liaison/ObservableArray.canObserve
* @param {Array} a The array to test.
* @returns {boolean}
* true if o can be observed with {@link module:liaison/ObservableArray.observe ObservableArray.observe()}.
*/
if (has("object-observe-api")) {
ObservableArray.canObserve = function (a) {
return typeof (a || {}).splice === "function";
};
} else {
ObservableArray.canObserve = ObservableArray.test;
}
if (!has("object-observe-api")) {
(function () {
/**
* Adds and/or removes elements from an array
* and automatically emits a change record compatible
* with {@link http://wiki.ecmascript.org/doku.php?id=harmony:observe ECMAScript Harmony Array.observe()}.
* @param {number} index Index at which to start changing the array.
* @param {number} removeCount [An integer indicating the number of old array elements to remove.
* @param {...Anything} [var_args] The elements to add to the array.
* @return {Array} An array containing the removed elements.
* @memberof module:liaison/ObservableArray#
*/
function splice(index, removeCount) {
/* jshint validthis: true */
if (index < 0) {
index = this.length + index;
}
var oldLength = this.length,
changeRecord = {
index: index,
removed: this.slice(index, index + removeCount),
addedCount: arguments.length - 2
},
result = EMPTY_ARRAY.splice.apply(this, arguments),
lengthRecord = oldLength !== this.length && {
type: "update",
object: this,
name: "length",
oldValue: oldLength
},
notifier = Observable.getNotifier(this);
notifier.performChange("splice", function () {
lengthRecord && notifier.notify(lengthRecord);
return changeRecord;
});
return result;
}
augmentedMethods = /** @lends module:liaison/ObservableArray# */ {
splice: splice,
/**
* Sets a value and automatically emits change record(s)
* compatible with
* {@link http://wiki.ecmascript.org/doku.php?id=harmony:observe ECMAScript Harmony Array.observe()}.
* @param {string} name The property name.
* @param value The property value.
* @returns The value set.
*/
set: function (name, value) {
var args;
if (name === "length") {
args = new Array(Math.max(value - this.length, 0));
args.unshift(Math.min(this.length, value), Math.max(this.length - value, 0));
splice.apply(this, args);
} else if (!isNaN(name) && +name >= this.length) {
args = new Array(name - this.length);
args.push(value);
args.unshift(this.length, 0);
splice.apply(this, args);
} else {
Observable.prototype.set.call(this, name, value);
}
return value;
},
/**
* Removes the last element from an array
* and automatically emits a change record compatible with
* {@link http://wiki.ecmascript.org/doku.php?id=harmony:observe ECMAScript Harmony Array.observe()}.
* @returns The element removed.
*/
pop: function () {
return splice.call(this, -1, 1)[0];
},
/**
* Adds one or more elements to the end of an array
* and automatically emits a change record compatible with
* {@link http://wiki.ecmascript.org/doku.php?id=harmony:observe ECMAScript Harmony Array.observe()}.
* @param {...Anything} var_args The elements to add to the end of the array.
* @returns The new length of the array.
*/
push: function () {
var args = [this.length, 0];
EMPTY_ARRAY.push.apply(args, arguments);
splice.apply(this, args);
return this.length;
},
/**
* Reverses the order of the elements of an array
* and automatically emits a splice type of change record.
* @returns {Array} The array itself.
*/
reverse: function () {
var changeRecord = {
type: "splice",
object: this,
index: 0,
removed: this.slice(),
addedCount: this.length
},
result = EMPTY_ARRAY.reverse.apply(this, arguments);
// Treat this change as a splice instead of updates in each entry
Observable.getNotifier(this).notify(changeRecord);
return result;
},
/**
* Removes the first element from an array
* and automatically emits a change record compatible with
* {@link http://wiki.ecmascript.org/doku.php?id=harmony:observe ECMAScript Harmony Array.observe()}.
* @returns The element removed.
*/
shift: function () {
return splice.call(this, 0, 1)[0];
},
/**
* Sorts the elements of an array in place
* and automatically emits a splice type of change record.
* @returns {Array} The array itself.
*/
sort: function () {
var changeRecord = {
type: "splice",
object: this,
index: 0,
removed: this.slice(),
addedCount: this.length
},
result = EMPTY_ARRAY.sort.apply(this, arguments);
// Treat this change as a splice instead of updates in each entry
Observable.getNotifier(this).notify(changeRecord);
return result;
},
/**
* Adds one or more elements to the front of an array
* and automatically emits a change record compatible with
* {@link http://wiki.ecmascript.org/doku.php?id=harmony:observe ECMAScript Harmony Array.observe()}.
* @param {...Anything} var_args The elements to add to the front of the array.
* @returns The new length of the array.
*/
unshift: function () {
var args = [0, 0];
EMPTY_ARRAY.push.apply(args, arguments);
splice.apply(this, args);
return this.length;
}
};
})();
}
/**
* Observes an ObservableArray for changes.
* Internally calls {@link module:decor/Observable.observe Observable.observe()}
* observing for the following types of change records:
* [
* "add",
* "update",
* "delete",
* "splice"
* ]
* All change records will be converted to "splice" and are sorted by index and merged to smaller number
* of change records.
* @method
* @param {Object} observable The {@link module:liaison/ObservableArray ObservableArray} to observe.
* @param {module:decor/Observable~ChangeCallback} callback The change callback.
* @returns {Handle} The handle to stop observing.
* @throws {TypeError} If the 1st argument is non-object or null.
*/
ObservableArray.observe = (function () {
function intersect(start1, end1, start2, end2) {
return end1 <= start2 ? end1 - start2 : // Adjacent or distant
end2 <= start1 ? end2 - start1 : // Adjacent or distant
Math.min(end1, end2) - Math.max(start1, start2); // Intersected or contained
}
function normalize(record) {
return record.type !== "add" && record.type !== "update" ? record :
{
type: "splice",
object: record.object,
index: +record.name,
removed: [record.oldValue],
addedCount: 1
};
}
function observeSpliceCallback(callback, records) {
var merged = [];
records.forEach(function (incoming) {
incoming = normalize(incoming);
var doneIncoming = false,
indexAdjustment = 0;
for (var i = 0; i < merged.length; ++i) {
var entry;
if (!has("object-observe-api") || !Object.isFrozen(merged[i])) {
entry = merged[i];
entry.index += indexAdjustment;
} else {
entry = merged[i] = {
type: "splice",
object: merged[i].object,
index: merged[i].index + indexAdjustment,
removed: merged[i].removed,
addedCount: merged[i].addedCount
};
}
/* jshint maxlen:150 */
var amount = intersect(entry.index, entry.index + entry.addedCount, incoming.index, incoming.index + incoming.removed.length);
if (amount >= 0) {
// Merge splices
merged.splice(i--, 1);
var removed,
addedCount = entry.addedCount - amount + incoming.addedCount;
if (entry.index < incoming.index) {
removed = incoming.removed.slice(Math.max(amount, 0));
EMPTY_ARRAY.unshift.apply(removed, entry.removed);
} else {
removed = incoming.removed.slice(0, amount > 0 ? entry.index - incoming.index : incoming.length);
EMPTY_ARRAY.push.apply(removed, entry.removed);
// Append happens when second splice's range contains first splice's range
EMPTY_ARRAY.push.apply(removed, incoming.removed.slice(entry.index + entry.addedCount - incoming.index));
}
/* jshint maxlen:120 */
if (removed.length === 0 && addedCount === 0) {
doneIncoming = true;
} else {
incoming = {
type: "splice",
object: entry.object,
index: Math.min(entry.index, incoming.index),
removed: removed,
addedCount: addedCount
};
}
indexAdjustment -= entry.addedCount - entry.removed.length; // entry is subsumed by incoming
} else if (incoming.index < entry.index) {
// Insert the new splice
var adjustment = incoming.addedCount - incoming.removed.length;
entry.index += adjustment;
indexAdjustment += adjustment;
merged.splice(i++, 0, incoming);
doneIncoming = true;
}
}
if (!doneIncoming) {
merged.push(incoming);
}
});
if (merged.length > 0) {
callback(merged);
}
}
if (has("object-observe-api")) {
return function (observableArray, callback) {
Array.observe(observableArray, callback = observeSpliceCallback.bind(observableArray, callback));
return {
deliver: Object.deliverChangeRecords.bind(Object, callback),
remove: Array.unobserve.bind(Array, observableArray, callback)
};
};
} else {
return function (observableArray, callback) {
var h = Object.create(Observable.observe(observableArray,
callback = observeSpliceCallback.bind(observableArray, callback), [
"add",
"update",
"delete",
"splice"
]));
h.deliver = Observable.deliverChangeRecords.bind(Observable, callback);
return h;
};
}
})();
return ObservableArray;
});