add Function.debounce

[SergioCrisostomo]

New feature suggestion: Function.debounce.
(related: #2694)

(edited to reflect the current simplified version)

This method will return a new function that will be called only once per group of close calls. After a defined delay it will be able to be called again.

Syntax:

var debounceFn = myFn.debounce(delay, leading);

Arguments:

1. delay - (number, optional, defaults to 250ms) The delay to wait before a call to the debounced function can happen again.
2. leading - (boolean, optional, defaults to false) If the call to the debounced function should happen in leading phase of group of calls or after.

Returns:

• (function) A debounce function that will be called only once per group of close function calls.

Examples:

// get scroll position after scroll has stopped
var getNewScrollPosition = function () {
    var scroll = window.getScroll();
    alert(scroll.y);
}
window.addEvent('scroll', getNewScrollPosition.debounce(500));

Comments are welcome.
If you think this is not suitable for Core let me know too.

[DimitarChristoff]

this is useful but I don't think the api is consistent.

I'd go for args of fn, delay, context= to be more like .delay - don't like
a config object.

lodash keeps it simple by just first two

On Friday, June 5, 2015, Sergio Crisostomo [email protected] wrote:

New feature suggestion: Function.debounce.
(related: #2694 #2694)

This method will return a new function that will be called only once per
group of close calls. After a defined delay it will be abble to be called
again.
Syntax:

var debounceFn = myFn.debounce({delay: 100});

Arguments:

1. obj - (mixed) If this argument is a number it will use it as the
   delay timeout of the debounce. If this argument is a object it will
   allow more specific configuration. Leaving the argument empty will fall to
   default values.

Returns:

• (function) A debounce function that will be called only once per
  group of close function calls.

Options:

• delay - The delay after which the debounce function is called.
  Defaults to 250ms.
• early - If true will call the function in the beggining of each
  groups of calls. Defaults to false.
• once - If true will call the function only once per event
  handler. Defaults to false.

Specs fiddle: http://jsfiddle.net/tcuzgeb1/
http://jsfiddle.net/tcuzgeb1/
Simple demo: http://jsfiddle.net/m3v56e7u/
http://jsfiddle.net/m3v56e7u/

Comments are welcome.

If you think this is not suitable for Core let me know too.

You can view, comment on, or merge this pull request online at:

#2720
Commit Summary

• add Function.debounce

File Changes

• M Docs/Types/Function.md
  https://github.com/mootools/mootools-core/pull/2720/files#diff-0
  (50)
• M Source/Types/Function.js
  https://github.com/mootools/mootools-core/pull/2720/files#diff-1
  (25)
• M Specs/Types/Function.js
  https://github.com/mootools/mootools-core/pull/2720/files#diff-2
  (231)

Patch Links:

• https://github.com/mootools/mootools-core/pull/2720.patch
• https://github.com/mootools/mootools-core/pull/2720.diff

—
Reply to this email directly or view it on GitHub
#2720.

Dimitar Christoff

"JavaScript is to JAVA what hamster is to ham"
@D_mitar - https://github.com/DimitarChristoff

[timwienk]

Firstly, we already have this in More for events, called "throttle", which is the main use of this, I'd guess:
https://github.com/mootools/mootools-more/blob/master/Source/Class/Events.Pseudos.js#L125

Regarding the API, I don't think an object as argument is a good idea. I agree with Dimitar, all it'd need is a "delay". I don't quite understand what the "early" or "once" things should do.

[SergioCrisostomo]

nice input @DimitarChristoff and @timwienk !

Note that the configuration object idea is optional, not passing it would fall back to default (fire late & 250ms delay).

@timwienk the debounce idea is different than throttle. The idea is to not fire during a serie of close event calls. Throttle will fire "periodically" during the series of events, debounce can fire just once per series of close event calls.

The ++ side of this implementation is that it allows to have both the function being called at start and end of each series of events. It also allow to be fired once (ie. once and never more).

If that is unnecessary I could just import/adapt (with due permission) the implementation lodash or underscore is using. No configuration object. Basically keeping down to early / late (it could also be called after, or trailing).

^ striked-out text referred to stuff not in the PR anymore

[SergioCrisostomo]

@DimitarChristoff made it more simple now. Thoughts?