southbay/lib/base.js

Cocoa-inspired key-value coding, binding, and observing for node

/**
 * Empty function for inheritance implementation
 */
var _ctor_ = function() {};
/**
 * An integer used as `tags` by some exports Objects as well
 * as a unique string for views when needed
 * @type {Number}
 * @private
 */
exports._unique_ = function(prefix) {
	return prefix ? prefix + this._uid_++ : this._uid_++;
};
/**
 * Some exports Objects use a unique integer as a `tag` for identification
 * Views for example. This ensures they are unique
 * @private
 */
exports._uid_ = 0;
/**
 * Inheritance implementation abstraction
 * @param {object} parent
 * @param {object} instance Methods on the new objects prototype, inherited by subclasses
 * @param {object} class Methods on the class object, not inherited
 */
exports.inherits = function(parent, instance, klass) {
	var o;
	if(instance && instance.hasOwnProperty('constructor')) {
	  o = instance.constructor;
	} else {
	  o = function() {parent.apply(this, arguments);};
	}
	_ctor_.prototype = parent.prototype;
	o.prototype = new _ctor_();
	if(instance) Object.extend(o.prototype, instance);
	if(klass) Object.extend(o, klass);
	o.prototype.constructor = o;
	return o;
};
/**
 * The KEYVALUECHANGE ('KVC') constants are used with the Change Dictionary passed to observers on events
 * indicating the type of change made.
 * KVC SETTING indicates that a change did occur
 * @const
 * @type {Number}
 */
exports.SETTING = 1;
/**
 * KVC INSERTION indicates that an object has been inserted into a to-many
 * relationship being observed
 * @const
 * @type {Number}
 */
exports.INSERTION = 2;
/**
 * KVC REMOVAL indicates that an object has been removed from a to-many relationship
 * that is being observed
 * @const
 * @type {Number}
 */
exports.REMOVAL = 3;
/**
 * KVCREPLACEMENT indicates that an object has been replaced in a to-many 
 * relationship that is being observed
 * @const
 * @type {Number}
 */
exports.REPLACEMENT = 4;
/**
 * The KEYVALUEOBSERVING options ('KVO') used in message dispatching. NEW
 * Indicates that a passed exports.Change Dictionary should contain the new value of an obseved key
 * @type {Number}
 */
exports.NEW = 1;
/**
 * Indicates that a passed exports.Change Dictionary should contain the old value of an obseved key
 * @type {Number}
 */
exports.OLD = 2;
/*
 * The Change object (dictionary) is passed as an arg to 
 * observeValueForKeyPath(path).ofObject(foo).change(dict)... recievers
 * NOTE: the properties of the Change dictionary start with an UPPERCASE
 * letter because of the 'new' keyword in Javascript

	 * kvc kind will hold one of the KEYVALUECHANGE values (SETTING, INSERTION, etc.)
	Change.Kind = n;

	 * If the value of Kind = SETTING and NEW was specified when
	 * the observer was registered, new will contain the new value of the key
	 * For INSERTION or REPLACEMENT with NEW the value will be
	 * an array containing the inserted objects, or the ones replacing others, respectively
	Change.New = foo;

	 * If the value of Kind = SETTING and OLD was specified when
	 * the observer was registered, old will contain the old value of the key
	 * For REMOVAL or REPLACEMENT with OLD the value will be
	 * an array containing the objects removed, or the ones having been replaced, respectively
	Change.Old = foo;

	 * if the value of Kind = INSERTION, REMOVAL or 
	 * REPLACEMENT the value of this key is a set of the indexes of the inserted, removed
	 * or replaced objects
	Change.Indexes = [n,m];
*/