feat: new util -- keepLatest

A utility decorator for smoothing out changes in upstream data between
refreshes / reload.

when using [[RemoteData]] (or some other promise-based "eventually a value" resource),
the value returned from the API is what's useful to see to users. But if the URL
changes, the remote request will start anew, and isLoading becomes true, and the value
is falsey until the request finishes. This can result in some flicker
until the new request finishes.

To smooth that out, we can use [[keepLatest]]

ember-resources/package.json

@@ -14,6 +14,7 @@
     "./core/function-based": "./dist/core/function-based/index.js",
     "./util": "./dist/util/index.js",
     "./util/cell": "./dist/util/cell.js",
+    "./util/keep-latest": "./dist/util/keep-latest.js",
     "./util/map": "./dist/util/map.js",
     "./util/helper": "./dist/util/helper.js",
     "./util/remote-data": "./dist/util/remote-data.js",
@@ -37,6 +38,9 @@
       "util/cell": [
         "dist/util/cell.d.ts"
       ],
+      "util/keep-latest": [
+        "dist/util/keep-latest.d.ts"
+      ],
       "util/function": [
         "dist/util/function.d.ts"
       ],

ember-resources/src/util/keep-latest.ts

@@ -0,0 +1,78 @@
+import { resource, resourceFactory } from '../core/function-based';
+
+const isEmpty = (x: undefined | unknown | unknown[]) => {
+  if (Array.isArray(x)) {
+    return x.length === 0;
+  }
+
+  if (typeof x === 'object') {
+    if (x === null) return true;
+
+    return x || Object.keys(x).length > 0;
+  }
+
+  return Boolean(x);
+};
+
+interface Options<T = unknown> {
+  /**
+   * A function who's return value, when true, will
+   * keep the latest truthy value as the "return value"
+   * (as determined by the `value` option's return value)
+   */
+  until: () => boolean;
+
+  /**
+   * A function who's return value will be used as the value
+   * of this resource.
+   */
+  value: () => T;
+}
+
+/**
+ * A utility decorator for smoothing out changes in upstream data between
+ * refreshes / reload.
+ *
+ * @example
+ * when using [[RemoteData]] (or some other promise-based "eventually a value" resource),
+ * the value returned from the API is what's useful to see to users. But if the URL
+ * changes, the remote request will start anew, and isLoading becomes true, and the value is falsey until the request finishes. This can result in some flicker
+ * until the new request finishes.
+ *
+ * To smooth that out, we can use [[keepLatest]]
+ *
+ * ```js
+ *  import { RemoteData } from 'ember-resources/util/remote-data';
+ *  import { keepLatest } from 'ember-resources/util/keep-latest';
+ *
+ *  class A {
+ *    @use request = RemoteData(() => 'some url');
+ *    @use data = keepLatest({
+ *      value: () => this.request.value,
+ *      when: () => this.request.isLoading,
+ *    });
+ *
+ *    get result() {
+ *      // after the initial request, this is always resolved
+ *      return this.data;
+ *    }
+ *  }
+ * ```
+ */
+export function keepLatest<Return = unknown>({ until, value: valueFn }: Options<Return>) {
+  return resource(() => {
+    let previous: Return | undefined;
+
+    return () => {
+      let value = valueFn();
+
+      if (until()) {
+        return (previous = isEmpty(value) ? previous : value);
+      }
+
+      return (previous = value);
+    };
+  });
+}
+
+resourceFactory(keepLatest);

testing/ember-app/tests/utils/keep-latest/js-test.ts

@@ -0,0 +1,48 @@
+import { tracked } from '@glimmer/tracking';
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
+
+import { timeout } from 'ember-concurrency';
+import { use } from 'ember-resources';
+import { trackedFunction } from 'ember-resources/util/function';
+import { keepLatest } from 'ember-resources/util/keep-latest';
+
+module('Utils | keepLatest | js', function (hooks) {
+  setupTest(hooks);
+
+  test('it works', async function (assert) {
+    class Test {
+      @tracked x = 1;
+
+      // @use request = trackedFunction(async () => {
+      request = trackedFunction(this, async () => {
+        let value = this.x;
+
+        await timeout(30);
+
+        return value;
+      });
+
+      @use data = keepLatest({
+        until: () => this.request.isLoading,
+        value: () => this.request.value,
+      });
+    }
+
+    let instance = new Test();
+
+    assert.strictEqual(instance.data, undefined);
+
+    await timeout(40);
+
+    assert.strictEqual(instance.data, 1);
+
+    instance.x = 2;
+
+    assert.strictEqual(instance.data, 1);
+    await timeout(15);
+    assert.strictEqual(instance.data, 1);
+    await timeout(40);
+    assert.strictEqual(instance.data, 2);
+  });
+});

testing/ember-app/tests/utils/keep-latest/rendering-test.gts

@@ -0,0 +1,58 @@
+import { tracked } from '@glimmer/tracking';
+// @ts-ignore
+import { fn, hash } from '@ember/helper';
+import { module, test } from 'qunit';
+import { render, settled } from '@ember/test-helpers';
+import { setupRenderingTest } from 'ember-qunit';
+
+import { timeout } from 'ember-concurrency';
+import { trackedFunction } from 'ember-resources/util/function';
+import { keepLatest } from 'ember-resources/util/keep-latest';
+
+module('Utils | keepLatest | rendering', function (hooks) {
+  setupRenderingTest(hooks);
+
+  test('it works', async function (assert) {
+    class Test {
+      @tracked x = 1;
+
+      // @use request = trackedFunction(async () => {
+      request = trackedFunction(this, async () => {
+        let value = this.x;
+
+        await timeout(30);
+
+        return value;
+      });
+    }
+
+    let instance = new Test();
+
+    let passthrough = (x: unknown) => x;
+
+    render(<template>
+      {{#let instance.request as |request|}}
+        {{keepLatest (hash
+          until=(fn passthrough request.isLoading)
+          value=(fn passthrough request.value)
+        )}}
+      {{/let}}
+    </template>);
+
+    await timeout(10);
+
+    assert.dom().hasNoText();
+
+    await settled();
+
+    assert.dom().hasText('1');
+
+    instance.x = 2;
+
+    assert.dom().hasText('1');
+    await timeout(15);
+    assert.dom().hasText('1');
+    await timeout(40);
+    assert.dom().hasText('2');
+  });
+});