Debounce: make it possible to inmediately return the initial value

ember-resources/src/util/debounce.ts

@@ -17,7 +17,7 @@ class TrackedValue<T> {
  *
  * A utility for debouncing high-frequency updates.
  * The returned value will only be updated every `ms` and is
- * initially undefined.
+ * initially undefined (unless you pass `true` as argument for the `initialize` parameter).
  *
  * This can be useful when a user's typing is updating a tracked
  * property and you want to derive data less frequently than on
@@ -63,17 +63,28 @@ class TrackedValue<T> {
  *
  * @param {number} ms delay in milliseconds to wait before updating the returned value
  * @param {() => Value} thunk function that returns the value to debounce
+ * @param {boolean} initialize whether the initial value should be returned inmediately, or undefined should be returned
  */
-export function debounce<Value = unknown>(ms: number, thunk: () => Value) {
+export function debounce<Value = unknown>(ms: number, thunk: () => Value, initialize: boolean = false) {
   let lastValue: Value;
   let timer: number;
   let state = new TrackedValue<Value>();
 
+  /**
+   * Whether the initial value has been returned inmediately or not
+   */
+  let wasInitialized = !initialize;
+
   return resource(({ on }) => {
     lastValue = thunk();
 
-    on.cleanup(() => timer && clearTimeout(timer));
-    timer = setTimeout(() => (state.value = lastValue), ms);
+    if (!wasInitialized) {
+      state.value = lastValue;
+      wasInitialized = true;
+    } else {
+      on.cleanup(() => timer && clearTimeout(timer));
+      timer = setTimeout(() => (state.value = lastValue), ms);
+    }
 
     return state.value;
   });

test-app/tests/utils/debounce/js-test.ts

@@ -14,7 +14,7 @@ module('Utils | debounce | js', function (hooks) {
   module('debounce', function () {
     test('works with @use', async function (assert) {
       class Test {
-        @tracked data = '';
+        @tracked data = 'initial';
 
         @use text = debounce(100, () => this.data);
       }
@@ -23,24 +23,75 @@ module('Utils | debounce | js', function (hooks) {
 
       setOwner(test, this.owner);
 
-      assert.strictEqual(test.text, undefined);
+      assert.strictEqual(test.text, undefined, 'Initial value is undefined');
 
       test.data = 'b';
+
+      // 25ms
+      await someTime();
+      assert.strictEqual(test.text, undefined, 'Initial value is undefined');
+      test.data = 'bo';
+
+      // another 25ms (= ~50ms < 100ms debounce)
+      await someTime();
+      assert.strictEqual(test.text, undefined, 'Initial value is undefined');
+      test.data = 'boo';
+
+      // another 25ms (= ~75ms < 100ms debounce)
+      await someTime();
+      assert.strictEqual(test.text, undefined, 'Initial value is undefined');
+
+      // 110ms > 100ms debounce, value should be set now
+      await someTime(110);
+      assert.strictEqual(test.text, 'boo');
+
+      // change the value again, wait 0ms, value is not updated yet
+      test.data = 'boop';
+      assert.strictEqual(test.text, 'boo');
+
+      // wait at least 100ms, value is now updated
+      await someTime(110);
+      assert.strictEqual(test.text, 'boop');
+    });
+
+    test('initialize = true', async function (assert) {
+      class Test {
+        @tracked data = 'initial';
+
+        @use text = debounce(100, () => this.data, true);
+      }
+
+      let test = new Test();
+
+      setOwner(test, this.owner);
+
+      assert.strictEqual(test.text, 'initial');
+
+      test.data = 'b';
+
+      // 25ms
       await someTime();
-      assert.strictEqual(test.text, undefined);
+      assert.strictEqual(test.text, 'initial');
       test.data = 'bo';
+
+      // another 25ms (= ~50ms < 100ms debounce)
       await someTime();
-      assert.strictEqual(test.text, undefined);
+      assert.strictEqual(test.text, 'initial');
       test.data = 'boo';
+
+      // another 25ms (= ~75ms < 100ms debounce)
       await someTime();
-      assert.strictEqual(test.text, undefined);
+      assert.strictEqual(test.text, 'initial');
 
+      // 110ms > 100ms debounce, value should be set now
       await someTime(110);
       assert.strictEqual(test.text, 'boo');
 
+      // change the value again, wait 0ms, value is not updated yet
       test.data = 'boop';
       assert.strictEqual(test.text, 'boo');
 
+      // wait at least 100ms, value is now updated
       await someTime(110);
       assert.strictEqual(test.text, 'boop');
     });