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.

Caution

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 properties a, 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 })

info

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 properties a, 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 });
Contributors
Commits