This method allows retrieving the state from each passed store and combining them into a single value, storing it in a new derived store. The resulting store will update every time any of the passed stores is updated.
If several stores update simultaneously, the method will process them all at once, meaning that combine
batches updates, which leads to more efficient operation without unnecessary computations.
combine
returns not just a common store. Instead, it returns DerivedStore, it cannot be modified by the events or used as target
in sample.
Common formulae
declare const $a: Store<A>;
declare const $b: Store<B>;
// State transformation
const $c: Store<C> = combine({ a: $a, b: $b }, (values: { a: A; b: B }) => C);
const $c: Store<C> = combine([ $a, $b ], (values: [A, B]) => C);
const $c: Store<C> = combine($a, $b, (a: A, b: B) => C);
// State combination
const $c: Store<{ a: A; b: B }> = combine({ a: $a, b: $b });
const $c: Store<[A, B]> = combine([ $a, $b ]);
State transformation
When function is passed to combine
it will act as state transformation funciton which will be called at every combine
update.
Result will be saved in created store. This function must be pure.
combine
function called synchronously during combine call, if this function will throw an error, application will crash. This will be fixed in 24 release
combine(...stores, fn)
Formulae
const $a: Store<A>
const $b: StoreWritable<B>
const $c: Store<C> | StoreWritable<C>
$result: Store<D> = combine(
$a, $b, $c, ...,
(a: A, b: B, c: C, ...) => result
)
- After call
combine
, state of each store is extracted and passed to function arguments,result
of a function call will be state of store$result
- Any number of stores can be passed to
combine
, but the latest argument always should be function-reducer that returns new state - If function returned the same
result
as previous, store$result
will not be triggered - If several stores updated at the same time (during one tick) there will be single call of function and single update of
$result
store - Function must be pure
Returns
DerivedStore: New derived store
Examples
combine({ A, B, C }, fn)
Formulae
const $a: Store<A>;
const $b: StoreWritable<B>;
const $c: Store<C> | StoreWritable<C>;
$result: Store<D> = combine(
{ a: $a, b: $b, c: $c },
({ a, b, c }: { a: A; b: B; c: C }): D => result,
);
- Read state from stores
$a
,$b
,$c
and assign it to propertiesa
,b
,c
accordingly, calls function with that object - The
result
of the function call saved in$result
store - If function returned the same
result
as previous, store$result
will not be triggered - If several stores updated at the same time (during one tick) there will be single call of function and single update of
$result
store - Function must be pure
Returns
DerivedStore: New derived store
Examples
combine([ A, B, C ], fn)
Formulae
const $a: Store<A>;
const $b: StoreWritable<B>;
const $c: Store<C> | StoreWritable<C>;
$result: Store<D> = combine([ $a, $b, $c ], ([A, B, C]): D => result);
- Read state from stores
$a
,$b
,$c
and assign it to array with the same order as passed stores, call function with that array - The
result
of the function call saved in$result
store - If function returned the same
result
as previous, store$result
will not be triggered - If several stores updated at the same time (during one tick) there will be single call of function and single update of
$result
store - Function must be pure
Returns
DerivedStore: New derived store
Examples
State combination
When there is no function in combine
it will act as state combinator, creating a store with array or object with fields from given stores
combine({ A, B, C })
Formerly known as createStoreObject
Formulae
const $a: Store<A>;
const $b: StoreWritable<B>;
const $c: Store<C> | StoreWritable<C>;
$result: Store<{ a: A; b: B; c: C }> = combine({ a: $a, b: $b, c: $c });
- Read state from stores
$a
,$b
,$c
and assign it to propertiesa
,b
,c
accordingly, that object will be saved to$result
store - Store
$result
contain object{a, b, c}
and will be updated on each update of passed stores - If several stores updated at the same time (during one tick) there will be single update of
$result
store
Returns
DerivedStore: New derived store
Examples
combine([ A, B, C ])
Formulae
const $a: Store<A>;
const $b: StoreWritable<B>;
const $c: Store<C> | StoreWritable<C>;
$result: Store<[A, B, C]> = combine([ $a, $b, $c ]);
- Read state from stores
$a
,$b
,$c
and assign it to array with the same order as passed stores, that array will be saved to$result
store - Store
$result
will be updated on each update of passed stores - If several stores updated at the same time (during one tick) there will be single update of
$result
store
Returns
DerivedStore: New derived store
Examples
combine
with primitives and objects
Primitives and objects can be used in combine
, and combine
will not be triggered. Effector will not track mutations of objects and primitives.
Examples
Parameters
All overloads of combine
with fn
provided are also supporting optional configuration object as the last parameter.
.skipVoid
Flag to control how specifically store should handle undefined
value (since effector 23.0.0
). If set to false
- store will use undefined
as a value. If set to true
(deprecated), store will read undefined
as a “skip update” command and will do nothing
Formulae
combine($a, $b, callback, { skipVoid: true });
- Type:
boolean
Examples
const $withFn = combine($a, $b, (a, b) => a || b, { skipVoid: false });