aurelia-async-bindable
How It Works (This Is IMPORTANT)
READMEs don't usually begin with this kind of information. However, with asyncBindable
, understanding how it works is really important.
If you use it incorrectly, you may have interesting things happen to you!
asyncBindable
is a powerful decorator that can be used to bind asynchronous getters to your aurelia views.
It should be used along with a getter on your view model that returns a promise.
Internally, the decorator does two things:
- It transforms your getter:
- It memoizes the return value (based on the dependencies - more on this later)
- Wraps your getter in a function that returns appropriate values depending on the state of the promise returned by your getter.
- It sets up an additional property on your view model and tells
@computedFrom
to watch that property.
When your promise resolves, asyncBindable
changes the property that @computedFrom
is watching and retriggers any dependant bindings.
Why memoize?
Async bindings are particularly sensitive to being called multiple times. This is because they often contain network calls which we only want executed once.
If asyncBindable
is used along with computedFrom
, the computedFrom
dependencies are taken into account in the memoization.
Implications
There are some important implications you should take away:
asyncBindable
by default will only make a call to the getter that you declared once. It does not magically know when to call your getter again. You need to tell it when to reevaluate the getter (see this section).- Because
asyncBindable
is usingcomputedFrom
internally, it is only natural that you can use them together (see this section) However, when using them together, order is important, theasyncBindable
decorator must be declared first. - Don't worry about dirty checking. Generally, when you bind to a regular getter, aurelia will have to resort to dirty checking to update the binding (because it has no way of knowing which properties to observe for the update).
However, because
asyncBindable
is usingcomputedFrom
internally, that automatically means that Aurelia will NOT use dirty checking to update any dependent bindings.
Using The Decorator
Simple Use
The simplest use case is if you want to bind the results of a network call:
@ { return remoteEndpoint ;}
Then, simply use in your view like so:
${item.label}
Options
There are three options:
@asyncBindable({
pendWith: 'Loading...', // pendWith takes a primitive value. As long as the promise is pending, this primitive will be provided to Aurelia.
resolveWith: resolvedValue => resolvedValue.slice(0, 10), // resolveWith can be a function like this example or a primitive.
rejectWith: rejectionErr => rejectionErr.message // rejectWith can be a function like this example or a primitive.
})
Using along with the computedFrom decorator
A very common use case is to need to use this decorator along with @computedFrom
.
For example, suppose you are showing a list of tasks for a specific story. A user can change the story that is selected, and the list of tasks needs to auto update:
View Model:
@ { return storiesEndpoint;} @@ { return tasksEndpoint;}
View:
${story.title} ${task.title}
PLEASE NOTE: When using asyncBindable
in conjunction with computedFrom
, the asyncBindable
declaration must come first.
Manually Refreshing Dependent Bindings
Suppose you want to manually retrigger bindings dependent on a asyncBindable
decorated getter.
For instance, in the example above, suppose you want to refresh the tasks without the storyId
changing.
A solution to this is to just add a dependency that you manually control like so:
@@ { return tasksEndpoint;} tasksRefreshes = 1;
Now, if you want to refresh the tasks:
{ // Do stuff. thistasksRefreshes++;}
Transpiling
To transpile to dist:
npm start -- transpile