feat($timeout): Add debouncing support

[lrlopez]

This feature allows resetting the timer on an ongoing $timeout promise. The implementation is really simple (see the diff) and fully backwards compatible. Documentation and tests are included. It adds just 98 bytes to the current minified build.

The PR adds a fourth optional argument to $timeout which is the old promise to be reset.

With this feature you can debounce events. In the following example, doRealSave() will only be called 2 seconds after the last model change:

var debounce;
var doRealSave = function() {
   // Save model to DB
}
$scope.save = function() {
   // debounce call for 2 seconds
   debounce = $timeout(doRealSave, 2000, false, debounce);
}

And in the form:

<input type="text" ng-model="name" ng-change="save()">

This PR has been extracted from a bigger one: #2129

[mary-poppins]

Thanks for the PR!

• Contributor signed CLA now or in the past
  • If you just signed, leave a comment here with your real name
• PR's commit messages follow the commit message format

If you need to make changes to your pull request, you can update the commit with git commit --amend.
Then, update the pull request with git push -f.

Thanks again for your help!

[lrlopez]

I've already signed the CLA. The commit message seems to be ok too, just tell me if I need to change anything.

[mgol]

it seems the signature is incorrect as the function timeout definition has the debounce argument in the 4th position.

[lrlopez]

Good catch! Fixed. Thanks!

[lrlopez]

By the way, I forgot to tell that the PR is rebased to a recent master.

[lrlopez]

@petebacondarwin,
Pete, I'm pinging you because you were involved in the related commit. Just a reminder: this PR still hasn't been assigned to anyone nor given a milestone.

[petebacondarwin]

@lrlopez - I'm afraid only regressions and documentation fixes are going to go into 1.2.0 now. We should push to get this in; along with, what I think is a great PR, #2129.

[lrlopez]

Ok. Thanks again!

[lrlopez]

Rebased to latest master (which is the official 1.2.0) and solved a rebase conflict. By the way, the Travis CI build failed due to #4822

[petebacondarwin]

@lrlopez - thanks for hanging in there on these PRs. No that 1.2.0 is out we can start going through these.

[lrlopez]

@petebacondarwin,
Yeah, we can work on them once you are ready...

[lrlopez]

It may be a good time to assign this PR a more concrete milestone...

[lrlopez]

Closed as #2945 has landed