import { type Store, type StoreWritable } from "effector";

Store is an object that holds the state value. Store gets updates when it receives a value that is not equal (!==) to the current one and to undefined. Store is a Unit. Some stores can be derived.

Immutability

A store in effector is immutable. This means that updates will only occur if the handler function (such as combine, sample, or on) returns a new object.

For example, before using array methods, you need to create a new reference to it. Here’s how to do it correctly:

$items.on(addItem, (items, newItem) => {
  const updatedItems = [...items];
  // βœ… .push method is called on a new array
  updatedItems.push(newItem);
  return updatedItems;
});

This approach should not be used, as the store will not be updated:

$items.on(addItem, (items, newItem) => {
  // ❌ Error! The array reference remains the same, the store will not be updated
  items.push(newItem);
  return items;
});

Updating objects works in a similar way.

A store in effector should be as small as possible, responsible for a specific part of the business logic, unlike, for example, Redux, whose store tends to hold everything together. When the state is atomic, the need for spreading objects becomes less frequent. However, if there is a need to frequently update deeply nested data, it is acceptable to use immer to simplify repetitive code when updating the state.

Store Methods

.map(fn)

Creates a derived store. It will call a provided function with the state when the original store updates, and will use the result to update the derived store.

Formulae

const $second = $first.map(fn);

Arguments

  1. fn (Function): Function that receives state and returns a new state for the derived store.
  2. config (Object): Optional configuration.

Returns

DerivedStore: New derived store.

Examples

Basic

import { createEvent, createStore } from "effector";

const changed = createEvent();
const $title = createStore("").on(changed, (_, newTitle) => newTitle);
const $length = $title.map((title) => title.length);

$length.watch((length) => {
  console.log("new length", length);
});

changed("hello");
changed("world");
changed("hello world");

Try it

SkipVoid

const $length = $title.map((title) => title.length, { skipVoid: false });

.on(trigger, reducer)

Updates state when trigger is triggered by using a reducer.

Formulae

$store.on(trigger, reducer);

Arguments

  1. trigger: Event, Effect, or another Store.
  2. reducer: Reducer: Function that receives state and params and returns a new state.

Returns

Store: Current store.

Examples

Basic

import { createEvent, createStore } from "effector";

const $store = createStore(0);
const changed = createEvent();

$store.on(changed, (value, incrementor) => value + incrementor);

$store.watch((value) => {
  console.log("updated", value);
});

changed(2);
changed(2);

Try it

.watch(watcher)

Calls watcher function each time when the store is updated.

Formulae

const unwatch = $store.watch(watcher);

Arguments

  1. watcher: Watcher: Watcher function that receives the current store state as the first argument.

Returns

Subscription: Unsubscribe function.

Examples

Basic

import { createEvent, createStore } from "effector";

const add = createEvent();
const $store = createStore(0).on(add, (state, payload) => state + payload);

$store.watch((value) => console.log(`current value: ${value}`));
add(4);
add(3);

Try it

.reset(...triggers)

Resets store state to the default value.

Formulae

$store.reset(...triggers);

Arguments

  1. triggers: ((Event | Effect | Store)[]): any number of Events, Effects, or Stores.

Returns

Store: Current store.

Examples

Basic

import { createEvent, createStore } from "effector";

const increment = createEvent();
const reset = createEvent();

const $store = createStore(0)
  .on(increment, (state) => state + 1)
  .reset(reset);

$store.watch((state) => console.log("changed", state));

increment();
increment();
reset();

Try it

.off(trigger)

Removes reducer for the given trigger.

Formulae

$store.off(trigger);

Arguments

  1. trigger: Event, Effect, or Store.

Returns

Store: Current store.

Examples

Basic

import { createEvent, createStore, merge } from "effector";

const changedA = createEvent();
const changedB = createEvent();

const $store = createStore(0);
const changed = merge([changedA, changedB]);

$store.on(changed, (state, params) => state + params);
$store.off(changed);

Try it

Store Properties

.updates

Returns

Event: Event that represents updates of the given store.

Example

import { createStore, is } from "effector";

const $clicksAmount = createStore(0);
is.event($clicksAmount.updates); // true

$clicksAmount.updates.watch((amount) => {
  console.log(amount);
});

Try it

.reinit

Returns

EventCallable: Event that can reinitialize a store with a default value.

Example

import { createStore, createEvent, sample, is } from "effector";

const $counter = createStore(0);
is.event($counter.reinit);

const increment = createEvent();

$counter.reinit();
console.log($counter.getState());

Try it

.shortName

Returns

(string): ID or short name of the store.

.defaultState

Returns

(State): Default state of the store.

Example

const $store = createStore("DEFAULT");
console.log($store.defaultState === "DEFAULT");

Utility methods

.getState()

Returns the current state of the store.

Returns

(State): Current state of the store.

Example

import { createEvent, createStore } from "effector";

const add = createEvent();

const $number = createStore(0).on(add, (state, data) => state + data);

add(2);
add(3);

console.log($number.getState());

Try it

Readonly store

TBD

Types

import { type StoreValue } from "effector";

StoreValue<S>

Extracts type of Store or StoreWritable value.

const $store: Store<Value>;
type Value = StoreValue<typeof $store>;
Contributors
Commits