Effect
[ ru ]Effect is a container for async function.
It can be safely used in place of the original async function.
Methods
use(handler)
Provides a function, which will be called when the effect is triggered.
Formulae
effect.use(fn);
- Set handler
fn
foreffect
- If effect already had an implementation at the time of the call, it will be replaced by a new one
Hint: current handler can be extracted with effect.use.getCurrent().
You must provide a handler either through .use method or handler
property in createEffect, otherwise effect will throw with no handler used in _%effect name%_
error when effect will be called.
Arguments
handler
(Function): Function, that receives the first argument passed to an effect call.
Returns
(Effect): The same effect
Example
const fetchUserReposFx = createEffect();
fetchUserReposFx.use(async (params) => {
console.log("fetchUserReposFx called with", params);
const url = `https://api.github.com/users/${params.name}/repos`;
const req = await fetch(url);
return req.json();
});
fetchUserReposFx({ name: "zerobias" });
// => fetchUserRepos called with {name: 'zerobias'}
use.getCurrent()
Returns current handler of effect. Useful for testing.
Formulae
fn = effect.use.getCurrent();
- Returns current handler for
effect
- If no handler was assigned to
effect
, default handler will be returned (that throws an error) - Hint: to set a new handler use effect.use(handler)
Returns
(Function): Current handler, defined by handler
property or via use
call.
Example
const handlerA = () => "A";
const handlerB = () => "B";
const fx = createEffect(handlerA);
console.log(fx.use.getCurrent() === handlerA);
// => true
fx.use(handlerB);
console.log(fx.use.getCurrent() === handlerB);
// => true
watch(watcher)
Subscribe to effect calls.
Formulae
const unwatch = effect.watch(fn);
- Call
fn
on eacheffect
call, pass payload ofeffect
as argument tofn
- When
unwatch
is called, stop callingfn
Arguments
watcher
(Watcher): A function that receivespayload
.
Returns
Subscription: Unsubscribe function.
Example
import { createEffect } from "effector";
const fx = createEffect((params) => params);
fx.watch((params) => {
console.log("effect called with value", params);
});
await fx(10);
// => effect called with value 10
prepend(fn)
Creates an event, upon trigger it sends transformed data into the source event. Works kind of like reverse .map
. In case of .prepend
data transforms before the original event occurs and in the case of .map
, data transforms after original event occurred.
Formulae
const event = effect.prepend(fn);
- When
event
is triggered, callfn
with payload fromevent
, then triggereffect
with the result offn()
Arguments
fn
(Function): A function that receivespayload
, should be pure.
Returns
Event: New event.
map(fn)
Creates a new event, which will be called after the original effect is called, applying the result of a fn
as a payload. It is a special function which allows you to decompose dataflow, extract or transform data.
Formulae
const second = first.map(fn);
- When
first
is triggered, pass payload fromfirst
tofn
- Trigger
second
with the result of thefn()
call as payload
Arguments
fn
(Function): A function that receivespayload
, should be pure.
Returns
Event: New event.
Example
import { createEffect } from "effector";
const userUpdate = createEffect(({ name, role }) => {
console.log(name, role);
});
const userNameUpdated = userUpdate.map(({ name }) => name); // you may decompose dataflow with .map() method
const userRoleUpdated = userUpdate.map(({ role }) => role.toUpperCase()); // either way you can transform data
userNameUpdated.watch((name) => console.log(`User's name is [${name}] now`));
userRoleUpdated.watch((role) => console.log(`User's role is [${role}] now`));
await userUpdate({ name: "john", role: "admin" });
// => User's name is [john] now
// => User's role is [ADMIN] now
// => john admin
Properties
You are not supposed to use parts of effect (like .done
and .pending
) as a target
in sample or forward (even though they are events and stores), since effect is a complete entity on its own. This behavior will not be supported.
done
Event, which is triggered when handler is resolved.
Do not manually call this event. It is an event that depends on effect.
Properties
Event triggered with an object of params
and result
:
params
(Params): An argument passed to the effect callresult
(Done): A result of the resolved handler
Example
import { createEffect } from "effector";
const fx = createEffect((value) => value + 1);
fx.done.watch(({ params, result }) => {
console.log("Call with params", params, "resolved with value", result);
});
await fx(2);
// => Call with params 2 resolved with value 3
doneData
Event, which is triggered by the result of the effect execution:
Formulae
event = effect.doneData;
doneData
is an event, that triggered wheneffect
is successfully resolved withresult
from .done
Do not manually call this event. It is an event that depends on the effect.
Event triggered when handler is resolved.
Example
import { createEffect } from "effector";
const fx = createEffect((value) => value + 1);
fx.doneData.watch((result) => {
console.log(`Effect was successfully resolved, returning ${result}`);
});
await fx(2);
// => Effect was successfully resolved, returning 3
fail
Event, which is triggered when handler is rejected or throws error.
Do not manually call this event. It is an event that depends on effect.
Properties
Event triggered with an object of params
and error
:
params
(Params): An argument passed to effect callerror
(Fail): An error caught from the handler
Example
import { createEffect } from "effector";
const fx = createEffect(async (value) => {
throw Error(value - 1);
});
fx.fail.watch(({ params, error }) => {
console.log("Call with params", params, "rejected with error", error.message);
});
fx(2);
// => Call with params 2 rejected with error 1
failData
Event, which is triggered with error thrown by the effect
Formulae
event = effect.failData;
failData
is an event, that triggered wheneffect
is rejected witherror
from .fail
Do not manually call this event. It is an event that depends on effect.
Event triggered when handler is rejected or throws error.
Example
import { createEffect } from "effector";
const fx = createEffect(async (value) => {
throw Error(value - 1);
});
fx.failData.watch((error) => {
console.log(`Execution failed with error ${error.message}`);
});
fx(2);
// => Execution failed with error 1
finally
Event, which is triggered when handler is resolved, rejected or throws error.
Do not manually call this event. It is an event that depends on effect.
Properties
Event, which is triggered with an object of status
, params
and error
or result
:
status
(string): A status of effect (done
orfail
)params
(Params): An argument passed to effect callerror
(Fail): An error caught from the handlerresult
(Done): A result of the resolved handler
Example
import { createEffect } from "effector";
const fetchApiFx = createEffect(async ({ time, ok }) => {
await new Promise((resolve) => setTimeout(resolve, time));
if (ok) return `${time} ms`;
throw Error(`${time} ms`);
});
fetchApiFx.finally.watch((value) => {
switch (value.status) {
case "done":
console.log("Call with params", value.params, "resolved with value", value.result);
break;
case "fail":
console.log("Call with params", value.params, "rejected with error", value.error.message);
break;
}
});
await fetchApiFx({ time: 100, ok: true });
// => Call with params {time: 100, ok: true}
// resolved with value 100 ms
fetchApiFx({ time: 100, ok: false });
// => Call with params {time: 100, ok: false}
// rejected with error 100 ms
pending
Store contains true
when effect is called but not resolved yet. Useful to show loaders.
Formulae
$store = effect.pending;
- $store will update when
done
orfail
are triggered - $store contains
true
value until the effect is resolved or rejected
Returns
Do not modify $store
value! It is derived store and should be in predictable state.
DerivedStore: Store that represents current state of the effect
Example
import React from "react";
import { createEffect } from "effector";
import { useStore } from "effector-react";
const fetchApiFx = createEffect((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
fetchApiFx.pending.watch(console.log);
const Loading = () => {
const loading = useStore(fetchApiFx.pending);
return <div>{loading ? "Loading..." : "Load complete"}</div>;
};
ReactDOM.render(<Loading />, document.getElementById("root"));
fetchApiFx(3000);
Itโs a shorthand for common use case
import { createEffect, createStore } from "effector";
const fetchApiFx = createEffect();
//now you can use fetchApiFx.pending instead
const $isLoading = createStore(false)
.on(fetchApiFx, () => true)
.on(fetchApiFx.done, () => false)
.on(fetchApiFx.fail, () => false);
inFlight
Shows how many effect calls arenโt settled yet. Useful for rate limiting.
Formulae
$count = effect.inFlight;
- Store
$count
will be0
if no calls ofeffect
in pending state, its default state - On each call of
effect
state in$count
store will be increased - When effect resolves to any state(done or fail) state in
$count
store will be decreased
Do not modify $count
value! It is derived store and should be in predictable state.
Returns
DerivedStore: Store that represents count of the running effects
Example
import { createEffect } from "effector";
const fx = createEffect(() => new Promise((rs) => setTimeout(rs, 500)));
fx.inFlight.watch((amount) => {
console.log("in-flight requests:", amount);
});
// => 0
const req1 = fx();
// => 1
const req2 = fx();
// => 2
await Promise.all([req1, req2]);
// => 1
// => 0