Using an AngularJS timeout

Question

I'm new to AngularJS. I'm currently looking at the $timeout service. I understand that it's like a wrapper for the setTimeout function. The documentation says that it provides exception handling. In addition, the documentation says I can cancel and flush a timeout.

Can someone please explain to me when an exception would happen with a timeout? I also don't understand why I need to flush a timeout. I would love an explanation or maybe a jsfiddle. For the life of me, I can't figure out why or even how to use these additional features.

Update: When I attempt to run the stop function, the catch handler associated with myTimer get's thrown. Here is my code:

var myTimer = null; 
$scope.hasStarted = false; 
$scope.start = function () { 
  if ($scope.hasStarted === false) { 
    $scope.isTimerActive = true; 
    myTimer = $timeout(function () { $scope.isTimerActive = false; }, 5000); 
    myTimer.catch(function (err) { 
      alert("An error happened with the clock."); 
    }); 
  }
} 

$scope.stopClock = function () { 
  $timeout.cancel(myTimer); 
  $scope.isClockActive = false; 
}  

Thank you!

Answer 1

$timeout is most awesome indeed.

Exception handling

$timeout returns a promise which can have an error state. For example

 var timePromise = $timeout(function(){ 
    throw new Error('I messed up');
 }, 10000);

 timePromise.catch(function(err){
    // do something with the error
 });

read all about promises here.

---

Cancel

Canceling a $timeout is easy. Instead of using clearTimeout you pass the promise back.

 var timePromise = $timeout(function(){
     // do thing
 }, 23432);

 // wait I didn't mean it!
 $timeout.cancel(timePromise);

---

Flush

Flush is most useful for unit testing, ultimately it fires any outstanding callbacks.

$timeout(function(){
   console.log('$timeout flush');
}, 222);

$timeout(function(){
   console.log('rocks my face');
}, 234232);

$timeout.flush(); // both console logs will fire right away!

or this file:

var itsDone = false;
$timeout(function(){
   itsDone = true;
}, 5000);

with this test:

// old no flush way (async)
it('should be done', function(done){
   expect(isDone).to.be.false;
   setTimeout(function(){
      expect(isDone).to.be.true;
      done();
   }, 5001);
});

// now with flush
it('should be done', function(){
   expect(isDone).to.be.false;
   $timeout.flush();
   expect(isDone).to.be.true;
});