initial triggerThen commit

Author: tgriesser

.gitignore

@@ -0,0 +1,5 @@
+raw
+*.sw?
+.DS_Store
+npm-debug.log
+node_modules

.npmignore

@@ -0,0 +1 @@
+test/

LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Tim Griesser
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package.json

@@ -0,0 +1,31 @@
+{
+  "name": "trigger-then",
+  "main": "trigger-then.js",
+  "author": {
+    "name": "Tim Griesser"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tgriesser/trigger-then"
+  },
+  "description": "Adding 'promise' triggers to Backbone events",
+  "version": "0.1.0",
+  "license": "MIT",
+  "readmeFilename": "README.md",
+  "scripts": {
+    "test": "mocha -R spec test/index.js"
+  },
+  "devDependencies": {
+    "backbone": "1.0.x",
+    "mocha": "1.7.x",
+    "when": "2.1.x",
+    "q": "0.9.x"
+  },
+  "dependencies": {},
+  "keywords": [
+    "backbone",
+    "deferred",
+    "promise",
+    "events"
+  ]
+}

test/index.js

@@ -0,0 +1,101 @@
+var assert = require('assert');
+var equal = assert.equal;
+var deepEqual = assert.deepEqual;
+
+var triggerThen = require('../trigger-then');
+var Backbone = require('backbone');
+var Q = require('q');
+var When = require('when');
+
+describe('triggerThen', function(value) {
+
+  it('should take two arguments, the Backbone instance and the promise lib', function() {
+    triggerThen(Backbone, Q.all);
+    equal(typeof Backbone.Events.triggerThen === 'function', true);
+  });
+
+  it('should swap out the promise lib if called more than once', function() {
+    triggerThen(Backbone, When.all);
+  });
+
+  it('should trigger events, returning a promise the event', function(ok) {
+    var model = new (Backbone.Model.extend({
+      initialize: function() {
+        this.on('fireEvent', this.regularFn, this);
+        this.on('fireEvent', this.dfdFn, this);
+        this.on('errorEvent', this.errorFn, this);
+      },
+      regularFn: function(time) {
+        return time;
+      },
+      dfdFn: function(time) {
+        var dfd = Q.defer();
+        setTimeout(function() {
+          dfd.resolve('This is a deferred object');
+        }, time);
+        return dfd.promise;
+      },
+      errorFn: function(time) {
+        var dfd = When.defer();
+        setTimeout(function() {
+          dfd.reject(new Error('This is a failed promise'));
+        }, time);
+        return dfd.promise;
+      }
+    }))();
+
+    model.trigger('fireEvent', 50);
+    model.triggerThen('fireEvent', 50).then(function(resp) {
+      equal(resp[0], 50);
+      equal(resp[1], 'This is a deferred object');
+    })
+    .then(function() {
+      return model.trigger('fireEvent errorEvent', 10);
+    })
+    .then(function() {
+      return model.triggerThen('fireEvent errorEvent', 10);
+    })
+    .then(null, function(e) {
+      equal(e.toString(), 'Error: This is a failed promise');
+      ok();
+    });
+  });
+
+  it('should resolve properly if there is no name', function(ok) {
+    Backbone.triggerThen().then(function() {
+      return Backbone.triggerThen('noname');
+    })
+    .then(function() {
+      ok();
+    });
+  });
+
+  it('should handle "all" properly', function(ok) {
+    var model = new (Backbone.Model.extend({
+      initialize: function() {
+        this.on('fireEvent', this.regularFn, this);
+        this.on('all', this.dfdFn, this);
+      },
+      regularFn: function(time) {
+        return time;
+      },
+      dfdFn: function(time) {
+        var dfd = Q.defer();
+        setTimeout(function() {
+          dfd.resolve('This is a deferred object');
+        }, time);
+        return dfd.promise;
+      }
+    }))();
+
+    model.trigger('fireEvent', 10);
+    model.triggerThen('fireEvent', 10).then(function(resp) {
+      equal(resp[0], 10);
+      equal(resp[1], 'This is a deferred object');
+      ok();
+    });
+
+  });
+
+
+});

trigger-then.js

@@ -0,0 +1,63 @@
+// Exports the function which mixes `triggerThen`
+// into the specified `Backbone` copy's `Events` object,
+// using the promise-lib's "all" implementation provided
+// in the second argument.
+(function(mixinFn) {
+  if (typeof exports === "object") {
+    module.exports = mixinFn;
+  } else if (typeof define === "function" && define.amd) {
+    define('trigger-then', [], function() { return mixinFn; });
+  } else {
+    this.triggerThen = mixinFn;
+  }
+}).call(this, function(Backbone, All) {
+
+  var Events = Backbone.Events;
+  var push   = Array.prototype.push;
+  var slice  = Array.prototype.slice;
+  var eventSplitter = /\s+/;
+
+  // A difficult-to-believe, but optimized internal dispatch function for
+  // triggering events. Tries to keep the usual cases speedy (most internal
+  // Backbone events have 3 arguments). Returns an array containing all of the
+  // event trigger calls, in case any return deferreds.
+  var triggerEvents = function(events, args) {
+    var ev, i = -1, l = events.length, a1 = args[0], a2 = args[1], a3 = args[2];
+    var dfds = [];
+    switch (args.length) {
+      case 0: while (++i < l) dfds.push((ev = events[i]).callback.call(ev.ctx)); return dfds;
+      case 1: while (++i < l) dfds.push((ev = events[i]).callback.call(ev.ctx, a1)); return dfds;
+      case 2: while (++i < l) dfds.push((ev = events[i]).callback.call(ev.ctx, a1, a2)); return dfds;
+      case 3: while (++i < l) dfds.push((ev = events[i]).callback.call(ev.ctx, a1, a2, a3)); return dfds;
+      default: while (++i < l) dfds.push((ev = events[i]).callback.apply(ev.ctx, args)); return dfds;
+    }
+  };
+
+  // Fires events as `trigger` normally would, but assumes that some of the `return`
+  // values from the events may be promises, and and returns a promise when all of the
+  // events are resolved.
+  var triggerThen = Events.triggerThen = function(name) {
+    if (!this._events) return All([]);
+    var names = [name];
+    var args  = slice.call(arguments, 1);
+    var dfds  = [];
+    var events = [];
+    if (eventSplitter.test(names[0])) names = names[0].split(eventSplitter);
+    for (var i = 0, l = names.length; i < l; i++) {
+      push.apply(events, this._events[names[i]]);
+    }
+    var allEvents = this._events.all;
+    if (events) push.apply(dfds, triggerEvents(events, args));
+    if (allEvents) push.apply(dfds, triggerEvents(allEvents, arguments));
+    return All(dfds);
+  };
+
+  // Mixin `triggerThen` to the appropriate objects and prototypes.
+  Backbone.triggerThen = triggerThen;
+
+  var objs = ['Model', 'Collection', 'Router', 'View', 'History'];
+
+  for (var i=0, l=objs.length; i<l; i++) {
+    Backbone[objs[i]].prototype.triggerThen = triggerThen;
+  }
+});