Aurelia provides a higher-level API for simplifying some common tasks to handle a common reactivity intent in any application: run a function again when any of its dependencies have been changed.
This function is called an effect, and the dependencies are typically tracked when they are accessed (read) inside this effect function. The builtin @observable
decorator from Aurelia enables this track-on-read capability by default.
Aurelia provides a few ways to declare a dependency for an effect function. The most common one is the track "on read" of a reactive property.
In the following example:
The property coord
of a MouseTracker
instance will be turned into a reactive property and is also aware of effect function dependency tracking.
Properties decorated with @observable
and any proxy based property accesses will be tracked as dependencies of the effect
The effect APIs are provided via the default implementation of the interface IObservation
, which can be retrieved like one of the following examples:
Getting from a container directly:
Getting through injection:
Or
After getting the observation object, there are two APIs that can be used to created effects as described in the following sections:
Watch effect is a way to describe a getter based observation of an object. An example to create watch effect is per the following:
Note that the effect function will be run immediately. If you do not want to run the callback immediately, pass an option immediate: false
as the 4th parameter:
By default, a watch effect is independent of any application lifecycle, which means it does not stop when the application that owns the observation
instance has stopped. To stop/destroy an effect, call the method stop()
on the effect object.
Run effects describe a function to be called repeatedly whenever any dependency tracked inside it changes.
After getting an IObservation
instance, a run effect can be created via the method run
of it:
Note that the effect function will be run immediately.
By default, a effect is independent of any application lifecycle, which means it does not stop when the application that owns the observation
instance has stopped. To stop/destroy an effect, call the method stop()
on the effect object:
The following section gives some examples of what it looks like when combining @observable
and run effect.
Now whenever the user moves the mouse around, a log will be added to the console with the coordinate of the mouse.