mixins/signalable.js

"use strict";
/**
 * @fileOverview Add the ability to fire signals on your objects. Signals are events, but hard coded into the object
 * and don't rely on strings like other events and `eventables`
 * @module mixins/signalable
 * @requires base
 * @requires signals
 * @requires base/logger
 */

var Base = require( "../base" );
var signals = require( 'signals' );
var format = require( "../strings/format" );
var sys = require( "lodash" );

/**
 * @typedef
 * @property {boolean=} memorize If Signal should keep record of previously dispatched parameters and automatically execute listener. Defaults to `false`
 * @property {array=} params Default parameters passed to listener during `Signal.raise`/`Signal.fire`/`Signal.trigger` and SignalBinding.execute. (curried parameters). Defaults to `null`
 * @property {object=} context When provided the signal will be raised in the context of this object. Defaults to `this` - the signal host
 * @name SignalOptions
 * @memberOf module:mixins/signalable
 * @example
 *
 *  signals:{
 *      opened: null,
 *      twisted: { memorize:true },
 *      applied: { memorize: false, params:[one, two] }
 *  }
 *
 *  // Setting the context initially can be a hassle, so this also supports a function that returns a hash
 *
 *  signals: function(){
 *      return {
 *      opened: null,
 *      twisted: { memorize:true },
 *      applied: { memorize: false, params:[one, two] },
 *      reversed: {context: someOtherRuntimeObject}
 *      };
 *  }
 *
 */

/**
 * @classDesc A signal that can be raised on an object. When you deploy the `Signalable` mixin, it
 * creates instances of these for you.
 *
 * @constructor
 * @param {?object} host If hosted, you can identify the host here.
 * @param {?string} name The name of the signal
 * @type module:mixins/signalable.SignalOptions
 */
var Signal = Base.compose( [Base, signals.Signal], /** @lends module:mixins/signalable~Signal# */{
	declaredClass : "mixins/Signal",

	constructor : function ( host, name, options ) {
		options = options || {};
		this.memorize = options.memorize === true;
		this.host = host;
		this.trigger = this.fire = this.raise = this.dispatch;
		this.name = name || sys.uniqueId( "signal" );
		this.params = options.params;
		this.defaultContext = options.context;
	},

	/**
	 * Cleans up
	 * @private
	 */
	destroy : function () {
		this.removeAll();
		this.dispose();
		this.host = null;
	},

	/**
	 * Ties a listener to a signal.
	 * @param {function} listener The function to call when the signal is raised
	 * @param {?object} listenerContext A context to set for the listener. The event host may set a default for this value, but you may override that here.
	 * @param {?number} priority A priority for the listener.
	 * @returns {SignalBinding}
	 */
	on       : function ( listener, listenerContext, priority ) {
		if ( sys.isNumber( listenerContext ) ) {
			priority = listenerContext;
			listenerContext = null;
		}
		listenerContext = listenerContext || this.defaultContext || this.host;
		var binding = this.add( listener, listenerContext, priority );
		if ( this.options.params ) {
			binding.params = this.arams;
		}
		return binding;
	},
	/**
	 * Ties a listener to for a signal for one execution.
	 * @param {function} listener The function to call when the signal is raised
	 * @param {?object} listenerContext A context to set for the listener. The event host may set a default for this value, but you may override that here.
	 * @param {?number} priority A priority for the listener.
	 * @returns {SignalBinding}
	 */
	once     : function ( listener, listenerContext, priority ) {
		if ( sys.isNumber( listenerContext ) ) {
			priority = listenerContext;
			listenerContext = null;
		}
		listenerContext = listenerContext || this.defaultContext || this.host;
		var binding = this.addOnce( listener, listenerContext, priority );
		if ( this.options.params ) {
			binding.params = this.params;
		}
		return binding;
	},
	/**
	 * Unbinds a listener to a signal.
	 * @param {function} listener The function to unbind
	 * @param {?object} listenerContext The context that was bound
	 * @returns {function}
	 */
	off      : function ( listener, listenerContext ) {
		listenerContext = listenerContext || this.host;
		return this.remove( listener, listenerContext );
	},
	/**
	 * Check if listener was attached to Signal.
	 * @param {function} listener The function to check
	 * @param {?object} listenerContext The context that was bound
	 * @returns {boolean}
	 */
	has      : function ( listener, listenerContext ) {
		listenerContext = listenerContext || this.defaultContext || this.host;
		return this.remove( listener, listenerContext );
	},
	/**
	 * Strings!
	 */
	toString : function () {
		return  format( "{0}\nname:{1}\nlisteners:{2}",
			this.declaredClass,
			this.name,
			this.getNumListeners()
		);
	}

} );

/**
 * @classDesc Make an object capable of handling a signal. Or many signals.
 * @exports mixins/signalable
 * @mixin
 * @extends base
 */
var Signalable = Base.compose( [Base], /** @lends mixins/signalable# */{
	declaredClass : "mixins/Signalable",

	constructor    : function () {
		this.autoLoadSignals = this.autoLoadSignals || true;
		if ( this.autoLoadSignals === true ) {
			this._loadSignals();
		}
	},
	/**
	 * When you make a change to the signals hash after loading, then you can make it reload
	 */
	refreshSignals : function () {
		this._loadSignals();
	},

	/**
	 * Interprets the `signals` hash and instantiates it
	 * @private
	 */
	_loadSignals : function () {
		var signals = this.signals || {};
		sys.each( signals, function ( value, key ) {
			var opts = {};
			if ( !sys.isEmpty( value ) ) {
				if ( sys.isBoolean( value.memorize ) ) {
					opts.memorize = value.memorize;
				}
				if ( sys.isBoolean( value.params ) ) {
					opts.params = value.params;
				}
				if ( !sys.isEmpty( value.context ) ) {
					opts.context = value.context;
				}
			}
			this._addSignal( key, opts );
		} );
	},
	/**
	 * Creates a single signal
	 * @param {string} name The name of the signal
	 * @param {module:mixins/signalable~SignalOptions} options The options the signal expects
	 * @private
	 */
	_addSignal   : function ( name, options ) {
		if ( sys.isEmpty( this[name] ) ) {
			this[name] = new Signal( this, name, options );
		}
	},

	/**
	 * Add a signal to an object. If any members of the hash already exist in `this.signals`, they will be overwritten.
	 * @param {module:mixins/signalable.SignalOptions} signals
	 * @private
	 */
	_addSignals : function ( signals ) {
		signals = signals || {};
		if ( this.options ) {signals = sys.extend( {}, sys.result( this, 'signals' ), signals );}
		this.signals = signals;
	},
	/**
	 * Clean up
	 * @private
	 */
	destroy     : function () {
		sys.each( sys.keys( this ), function ( key ) {
			if ( this[key] instanceof Signal || this[key] instanceof signals.Signal ) {
				this[key].close();
			}
		}, this );
	}
} );

module.exports = Signalable;
alable.Signal = Signal;
Signalable.mixin = Base.mixin;

/**
 * When true, the class will load the `signals` hash and create the signal definitions during construction
 * @memberOf mixins/signalable#
 * @name autoLoadSignals
 * @type boolean
 */


/**
 * A hash of signals to create automatically. Each definition consists of a name for the signal as the key
 * and then a hash of options (nullable) for each signal
 * @type {hash|function():hash}
 * @memberOf mixins/signalable#
 * @name signals
 * @type module:mixins/signalable.SignalOptions
 */