status-mobile/doc
Icaro Motta a17efa7299
Make json-rpc/call effect more in line with re-frame standards (#15936)
Changes effect :json/rpc-call to accept on-success and on-error parameters
either as functions OR as re-frame event vectors. The changes are 100% backwards
compatible.

## Why?

Re-frame is very explicit in its documentation and its architecture, saying that
event handlers should be pure. Calling re-frame.core/dispatch in event handlers
makes them sort of stateful.

> So, you can "get away with it". But it ain't pure.
>
> -- https://day8.github.io/re-frame/EffectfulHandlers/#90-solution

In status-mobile, arguably one of our most important effects (not to be confused
with event handlers) is :json-rpc/call, but at the moment, the on-success and
on-error values are expected to be stateful functions (e.g. usually used for
logging and dispatching subsequent events).

This creates two important problems:

1. The value returned by event handlers is more opaque and cannot be easily
   inspected (for example using tap>, log/debug or just println). If we try to
   inspect or log them, on-success and on-error will be printed as
   #object[Function].
2. Testing event handlers using :json-rpc/call becomes an exercise of
   frustration, because we can't simply compare the results of the event handler
   with a good expected value, which is one of the big selling points of testing
   pure functions.

### The testability of event handlers

> For any re-frame app, there's three things to test:
>
> - Event Handlers - most of your testing focus will be here because this is
>   where most of the logic lives
> - Subscription Handlers - often not a lot to test here. Only Layer 3
>   subscriptions need testing.
> - View functions - I don't tend to write tests for views.
>
> -- https://day8.github.io/re-frame/Testing/#what-to-test

So re-frame is saying event handlers should be pure, and that event handlers
should be tested.

In order to achieve the divine simplicity of testing event handlers as pure
functions, we need to make :json-rpc/call also accept on-success and
on-error as event vectors.

Good news is that there is a known pattern to solve this problem, e.g. used by
the library https://github.com/Day8/re-frame-http-fx.

The pattern is simple once we see it: behind the scenes, :json-rpc/call conj'es
the results of the RPC call into the event vectors on-success and on-error, and
:json-rpc/call dispatches the events itself. This eliminates the need for the
stateful dispatch call in event handlers.
2023-05-18 15:56:10 -03:00
..
decisions moving security from status-im ns to root utils (#14567) 2022-12-20 17:56:21 +05:30
images Separate doc with debug tips (#15849) 2023-05-10 10:38:59 +01:00
sign_in remove realm 2019-09-09 18:40:15 +02:00
README.md Separate doc with debug tips (#15849) 2023-05-10 10:38:59 +01:00
codebase-structure-and-guidelines.md Separate doc with debug tips (#15849) 2023-05-10 10:38:59 +01:00
component-tests-overview.md feat: add in-app notification, refactor toast (#15642) 2023-04-17 14:01:25 +08:00
debugging.md Separate doc with debug tips (#15849) 2023-05-10 10:38:59 +01:00
dependencies.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
export-icons.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
fdroid.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
how-to-launch-e2e.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
ide-setup.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
merging-pr-process.md we should explicitly mention testing status-go in our docs (#15091) 2023-02-15 17:06:55 +05:30
new-guidelines.md Make json-rpc/call effect more in line with re-frame standards (#15936) 2023-05-18 15:56:10 -03:00
pipeline_process.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
post-mortem.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
release-checklist.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
release-guide.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
starting-guide.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00
testing.md ci: add component test (#15071) 2023-02-21 13:42:33 +08:00
troubleshooting.md Documentation updated (#14933) 2023-01-31 12:06:29 +00:00