Debounce async (microsoft#4945)

(for microsoft#4641)

Author: ericsnowcurrently

news/3 Code Health/4641.md

@@ -0,0 +1 @@
+Support debouncing decorated async methods.

src/client/common/utils/decorators.ts

@@ -11,20 +11,56 @@ import { InMemoryInterpreterSpecificCache } from './cacheUtils';
 const _debounce = require('lodash/debounce') as typeof import('lodash/debounce');
 
 type VoidFunction = (...any: any[]) => void;
+type AsyncVoidFunction = (...any: any[]) => Promise<void>;
+
 /**
- * Debounces a function execution. Function must return either a void or a promise that resolves to a void.
+ * Combine multiple sequential calls to the decorated function into one.
  * @export
- * @param {number} [wait] Wait time.
+ * @param {number} [wait] Wait time (milliseconds).
  * @returns void
+ *
+ * The point is to ensure that successive calls to the function result
+ * only in a single actual call. Following the most recent call to
+ * the debounced function, debouncing resets after the "wait" interval
+ * has elapsed.
+ *
+ * The decorated function must return either a void or a promise that
+ * resolves to a void.
  */
 export function debounce(wait?: number) {
+ if (isTestExecution()) {
+ // If running tests, lets not debounce (so tests run fast).
+ wait = undefined;
+ // tslint:disable-next-line:no-suspicious-comment
+ // TODO: We should be able to return a noop decorator instead...
+ }
+ return makeDebounceDecorator(wait);
+}
+
+export function makeDebounceDecorator(wait?: number) {
  // tslint:disable-next-line:no-any no-function-expression
- return function (_target: any, _propertyName: string, descriptor: TypedPropertyDescriptor<VoidFunction>) {
+ return function (_target: any, _propertyName: string, descriptor: TypedPropertyDescriptor<VoidFunction> | TypedPropertyDescriptor<AsyncVoidFunction>) {
+ // We could also make use of _debounce() options. For instance,
+ // the following causes the original method to be called
+ // immediately:
+ //
+ // {leading: true, trailing: false}
+ //
+ // The default is:
+ //
+ // {leading: false, trailing: true}
+ //
+ // See https://lodash.com/docs/#debounce.
+ const options = {};
  const originalMethod = descriptor.value!;
- // If running tests, lets not debounce (so tests run fast).
- wait = wait && isTestExecution() ? undefined : wait;
- // tslint:disable-next-line:no-invalid-this no-any
- (descriptor as any).value = _debounce(function (this: any) { return originalMethod.apply(this, arguments as any); }, wait);
+ const debounced = _debounce(
+ function (this: any) {
+ return originalMethod.apply(this, arguments as any);
+ },
+ wait,
+ options
+ );
+ (descriptor as any).value = debounced;
  };
 }
 

src/test/common/utils/decorators.unit.test.ts

@@ -7,7 +7,9 @@ import { expect } from 'chai';
 import { Uri } from 'vscode';
 import { Resource } from '../../../client/common/types';
 import { clearCache } from '../../../client/common/utils/cacheUtils';
-import { cacheResourceSpecificInterpreterData } from '../../../client/common/utils/decorators';
+import {
+ cacheResourceSpecificInterpreterData, makeDebounceDecorator
+} from '../../../client/common/utils/decorators';
 import { sleep } from '../../core';
 
 // tslint:disable:no-any max-func-body-length no-unnecessary-class
@@ -97,6 +99,117 @@ suite('Common Utils - Decorators', () => {
 
  expect(result).to.equal(3);
  expect(cls.invoked).to.equal(true, 'Must be invoked');
+ });
+
+ // debounce()
+ class Base {
+ public created: number;
+ public calls: string[];
+ public timestamps: number[];
+ constructor() {
+ this.created = Date.now();
+ this.calls = [];
+ this.timestamps = [];
+ }
+ protected _addCall(funcname: string, timestamp?: number): void {
+ if (!timestamp) {
+ timestamp = Date.now();
+ }
+ this.calls.push(funcname);
+ this.timestamps.push(timestamp);
+ }
+ }
+ async function waitForCalls(timestamps: number[], count: number, delay = 10, timeout = 1000) {
+ const steps = timeout / delay;
+ for (let i = 0; i < steps; i += 1) {
+ if (timestamps.length >= count) {
+ return;
+ }
+ await sleep(delay);
+ }
+ if (timestamps.length < count) {
+ throw Error(`timed out after ${timeout}ms`);
+ }
+ }
+ test('Debounce: one sync call', async () => {
+ const wait = 100;
+ // tslint:disable-next-line:max-classes-per-file
+ class One extends Base {
+ @makeDebounceDecorator(wait)
+ public run(): void {
+ this._addCall('run');
+ }
+ }
+ const one = new One();
+
+ const start = Date.now();
+ one.run();
+ await waitForCalls(one.timestamps, 1);
+ const delay = one.timestamps[0] - start;
+
+ expect(delay).to.be.at.least(wait);
+ expect(one.calls).to.deep.equal(['run']);
+ expect(one.timestamps).to.have.lengthOf(one.calls.length);
+ });
+ test('Debounce: one async call', async () => {
+ const wait = 100;
+ // tslint:disable-next-line:max-classes-per-file
+ class One extends Base {
+ @makeDebounceDecorator(wait)
+ public async run(): Promise<void> {
+ this._addCall('run');
+ }
+ }
+ const one = new One();
+
+ const start = Date.now();
+ await one.run();
+ await waitForCalls(one.timestamps, 1);
+ const delay = one.timestamps[0] - start;
+
+ expect(delay).to.be.at.least(wait);
+ expect(one.calls).to.deep.equal(['run']);
+ expect(one.timestamps).to.have.lengthOf(one.calls.length);
+ });
+ test('Debounce: multiple calls grouped', async () => {
+ const wait = 100;
+ // tslint:disable-next-line:max-classes-per-file
+ class One extends Base {
+ @makeDebounceDecorator(wait)
+ public run(): void {
+ this._addCall('run');
+ }
+ }
+ const one = new One();
+
+ const start = Date.now();
+ one.run();
+ one.run();
+ one.run();
+ await waitForCalls(one.timestamps, 1);
+ const delay = one.timestamps[0] - start;
+
+ expect(delay).to.be.at.least(wait);
+ expect(one.calls).to.deep.equal(['run']);
+ expect(one.timestamps).to.have.lengthOf(one.calls.length);
+ });
+ test('Debounce: multiple calls spread', async () => {
+ const wait = 100;
+ // tslint:disable-next-line:max-classes-per-file
+ class One extends Base {
+ @makeDebounceDecorator(wait)
+ public run(): void {
+ this._addCall('run');
+ }
+ }
+ const one = new One();
+
+ one.run();
+ await sleep(wait);
+ one.run();
+ await waitForCalls(one.timestamps, 2);
 
+ expect(one.calls).to.deep.equal(['run', 'run']);
+ expect(one.timestamps).to.have.lengthOf(one.calls.length);
  });
 });