Merge pull request #522 from NullVoxPopuli/debounce

feat: new util: debounce

.gitignore

@@ -3,6 +3,7 @@
 # compiled output
 dist/
 tmp/
+tsconfig.tsbuildinfo
 
 # dependencies
 node_modules/

ember-resources/package.json

@@ -14,6 +14,7 @@
     "./util/map": "./dist/util/map.js",
     "./util/helper": "./dist/util/helper.js",
     "./util/remote-data": "./dist/util/remote-data.js",
+    "./util/debounce": "./dist/util/debounce.js",
     "./util/function": "./dist/util/function.js",
     "./util/function-resource": "./dist/util/function-resource.js",
     "./util/ember-concurrency": "./dist/util/ember-concurrency.js",
@@ -42,6 +43,9 @@
       "util/helper": [
         "dist/util/helper.d.ts"
       ],
+      "util/debounce": [
+        "dist/util/debounce.d.ts"
+      ],
       "util/remote-data": [
         "dist/util/remote-data.d.ts"
       ],

ember-resources/src/util/debounce.ts

@@ -0,0 +1,72 @@
+import { tracked } from '@glimmer/tracking';
+
+import { resource } from './function-resource';
+
+class TrackedValue<T> {
+  @tracked value: T | undefined;
+}
+
+/**
+ * A utility for debouncing high-frequency updates.
+ * The returned value will only be updated every `ms` and is
+ * initially undefined.
+ *
+ * This can be useful when a user's typing is updating a tracked
+ * property and you want to derive data less frequently than on
+ * each keystroke.
+ *
+ * Note that this utility requires the @use decorator
+ * (debounce could be implemented without the need for the @use decorator
+ * but the current implementation is 8 lines)
+ *
+ * @example
+ * ```js
+ *  import Component from '@glimmer/component';
+ *  import { tracked } from '@glimmer/tracking';
+ *  import { debounce } from 'ember-resources/util/debounce';
+ *
+ *  const delay = 100; // ms
+ *
+ *  class Demo extends Component {
+ *    @tracked userInput = '';
+ *
+ *    @use debouncedInput = debounce(delay, () => this.userInput);
+ *  }
+ * ```
+ *
+ * @example
+ * This could be further composed with [[RemoteData]]
+ * ```js
+ *  import Component from '@glimmer/component';
+ *  import { tracked } from '@glimmer/tracking';
+ *  import { debounce } from 'ember-resources/util/debounce';
+ *  import { RemoteData } from 'ember-resources/util/remote-data';
+ *
+ *  const delay = 100; // ms
+ *
+ *  class Demo extends Component {
+ *    @tracked userInput = '';
+ *
+ *    @use debouncedInput = debounce(delay, () => this.userInput);
+ *
+ *    @use search = RemoteData(() => `https://my.domain/search?q=${this.debouncedInput}`);
+ *  }
+ * ```
+ *
+ * @param {number} ms delay in milliseconds to wait before updating the returned value
+ * @param {() => Value} thunk function that returns the value to debounce
+ */
+export function debounce<Value = unknown>(ms: number, thunk: () => Value) {
+  let lastValue: Value;
+  let timer: number;
+  let state = new TrackedValue();
+
+  return resource(({ on }) => {
+    lastValue = thunk();
+
+    on.cleanup(() => timer && clearTimeout(timer));
+    timer = setTimeout(() => (state.value = lastValue), ms);
+
+    return state.value;
+  });
+}

ember-resources/tsconfig.json

@@ -1,10 +1,14 @@
 {
   "compilerOptions": {
+    // So that the test app's type checking doesn't break when we change types
+    "composite": true,
+
     // Path resolution
     "baseUrl": "./src",
     "moduleResolution": "node",
     // We only use tsc for type checking and declaration output
     "emitDeclarationOnly": false,
+    "declarationDir": "./dist",
     "declaration": true,
     "declarationMap": true,
     // Build settings

package.json

@@ -17,7 +17,7 @@
     "@commitlint/cli": "^13.1.0",
     "@commitlint/config-conventional": "^13.1.0",
     "@nullvoxpopuli/eslint-configs": "^2.2.19",
-    "concurrency": "^0.1.4",
+    "concurrently": "^7.2.1",
     "eslint": "^7.32.0",
     "loader.js": "^4.7.0",
     "prettier": "^2.6.2",
@@ -41,7 +41,9 @@
       "mustache": "ember-cli -> testem -> consolidate -> mustache is ancient"
     },
     "peerDependencyRules": {
-      "ignoreMissing": ["msw"],
+      "ignoreMissing": [
+        "msw"
+      ],
       "allowedVersions": {
         "typescript": "*"
       }

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

@@ -0,0 +1,48 @@
+import { tracked } from '@glimmer/tracking';
+import { setOwner } from '@ember/application';
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
+
+import { debounce } from 'ember-resources/util/debounce';
+import { use } from 'ember-resources/util/function-resource';
+
+module('Utils | debounce | js', function (hooks) {
+  setupTest(hooks);
+
+  let someTime = (ms = 25) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  module('debounce', function () {
+    test('works with @use', async function (assert) {
+      class Test {
+        @tracked data = '';
+
+        @use text = debounce(100, () => this.data);
+      }
+
+      let test = new Test();
+
+      setOwner(test, this.owner);
+
+      assert.strictEqual(test.text, undefined);
+
+      test.data = 'b';
+      await someTime();
+      assert.strictEqual(test.text, undefined);
+      test.data = 'bo';
+      await someTime();
+      assert.strictEqual(test.text, undefined);
+      test.data = 'boo';
+      await someTime();
+      assert.strictEqual(test.text, undefined);
+
+      await someTime(110);
+      assert.strictEqual(test.text, 'boo');
+
+      test.data = 'boop';
+      assert.strictEqual(test.text, 'boo');
+
+      await someTime(110);
+      assert.strictEqual(test.text, 'boop');
+    });
+  });
+});

testing/ember-app/tsconfig.json

@@ -37,5 +37,8 @@
     "app/**/*",
     "tests/**/*",
     "types/**/*"
+  ],
+  "references": [
+    { "path": "../../ember-resources" }
   ]
 }