A promise system built on top of Backbone.When

backbone.promise.js

define(function(require) {
	'use strict';

	/* MODULE DEPENDENCIES */
	var
	Backbone		= require('backbone'),
	When			= require('lib/backbone.when'),

	var log = console.log;

	/*
	Backbone.Promise
	2014-02-20 by pascal
	
	Leverages Backbone.When to provide a Javascript promise framework.
	
	Any object that is asked to do some work (which might be asynchronous) can return a promise immediately, and then the calling object can call methods on the promise, passing handlers for various scenarios.
	
	usage:
		inside MyModule:
			requestWork: function() {
				var promise = SomeOtherModule.doWork(arguments);
				promise.kept(this.successHandler, this);
				promise.broken(this.errorHandler, this);
				promise.done(this.completeHandler, this);
			}
			
		inside SomeOtherModule:
			var Promise = require('lib/backbone.promise');
			
			doWork: function() {
				var promise = new Promise();
				
				... make an ajax request ...
				... when the ajax completes ...
				promise.keep(ajax_output);
				or promise.break();
				or promise.complete() // will be triggered automatically by keep or break
				
				return promise;
				
			}

	*/
	
	var Promise = function() {
		this.id = _.uniqueId('promise');
		this.timer = null;
	};
	Promise.prototype = {
		keep: function() {
			log('keep', this.id)
			var args = Array.prototype.slice.call(arguments, 0);
			args.unshift('kept');
			this.trigger.apply(this, args);
			this.complete.apply(this, arguments);
		},
		break: function() {
			log('break', this.id)
			var args = Array.prototype.slice.call(arguments, 0);
			args.unshift('broken');
			this.trigger.apply(this, args);
			this.complete.apply(this, arguments);
		},
		complete: function() {
			log('complete', this.id)
			var args = Array.prototype.slice.call(arguments, 0);
			args.unshift('done');
			this.trigger.apply(this, args);
			this._events = {};
		},
		
		kept: function(handler, context) {
			this.when('kept', handler, context);
		},
		broken: function(handler, context) {
			this.when('broken', handler, context);
		},
		done: function(handler, context) {
			this.when('done', handler, context);
		},
		
		// TODO flesh out this idea
		deadline: function(n) {
			n = n || 1000;
			clearTimeout(this.timer);
			this.timer = setTimeout(n, _.bind(this.break, this));
		}
	};
	_.extend(Promise.prototype, Backbone.Events, When.Events);
	// Promises don't get .whenever
	delete Promise.prototype.whenever;
	
	return Promise;

});