Added throttling function

CHANGES.md

@@ -7,6 +7,7 @@ New Features:
 
 * [#1761](https://github.com/ckeditor/ckeditor-dev/issues/1761): [Autolink](https://ckeditor.com/cke4/addon/autolink) plugin supports email links.
 * [#1703](https://github.com/ckeditor/ckeditor-dev/issues/1703): Introduced Mentions plugin providing autocompletion feature for usernames.
+* [#1993](https://github.com/ckeditor/ckeditor-dev/issues/1993): Added [`CKEDITOR.tools.throttle`](http://docs.ckeditor.com/ckeditor4/docs/#!/api/CKEDITOR_tools.html#method-throttle) function.
 
 Fixed Issues:
 

core/tools.js

@@ -579,6 +579,90 @@
 			}, milliseconds || 0 );
 		},
 
+		/**
+		 * Throttles `input` events (or any `input` calls)
+		 * and triggers `output` not more often than once per `minInterval`.
+		 *
+		 * After each `input` scheduled `output` will be destroyed and replaced with
+		 * new one. It gives you the opportunity to modify passed parameters into `input` function and get
+		 * different results.
+		 *
+		 *		var buffer = CKEDITOR.tools.throttle( 200, function( message ) {
+		 *			console.log( message );
+		 *		} );
+		 *
+		 *		buffer.input( 'foo!' );
+		 *		// 'foo!' logged immediately.
+		 *		buffer.input( 'buz!' );
+		 *		// Nothing logged.
+		 *		buffer.input( 'bar!' );
+		 *		// Nothing logged.
+		 *		// ... after 200ms a single 'bar!' will be logged.
+		 *
+		 * Can be easily used with events:
+		 *
+		 *		var buffer = CKEDITOR.tools.throttle( 200, function( evt ) {
+		 *			console.log( evt.data.text );
+		 *		} );
+		 *
+		 *		editor.on( 'key', buffer.input );
+		 *		// Note: There is no need to bind buffer as a context.
+		 *
+		 * @since 4.10.0
+		 * @param {Number} minInterval Minimum interval between `output` calls in milliseconds.
+		 * @param {Function} output Function that will be executed as `output`.
+		 * @param {Object} [scopeObj] The object used to scope the listener call (the `this` object).
+		 * @returns {Object}
+		 * @returns {Function} return.input Buffer's input method.
+		 * Accepts parameters which will be directly passed into `output` function.
+		 * @returns {Function} return.reset Resets buffered events — `output` will not be executed
+		 * until next `input` is triggered.
+		 */
+		throttle: function( minInterval, output, scopeObj ) {
+			var scheduled,
+				lastOutput = 0;
+
+			scopeObj = scopeObj || {};
+
+			return {
+				input: input,
+				reset: reset
+			};
+
+			function input() {
+				var args = Array.prototype.slice.call( arguments );
+
+				if ( scheduled ) {
+					clearTimeout( scheduled );
+					scheduled = 0;
+				}
+
+				var diff = ( new Date() ).getTime() - lastOutput;
+
+				// If less than minInterval passed after last check,
+				// schedule next for minInterval after previous one.
+				if ( diff < minInterval ) {
+					scheduled = setTimeout( triggerOutput, minInterval - diff );
+				} else {
+					triggerOutput();
+				}
+
+				function triggerOutput() {
+					lastOutput = ( new Date() ).getTime();
+					scheduled = false;
+
+					output.apply( scopeObj, args );
+				}
+			}
+
+			function reset() {
+				if ( scheduled ) {
+					clearTimeout( scheduled );
+					scheduled = lastOutput = 0;
+				}
+			}
+		},
+
 		/**
 		 * Removes spaces from the start and the end of a string. The following
 		 * characters are removed: space, tab, line break, line feed.

tests/core/tools.js

@@ -628,6 +628,99 @@
 			assert.areSame( 'ABcDeF', c( 'aBcDeF', true ) );
 		},
 
+		'test throttle': function() {
+			var output = 0,
+				foo = 'foo',
+				buz = 'buz',
+				message,
+				buffer = CKEDITOR.tools.throttle( 200, function( arg ) {
+					output++;
+					message = arg;
+				} );
+
+			assert.areSame( 0, output );
+
+			buffer.input( foo );
+
+			assert.areSame( 1, output );
+			assert.areSame( foo, message );
+
+			buffer.input( buz );
+			buffer.input( buz );
+			buffer.input( buz );
+
+			assert.areSame( 1, output );
+			assert.areSame( foo, message );
+
+			wait( function() {
+				assert.areSame( 1, output );
+				assert.areSame( foo, message );
+
+				wait( function() {
+					assert.areSame( 2, output );
+					assert.areSame( buz, message );
+
+					buffer.input( foo );
+
+					assert.areSame( 2, output );
+					assert.areSame( buz, message );
+
+					wait( function() {
+						assert.areSame( 3, output );
+						assert.areSame( foo, message );
+
+						// Check that input triggered after 70ms from previous
+						// buffer.input will trigger output after next 140ms (200-70).
+						wait( function() {
+							buffer.input( buz );
+
+							assert.areSame( 3, output );
+							assert.areSame( foo, message );
+
+							wait( function() {
+								assert.areSame( 4, output );
+								assert.areSame( buz, message );
+							}, 140 );
+						}, 70 );
+					}, 210 );
+				}, 110 );
+			}, 100 );
+		},
+
+		'test throttle.reset': function() {
+			var output = 0,
+				buffer = CKEDITOR.tools.throttle( 100, function() {
+					output++;
+				} );
+
+			assert.areSame( 0, output );
+
+			buffer.input();
+
+			assert.areSame( 1, output );
+
+			buffer.input();
+			buffer.reset();
+
+			wait( function() {
+				assert.areSame( 1, output );
+
+				buffer.input();
+
+				assert.areSame( 2, output );
+			}, 110 );
+		},
+
+		'test throttle contex': function() {
+			var spy = sinon.spy(),
+				ctxObj = {},
+				buffer = CKEDITOR.tools.throttle( 100, spy, ctxObj );
+
+			buffer.input();
+
+			assert.areSame( ctxObj, spy.getCall( 0 ).thisValue, 'callback was executed with the right context' );
+		},
+
 		'test checkIfAnyObjectPropertyMatches': function() {
 			var c = CKEDITOR.tools.checkIfAnyObjectPropertyMatches,
 				r1 = /foo/,

tests/core/tools/manual/throttle.html

@@ -0,0 +1,21 @@
+<style>
+.red {
+	background-color: red;
+}
+.blue {
+	background-color: blue;
+}
+</style>
+
+<button id="btn" class="red" >Click me!</button>
+
+<script>
+	var button = document.getElementById( 'btn' ),
+		buffer = CKEDITOR.tools.throttle( 2000, function ( css ) {
+		button.className = css === 'red' ? 'blue' : 'red';
+	} );
+
+	button.addEventListener( 'click', function() {
+		buffer.input( button.className );
+	} );
+</script>

tests/core/tools/manual/throttle.md

@@ -0,0 +1,15 @@
+@bender-tags: feature, 4.10.0, 1993
+@bender-ui: collapsed
+@bender-ckeditor-plugins: toolbar, wysiwygarea
+
+1. Click button `Click me` five times as fast as possible.
+
+## Expected
+
+Button changes its color:
+1. After first click to blue.
+1. After last click to red.
+
+## Unexpected
+
+Button changes its color in invalid order.