@wordpress/compose 5.15.2 → 5.16.1-next.4d3b314fd5.0

package/src/utils/debounce/test/index.ts

@@ -0,0 +1,367 @@
+/**
+ * Internal dependencies
+ */
+import { debounce } from '../index';
+
+const identity = ( value ) => value;
+
+beforeAll( () => {
+	jest.useRealTimers();
+} );
+
+afterAll( () => {
+	jest.useFakeTimers();
+} );
+
+describe( 'debounce', () => {
+	it( 'should debounce a function', () => {
+		return new Promise( ( done ) => {
+			let callCount = 0;
+
+			const debounced = debounce( function ( value ) {
+				++callCount;
+				return value;
+			}, 32 );
+
+			let results = [
+				debounced( 'a' ),
+				debounced( 'b' ),
+				debounced( 'c' ),
+			];
+			expect( results ).toStrictEqual( [
+				undefined,
+				undefined,
+				undefined,
+			] );
+			expect( callCount ).toBe( 0 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 1 );
+
+				results = [
+					debounced( 'd' ),
+					debounced( 'e' ),
+					debounced( 'f' ),
+				];
+				expect( results ).toStrictEqual( [ 'c', 'c', 'c' ] );
+				expect( callCount ).toBe( 1 );
+			}, 128 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 2 );
+				done( null );
+			}, 256 );
+		} );
+	} );
+
+	it( 'should return the last `func` result on subsequent debounced calls', () => {
+		return new Promise( ( done ) => {
+			const debounced = debounce( identity, 32 );
+			debounced( 'a' );
+
+			setTimeout( function () {
+				expect( debounced( 'b' ) ).not.toBe( 'b' );
+			}, 64 );
+
+			setTimeout( function () {
+				expect( debounced( 'c' ) ).not.toBe( 'c' );
+				done( null );
+			}, 128 );
+		} );
+	} );
+
+	it( 'should not immediately call `func` when `wait` is `0`', () => {
+		return new Promise( ( done ) => {
+			let callCount = 0;
+			const debounced = debounce( function () {
+				++callCount;
+			}, 0 );
+
+			debounced();
+			debounced();
+			expect( callCount ).toBe( 0 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 1 );
+				done( null );
+			}, 5 );
+		} );
+	} );
+
+	it( 'should apply default options', () => {
+		return new Promise( ( done ) => {
+			let callCount = 0;
+			const debounced = debounce(
+				function () {
+					callCount++;
+				},
+				32,
+				{}
+			);
+
+			debounced();
+			expect( callCount ).toBe( 0 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 1 );
+				done( null );
+			}, 64 );
+		} );
+	} );
+
+	it( 'should support a `leading` option', () => {
+		return new Promise( ( done ) => {
+			const callCounts = [ 0, 0 ];
+
+			const withLeading = debounce(
+				function () {
+					callCounts[ 0 ]++;
+				},
+				32,
+				{ leading: true }
+			);
+
+			const withLeadingAndTrailing = debounce(
+				function () {
+					callCounts[ 1 ]++;
+				},
+				32,
+				{ leading: true }
+			);
+
+			withLeading();
+			expect( callCounts[ 0 ] ).toBe( 1 );
+
+			withLeadingAndTrailing();
+			withLeadingAndTrailing();
+			expect( callCounts[ 1 ] ).toBe( 1 );
+
+			setTimeout( function () {
+				expect( callCounts ).toStrictEqual( [ 1, 2 ] );
+
+				withLeading();
+				expect( callCounts[ 0 ] ).toBe( 2 );
+
+				done( null );
+			}, 64 );
+		} );
+	} );
+
+	it( 'should return the last `func` result for subsequent leading debounced calls', () => {
+		return new Promise( ( done ) => {
+			const debounced = debounce( identity, 32, {
+				leading: true,
+				trailing: false,
+			} );
+			let results = [ debounced( 'a' ), debounced( 'b' ) ];
+
+			expect( results ).toStrictEqual( [ 'a', 'a' ] );
+
+			setTimeout( function () {
+				results = [ debounced( 'c' ), debounced( 'd' ) ];
+				expect( results ).toStrictEqual( [ 'c', 'c' ] );
+				done( null );
+			}, 64 );
+		} );
+	} );
+
+	it( 'should support a `trailing` option', () => {
+		return new Promise( ( done ) => {
+			let withCount = 0;
+			let withoutCount = 0;
+
+			const withTrailing = debounce(
+				function () {
+					withCount++;
+				},
+				32,
+				{ trailing: true }
+			);
+
+			const withoutTrailing = debounce(
+				function () {
+					withoutCount++;
+				},
+				32,
+				{ trailing: false }
+			);
+
+			withTrailing();
+			expect( withCount ).toBe( 0 );
+
+			withoutTrailing();
+			expect( withCount ).toBe( 0 );
+
+			setTimeout( function () {
+				expect( withCount ).toBe( 1 );
+				expect( withoutCount ).toBe( 0 );
+				done( null );
+			}, 64 );
+		} );
+	} );
+
+	it( 'should support a `maxWait` option', () => {
+		return new Promise( ( done ) => {
+			let callCount = 0;
+
+			const debounced = debounce(
+				function ( value ) {
+					++callCount;
+					return value;
+				},
+				32,
+				{ maxWait: 64 }
+			);
+
+			debounced( 42 );
+			debounced( 42 );
+			expect( callCount ).toBe( 0 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 1 );
+				debounced( 42 );
+				debounced( 42 );
+				expect( callCount ).toBe( 1 );
+			}, 128 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 2 );
+				done( null );
+			}, 256 );
+		} );
+	} );
+
+	it( 'should support `maxWait` in a tight loop', () => {
+		return new Promise( ( done ) => {
+			const limit = 320;
+			let withCount = 0;
+			let withoutCount = 0;
+
+			const withMaxWait = debounce(
+				function () {
+					withCount++;
+				},
+				64,
+				{ maxWait: 128 }
+			);
+
+			const withoutMaxWait = debounce( function () {
+				withoutCount++;
+			}, 96 );
+
+			const start = Date.now();
+			while ( Date.now() - start < limit ) {
+				withMaxWait();
+				withoutMaxWait();
+			}
+			const actual = [ Boolean( withoutCount ), Boolean( withCount ) ];
+			setTimeout( function () {
+				expect( actual ).toStrictEqual( [ false, true ] );
+				done( null );
+			}, 1 );
+		} );
+	} );
+
+	it( 'should queue a trailing call for subsequent debounced calls after `maxWait`', () => {
+		return new Promise( ( done ) => {
+			let callCount = 0;
+
+			const debounced = debounce(
+				function () {
+					++callCount;
+				},
+				200,
+				{ maxWait: 200 }
+			);
+
+			debounced();
+
+			setTimeout( debounced, 190 );
+			setTimeout( debounced, 200 );
+			setTimeout( debounced, 210 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 2 );
+				done( null );
+			}, 500 );
+		} );
+	} );
+
+	it( 'should cancel when `cancel` is invoked', () => {
+		return new Promise( ( done ) => {
+			let callCount = 0;
+
+			const debounced = debounce( function () {
+				callCount++;
+			}, 32 );
+
+			debounced();
+
+			setTimeout( function () {
+				debounced.cancel();
+				expect( callCount ).toBe( 0 );
+			}, 16 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 0 );
+				done( null );
+			}, 64 );
+		} );
+	} );
+
+	it( 'should cancel `maxDelayed` when `delayed` is invoked', () => {
+		return new Promise( ( done ) => {
+			let callCount = 0;
+
+			const debounced = debounce(
+				function () {
+					callCount++;
+				},
+				32,
+				{ maxWait: 64 }
+			);
+
+			debounced();
+
+			setTimeout( function () {
+				debounced();
+				expect( callCount ).toBe( 1 );
+			}, 128 );
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 2 );
+				done( null );
+			}, 192 );
+		} );
+	} );
+
+	it( 'should invoke the trailing call with the correct arguments and `this` binding', () => {
+		return new Promise( ( done ) => {
+			let actual;
+			let callCount = 0;
+			const object = {};
+
+			const debounced = debounce(
+				function ( ...args ) {
+					actual = [ this ];
+					Array.prototype.push.apply( actual, args );
+					return ++callCount !== 2;
+				},
+				32,
+				{ leading: true, maxWait: 64 }
+			);
+
+			while ( true ) {
+				if ( ! debounced.call( object, 'a' ) ) {
+					break;
+				}
+			}
+
+			setTimeout( function () {
+				expect( callCount ).toBe( 2 );
+				expect( actual ).toStrictEqual( [ object, 'a' ] );
+				done( null );
+			}, 64 );
+		} );
+	} );
+} );

package/src/utils/throttle/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Parts of this source were derived and modified from lodash,
+ * released under the MIT license.
+ *
+ * https://github.com/lodash/lodash
+ *
+ * Copyright JS Foundation and other contributors <https://js.foundation/>
+ *
+ * Based on Underscore.js, copyright Jeremy Ashkenas,
+ * DocumentCloud and Investigative Reporters & Editors <http://underscorejs.org/>
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals. For exact contribution history, see the revision history
+ * available at https://github.com/lodash/lodash
+ *
+ * The following license applies to all parts of this software except as
+ * documented below:
+ *
+ * ====
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * Internal dependencies
+ */
+import { debounce } from '../debounce';
+
+export interface ThrottleOptions {
+	leading?: boolean;
+	trailing?: boolean;
+}
+
+/**
+ * A simplified and properly typed version of lodash's `throttle`, that
+ * always uses timers instead of sometimes using rAF.
+ *
+ * Creates a throttled function that only invokes `func` at most once per
+ * every `wait` milliseconds. The throttled function comes with a `cancel`
+ * method to cancel delayed `func` invocations and a `flush` method to
+ * immediately invoke them. Provide `options` to indicate whether `func`
+ * should be invoked on the leading and/or trailing edge of the `wait`
+ * timeout. The `func` is invoked with the last arguments provided to the
+ * throttled function. Subsequent calls to the throttled function return
+ * the result of the last `func` invocation.
+ *
+ * **Note:** If `leading` and `trailing` options are `true`, `func` is
+ * invoked on the trailing edge of the timeout only if the throttled function
+ * is invoked more than once during the `wait` timeout.
+ *
+ * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
+ * until the next tick, similar to `setTimeout` with a timeout of `0`.
+ *
+ * @param {Function}                   func             The function to throttle.
+ * @param {number}                     wait             The number of milliseconds to throttle invocations to.
+ * @param {Partial< ThrottleOptions >} options          The options object.
+ * @param {boolean}                    options.leading  Specify invoking on the leading edge of the timeout.
+ * @param {boolean}                    options.trailing Specify invoking on the trailing edge of the timeout.
+ * @return Returns the new throttled function.
+ */
+export const throttle = < FunctionT extends ( ...args: unknown[] ) => unknown >(
+	func: FunctionT,
+	wait: number,
+	options?: ThrottleOptions
+) => {
+	let leading = true;
+	let trailing = true;
+
+	if ( options ) {
+		leading = 'leading' in options ? !! options.leading : leading;
+		trailing = 'trailing' in options ? !! options.trailing : trailing;
+	}
+	return debounce( func, wait, {
+		leading,
+		trailing,
+		maxWait: wait,
+	} );
+};

package/src/utils/throttle/test/index.ts

@@ -0,0 +1,256 @@
+/**
+ * Internal dependencies
+ */
+import { throttle } from '../index';
+
+const identity = ( value ) => value;
+
+describe( 'throttle', () => {
+	beforeEach( () => {
+		jest.useFakeTimers();
+	} );
+
+	afterEach( () => {
+		jest.useRealTimers();
+	} );
+
+	it( 'should throttle a function', () => {
+		let callCount = 0;
+		const throttled = throttle( function () {
+			callCount++;
+		}, 32 );
+
+		throttled();
+		throttled();
+		throttled();
+
+		const lastCount = callCount;
+		expect( callCount ).toBeGreaterThan( 0 );
+
+		jest.advanceTimersByTime( 64 );
+
+		expect( callCount ).toBeGreaterThan( lastCount );
+	} );
+
+	it( 'should return the result of the first call on subsequent calls', () => {
+		const throttled = throttle( identity, 32 );
+		let results = [ throttled( 'a' ), throttled( 'b' ) ];
+
+		expect( results ).toStrictEqual( [ 'a', 'a' ] );
+
+		jest.advanceTimersByTime( 64 );
+
+		results = [ throttled( 'c' ), throttled( 'd' ) ];
+		expect( results[ 0 ] ).not.toBe( 'a' );
+		expect( results[ 0 ] ).not.toBe( undefined );
+
+		expect( results[ 1 ] ).not.toBe( 'd' );
+		expect( results[ 1 ] ).not.toBe( undefined );
+	} );
+
+	it( 'should clear timeout when `func` is called', () => {
+		let callCount = 0;
+		let dateCount = 0;
+
+		const globalDateNow = global.Date.now;
+		global.Date.now = function () {
+			return ++dateCount === 5 ? Infinity : +new Date();
+		};
+
+		const throttled = throttle( () => {
+			callCount++;
+		}, 32 );
+
+		throttled();
+		throttled();
+
+		jest.advanceTimersByTime( 64 );
+
+		expect( callCount ).toBe( 2 );
+		global.Date.now = globalDateNow;
+	} );
+
+	it( 'should not trigger a trailing call when invoked once', () => {
+		let callCount = 0;
+		const throttled = throttle( () => {
+			callCount++;
+		}, 32 );
+
+		throttled();
+		expect( callCount ).toBe( 1 );
+
+		jest.advanceTimersByTime( 64 );
+
+		expect( callCount ).toBe( 1 );
+	} );
+
+	[ true, false ].forEach( ( leading ) => {
+		it(
+			'should trigger a call when invoked repeatedly' +
+				( ! leading ? ' and `leading` is `false`' : '' ),
+			() => {
+				let callCount = 0;
+				const limit = 320;
+				const options = leading ? {} : { leading: false };
+				const throttled = throttle(
+					() => {
+						callCount++;
+					},
+					32,
+					options
+				);
+
+				const start = Date.now();
+				while ( Date.now() - start < limit ) {
+					throttled();
+					jest.advanceTimersByTime( 1 );
+				}
+				const actual = callCount;
+
+				jest.advanceTimersByTime( 1 );
+
+				expect( actual ).toBeGreaterThan( 1 );
+			}
+		);
+	} );
+
+	it( 'should trigger a second throttled call as soon as possible', () => {
+		let callCount = 0;
+
+		const throttled = throttle(
+			() => {
+				callCount++;
+			},
+			128,
+			{ leading: false }
+		);
+
+		throttled();
+
+		jest.advanceTimersByTime( 192 );
+
+		expect( callCount ).toBe( 1 );
+		throttled();
+
+		jest.advanceTimersByTime( 64 );
+
+		expect( callCount ).toBe( 1 );
+
+		jest.advanceTimersByTime( 130 );
+
+		expect( callCount ).toBe( 2 );
+	} );
+
+	it( 'should apply default options', () => {
+		let callCount = 0;
+		const throttled = throttle(
+			() => {
+				callCount++;
+			},
+			32,
+			{}
+		);
+
+		throttled();
+		throttled();
+		expect( callCount ).toBe( 1 );
+
+		jest.advanceTimersByTime( 128 );
+
+		expect( callCount ).toBe( 2 );
+	} );
+
+	it( 'should support a `leading` option', () => {
+		const withLeading = throttle( identity, 32, { leading: true } );
+		expect( withLeading( 'a' ) ).toBe( 'a' );
+
+		const withoutLeading = throttle( identity, 32, { leading: false } );
+		expect( withoutLeading( 'a' ) ).toBeUndefined();
+	} );
+
+	it( 'should support a `trailing` option', () => {
+		let withCount = 0;
+		let withoutCount = 0;
+
+		const withTrailing = throttle(
+			( value ) => {
+				withCount++;
+				return value;
+			},
+			64,
+			{ trailing: true }
+		);
+
+		const withoutTrailing = throttle(
+			( value ) => {
+				withoutCount++;
+				return value;
+			},
+			64,
+			{ trailing: false }
+		);
+
+		expect( withTrailing( 'a' ) ).toBe( 'a' );
+		expect( withTrailing( 'b' ) ).toBe( 'a' );
+
+		expect( withoutTrailing( 'a' ) ).toBe( 'a' );
+		expect( withoutTrailing( 'b' ) ).toBe( 'a' );
+
+		jest.advanceTimersByTime( 256 );
+
+		expect( withCount ).toBe( 2 );
+		expect( withoutCount ).toBe( 1 );
+	} );
+
+	it( 'should not update `lastCalled`, at the end of the timeout, when `trailing` is `false`', () => {
+		let callCount = 0;
+
+		const throttled = throttle(
+			function () {
+				callCount++;
+			},
+			64,
+			{ trailing: false }
+		);
+
+		throttled();
+		throttled();
+
+		jest.advanceTimersByTime( 96 );
+
+		throttled();
+		throttled();
+
+		jest.advanceTimersByTime( 96 );
+
+		expect( callCount ).toBeGreaterThan( 1 );
+	} );
+
+	it( 'should work with a system time of `0`', () => {
+		let callCount = 0;
+		let dateCount = 0;
+
+		const globalDateNow = global.Date.now;
+		global.Date.now = function () {
+			return ++dateCount < 4 ? 0 : +new Date();
+		};
+
+		const throttled = throttle( ( value ) => {
+			callCount++;
+			return value;
+		}, 32 );
+
+		const results = [
+			throttled( 'a' ),
+			throttled( 'b' ),
+			throttled( 'c' ),
+		];
+		expect( results ).toStrictEqual( [ 'a', 'a', 'a' ] );
+		expect( callCount ).toBe( 1 );
+
+		jest.advanceTimersByTime( 64 );
+
+		expect( callCount ).toBe( 2 );
+		global.Date.now = globalDateNow;
+	} );
+} );