ember-async-data
Advanced tools
A utility/helper and data structure for representing a `Promise` in a declarative, reactive way in Glimmer.js and Ember Octane.
A utility/helper and data structure for representing a Promise in a declarative, reactive way in Glimmer.js and Ember Octane.
Render a promise in a declarative way in template-only code:
{{#let (load @somePromise) as |result|}}
{{#if result.isResolved}}
<PresentTheData @data={{result.value}} />
{{else if result.isPending}}
<LoadingSpinner />
{{else if result.isRejected}}
<p>
Whoops! Looks like something went wrong!
{{result.error.message}}
</p>
{{/endif}}
{{/let}}
Create declarative data fetches based on arguments to a component in a backing class:
import Component from '@glimmer/component';
import { cached } from '@glimmer/tracking';
import { inject as service } from '@ember/service';
import { TrackedAsyncData } from 'ember-async-data';
export default class SmartProfile extends Component {
@service store;
@cached
get someData() {
let recordPromise = this.store.findRecord('user', this.args.id);
return new TrackedAsyncData(recordPromise);
}
}
(See the guide below for why this uses @cached!)
{{#if this.someData.isResolved}}
<PresentTheData @data={{this.someData.value}} />
{{else if this.someData.isPending}}
<LoadingSpinner />
{{else if this.someData.isRejected}}
<p>
Whoops! Looks like something went wrong!
{{this.someData.error.message}}
</p>
{{/endif}}
This project follows the current draft of the Semantic Versioning for TypeScript Types proposal.
-private module are publicember install ember-async-data
Sometimes it doesn't make sense for a route to fetch the data required by a given component. This can be the case for a number of reasons:
Additionally, it's often valuable to load data only when required, because it factors into network speed and CPU cost and often goes unused entirely. Though these concerns are present everywhere, they are especially important in rural areas and emerging markets where:
You can use TrackedAsyncData either directly in JavaScript or via the {{load}} helper in templates.
To create a TrackedAsyncData, simply import it from the library and call its constructor with a Promise.
First, a small utility function for being able to resolve or reject a Promise at will (so we can see how the lifecycle behaves):
function defer() {
let deferred!: {
resolve: (value: unknown) => void;
reject: (reason?: unknown) => void;
} = {};
deferred.promise = new Promise((resolve, reject) => {
deferred.resolve = resolve;
deferred.reject = reject;
});
return deferred;
}
Now we can create promises to resolve or reject and pass them to TrackedAsyncData:
import { TrackedAsyncData } from 'ember-async-data';
let firstDeferred = defer();
let willResolve = new TrackedAsyncData(firstDeferred.promise);
console.log(willResolve);
/*
TrackedAsyncData: {
"isPending": true,
"isResolved": false,
"isRejected": false
}
*/
await firstDeferred.resolve('potato');
console.log(willResolve);
/*
TrackedAsyncData: {
"isPending": false,
"isResolved": true,
"value": "potato",
"isRejected": false
}
*/
// create another promise, this time to reject
let secondDeferred = defer();
let willReject = new TrackedAsyncData(secondDeferred.promise);
console.log(willReject);
/*
TrackedAsyncData: {
"isPending": true,
"isResolved": false,
"isRejected": false
}
*/
await secondDeferred.reject('wat');
console.log(willReject);
/*
TrackedAsyncData: {
"isPending": false,
"isResolved": false,
"isRejected": true,
"error": "wat"
}
*/
You can use TrackedAsyncData with any value, not just a Promise, which is convenient when working with data which may or may not already be in a Promise.
This library provides full type safety for TrackedAsyncData; see API below for details. The resulting value will always be of the same type as the Promise you pass in. Type narrowing works correctly: if you check the .state property or any of the .isPending, .isResolved, or .isRejected properties, the resulting type will
With .state:
let example = new TrackedAsyncData(Promise.resolve({ theAnswer: 42 }));
switch (example.state) {
case 'PENDING':
console.log(example.value?.theAnswer); // 🛑 WARN; type is `number | null`
console.log(example.error); // 🛑 WARN
break;
case 'RESOLVED':
console.log(example.value.theAnswer); // ✅
console.log(example.error); // 🛑 WARN
break;
case 'RESOLVED':
console.log(example.value?.theAnswer); // 🛑 WARN; type is `number |
console.log(example.error); // ✅
break;
default:
assertUnreachable(example); // ✅ as long as all cases covered
}
With the boolean property checks .isPending, .isResolved, or .isRejected:
let example = new TrackedAsyncData(Promise.resolve("a string"));
if (example.isResolved) {
console.log(example.value.length); // ✅ type is `string`
}
When using TrackedAsyncData with an API call in a getter, it is important to use @cached (via the ember-cached-decorator-polyfill) with the getter. Otherwise, you can end up triggering the creation of multiple API calls. For example, given a backing class like this:
import Component from '@glimmer/component';
import { inject as service } from '@ember/service';
import type Store from '@ember-data/store';
import { TrackedAsyncData } from 'ember-async-data';
export default class Profile extends Component<{ userId: string }> {
@service store: Store;
get fullProfile() {
return new TrackedAsyncData(this.store.findRecord('user', userId), this);
}
}
Then if the template checks the fullProfile state in multiple places, it will invoke the getter multiple times per render:
{{#if this.fullProfile.isPending}}
<LoadingSpinner />
{{/if}}
<div class='profile {{if (not this.fullProfile.isResolved) "pending"}}'>
{{#if this.fullProfile.isResolved}}
{{#let this.fullProfile.value as |profile|}}
<p>{{profile.name}} ({{profile.description}})</p>
<img
src={{profile.avatar}}
alt="avatar for {{profile.name}}"
/>
{{/let}}
{{/if}}
</div>
This code would invoke the getter twice on first render, which would therefore trigger two separate calls to the store, one of which would effectively be thrown away. Then, once the second call did resolve, it would invoke the getter multiple more times, and the result would be a sort of ping-ponging back and forth between pending and resolved states as a cascade of new API calls are triggered by each invocation of the getter.
This is the correct default behavior, even though it might be surprising at first:
TrackedAsyncData API, this similarly means we don't pay for extra caching of arguments in the many cases we don't need it. (We do guarantee we only ever have a single TrackedAsyncData per Promise, as described elsewhere in the docs, so we don't pay more than we need to.)Note: in the future, we will make a set of Resources layered on top of the core data types here, which will allow us to build in caching for API calls.
load functionFor symmetry with templates, you can also use load in JavaScript; it has the exact same semantics as calling new TrackedPromise. Using load, the example from the top of the README would look like this:
import Component from '@glimmer/component';
import { cached } from '@glimmer/tracking';
import { inject as service } from '@ember/service';
import { load } from 'ember-async-data';
export default class SmartProfile extends Component {
@service store;
@cached
get someData() {
return load(this.store.findRecord('user', this.args.id), this);
}
}
Note that this has the exact same requirements around API calls as the direct use of the constructor.
It is illegal to subclass TrackedAsyncData; trying to invoke a subclass will throw an error.
To use a TrackedAsyncData in templates, we provide the load helper. You can pass it any value, and it will return a TrackedAsyncData for that value. You can then use the .isPending, .isResolved, and .isRejected properties to conditionally render content based on the state of the promise.
You could use this to build a component which uses named blocks to provide a nice API for end users:
<div class='loader'>
{{#let (load @promise) as |result|}}
{{#if result.isPending}}
<div class='loader__pending'>
{{if (has-block "pending")}}
{{yield to="pending"}}
{{else}}
Loading...
{{/if}}
</div>
{{else if result.isResolved}}
<div class='loader__resolved'>
{{if (has-block "resolved")}}
{{yield result.value to="resolved"}}
{{else}}
{{result.value}}
{{/if}}
</div>
{{else if result.isRejected}}
<div class='loader__rejected'>
{{if (has-block "rejected")}}
{{yield result.error to="rejected"}}
{{else}}
{{result.error}}
{{/if}}
</div>
{{/if}}
{{yield
{{/let}}
</div>
Then callers could use it like this:
<Loader @promise={{this.someQuery}}>
<:pending>Hang on, we’ll get that data for you!</:pending>
<:resolved as |value|>
Cool! The value you asked for was: {{value}}.
<:/resolve>
<:rejected as |error|>
Oh no, we couldn't get that data for you. Here's what we know: {{error}}
<:/rejected>
</Loader>
Working with the full range of behavior from TrackedAsyncData in tests will require you to manage the inherent asynchrony of the system much more explicitly than you may be used to. This is unavoidable: the point of the helper and data type is dealing with asynchrony in an explicit way.
As a starting point, you can and should ask: "Is testing the a loading spinner when someTrackedAsyncData.isLoading something I actually need an automated test for, or can I verify it manually just once?" Depending on your app, your answer might be that just verifying it manually is a better use of your time! In other cases, testing that behavior might be essential: for example, if you are building an abstraction on top of TrackedAsyncData for others to consume.
Unit testing is straightforward. Using a tool like RSVP.defer(), you can create a promise and control its resolution and verify that your use of TrackedAsyncData does what you need it to. Whenever you trigger a change in the state of the underlying promise, you will need to wait for promise resolution in the test. There are two ways to do this:
await the promise itself.await the settled() helper from @ember/test-helpers, since TrackedAsyncData integrates into Ember’s test waiter system.import { TrackedAsyncData } from 'ember-async-data';
import { defer } from 'rsvp';
import { module, test } from 'qunit';
import { settled } from '@ember/test-helpers';
module('my very own tests', function (hooks) {
test('directly awaiting the promise works', async function (assert) {
let { promise, resolve } = defer();
let asyncData = new TrackedAsyncData(promise);
assert.true(asyncData.isPending);
let expectedValue = "cool";
resolve(expectedValue);
await promise;
assert.true(asyncData.isResolved);
asset.equal(asyncData.value, expectedValue);
});
test('awaiting `settled` also works', async function (assert) {
let { promise, resolve } = defer();
let asyncData = new TrackedAsyncData(promise);
assert.true(asyncData.isPending);
let expectedValue = "cool";
resolve(expectedValue);
await settled();
assert.true(asyncData.isResolved);
asset.equal(asyncData.value, expectedValue);
});
});
Handling errors is slightly more complicated: TrackedAsyncData “re-throws” the promises it works with when they have errors, to avoid silently swallowing them in a way that prevents you from using them with logging infrastructure or otherwise dealing with them in your app’s infrastructure. However, this means you must also account for them in your testing:
test('it handles errors', function (assert) {
assert.expect(2);
let { promise, reject } = defer();
let asyncData = new TrackedAsyncData(promise);
reject(new Error("this is the error!"));
await promise.catch((error) => {
assert.equal(error.message, "this is the error!");
});
assert.true(asyncData.isRejected);
assert.equal(asyncData.error.message, "this is the error!");
});
Integration/render tests are similar to those with unit testing, but with an additional wrinkle: all of Ember’s integration test helpers are also asynchronous, and the asynchrony of those test helpers and the TrackedAsyncData become “entangled” when they interact. That is: when you render something which depends on the state of the TrackedAsyncData, the promise which TrackedAsyncData is handling and the promise for rendering are effectively tied together.
So this code, which you might write if you haven’t dealt with this before, WILL NOT WORK:
import { TrackedAsyncData } from 'ember-async-data';
import { defer } from 'rsvp';
import { module, test } from 'qunit';
import { setupRenderingTest } from '@ember/test-helpers';
import { render } from "@ember/test-helpers";
import hbs from "htmlbars-inline-precompile";
module('my very own tests', function (hooks) {
setupRenderingTest(hooks);
test('THIS DOES NOT WORK', function (assert) {
let { promise, resolve } = defer();
this.data = new TrackedAsyncData(promise);
await render(hbs`
<div data-test-data>
{{#if this.data.isPending}}
Loading...
{{else if this.data.isResolved}}
Loaded: {{this.data.value}}
{{else if this.data.isRejected}}
Error: {{this.data.error.message}}
{{/if}}
</div>
`);
assert.dom('[data-test-data]').hasText('Loading...');
});
});
This test will simply time out without ever having finished, because the test waiters in the render promise and the test waiters in TrackedAsyncData are tangled up together. Instead, we need to separate the rendering promise from the promise in TrackedAsyncData. We can instead render the template and, instead of waiting for that promise to resolve, use Ember’s waitFor helper to wait for the results of rendering to happen. Then when we are done dealing with the promise, we can resolve it and then await the result of the render promise. This will let the test clean up correctly:
import { TrackedAsyncData } from 'ember-async-data';
import { defer } from 'rsvp';
import { module, test } from 'qunit';
import { setupRenderingTest } from '@ember/test-helpers';
import { render, waitFor } from "@ember/test-helpers";
import hbs from "htmlbars-inline-precompile";
module('my very own tests', function (hooks) {
setupRenderingTest(hooks);
test('this actually works', function (assert) {
let { promise, resolve } = defer();
this.data = new TrackedAsyncData(promise);
const renderPromise = render(hbs`
<div data-test-data>
{{#if this.data.isPending}}
Loading...
{{else if this.data.isResolved}}
Loaded: {{this.data.value}}
{{else if this.data.isRejected}}
Error: {{this.data.error.message}}
{{/if}}
</div>
`);
// Here we waits for the *result* of rendering, rather than the render
// promise itself. Once we have rendered, we can make assertions about
// what rendered:
await waitFor('data-test-data');
assert.dom('[data-test-data]').hasText('Loading...');
// Then to clean up the test, we need the original promise to resolve
// so the test waiter system isn't just stuck waiting for it forever.
resolve();
// Finally, we
await renderPromise;
});
});
While this might seem a bit annoying, it means that we actually can control all the related bits of asynchronous code that we need, and—more just as importantly—it means we avoid leaking promises across tests (a common cause of test instability) and means that in general tests following the “happy path” don’t have to worry about managing this asynchrony themselves.
For that happy path, you can use a resolved TrackedAsyncData and everything will always “just work” as you’d expect:
test('the "happy path" works easily', async function (assert) {
this.data = new TrackedAsyncData(Promise.resolve("a value"));
await render(hbs`
<div data-test-data>
{{#if this.data.isPending}}
Loading...
{{else if this.data.isResolved}}
Loaded: {{this.data.value}}
{{else if this.data.isRejected}}
Error: {{this.data.error.message}}
{{/if}}
</div>
`);
assert.dom('[data-test-data]').hasText('Loaded: a value');
});
In other words, the only time you have to care about the details of handling async in your tests is when you want to render and step through the different async states explicitly.
You can currently use this in three distinct ways:
TrackedAsyncData class directly in JavaScript.load utility function exported from the helper file. (This is not preferred, but exists for backwards compatibility and symmetry with the helper, until we have a Resource-style API available.){{load}} helper in templates.TrackedAsyncDataThe public API for TrackedAsyncData:
class TrackedAsyncData<T> {
constructor(data: T | Promise<T>, context?: object);
get state(): "PENDING" | "RESOLVED" | "REJECTED";
get isPending(): boolean;
get isResolved(): boolean;
get isRejected(): boolean;
// Only available if `isResolved`.
get value(): T | null;
// Only available if `isRejected`.
get error(): unknown;
}
value is T | null today, but only for the sake of safe interop with Ember Classic computed properties (which eagerly evaluate getters for the sake of). You should not rely on the null fallback, as accessing value when isResolved is false will become a hard error at the 1.0 release. The same is true of error.context argument is currently optional but will become mandatory at the 1.0 release. This allows the type to be torn down correctly as part of Ember's "destroyables" API.value and error getters will warn if you access them and the underlying promise is in the wrong state. In the future, this will be converted to throwing an error. (It currently only warns because classic computed properties actively lookup and cache the values returned from their dependent keys.)load functionThe load helper function is basically just a static constructor for TrackedAsyncData:
function load<T>(data: T | Promise<T>, context?: object): TrackedAsyncData<T>;
The {{load}} helper is identical to the load function but in template space: it accepts a single positional parameter of a promise as its only argument, and yields a TrackedAsyncData for that promise. (See usage examples above.)
For a deep dive, see this pair of blog posts (the API has changed slightly since these were authored, but the fundamental ideas are the same):
You can think of this as an autotracked, Ember-friendly implementation of the idea in How Elm Slays a UI Antipattern.
In the past, Ember developers tended to reach for PromiseProxyMixin to solve this problem. However, PromiseProxyMixin has two significant issues:
await or with .then()).The load helper is a fully-featured replacement for PromiseProxyMixin, with none of these pitfalls. This takes a promise as a parameter and returns a TrackedAsyncData object which handles the pending/resolved/rejected state as well as value/error data. The associated load helper provides a consistent way for developers to load data in their component templates.
See the Contributing guide for details.
This project is licensed under the MIT License.
Research into the ideas behind this code happened at LinkedIn, with key work done by Yaobin Dong, Lucy Lin, Lewis Miller, and Chris Krycho. While this new implementation is distinct from that one in many ways, it would have been impossible without those initial efforts!
v0.5.1 (2021-09-04)
FAQs
A utility/helper and data structure for representing a `Promise` in a declarative, reactive way in Glimmer.js and Ember Octane.
The npm package ember-async-data receives a total of 7,050 weekly downloads. As such, ember-async-data popularity was classified as popular.
We found that ember-async-data demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.