Update 12/2022: This package is considered completed and no longer being updated with new features. Please consider using @thi.ng/rstream instead...
{{pkg.description}}
The idea of interceptors is quite similar to functional composition and
AOP (aspect oriented
programming).
You want to reuse some functionality across components within your app.
For example, if you have multiple actions which should be undoable, you
can compose your main event handlers with the
snapShot()
interceptor, which requires a
@thi.ng/atom/History-like
instance and records a snapshot of the current app state, but else is
completely invisible.
[UNDOABLE_EVENT]: [snapshot(), valueSetter("foo")]
The idea of event handlers is being responsible to assign parameters
to side effects, rather than executing effects themselves, is again
mainly to do with the DRY-principle, instrumentation potential and
performance. Most composed event handler chains are setup so that your
"actual" main handler is last in line in the pre processing phase. If
e.g. your event handlers would directly update the state atom, then any
attached watches (derived views, cursors, other
subscriptions)
would be re-run each time. By assigning the updated state to, e.g., an
FX_STATE event, we can avoid these interim updates and only apply the
new state once all events in the current frame have been processed.
Furthermore, a post interceptor might cancel the event due to validation
errors etc.
To briefly summarize the differences between event handlers & effects:
Event handlers are triggered by events, but each event handler is technically a chain of interceptors (even though many are just a single item). Even if you just specify a single function, it's internally translated into an array of interceptor objects like:
valueSetter("route") -> [{ pre: (...) => {[FX_STATE]: ...}, post: undefined }]
When processing an event, these interceptors are then executed first in
ascending order for any pre functions and then backwards again for any
post functions (only if there are any in the chain). So if you had
defined an handler with this chain: [{pre: f1, post: f2}, {pre: f3}, {pre: f4, post: f5}], then the functions would be called in this order:
f1, f3, f4, f5, f2. The post phase is largely intended for state/effect
validation & logging post-update. I.e., interceptors commonly need pre
only.
Like with
trace() some
interceptors DO have side effects, but they're really the exception to the rule.
For example, snapshot() is idempotent since it only records a new snapshot if
it's different from the last and trace(), but is typically used during
development only - its side effect is outside the scope of your app (i.e. the
console).
In most apps there're far more event types/handlers than possible
actions any component can take. So assigning them to registered side
effects enables better code reuse. Another use-case is debugging. With a
break point set at the beginning of processEffects() (in
event-bus.ts)
you can see exactly which side effects have occurred at each frame. This
can be very helpful for debugging and avoid having to "keep everything
in your head" or - as Rich Hickey would say - make your app "Easier to
reason about".
More comprehensive description forthcoming. Please check the detailed commented source code and examples for now:
{{meta.status}}
{{repo.supportPackages}}
{{repo.relatedPackages}}
{{meta.blogPosts}}
{{pkg.install}}
{{pkg.size}}
{{pkg.deps}}
{{repo.examples}}
{{pkg.docs}}
TODO