feat($timeout): add $timeout service that supersedes $defer

$timeout has a better name ($defer got often confused with something related to $q) and
is actually promise based with cancelation support.

With this commit the $defer service is deprecated and will be removed before 1.0.

Closes #704, #532

3 files changed, 164 insertions, 0 deletions

diff --git a/test/ng/deferSpec.js b/test/ng/deferSpec.js
index 48c9e912..2e31aadb 100644
--- a/test/ng/deferSpec.js
+++ b/test/ng/deferSpec.js
@@ -5,6 +5,7 @@ describe('$defer', function() {
     $provide.factory('$exceptionHandler', function(){
       return jasmine.createSpy('$exceptionHandler');
     });
+    $provide.value('$log', {warn: noop});
   }));
 
 
diff --git a/test/ng/timeoutSpec.js b/test/ng/timeoutSpec.js
new file mode 100644
index 00000000..19db1227
--- /dev/null
+++ b/test/ng/timeoutSpec.js
@@ -0,0 +1,146 @@
+'use strict';
+
+describe('$timeout', function() {
+
+  beforeEach(module(provideLog));
+
+
+  it('should delegate functions to $browser.defer', inject(function($timeout, $browser) {
+    var counter = 0;
+    $timeout(function() { counter++; });
+
+    expect(counter).toBe(0);
+
+    $browser.defer.flush();
+    expect(counter).toBe(1);
+
+    expect(function() {$browser.defer.flush();}).toThrow('No deferred tasks to be flushed');
+    expect(counter).toBe(1);
+  }));
+
+
+  it('should call $apply after each callback is executed', inject(function($timeout, $rootScope) {
+    var applySpy = spyOn($rootScope, '$apply').andCallThrough();
+
+    $timeout(function() {});
+    expect(applySpy).not.toHaveBeenCalled();
+
+    $timeout.flush();
+    expect(applySpy).toHaveBeenCalledOnce();
+
+    applySpy.reset();
+
+    $timeout(function() {});
+    $timeout(function() {});
+    $timeout.flush();
+    expect(applySpy.callCount).toBe(2);
+  }));
+
+
+  it('should NOT call $apply if skipApply is set to true', inject(function($timeout, $rootScope) {
+    var applySpy = spyOn($rootScope, '$apply').andCallThrough();
+
+    $timeout(function() {}, 12, false);
+    expect(applySpy).not.toHaveBeenCalled();
+
+    $timeout.flush();
+    expect(applySpy).not.toHaveBeenCalled();
+  }));
+
+
+  it('should allow you to specify the delay time', inject(function($timeout, $browser) {
+    var defer = spyOn($browser, 'defer');
+    $timeout(noop, 123);
+    expect(defer.callCount).toEqual(1);
+    expect(defer.mostRecentCall.args[1]).toEqual(123);
+  }));
+
+
+  it('should return a promise which will be resolved with return value of the timeout callback',
+      inject(function($timeout, log) {
+    var promise = $timeout(function() { log('timeout'); return 'buba'; });
+
+    promise.then(function(value) { log('promise success: ' + value); }, log.fn('promise error'));
+    expect(log).toEqual([]);
+
+    $timeout.flush();
+    expect(log).toEqual(['timeout', 'promise success: buba']);
+  }));
+
+
+  describe('exception handling', function() {
+
+    beforeEach(module(function($exceptionHandlerProvider) {
+      $exceptionHandlerProvider.mode('log');
+    }));
+
+
+    it('should delegate exception to the $exceptionHandler service', inject(
+        function($timeout, $exceptionHandler) {
+      $timeout(function() {throw "Test Error";});
+      expect($exceptionHandler.errors).toEqual([]);
+
+      $timeout.flush();
+      expect($exceptionHandler.errors).toEqual(["Test Error"]);
+    }));
+
+
+    it('should call $apply even if an exception is thrown in callback', inject(
+        function($timeout, $rootScope) {
+      var applySpy = spyOn($rootScope, '$apply').andCallThrough();
+
+      $timeout(function() {throw "Test Error";});
+      expect(applySpy).not.toHaveBeenCalled();
+
+      $timeout.flush();
+      expect(applySpy).toHaveBeenCalled();
+    }));
+
+
+    it('should reject the timeout promise when an exception is thrown in the timeout callback',
+        inject(function($timeout, log) {
+      var promise = $timeout(function() { throw "Some Error"; });
+
+      promise.then(log.fn('success'), function(reason) { log('error: ' + reason); });
+      $timeout.flush();
+
+      expect(log).toEqual('error: Some Error');
+    }));
+  });
+
+
+  describe('cancel', function() {
+    it('should cancel tasks', inject(function($timeout) {
+      var task1 = jasmine.createSpy('task1'),
+          task2 = jasmine.createSpy('task2'),
+          task3 = jasmine.createSpy('task3'),
+          promise1, promise3;
+
+      promise1 = $timeout(task1);
+      $timeout(task2);
+      promise3 = $timeout(task3, 333);
+
+      $timeout.cancel(promise3);
+      $timeout.cancel(promise1);
+      $timeout.flush();
+
+      expect(task1).not.toHaveBeenCalled();
+      expect(task2).toHaveBeenCalledOnce();
+      expect(task3).not.toHaveBeenCalled();
+    }));
+
+
+    it('should return true if a task was successfully canceled', inject(function($timeout) {
+      var task1 = jasmine.createSpy('task1'),
+          task2 = jasmine.createSpy('task2'),
+          promise1, promise2;
+
+      promise1 = $timeout(task1);
+      $timeout.flush();
+      promise2 = $timeout(task2);
+
+      expect($timeout.cancel(promise1)).toBe(false);
+      expect($timeout.cancel(promise2)).toBe(true);
+    }));
+  });
+});
diff --git a/test/ngMock/angular-mocksSpec.js b/test/ngMock/angular-mocksSpec.js
index 469df91e..62190072 100644
--- a/test/ngMock/angular-mocksSpec.js
+++ b/test/ngMock/angular-mocksSpec.js
@@ -313,6 +313,23 @@ describe('ngMock', function() {
   });
 
 
+  describe('$timeout', function() {
+    it('should expose flush method that will flush the pending queue of tasks', inject(
+        function($timeout) {
+      var logger = [],
+          logFn = function(msg) { return function() { logger.push(msg) }};
+
+      $timeout(logFn('t1'));
+      $timeout(logFn('t2'), 200);
+      $timeout(logFn('t3'));
+      expect(logger).toEqual([]);
+
+      $timeout.flush();
+      expect(logger).toEqual(['t1', 't3', 't2']);
+    }));
+  });
+
+
   describe('angular.mock.dump', function(){
     var d = angular.mock.dump;