;
}
```
* **Детальное описание**
Это свойство избавляет от необходимости писать подобный код:
```js
const $isRequestPending = createStore(false)
.on(requestFx, () => true)
.on(requestFx.done, () => false)
.on(requestFx.fail, () => false);
```
* **Примеры**
```jsx
import React from "react";
import { createEffect } from "effector";
import { useUnit } from "effector-react";
const fetchApiFx = createEffect(async (ms) => {
await new Promise((resolve) => setTimeout(resolve, ms));
});
fetchApiFx.pending.watch(console.log);
// => false
const App = () => {
const loading = useUnit(fetchApiFx.pending);
return {loading ? "Загрузка..." : "Загрузка завершена"}
;
};
fetchApiFx(1000);
// => true
// => false
```
Запустить пример.
***
#### `.inFlight`
[Производный стор][storeTypes], который показывает число запущенных эффектов, которые находятся в процессе выполнения. Может использоваться для ограничения числа одновременных запросов.
* **Тип**
```ts
interface Effect {
inFlight: Store;
}
```
* **Детальное описание**
Это свойство избавляет от необходимости писать подобный код:
```js
const $requestsInFlight = createStore(0)
.on(requestFx, (n) => n + 1)
.on(requestFx.done, (n) => n - 1)
.on(requestFx.fail, (n) => n - 1);
```
* **Примеры**
```js
import { createEffect } from "effector";
const fx = createEffect(async () => {
await new Promise((resolve) => setTimeout(resolve, 500));
});
fx.inFlight.watch((amount) => {
console.log("выполняется запросов:", amount);
});
// => выполняется запросов: 0
const req1 = fx();
// => выполняется запросов: 1
const req2 = fx();
// => выполняется запросов: 2
await Promise.all([req1, req2]);
// => выполняется запросов: 1
// => выполняется запросов: 0
```
Запустить пример.
***
#### `.sid`
Уникальный идентификатор юнита. Важно отметить, что SID не изменяется при каждом запуске приложения, он статически записывается в пакет вашего приложения для абсолютной идентификации юнитов. Задаётся автоматически через Babel plugin.
* **Тип**
```ts
interface Effect {
sid: string | null;
}
```
***
#### `.shortName`
Свойство типа `string`, содержащее имя переменной, в которой объявлен эффект. Имя эффекта. Задаётся либо явно, через поле `name` в createEffect, либо автоматически через babel plugin.
* **Тип**
```ts
interface Effect {
shortName: string;
}
```
***
#### `.compositeName`
Комплексное имя эффекта (включая домен и короткое имя) — удобно для логирования и трассировки.
* **Тип**
```ts
interface Effect {
compositeName: {
shortName: string;
fullName: string;
path: Array;
};
}
```
* **Примеры**
```ts
import { createEffect, createDomain } from "effector";
const first = createEffect();
const domain = createDomain();
const second = domain.createEffect();
console.log(first.compositeName);
// {
// "shortName": "first",
// "fullName": "first",
// "path": [
// "first"
// ]
// }
console.log(second.compositeName);
// {
// "shortName": "second",
// "fullName": "domain/second",
// "path": [
// "domain",
// "second"
// ]
// }
```
### Связанные API и статьи
* **API**
* createEffect - Создание нового эффекта
* Event API - Описание событий, его методов и свойств
* Store API - Описание сторов, его методов и свойств
* sample - Ключевой оператор для построения связей между юнитами
* attach - Создает новые эффекты на основе других эффектов
* **Статьи**
* Работа с эффектами
* Как типизировать эффекты и не только
* Гайд по тестированию эффектов и других юнитов
# Event
import Tabs from "@components/Tabs/Tabs.astro";
import TabItem from "@components/Tabs/TabItem.astro";
## Event API
```ts
import { type Event, type EventCallable, createEvent } from "effector";
const event = createEvent();
```
Событие в effector представляет действие пользователя, шаг в процессе приложения, команду к выполнению или намерение внести изменения и многое другое.
Событие служит как точка входа в реактивный поток данных — простой способ сказать приложению "что-то произошло".
> TIP это ваше каноничное событие:
>
> Если вы не знакомы с событиями и способами работы с ними, то вам сюда Что такое события и как работать с ними.
### Типы событий
Важно понять, что существуют два типа событий:
1. **Обычное событие**, которое создается с помощью createEvent, .prepend; эти события имеют тип EventCallable и могут быть вызваны, либо использованы в target метода sample.
2. **Производное событие**, который создается с помощью .map, .filter, .filterMap. Такие события имеют тип Event и их **нельзя вызывать или передавать в target**, effector сам вызовет их в нужном порядке, однако вы можете подписываться на эти события с помощью sample или watch.
### Интерфейс Event
Доступные методы и свойства событий:
| Метод/Свойство
| Описание |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| prepend(fn) | Создаёт новое событие `EventCallable`, трансформируют входные данные через `fn` и передает в исходное событие. |
| map(fn) | Создаёт новое событие типа `Event` с результатом вызова `fn` после срабатывания исходного события. |
| filter({fn}) | Создаёт новое событие типа `Event`, срабатывающий только если `fn` возвращает `true`. |
| filterMap(fn) | Создаёт событие типа `Event`, срабатывающий с результатом `fn`, если тот не вернул `undefined`. |
| watch(watcher) | Добавляет слушатель, вызывающий `watcher` при каждом срабатывании события. |
| subscribe(observer) | Низкоуровневый метод для интеграции события со стандартным шаблоном `Observable`. |
| sid | Уникальный идентификатор юнита (`unit`). |
| shortName | Свойство типа `string`, содержащее имя переменной, в которой объявлено событие. |
| compositeName | Комплексное имя Event (включая домен и короткое имя) — удобно для логирования и трассировки. |
### Методы событий
#### `.prepend(fn)`
> INFO информация:
>
> Этот метод существует **только** для обычных событий (`EventCallable`)! Это значит что этот метод может использоваться только на событиях созданных с помощью createEvent.
Создает новое событие `EventCallable`, который можно вызвать. При его срабатывании вызвает `fn` и передает преобразованные данные в исходное событие.
* **Формула**
```ts
const second = first.prepend(fn);
```
* **Тип**
```ts
event.prepend(
fn: (_: Before) => Payload
): EventCallable
```
* **Примеры**
```ts
import { createEvent } from "effector";
// исходное событие
const userPropertyChanged = createEvent();
const changeName = userPropertyChanged.prepend((name) => ({
field: "name",
value: name,
}));
const changeRole = userPropertyChanged.prepend((role) => ({
field: "role",
value: role.toUpperCase(),
}));
userPropertyChanged.watch(({ field, value }) => {
console.log(`Свойство пользователя "${field}" изменилось на ${value}`);
});
changeName("john");
// => Свойство пользователя "name" изменилось на john
changeRole("admin");
// => Свойство пользователя "role" изменилось на ADMIN
changeName("alice");
// => Свойство пользователя "name" изменилось на alice
```
Открыть пример
Вы можете считать этот метод функцией-обёрткой. Допустим, у нас есть функция с неидеальным API, но нам нужно часто её вызывать:
```ts
import { sendAnalytics } from "./analytics";
export function reportClick(item: string) {
const argument = { type: "click", container: { items: [arg] } };
return sendAnalytics(argument);
}
```
Это именно то, как работает `.prepend()`:
```ts
import { sendAnalytics } from "./analytics";
export const reportClick = sendAnalytics.prepend((item: string) => {
return { type: "click", container: { items: [arg] } };
});
reportClick("example");
// reportClick сработал "example"
// sendAnalytics сработал с { type: "click", container: { items: ["example"] } }
```
* **Детальное описание**
Работает как обратный .map. В случае `.prepend` данные преобразуются **до срабатывания** исходного события, а в случае .map данные преобразуются **после срабатывания**.
Если исходное событие принадлежит какому-либо домену, то новое событие также будет ему принадлежать.
* **Возвращаемое значение**
Возвращает новое событие `EventCallable`.
Ознакомьтесь со всеми другими методами в Event.
***
#### `.map(fn)`
Создает новое производное событие, которое будет вызвано после того, как будет вызвано исходное событие, используя результат функции `fn` в качестве его аргумента.
> INFO Чистота наше все!:
>
> Функция `fn` **должна быть чистой**.
* **Формула**
```ts
// Событие любого типа, как производное так и обычное
const first: Event | EventCallable;
const second: Event = first.map(fn);
```
* **Тип**
```ts
event.map(fn: (payload: Payload) => T): Event
```
* **Примеры**
```ts
import { createEvent } from "effector";
const userUpdated = createEvent<{ name: string; role: string }>();
// вы можете разбить поток данных с помощью метода .map()
const userNameUpdated = userUpdated.map(({ user }) => name);
// либо преобразовать данные
const userRoleUpdated = userUpdated.map((user) => user.role.toUpperCase());
userNameUpdated.watch((name) => console.log(`Имя пользователя теперь [${name}]`));
userRoleUpdated.watch((role) => console.log(`Роль пользователя теперь [${role}]`));
userUpdated({ name: "john", role: "admin" });
// => Имя пользователя теперь [john]
// => Роль пользователя теперь [ADMIN]
```
Открыть пример
* **Детальное описание**
Метод `.map` позволяет вам разбивать и управлять потоком данных, а также извлекать или преобразовывать данные в рамках вашей модели бизнес-логики.
* **Возвращаемое значение**
Возвращает новое производное событие.
***
#### `.filter({ fn })`
> TIP совет:
>
> sample с аргументом `filter` является предпочтительным методом фильтрации:
>
> ```ts
> const event = createEvent();
>
> const filteredEvent = sample({
> clock: event,
> filter: () => true,
> });
> ```
Метод `.filter` генерирует новое производное событие, которое будет вызвано после исходного события,в случае если функция `fn` вернет `true`. Эта специальная функция позволяет вам разбить поток данных на ветви и подписаться на них в рамках модели бизнес-логики.
Это очень удобно, если мы хотим на события которые срабатывают по условию.
* **Формула**
```ts
// Событие любого типа, как производное так и обычное
const first: Event | EventCallable;
const second: Event = first.filter({ fn });
```
* **Тип**
```ts
event.filter(config: {
fn(payload: Payload): boolean
}): Event
```
* **Примеры**
```js
import { createEvent, createStore } from "effector";
const numbers = createEvent();
const positiveNumbers = numbers.filter({
fn: ({ x }) => x > 0,
});
const $lastPositive = createStore(0);
$lastPositive.on(positiveNumbers, (n, { x }) => x);
$lastPositive.watch((x) => {
console.log("последнее положительное:", x);
});
// => последнее положительное: 0
numbers({ x: 0 });
// нет реакции
numbers({ x: -10 });
// нет реакции
numbers({ x: 10 });
// => последнее положительное: 10
```
[Открыть пример](https://share.effector.dev/H2Iu4iJH)
```js
import { createEvent, createStore, sample } from "effector";
const numbers = createEvent();
const positiveNumbers = sample({
clock: numbers,
filter: ({ x }) => x > 0,
});
const $lastPositive = createStore(0);
$lastPositive.on(positiveNumbers, (n, { x }) => x);
$lastPositive.watch((x) => {
console.log("последнее положительное:", x);
});
// => последнее положительное: 0
numbers({ x: 0 });
// нет реакции
numbers({ x: -10 });
// нет реакции
numbers({ x: 10 });
// => последнее положительное: 10
```
* **Возвращаемое значение**
Возвращает новое производное событие.
***
#### `.filterMap(fn)`
> TIP наш любимый sample:
>
> Этот метод также можно заменить на операцию sample с аргументами `filter` + `fn`:
>
> ```ts
> const event = createEvent();
>
> const filteredAndMappedEvent = sample({
> clock: event,
> filter: () => true,
> fn: () => "value",
> });
> ```
Этот метод генерирует новое производное событие, которое **может быть вызвано** после исходного события, но с преобразованным аргументом. Этот специальный метод позволяет одновременно преобразовывать данные и фильтровать срабатывание события.
Этот метод наиболее полезен с API JavaScript, которые иногда возвращают `undefined`.
* **Формула**
```ts
// Событие любого типа, как производное так и обычное
const first: Event | EventCallable;
const second: Event = first.filterMap(fn);
```
* **Тип**
```ts
event.filterMap(fn: (payload: Payload) => T | undefined): Event
```
* **Примеры**
```tsx
import { createEvent } from "effector";
const listReceived = createEvent();
// Array.prototype.find() возвращает `undefined`, когда элемент не найден
const effectorFound = listReceived.filterMap((list) => {
return list.find((name) => name === "effector");
});
effectorFound.watch((name) => console.info("найден", name));
listReceived(["redux", "effector", "mobx"]); // => найден effector
listReceived(["redux", "mobx"]);
```
> INFO Внимание:
>
> Функция `fn` должна возвращать некоторые данные. Если возвращается `undefined`, вызов производного события будет пропущено.
Открыть пример
* **Возвращаемое значение**
Возвращает новое производное событие.
***
#### `.watch(watcher)`
Метод `.watch` вызывается колбэк `watcher` каждый раз при срабатывании события.
> TIP Помните:
>
> Метод `watch` не обрабатывает и не сообщает о исключениях, не управляет завершением асинхронных операций и не решает проблемы гонки данных.
>
> Его основное предназначение — для краткосрочного отладки и логирования.
Подробнее в разделе изучения.
* **Формула**
```ts
// Событие любого типа, как производное так и обычное
const event: Event | EventCallable;
const unwatch: () => void = event.watch(fn);
```
* **Тип**
```ts
event.watch(watcher: (payload: Payload) => any): Subscription
```
* **Примеры**
```js
import { createEvent } from "effector";
const sayHi = createEvent();
const unwatch = sayHi.watch((name) => console.log(`${name}, привет!`));
sayHi("Питер"); // => Питер, привет!
unwatch();
sayHi("Дрю"); // => ничего не произошло
```
Открыть пример
* **Возвращаемое значение**
Возвращает функцию для отмены подписки.
***
#### `.subscribe(observer)`
Это низкоуровневый метод для интеграции события со стандартным шаблоном `Observable`.
Подробнее:
* https://rxjs.dev/guide/observable
* https://github.com/tc39/proposal-observable
> INFO Помните:
>
> Вам не нужно использовать этот метод самостоятельно. Он используется под капотом движками рендеринга и так далее.
* **Формула**
```ts
const event = createEvent();
event.subscribe(observer);
```
* **Тип**
```ts
event.subscribe(observer: Observer): Subscription
```
* **Примеры**
```ts
import { createEvent } from "effector";
const userLoggedIn = createEvent();
const subscription = userLoggedIn.subscribe({
next: (login) => {
console.log("User login:", login);
},
});
userLoggedIn("alice"); // => User login: alice
subscription.unsubscribe();
userLoggedIn("bob"); // ничего не произойдет
```
### Свойства
Этот набор свойств в основном задается с помощью effector/babel-plugin или @effector/swc-plugin. Таким образом, они существуют только при использовании Babel или SWC.
#### `.sid`
Это уникальный идентификатор для каждого события.
Важно отметить, что SID не изменяется при каждом запуске приложения, он статически записывается в пакет вашего приложения для абсолютной идентификации юнитов.
Это может быть полезно для отправки событий между рабочими или
сервером/браузером: [examples/worker-rpc](https://github.com/effector/effector/tree/master/examples/worker-rpc).
* **Тип**
```ts
interface Event {
sid: string | null;
}
```
***
#### `.shortName`
Это свойство содержащее имя переменной, в которой объявлено событие.
```ts
import { createEvent } from "effector";
const demo = createEvent();
// demo.shortName === 'demo'
```
Но переопределение события в другую переменную ничего не изменит:
```ts
const another = demo;
// another.shortName === 'demo'
```
* **Тип**
```ts
interface Event {
shortName: string;
}
```
***
#### `.compositeName`
Это свойство содержит полную внутреннюю цепочку юнитов. Например, событие может быть создано доменом, поэтому составное имя будет содержать имя домена внутри него.
> TIP Помните:
>
> Обычно, если требуется длинное имя, лучше передать его явно в поле `name`.
```ts
import { createEvent, createDomain } from "effector";
const first = createEvent();
const domain = createDomain();
const second = domain.createEvent();
console.log(first.compositeName);
// {
// "shortName": "first",
// "fullName": "first",
// "path": [
// "first"
// ]
// }
console.log(second.compositeName);
// {
// "shortName": "second",
// "fullName": "domain/second",
// "path": [
// "domain",
// "second"
// ]
// }
```
* **Тип**
```ts
interface Event {
compositeName: {
shortName: string;
fullName: string;
path: Array;
};
}
```
### Особенности Event
1. В Effector любое событие поддерживает только **один аргумент**.
Вызов события с двумя или более аргументами, как в случае `someEvent(first, second)`, будет игнорировать все аргументы кроме первого.
2. В методах событий нельзя вызывать другие события или эффекты - **функции должны быть чистыми**
### Связанные API и статьи
* **API**
* createEvent - Создание нового события
* createApi - Создание набора событий для стора
* merge - Слияние событий в одно
* sample - Ключевой оператор для построения связей между юнитами
* **Статьи**
* Как работать с событиями
* Как мыслить в effector и почему события важны
* Гайд по типизации событий и юнитов
# Scope API
## Scope API
```ts
import { type Scope, fork } from "effector";
const scope = fork();
```
`Scope` — это полностью изолированный экземпляр приложения.
Основное назначение скоупа связано с SSR (Server-Side Rendering), но не ограничивается только этим случаем использования.
Скоуп содержит независимую копию всех юнитов (включая связи между ними), а также базовые методы для работы с ними.
> TIP скоуп важен:
>
> Если вы хотите глубже разобраться в скоупах, ознакомьтесь с отличной статьёй про изолированыне контексты.
> У нас также есть несколько гайдов связанных со скоупом:
>
> * Как исправить потерянный скоуп
> * Использование скоупов с SSR
> * Написание тестов
### Особенности скоупов
1. Существует несколько правил, которые нужно соблюдать, чтобы успешно работать со скоупом.
2. Скоуп можно потерять — чтобы этого избежать, используйте .
### Методы скоупа
#### `.getState($store)`
Возвращает значение стора в данном скоупе:
* **Формула**
```ts
const scope: Scope;
const $value: Store | StoreWritable;
const value: T = scope.getState($value);
```
* **Тип**
```ts
scope.getState(store: Store): T;
```
* **Возвращает**
Значение стора.
* **Пример**
Создадим два экземпляра приложения, вызовем события в каждом из них и проверим значение стора `$counter` в обоих случаях:
```js
import { createStore, createEvent, fork, allSettled } from "effector";
const inc = createEvent();
const dec = createEvent();
const $counter = createStore(0);
$counter.on(inc, (value) => value + 1);
$counter.on(dec, (value) => value - 1);
const scopeA = fork();
const scopeB = fork();
await allSettled(inc, { scope: scopeA });
await allSettled(dec, { scope: scopeB });
console.log($counter.getState()); // => 0
console.log(scopeA.getState($counter)); // => 1
console.log(scopeB.getState($counter)); // => -1
```
Попробовать.
### Связанные API и статьи
* **API**
* scopeBind – Метод для привязки юнита к скоупу
* fork – Оператор для создания скоупа
* allSettled – Метод для вызова юнита в указанном скоупе и ожидания завершения всей цепочки эффектов
* serialize – Метод для получения сериализованных значений сторов
* hydrate – Метод для гидрации сериализованных данных
* **Статьи**
* Что такое потеря скоупа и как её исправить
* Использование скоупов с SSR
* Как тестировать юниты
# Store API
## Store API
```ts
import { type Store, type StoreWritable, createStore } from "effector";
const $store = createStore();
```
*Store* — это объект, который хранит значение состояния. Обновление стора происходит когда новое значение не равно (`!==`) текущему, а также когда не равно `undefined` (если в конфигурации стора не указан `skipVoid:false`). Стор является Unit. Некоторые сторы могут быть производными.
> TIP Кто такой этот ваш стор?:
>
> Если вы еще не знакомы как работать со стором, то добро пожаловать сюда.
### Интерфейс стора
Доступные методы и свойства стора:
| Метод/Свойство | Описание |
| ------------------------------------------------------ | ------------------------------------------------------------- |
| map(fn) | Создает новый производный стор |
| on(trigger, reducer) | Обновление стейта c помощью `reducer`, когда вызван `trigger` |
| watch(watcher) | Вызывает функцию `watcher` каждый раз, когда стор обновляется |
| reset(...triggers) | Метод для сброса к начальному состоянию |
| off(trigger) | Удаляет подписку на указанный триггер |
| updates() | Событие срабатывающие при обновление стора |
| reinit() | Событие для реинициализации стора |
| shortName | ID или короткое имя store |
| defaultState | Начальное состояние стора |
| getState() | Возвращает текущий стейт |
### Иммутабельность
Store в effector иммутабелен. Это значит, что обновления в нём будут происходить только если в функции-обработчике (например `combine`, `sample` или `on`) вернуть новый объект
Например, прежде чем использовать методы массива, нужно создать новую ссылку на него. Как правильно:
```ts
$items.on(addItem, (items, newItem) => {
const updatedItems = [...items];
// ✅ метод .push вызывается на новом массиве
updatedItems.push(newItem);
return updatedItems;
});
```
Так делать нельзя, обновления стора **не произойдёт**
```ts
$items.on(addItem, (items, newItem) => {
// ❌ ошибка! Ссылка на массив осталась та же, обновления стора не произойдёт
items.push(newItem);
return items;
});
```
Обновление объектов происходит аналогичным образом
Сторы в effector должен быть размером как можно меньше, чтобы отвечать за конкретную часть в бизнес логике, в отличии от например redux стора, который имеет тенденцию к тому чтобы держать рядом всё и сразу. Когда состояние атомарное, то необходимости в спредах объектов становится меньше. Однако, если возникает потребность часто обновлять сильно вложенные данные, для обновления состояния допустимо применять [immer](https://immerjs.github.io/immer/produce) чтобы упростить повторяющийся код
### Методы стора
#### `.map(fn)`
Принимает функцию `fn` и возвращает производный стор, который автоматически обновляется, когда исходный стор изменяется.
* **Формула**
```ts
$source.map(fn, config?);
```
* **Тип**
```ts
const $derived = $source.map(
fn: (value: SourceValue) => T,
config?: {
skipVoid?: boolean
}
): Store
```
* **Примеры**
Базовое использование:
```ts
import { createEvent, createStore } from "effector";
const changed = createEvent();
const $title = createStore("");
const $titleLength = $title.map((title) => title.length);
$title.on(changed, (_, newTitle) => newTitle);
$titleLength.watch((length) => {
console.log("new length", length);
});
changed("hello");
changed("world");
changed("hello world");
```
Попробовать
Вторым аргументом можно передать объект конфига со значением `skipVoid:false`, тогда стор сможет принимать `undefined` значения:
```js
const $titleLength = $title.map((title) => title.length, { skipVoid: false });
```
* **Детальное описание**
Метод `map` вызывает переданную функцию `fn` с состоянием исходного стора в аргументе, каждый раз когда оригинальный стор обновляется.
Результат выполнения функции используется как значение стора.
* **Возвращаемое значение**
Возвращает новый производный стор.
#### `.on(trigger, reducer)`
Обновляет состояние используя reducer, при срабатывании `trigger`.
* **Формула**
```ts
$store.on(trigger, reducer);
```
* **Тип**
```ts
$store.on(
trigger: Unit | Unit[]
reducer: (state: State, payload: T) => State | void
): this
```
* **Примеры**
```ts
import { createEvent, createStore } from "effector";
const $counter = createStore(0);
const incrementedBy = createEvent();
$counter.on(incrementedBy, (value, incrementor) => value + incrementor);
$counter.watch((value) => {
console.log("updated", value);
});
incrementedBy(2);
incrementedBy(2);
```
Попробовать
* **Возвращаемое значение**
Возвращает текущий стор.
#### `.watch(watcher)`
Вызывает функцию `watcher` каждый раз, когда стор обновляется.
* **Формула**
```ts
const unwatch = $store.watch(watcher);
```
* **Тип**
```ts
$store.watch(watcher: (state: State) => any): Subscription
```
* **Примеры**
```ts
import { createEvent, createStore } from "effector";
const add = createEvent();
const $store = createStore(0);
$store.on(add, (state, payload) => state + payload);
$store.watch((value) => console.log(`current value: ${value}`));
add(4);
add(3);
```
Попробовать
* **Возвращаемое значение**
Возвращает функцию для отмены подписки.
#### `.reset(...triggers)`
Сбрасывает состояние стора до значения по умолчанию при срабатывании любого `trigger`.
* **Формула**
```ts
$store.reset(...triggers);
```
* **Тип**
```ts
$store.reset(...triggers: Array>): this
```
* **Примеры**
```ts
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();
```
Попробовать
* **Возвращаемое значение**
Возвращает текущий стор.
#### `.off(trigger)`
Удаляет reducer для указанного `trigger`.
* **Формула**
```ts
$store.off(trigger);
```
* **Тип**
```ts
$store.off(trigger: Unit): this
```
* **Примеры**
```ts
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);
```
Попробовать
* **Возвращаемое значение**
Возвращает текущий стор.
### Свойства стора
#### `.updates`
Событие срабатывающие при обновление стора.
* **Примеры**
```ts
import { createStore, is } from "effector";
const $clicksAmount = createStore(0);
is.event($clicksAmount.updates); // true
$clicksAmount.updates.watch((amount) => {
console.log(amount);
});
```
Попробовать
* **Возвращаемое значение**
Производное событие, представляющее обновления данного стора.
#### `.reinit`
Событие для реинициализации стора.
* **Примеры**
```ts
import { createStore, createEvent, sample, is } from "effector";
const $counter = createStore(0);
is.event($counter.reinit);
const increment = createEvent();
$counter.reinit();
console.log($counter.getState());
```
Попробовать
* **Возвращаемое значение**
Событие, которое может реинициализировать стор до значения по умолчанию.
#### `.shortName`
Cтроковое свойство, которое содержит ID или короткое имя стора.
* **Примеры**
```ts
const $store = createStore(0, {
name: "someName",
});
console.log($store.shortName); // someName
```
Попробовать
* **Возвращаемое значение**
ID или короткое имя store.
#### `.defaultState`
Свойство, которое содержит значение состояния по умолчанию стора.
* **Пример**
```ts
const $store = createStore("DEFAULT");
console.log($store.defaultState === "DEFAULT"); // true
```
* **Возвращаемое значение**
Значение состояния по умолчанию.
### Вспомогательные методы
#### `.getState()`
Метод, который возвращает текущее состояние стора.
> WARNING Осторожно!:
>
> `getState()` не рекомендуется использовать в бизнес-логике - лучше передавать данные через `sample`.
* **Примеры**
```ts
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());
```
Попробовать
* **Возвращаемое значение**
Текущее состояние стора.
### Связанные API
* createStore - Создает новый стор
* combine - Комбинирует несколько сторов и возращает новый производный стор
* sample - Ключевой оператор для построения связей между юнитами
* createEvent - Создает события
* createEffect - Создает эффекты
# allSettled
## Методы
### `allSettled(unit, {scope, params?})`
Вызывает предоставленный юнит в переданном скоупе и ожидает завершения всех запущенных юнитов.
#### Формула
```ts
allSettled(unit: Event, {scope: Scope, params?: T}): Promise
allSettled(unit: Effect, {scope: Scope, params?: T}): Promise<
| {status: 'done'; value: Done}
| {status: 'fail'; value: Fail}
>
allSettled(unit: Store, {scope: Scope, params?: T}): Promise
```
#### Аргументы
1. `unit`: или , который нужно вызвать.
2. `scope`: — скоуп.
3. `params`: параметры, передаваемые в `unit`.
> INFO Обратите внимание:
>
> Возвращаемое значение для эффекта поддерживается с версии [effector 21.4.0](https://changelog.effector.dev/#effector-21-4-0).
#### Примеры
```ts
const scope = fork();
const event = createEvent();
event.watch(console.log);
await allSettled(event, { scope, params: 123 }); // в консоль выведется 123
```
```ts
const scopeA = fork();
const scopeB = fork();
const $store = createStore(0);
const inc = createEvent();
await allSettled($store, { scope: scopeA, params: 5 });
await allSettled($store, { scope: scopeB, params: -5 });
$store.watch(console.log);
await allSettled(inc, { scope: scopeA, params: 2 }); // в консоль выведется 7
await allSettled(inc, { scope: scopeB, params: 2 }); // в консоль выведется -3
```
### `allSettled(scope)`
Проверяет предоставленный скоуп на наличие текущих вычислений и ожидает их завершения.
#### Формула
```ts
allSettled(scope): Promise
```
#### Аргументы
1. `scope`: — скоуп.
> INFO Начиная с:
>
> effector 22.5.0.
#### Примеры
##### Использование в тестах
Тесты, которые проверяют интеграцию с внешним реактивным API.
```ts
import {createEvent, sample, fork, scopeBind, allSettled} from 'effector'
test('интеграция с externalSource', async () => {
const scope = fork()
const updated = createEvent()
sample({
clock: updated,
target: someOtherLogicStart,
})
// 1. Подписываем событие на внешний источник
const externalUpdated = scopeBind(updated, {scope})
externalSource.listen(() => externalUpdates())
// 2. Запускаем обновление внешнего источника
externalSource.trigger()
// 3. Ожидаем завершения всех запущенных вычислений в области видимости effector, даже если они были запущены не самим effector
await allSettled(scope)
// 4. Проверяем что-либо как обычно
expect(...).toBe(...)
})
```
# attach API
import Tabs from "@components/Tabs/Tabs.astro";
import TabItem from "@components/Tabs/TabItem.astro";
[effectApi]: /ru/api/effector/Effect
[storeApi]: /ru/api/effector/Store
## `attach` API
```ts
import { attach } from "effector";
```
Метод `attach` позволяет создавать новые [эффекты][effectApi] на основе существующих c возможностью доступа к данным из [стора][storeApi]. Этот метод позволяет переиспользовать логику эффектов с разными параметрами и автоматически передавать данные из сторов.
> INFO Свойства прикрепленных эффектов:
>
> Прикрепленный эффект является таким же полноценным эффектом, который имеет собственные свойства `.done`, `.fail`, и др. Они срабатывают только при вызовах прикрепленного эффекта, а не оригинального.
>
> ```ts
> const originalFx = createEffect(async (x: number) => x * 2);
> const attachedFx = attach({ effect: originalFx });
>
> originalFx.done.watch(() => console.log("original done"));
> attachedFx.done.watch(() => console.log("attached done"));
>
> await attachedFx(5);
> // original done
> // attached done
>
> await originalFx(5);
> // original done
> // (attached done не сработает)
> ```
### Алгоритм работы
1. Вы вызываете эффект, который вернул `attach`, передав свои параметры.
2. Если указан `source`, тогда Effector берёт текущее значение из этого стора.
3. Если указан `mapParams`, вызывается эта функция с вашими параметрами и (если есть) данными из `source`.
4. Результат функции `mapParams` передаётся в оригинальный эффект `effect`.
5. Возвращается результат выполнения оригинального эффекта.
### Виды конфигураций `attach`
| Форма
| Описание |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| attach({ effect }) | Создает локальную копию эффекта с тем же поведением. |
| attach({ source, effect }) | Создает эффект, который автоматически передает данные из `source` в оригинальный эффект при вызове. |
| attach({ mapParams, effect }) | Создает эффект с преобразованием входных параметров через функцию `mapParams` перед передачей в оригинальный эффект. |
| attach({ source, mapParams, effect }) | Создает эффект, который комбинирует данные из `source` с входными параметрами через `mapParams` и передает результат в оригинальный эффект. |
### Конфигурации
#### `attach({ effect })`
Создает новый прикрепленный [эффект][effectApi], который будет вызывать `effect` с переданными параметрами как есть. Это позволяет создавать отдельные эффекты с общим поведением.
* **Формула**
```ts
const attachedFx = attach({
effect, // оригинальный эффект чье поведение копируем
name? // имя нового эффекта
});
```
* **Тип**
```ts
export function attach>(config: {
effect: FX;
name?: string;
}): Effect, EffectResult, EffectError>;
```
* **Примеры**
Это позволяет создать *локальную* копию эффекта, чтобы реагировать только на вызовы из текущего *локального* кода.
```ts
// Общий эффект для всего приложения
const sendAnalyticsFx = createEffect(async (event: { name: string; data: any }) => {
console.log("Analytics:", event.name);
});
// В модуле авторизации - локальная копия
const trackAuthFx = attach({
effect: sendAnalyticsFx,
name: "trackAuthFx",
});
// Обрабатываем только события из модуля авторизации
trackAuthFx.done.watch(() => {
console.log("Auth event tracked");
});
// В модуле корзины - другая локальная копия
const trackCartFx = attach({
effect: sendAnalyticsFx,
name: "trackCartFx",
});
// Обрабатываем только события из модуля корзины
trackCartFx.done.watch(() => {
console.log("Cart event tracked");
});
trackAuthFx({ name: "login", data: {} });
// Analytics: login
// Auth event tracked
trackCartFx({ name: "add_to_cart", data: {} });
// Analytics: add_to_cart
// Cart event tracked
```
Запустить пример.
#### `attach({ source, effect })`
Создает новый прикрепленный [эффект][effectApi], который при вызове будет запускать оригинальный эффект `effect` или обработчик с данными из `source`.
* **Формула**
```ts
const attachedFx = attach({
source, // источник данных передаваемый в эффект
effect, // оригинальный эффект чье поведение копируем
name? // имя нового эффекта
domain? //домен, в случае если effect это обработчик
});
```
* **Тип**
```ts
export function attach<
States extends StoreShape,
FX extends
| Effect, any, any>
| ((state: GetShapeValue, ...params: any[]) => any),
>(config: {
source: States;
effect: FX;
name?: string;
domain?: Domain;
}): Effect, EffectError>;
```
* **Особенности**
* Аргумент `effect` может быть как [эффектом][effectApi], так и обычным обработчиком.
* Аргумент `source` не является реактивным - изменения сторов не вызывают автоматический запуск эффекта.
* `source` может быть стором, объектом сторов или массивом сторов.
* Параметр `domain` может быть передан только в случае, если `effect` является обработчиком.
* **Примеры**
Простое использование с одним стором и обработчиком:
```ts
// Эффект для загрузки данных
const loadDataFx = createEffect(async (id: number) => {
return fetch(`/api/data/${id}`).then((res) => res.json());
});
// Стор с текущим id
const $currentId = createStore(1);
// Эффект с привязкой стора
const loadCurrentDataFx = attach({
source: $currentId,
effect: async (id: number) => {
const res = await fetch(`/api/data/${id}`);
return await res.json();
},
});
```
Аргумент `source` как объект:
```ts
import { createEffect, createStore, attach } from "effector";
const requestPageFx = createEffect<{ page: number; size: number }, number>(
async ({ page, size }) => {
console.log("Запрошено", page);
return page * size;
},
);
const $page = createStore(1);
const $size = createStore(20);
const requestNextPageFx = attach({
source: { page: $page, size: $size },
effect: requestPageFx,
});
$page.on(requestNextPageFx.done, (page) => page + 1);
requestPageFx.doneData.watch((position) => console.log("requestPageFx.doneData", position));
await requestNextPageFx();
// => Запрошено 1
// => requestPageFx.doneData 20
```
Использование с массивом сторов:
```ts
const $lat = createStore(55.7558);
const $lon = createStore(37.6173);
// Эффект получения погоды
const fetchWeatherFx = createEffect(([lat, lon]: [number, number]) =>
fetch(`/api/weather?lat=${lat}&lon=${lon}`).then((res) => res.json()),
);
// Объединение массива сторов
const loadWeatherFx = attach({
source: combine([$lat, $lon]),
effect: fetchWeatherFx,
});
```
* **Возвращаемое значение**
Возвращает новый [эффект][effectApi].
#### `attach({ mapParams, effect })`
Создает новый прикрепленный [эффект][effectApi], который при вызове будет запускать оригинальный эффект `effect`, преобразуя параметры с помощью функции `mapParams`.
* **Формула**
```ts
const attachedFx = attach({
effect, // оригинальный эффект чье поведение копируем
mapParams, // функция для преобразования данных
name? // имя нового эффекта
});
```
* **Тип**
```ts
export function attach>(config: {
effect: FX;
mapParams: (params: Params) => EffectParams;
name?: string;
}): Effect, EffectError>;
```
* **Особенности**
* Если `mapParams` завершится с ошибкой, тогда прикрепленный эффект сразу завершит свое выполнение, а оригинальный эффект не вызовется.
* `mapParams` должна возвращать тот же тип, который принимает `originalFx` в качестве параметров. В случае ошибки вам нужно самому проконтролировать совместимость типов ошибок с эффектом, TypeScript здесь не поможет.
```ts
const attachedFx: Effect = attach({
effect: originalFx,
mapParams: (): A {
throw new AnyNonFailType(); // Это может быть несовместимо с типом `Fail`.
},
});
```
* **Примеры**
С помощью `mapParams` можно преобразовать аргументы:
```ts
import { createEffect, attach } from "effector";
const originalFx = createEffect((a: { input: number }) => a);
const attachedFx = attach({
effect: originalFx,
mapParams(a: number) {
return { input: a * 100 };
},
});
originalFx.watch((params) => console.log("originalFx started", params));
attachedFx(1);
// => originalFx { input: 100 }
```
Запустить пример
А также обрабатывать исключения:
```ts
import { createEffect, attach } from "effector";
const originalFx = createEffect((a: { a: number }) => a);
const attachedFx = attach({
effect: originalFx,
mapParams(a: number) {
throw new Error("custom error");
return { a };
},
});
attachedFx.failData.watch((error) => console.log("attachedFx.failData", error));
attachedFx(1);
// => attachedFx.failData
// => Error: custom error
```
Запустить пример
* **Возвращаемое значение**
Возвращает новый [эффект][effectApi].
#### `attach({ source, mapParams, effect })`
Создает новый прикрепленный [эффект][effectApi], который будет читать значения из `source` стора, передавать их с параметрами в функцию `mapParams`, а затем вызывать `effect` с результатом.
* **Формула**
```ts
const attachedFx = attach({
source, // источник данных передаваемый в эффект
mapParams, // функция для преобразования данных
effect, // оригинальный эффект чье поведение копируем
name? // имя нового эффекта
});
```
* **Тип**
```ts
export function attach<
States extends StoreShape,
FX extends Effect,
FN extends (params: any, source: GetShapeValue) => EffectParams,
>(config: {
source: States;
effect: FX;
mapParams: FN;
name?: string;
}): Effect[0], EffectResult, EffectError>;
```
* **Особенности**
* Если `mapParams` завершится с ошибкой, тогда прикрепленный эффект сразу завершит свое выполнение, а оригинальный эффект не вызовется.
* Функция `mapParams` должна возвращать тот же тип, который принимает эффект в аргументе `effect` в качестве параметров. В случае ошибки вам нужно самому проконтролировать совместимость типов ошибок с эффектом, TypeScript здесь не поможет.
* Аргумент `source` не является реактивным - изменения сторов не вызывают автоматический запуск эффекта.
* `source` может быть стором, объектом сторов или массивом сторов.
* **Примеры**
```ts
import { createStore, createEvent, createEffect, attach, sample } from "effector";
const $credentials = createStore({ username: "", password: "" });
const $authToken = createStore("");
const apiFx = createEffect(async ({ url, data, token }) => {
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: token ? `Bearer ${token}` : "",
},
body: JSON.stringify(data),
});
return response.json();
});
const loginFx = attach({
source: { creds: $credentials, token: $authToken },
mapParams: (_, { creds, token }) => ({
url: "/api/login",
data: creds,
token,
}),
effect: apiFx,
});
```
* **Возвращаемое значение**
Возвращает новый [эффект][effectApi].
### Связанные API и статьи
* **API**
* Effect API - Описание эффектов, его методов и свойств
* createEffect - Создание нового эффекта
* sample - Ключевой оператор для построения связей между юнитами
* Store API - Описание сторов, его методов и свойств
* **Статьи**
* Работа с эффектами
* Типизация
# Babel плагин
Встроенный плагин для Babel может использоваться для SSR и отладки. Он добавляет имя юнита,
выведенное из имени переменной, и `sid` (Стабильный Идентификатор), вычисленный из местоположения в исходном коде.
Например, в случае эффектов без обработчиков, это улучшает сообщения об ошибках,
показывая, в каком именно эффекте произошла ошибка.
```js
import { createEffect } from "effector";
const fetchFx = createEffect();
fetchFx();
// => no handler used in fetchFx
```
Запустить пример
## Использование
В простейшем случае его можно использовать без какой-либо конфигурации:
```json
// .babelrc
{
"plugins": ["effector/babel-plugin"]
}
```
## SID
> INFO Начиная с:
>
> [effector 20.2.0](https://changelog.effector.dev/#effector-20-2-0)
Стабильный хэш-идентификатор для событий, эффектов, сторов и доменов, сохраняемый между окружениями, для обработки взаимодействия клиент-сервер
в рамках одной кодовой базы.
Ключевое значение sid заключается в том, что он может быть автоматически сгенерирован `effector/babel-plugin` с конфигурацией по умолчанию, и он будет стабильным между сборками.
> TIP Подробное объяснение:
>
> Если вам нужно подробное объяснение о том, зачем нужны SID и как они используются внутри, вы можете найти его, перейдя по этой ссылке
Смотрите [пример проекта](https://github.com/effector/effector/tree/master/examples/worker-rpc)
```js
// common.js
import { createEffect } from "effector";
export const getUser = createEffect({ sid: "GET /user" });
console.log(getUsers.sid);
// => GET /user
```
```js
// worker.js
import { getUsers } from "./common.js";
getUsers.use((userID) => fetch(userID));
getUsers.done.watch(({ result }) => {
postMessage({ sid: getUsers.sid, result });
});
onmessage = async ({ data }) => {
if (data.sid !== getUsers.sid) return;
getUsers(data.userID);
};
```
```js
// client.js
import { createEvent } from "effector";
import { getUsers } from "./common.js";
const onMessage = createEvent();
const worker = new Worker("worker.js");
worker.onmessage = onMessage;
getUsers.use(
(userID) =>
new Promise((rs) => {
worker.postMessage({ sid: getUsers.sid, userID });
const unwatch = onMessage.watch(({ data }) => {
if (data.sid !== getUsers.sid) return;
unwatch();
rs(data.result);
});
}),
);
```
## Конфигурация
### `hmr`
> INFO Начиная с:
>
> [effector 23.4.0](https://changelog.effector.dev/#effector-23.4.0)
Включите поддержку Hot Module Replacement (HMR) для очистки связей, подписок и побочных эффектов, управляемых Effector. Это предотвращает двойное срабатывание эффектов и подписок
> WARNING Взаимодействие с фабриками:
>
> Поддержка HMR показывает наилучшие результаты когда все фабрики в проекте правильно описаны, это помогает плагину и рантайму понимать, какой код нужно удалять при обновлении
#### Формула
```json
"effector/babel-plugin",
{
"hmr": "es"
}
]
```
* Тип: `boolean` | `"es"` | `"cjs"`
* `true`: Использует API HMR с автоопределением необходимого варианта работы. Работает на базе функциональности бабеля [supportsStaticESM](https://babeljs.io/docs/options#caller), которая широко поддерживается в сборщиках
* `"es"`: Использует API HMR `import.meta.hot` в сборщиках, соответствующих ESM, таких как Vite и Rollup
* `"cjs"`: Использует API HMR `module.hot` в сборщиках, использующих CommonJS модули, таких как Webpack, Next.js и React Native
* `false`: Отключает Hot Module Replacement.
* По умолчанию: `false`
> INFO Сборка для продакшна:
>
> При сборке для продакшена убедитесь, что задали опции `hmr` значение `false` или удалили опцию полностью, чтобы уменьшить размер бандла и улучшить производительность в runtime.
### `importName`
Указание имени или имен импорта для обработки плагином. Импорт должен использоваться в коде как указано.
#### Формула
```json
[
"effector/babel-plugin",
{
"importName": ["effector"]
}
]
```
* Тип: `string | string[]`
* По умолчанию: `['effector', 'effector/compat']`
### `factories`
Принимает массив имен модулей, экспорты которых рассматриваются как пользовательские фабрики, поэтому каждый вызов функции предоставляет уникальный префикс для sids юнитов внутри них. Используется для
SSR (серверный рендеринг) и не требуется для клиентских приложений.
> INFO с:
>
> [effector 21.6.0](https://changelog.effector.dev/#effector-21-6-0)
#### Формула
```json
[
"effector/babel-plugin",
{
"factories": ["path/here"]
}
]
```
* Тип: `string[]`
* Фабрики могут иметь любое количество аргументов.
* Фабрики могут создавать любое количество юнитов.
* Фабрики могут вызывать любые методы effector.
* Фабрики могут вызывать другие фабрики из других модулей.
* Модули с фабриками могут экспортировать любое количество функций.
* Фабрики должны быть скомпилированы с `effector/babel-plugin`, как и код, который их использует.
#### Примеры
```json
// .babelrc
{
"plugins": [
[
"effector/babel-plugin",
{
"factories": ["src/createEffectStatus", "~/createCommonPending"]
}
]
]
}
```
```js
// ./src/createEffectStatus.js
import { rootDomain } from "./rootDomain";
export function createEffectStatus(fx) {
const $status = rootDomain.createStore("init").on(fx.finally, (_, { status }) => status);
return $status;
}
```
```js
// ./src/statuses.js
import { createEffectStatus } from "./createEffectStatus";
import { fetchUserFx, fetchFriendsFx } from "./api";
export const $fetchUserStatus = createEffectStatus(fetchUserFx);
export const $fetchFriendsStatus = createEffectStatus(fetchFriendsFx);
```
Импорт `createEffectStatus` из `'./createEffectStatus'` рассматривался как фабричная функция, поэтому каждый стор, созданный ею,
имеет свой собственный sid и будет обрабатываться serialize
независимо, хотя без `factories` они будут использовать один и тот же `sid`.
### `reactSsr`
Заменяет импорты из `effector-react` на `effector-react/scope`. Полезно для сборки как серверных, так и клиентских
сборок из одной кодовой базы.
> WARNING Устарело:
>
> С [effector 23.0.0](https://changelog.effector.dev/#effector-23-0-0) команда разработчиков рекомендует удалить эту опцию из конфигурации `babel-plugin`, потому что effector-react поддерживает SSR по умолчанию.
#### Формула
```json
[
"effector/babel-plugin",
{
"reactSsr": false
}
]
```
* Тип: `boolean`
* По умолчанию: `false`
### `addNames`
Добавляет имя к вызовам фабрик юнитов. Полезно для минификации и обфускации production сборок.
> INFO Начиная с:
>
> [effector 21.8.0](https://changelog.effector.dev/#effector-21-8-0)
#### Формула
```json
[
"effector/babel-plugin",
{
"addNames": true
}
]
```
* Тип: `boolean`
* По умолчанию: `true`
### `addLoc`
Добавляет местоположение к вызовам методов. Используется devtools, например [effector-logger](https://github.com/effector/logger).
#### Формула
```json
[
"effector/babel-plugin",
{
"addLoc": false
}
]
```
* Тип: `boolean`
* По умолчанию: `false`
### `debugSids`
Добавляет путь к файлу и имя переменной определения юнита к sid. Полезно для отладки SSR.
#### Формула
```json
[
"effector/babel-plugin",
{
"debugSids": false
}
]
```
* Тип: `boolean`
* По умолчанию: `false`
### `noDefaults`
Опция для `effector/babel-plugin` для создания пользовательских фабрик юнитов с чистой конфигурацией.
> INFO с:
>
> [effector 20.2.0](https://changelog.effector.dev/#effector-20-2-0)
#### Формула
```json
[
"effector/babel-plugin",
{
"noDefaults": false
}
]
```
* Тип: `boolean`
* По умолчанию: `false`
#### Примеры
```json
// .babelrc
{
"plugins": [
["effector/babel-plugin", { "addLoc": true }],
[
"effector/babel-plugin",
{
"importName": "@lib/createInputField",
"storeCreators": ["createInputField"],
"noDefaults": true
},
"createInputField"
]
]
}
```
```js
// @lib/createInputField.js
import { createStore } from "effector";
import { resetForm } from "./form";
export function createInputField(defaultState, { sid, name }) {
return createStore(defaultState, { sid, name }).reset(resetForm);
}
```
```js
// src/state.js
import { createInputField } from "@lib/createInputField";
const foo = createInputField("-");
/*
будет обработано как создатель стор и скомпилировано в
const foo = createInputField('-', {
name: 'foo',
sid: 'z&si65'
})
*/
```
## Использование со сборщиками
### Vite + React (SSR)
Для использования с `effector/babel-plugin`, необходимо выполнить следующие шаги:
1. Установите пакет `@vitejs/plugin-react`.
2. `vite.config.js` должен выглядеть следующим образом:
> Примечание: `effector/babel-plugin` не является отдельным пакетом, он входит в состав `effector`
```js
// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [
react({
babel: {
plugins: ["effector/babel-plugin"],
// Использовать .babelrc файлы
babelrc: true,
// Использовать babel.config.js файлы
configFile: true,
},
}),
],
});
```
# clearNode
Низкоуровневый метод для уничтожения юнитов и их связей
## `clearNode` API
### Формула
```ts
clearNode(unit: Unit): void
clearNode(unit: Unit, config: {deep?: boolean}): void
```
#### Аргументы
1. **`unit`**: Любой юнит включая домены и scope. Переданный юнит будет уничтожен и удалён из памяти
2. **`config?`**: Объект конфигурации
* **`deep?`**: *boolean*
Глубокое удаление. Уничтожает юнит и *все* его производные
#### Возвращает
*void*
### Примеры
#### Пример удаления стора
```js
import { createStore, createEvent, clearNode } from "effector";
const inc = createEvent();
const store = createStore(0).on(inc, (x) => x + 1);
inc.watch(() => console.log("inc called"));
store.watch((x) => console.log("store state: ", x));
// => store state: 0
inc();
// => inc called
// => store state: 1
clearNode(store);
inc();
// => inc called
```
Запустить пример
#### Пример с deep
```js
import { createStore, createEvent, clearNode } from "effector";
const inc = createEvent();
const trigger = inc.prepend(() => {});
const store = createStore(0).on(inc, (x) => x + 1);
trigger.watch(() => console.log("trigger called"));
inc.watch(() => console.log("inc called"));
store.watch((x) => console.log("store state: ", x));
// => store state: 0
trigger();
// => trigger called
// => inc called
// => store state: 1
clearNode(trigger, { deep: true });
trigger();
// no reaction
inc();
// no reaction!
// all units, which depend on trigger, are erased
// including inc and store, because it depends on inc
```
Запустить пример
# combine API
[storeApi]: /ru/api/effector/Store
## `combine` API
```ts
import { combine } from "effector";
```
Метод `combine` позволяет получить состояние из каждого переданного [стора][storeApi] и комбинировать их в одно значение, сохраняя его в новом производном сторе. Полученный стор будет обновляться каждый раз, когда обновляется любой из переданных сторов.
### Алгоритм
1. `combine` читает текущее состояние из всех переданных сторов.
2. Если предоставлена функция трансформации `fn`, она вызывается со значениями из сторов.
3. Результат сохраняется в новом производном сторе.
4. Производный стор обновляется при каждом изменении любого из исходных сторов.
### Особенности
* **Батчинг обновлений**: Когда несколько сторов обновляются одновременно (за один тик), `combine` обрабатывает их все сразу, что приводит к единственному обновлению производного стора.
* **Смешивание сторов с примитивами**: В `combine` можно передавать не только сторы, но и примитивы и объекты. Effector не будет отслеживать мутации этих примитивов и объектов - они рассматриваются как статические значения.
* **Чистые функции трансформации**: Все функции трансформации, передаваемые в `combine`, должны быть чистыми.
* **Проверка строгого равенства**: Если функция трансформации возвращает то же значение, что и предыдущее (сравнение через `!==`), производный стор не обновится.
* **Обработка ошибок**: Если функция трансформации выбрасывает ошибку во время выполнения, приложение завершится сбоем. Это будет исправлено в [effector v24](https://github.com/effector/effector/issues/1163).
### Формы конфигурации
| Форма
| Описание |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------- |
| combine($a, fn) | Трансформирует значение одного стора через `fn`. |
| combine(...$stores, fn?) | Комбинирует несколько сторов/значений, опционально трансформируя через `fn`. |
| combine({ a: $a, b: $b }, fn?) | Комбинирует сторы в объект-стор, опционально трансформируя через `fn`. |
| combine(\[$a, $b], fn?) | Комбинирует сторы в массив-стор, опционально трансформируя через `fn`. |
### Конфигурации
#### `combine($store, fn)`
Создает новый производный стор путем трансформации значения одного стора. Это **предпочтительный метод** для создания производных сторов с одним источником. Является альтернативным способом для Store.map().
* **Формула**
```ts
const $result = combine($source, (value) => {
// логика трансформации
return result;
});
```
* **Тип**
```ts
export function combine(
a: Store,
fn: (a: A) => R,
config?: {
skipVoid?: boolean;
},
): Store;
```
* **Особенности**
* Функция трансформации `fn` должна быть чистой.
* Если `fn` возвращает то же значение, что и предыдущее (сравнение через `!==`), стор не обновится.
* Если `fn` выбрасывает ошибку во время выполнения, приложение завершится сбоем (это будет исправлено в [effector v24](https://github.com/effector/effector/issues/1163)).
* Опциональный параметр `config`: см. конфигурацию для деталей о `skipVoid`.
* **Примеры**
```ts
import { createStore, combine } from "effector";
const $name = createStore("John");
const $greeting = combine($name, (name) => `Hello, ${name}!`);
$greeting.watch((greeting) => console.log(greeting));
// => Hello, John!
```
```ts
import { createStore, combine } from "effector";
const $price = createStore(100);
const $priceWithTax = combine($price, (price) => price * 1.2);
$priceWithTax.watch((price) => console.log("Price with tax:", price));
// => Price with tax: 120
```
* **Возвращает**
Новый производный стор.
***
#### `combine(...$stores, fn?)`
Создает новый производный стор, который комбинирует любое количество сторов и значений. Принимает любое количество аргументов - сторы, примитивы или объекты. Последний аргумент может опционально быть функцией трансформации.
Без `fn` оборачивает все значения в массив. С `fn` трансформирует значения с помощью функции, где сторы передаются как отдельные аргументы.
* **Формула**
```ts
// без функции трансформации
const $result = combine($a);
const $result = combine($a, $b, $c);
// с функцией трансформации
const $result = combine($a, (value) => {
// логика трансформации
return result;
});
const $result = combine($a, $b, $c, (a, b, c) => {
// логика трансформации
return result;
});
```
* **Тип**
```ts
export function combine(
...stores: T
): Store<{ [K in keyof T]: T[K] extends Store ? U : T[K] }>;
export function combine(
...stores: T,
fn: (...stores: [K in keyof T]: T[K] extends Store ? U : T[K]) => R,
config?: { skipVoid?: boolean },
): Store;
// также поддерживает любое количество сторов с опциональной fn в качестве последнего аргумента
```
* **Особенности**
* Принимает любое количество сторов, примитивов или объектов в качестве аргументов.
* Можно смешивать сторы со значениями как примитивы или объекты.
* Без `fn` возвращает массив-стор со значениями в том же порядке, что и аргументы.
* Когда предоставлена `fn`:
* Функция трансформации `fn` должна быть чистой.
* Если `fn` возвращает то же значение, что и предыдущее (сравнение через `!==`), стор не обновится.
* Если `fn` выбрасывает ошибку во время выполнения, приложение завершится сбоем (это будет исправлено в [effector v24](https://github.com/effector/effector/issues/1163)).
* Опциональный параметр `config`: см. конфигурацию для деталей о `skipVoid`.
* **Примеры**
Без функции трансформации - создает массив-стор:
```ts
import { createStore, combine } from "effector";
const $firstName = createStore("John");
const $lastName = createStore("Doe");
const $age = createStore(30);
const $userData = combine($firstName, $lastName, $age);
$userData.watch((data) => console.log(data));
// => ["John", "Doe", 30]
```
С функцией трансформации - трансформирует комбинированные значения:
```ts
import { createStore, combine } from "effector";
const $firstName = createStore("John");
const $lastName = createStore("Doe");
const $fullName = combine($firstName, $lastName, (first, last) => {
return `${first} ${last}`;
});
$fullName.watch((name) => console.log(name));
// => "John Doe"
```
Комбинирование нескольких сторов с трансформацией:
```ts
import { createStore, combine } from "effector";
const $price = createStore(100);
const $quantity = createStore(2);
const $discount = createStore(0.1);
const $total = combine($price, $quantity, $discount, (price, qty, disc) => {
const subtotal = price * qty;
return subtotal - subtotal * disc;
});
$total.watch((total) => console.log(`Total: $${total}`));
// => Total: $180
```
Смешивание сторов с примитивами:
```ts
import { createStore, combine } from "effector";
const $userName = createStore("Alice");
const API_URL = "https://api.example.com";
const $userEndpoint = combine($userName, API_URL, (name, url) => {
return `${url}/users/${name}`;
});
$userEndpoint.watch((endpoint) => console.log(endpoint));
// => https://api.example.com/users/Alice
```
* **Возвращает**
Новый производный стор.
***
#### `combine({ a: $a, b: $b }, fn?)`
Создает новый производный стор, который комбинирует объект сторов. Без `fn` создает объект-стор со значениями из переданных сторов. С `fn` трансформирует комбинированные значения с помощью функции.
* **Формула**
```ts
// без функции трансформации
const $result = combine({
a: $a,
b: $b,
// ... больше сторов
});
// с функцией трансформации
const $result = combine({ a: $a, b: $b, c: $c }, ({ a, b, c }) => {
// логика трансформации
return result;
});
```
* **Тип**
```ts
export function combine(
shape: State,
fn?: (shape: { [K in keyof State]: State[K] extends Store ? U : State[K] }) => R,
config?: {
skipVoid?: boolean;
},
): Store;
```
* **Особенности**
* Обновления батчатся, когда несколько сторов изменяются одновременно.
* Можно смешивать сторы со значениями как примитивы или объекты.
* если предоставлена `fn`:
* Функция трансформации `fn` должна быть чистой.
* Если `fn` возвращает то же значение, что и предыдущее (сравнение через `!==`), стор не обновится.
* Если `fn` выбрасывает ошибку во время выполнения, приложение завершится сбоем (это будет исправлено в [effector v24](https://github.com/effector/effector/issues/1163)).
* Опциональный параметр `config`: см. конфигурацию для деталей о `skipVoid`.
* **Примеры**
Без функции трансформации - создает объект-стор:
```ts
import { createStore, combine } from "effector";
const $firstName = createStore("John");
const $lastName = createStore("Doe");
const $age = createStore(30);
const $user = combine({
firstName: $firstName,
lastName: $lastName,
age: $age,
});
$user.watch((user) => console.log(user));
// => { firstName: "John", lastName: "Doe", age: 30 }
```
С функцией трансформации - трансформирует значения объекта:
```ts
import { createStore, combine } from "effector";
const $firstName = createStore("John");
const $lastName = createStore("Doe");
const $age = createStore(30);
const $userSummary = combine(
{ firstName: $firstName, lastName: $lastName, age: $age },
({ firstName, lastName, age }) => {
return `${firstName} ${lastName}, ${age} years old`;
},
);
$userSummary.watch((summary) => console.log(summary));
// => "John Doe, 30 years old"
```
Практический пример - валидация формы:
```ts
import { createStore, combine } from "effector";
const $email = createStore("");
const $password = createStore("");
const $confirmPassword = createStore("");
const $formValidation = combine(
{ email: $email, password: $password, confirmPassword: $confirmPassword },
({ email, password, confirmPassword }) => {
const errors = [];
if (!email.includes("@")) {
errors.push("Invalid email");
}
if (password.length < 8) {
errors.push("Password must be at least 8 characters");
}
if (password !== confirmPassword) {
errors.push("Passwords don't match");
}
return {
isValid: errors.length === 0,
errors,
};
},
);
```
Смешивание сторов с примитивами и объектами:
```ts
import { createStore, combine } from "effector";
const $userId = createStore(123);
const $isActive = createStore(true);
const $userData = combine({
id: $userId,
isActive: $isActive,
role: "user",
permissions: ["read", "write"],
});
$userData.watch((data) => console.log(data));
// => { id: 123, isActive: true, role: "user", permissions: ["read", "write"] }
```
* **Возвращает**
Новый производный стор.
***
#### `combine([$a, $b], fn?)`
Создает новый производный стор, который комбинирует массив сторов. Без `fn` создает массив-стор со значениями из переданных сторов в том же порядке. С `fn` трансформирует комбинированные значения с помощью функции.
* **Формула**
```ts
// без функции трансформации
const $result = combine([$a, $b, $c]);
// с функцией трансформации
const $result = combine([$a, $b, $c], ([a, b, c]) => {
// логика трансформации
return result;
});
```
* **Тип**
```ts
export function combine(
tuple: State,
): Store<{ [K in keyof State]: State[K] extends Store ? U : State[K] }>;
export function combine(
tuple: State,
fn: (tuple: { [K in keyof State]: State[K] extends Store ? U : State[K] }) => R,
config?: { skipVoid?: boolean },
): Store;
```
* **Особенности**
* Порядок массива совпадает с порядком переданных сторов.
* Обновления батчатся, когда несколько сторов изменяются одновременно.
* Можно смешивать сторы с не-сторовыми значениями, такими как примитивы или объекты.
* Когда предоставлена `fn`:
* Функция трансформации `fn` должна быть чистой.
* Функция получает массив, в котором порядок совпадает с порядком входного массива.
* Если `fn` возвращает то же значение, что и предыдущее (сравнение через `!==`), стор не обновится.
* Если `fn` выбрасывает ошибку во время выполнения, приложение завершится сбоем (это будет исправлено в [effector v24](https://github.com/effector/effector/issues/1163)).
* Опциональный параметр `config`: см. конфигурацию для деталей о `skipVoid`.
* **Примеры**
Без функции трансформации - создает массив-стор:
```ts
import { createStore, combine } from "effector";
const $x = createStore(10);
const $y = createStore(20);
const $z = createStore(30);
const $coordinates = combine([$x, $y, $z]);
$coordinates.watch((coords) => console.log(coords));
// => [10, 20, 30]
```
С функцией трансформации - трансформирует значения массива:
```ts
import { createStore, combine } from "effector";
const $x = createStore(3);
const $y = createStore(4);
const $distance = combine([$x, $y], ([x, y]) => {
return Math.sqrt(x * x + y * y);
});
$distance.watch((dist) => console.log(`Distance: ${dist}`));
// => Distance: 5
```
Практический пример - вычисление итогов из массива:
```ts
import { createStore, combine } from "effector";
const $itemPrice1 = createStore(10);
const $itemPrice2 = createStore(25);
const $itemPrice3 = createStore(15);
const $cartTotal = combine([$itemPrice1, $itemPrice2, $itemPrice3], (prices) => {
return prices.reduce((sum, price) => sum + price, 0);
});
$cartTotal.watch((total) => console.log(`Total: $${total}`));
// => Total: $50
```
Массив с разными типами:
```ts
import { createStore, combine } from "effector";
const $userName = createStore("Alice");
const $score = createStore(100);
const $isActive = createStore(true);
const $playerInfo = combine([$userName, $score, $isActive], ([name, score, active]) => {
return `Player ${name}: ${score} points (${active ? "online" : "offline"})`;
});
$playerInfo.watch((info) => console.log(info));
// => Player Alice: 100 points (online)
```
Смешивание сторов с примитивами в массиве:
```ts
import { createStore, combine } from "effector";
const $currentPage = createStore(1);
const MAX_PAGES = 10;
const $pagination = combine([$currentPage, MAX_PAGES], ([current, max]) => {
return {
current,
max,
hasNext: current < max,
hasPrev: current > 1,
};
});
$pagination.watch((pagination) => console.log(pagination));
// => { current: 1, max: 10, hasNext: true, hasPrev: false }
```
* **Возвращает**
Новый производный стор.
### Связанное API и статьи
* **API**
* Store API - Описание сторов, их методов и свойств
* createStore - Создание нового стора
* sample - Ключевой оператор для построения связей между юнитами
* createEvent - Создание события
* **Статьи**
* Управление состояниями в effector и как использовать производные сторы
# createApi
Способ массового создания событий-команд для обновления стора на основе объекта с функциями-обработчиками. Если стор принадлежит какому-либо домену, то новые события также будут принадлежать ему
## Методы
### Формула
```ts
declare const $store: Store; // управляемый стор
const api: {
event1: Event; // созданное событие-команда
event2: Event; // созданное событие-команда
} = createApi(
/*store*/ $store,
/*handlers*/ {
event1: /*handler*/ (state: T, data: S) => T,
event2: /*handler*/ (state: T, data: Q) => T,
},
);
```
#### Аргументы
1. **`store`**: Стор, чьим значением требуется управлять
2. **`handlers`**: Объект с функциями-обработчиками, на каждую функцию будет создано по событию
**`handler`**: `(state: T, data: S) => T`
Функция-обработчик, которая будет вычислять новое состояние `стора` на основе его предыдущего состояния и данных, отправленных в полученное событие-команду, должна быть
**Аргументы**
* **`state`**: Текущее состояние стора
* **`data`**: Значение, с которым было вызвано событие
**Возвращает**
Новое значение для хранения в `сторе`. Если функция возвращает undefined или текущее состояние стора, то обновления не будет
#### Возвращает
Объект с событиями, по событию на каждый переданный обработчик
### Примеры
#### Управление позицией игрока
```js
import { createStore, createApi } from "effector";
const playerPosition = createStore(0);
const api = createApi(playerPosition, {
moveLeft: (pos, n) => pos - n,
moveRight: (pos, n) => pos + n,
});
playerPosition.watch((pos) => {
console.log("position", pos);
});
// => position 0
api.moveRight(10);
// => position 10
api.moveLeft(5);
// => position 5
```
Запустить пример
# createDomain
Метод для создания доменов
## Методы
```typescript
createDomain(name?)
```
**Аргументы**
1. `name`? (*string*): имя домена
**Возвращает**
: Новый домен
#### Пример
```js
import { createDomain } from "effector";
const domain = createDomain(); // безымянный домен
const httpDomain = createDomain("http"); // именованный домен
const statusCodeChanged = httpDomain.createEvent();
const downloadFx = httpDomain.createEffect();
const apiDomain = httpDomain.createDomain(); // вложенный домен
const $data = httpDomain.createStore({ status: -1 });
```
Запустить пример
# createEffect
## createEffect
```ts
import { createEffect } from "effector";
const effectFx = createEffect();
```
Метод для создания эффектов. Возвращает новый эффект.
### Способы создания эффектов
Метод `createEffect` поддерживает несколько способов создания эффектов:
1. С обработчиком - это самый простой способ.
2. С конфигурацией.
3. А также без обработчика, его можно будет задать позже с помощью метода .use(handler).
#### С обработчиком
* **Тип**
```ts
createEffect(
handler: (params: Params) => Done | Promise,
): Effect
```
* **Пример**
```ts
import { createEffect } from "effector";
const fetchUserReposFx = createEffect(async ({ name }) => {
const url = `https://api.github.com/users/${name}/repos`;
const req = await fetch(url);
return req.json();
});
fetchUserReposFx.done.watch(({ params, result }) => {
console.log(result);
});
await fetchUserReposFx({ name: "zerobias" });
```
#### С конфигурацией
Поле `name` используется для улучшения сообщений об ошибках и отладки.
* **Тип**
```ts
export function createEffect(config: {
name?: string;
handler?: (params: Params) => Promise | Done;
}): Effect;
```
* **Пример**
```ts
import { createEffect } from "effector";
const fetchUserReposFx = createEffect({
name: "fetch user repositories",
async handler({ name }) {
const url = `https://api.github.com/users/${name}/repos`;
const req = await fetch(url);
return req.json();
},
});
await fetchUserReposFx({ name: "zerobias" });
```
#### Без обработчика
Чаще всего используется для тестов. Более подробная информация.
> WARNING use - это антипаттерн:
>
> Старайтесь не использовать `.use()`, так как это является антипаттерном и ухудшает вывод типов.
* **Пример**
```ts
import { createEffect } from "effector";
const fetchUserReposFx = createEffect();
fetchUserReposFx.use(async ({ name }) => {
const url = `https://api.github.com/users/${name}/repos`;
const req = await fetch(url);
return req.json();
});
await fetchUserReposFx({ name: "zerobias" });
```
### Примеры
* **Изменение состояния по завершению эффекта**:
```ts
import { createStore, createEffect } from "effector";
interface Repo {
// ...
}
const $repos = createStore([]);
const fetchUserReposFx = createEffect(async (name: string) => {
const url = `https://api.github.com/users/${name}/repos`;
const req = await fetch(url);
return req.json();
});
$repos.on(fetchUserReposFx.doneData, (_, repos) => repos);
$repos.watch((repos) => {
console.log(`${repos.length} repos`);
});
// => 0 репозиториев
await fetchUserReposFx("zerobias");
// => 26 репозиториев
```
Запустить пример
* **Наблюдение за состоянием эффекта**:
```js
import { createEffect } from "effector";
const fetchUserReposFx = createEffect(async ({ name }) => {
const url = `https://api.github.com/users/${name}/repos`;
const req = await fetch(url);
return req.json();
});
fetchUserReposFx.pending.watch((pending) => {
console.log(`effect is pending?: ${pending ? "yes" : "no"}`);
});
fetchUserReposFx.done.watch(({ params, result }) => {
console.log(params); // {name: 'zerobias'}
console.log(result); // разрешенное значение, результат
});
fetchUserReposFx.fail.watch(({ params, error }) => {
console.error(params); // {name: 'zerobias'}
console.error(error); // отклоненное значение, ошибка
});
fetchUserReposFx.finally.watch(({ params, status, result, error }) => {
console.log(params); // {name: 'zerobias'}
console.log(`handler status: ${status}`);
if (error) {
console.log("handler rejected", error);
} else {
console.log("handler resolved", result);
}
});
await fetchUserReposFx({ name: "zerobias" });
```
Запустить пример
### Основные ошибки
Ниже приведен список возможных ошибок, с которыми вы можете столкнуться при работе с эффектами:
* no handler used in \[effect name]
### Связанные API и статьи
* **API**
* Effect API - Описание эффектов, его методов и свойств
* sample - Ключевой оператор для построения связей между юнитами
* attach - Создает новые эффекты на основе других эффектов
* **Статьи**
* Работа с эффектами
* Как типизировать эффекты и не только
* Гайд по тестированию эффектов и других юнитов
# createEvent
## createEvent
```ts
import { createEvent } from "effector";
const event = createEvent();
```
Метод для создания [событий][eventApi].
### Формула
```ts
createEvent(eventName?: string): EventCallable
createEvent(config: {
name?: string
sid?: string
domain?: Domain
}): EventCallable
```
* **Аргументы**
* `eventName`: Опциональный аргумент. Имя события для отладки.
* `config`: Опциональный аргумент. Объект конфигурации.
* `name`: Имя события.
* `sid`: Стабильный идентификатор для SSR.
* `domain`: Домен для события.
* **Возвращаемое значение**
Возвращает новое вызываемое [событие][eventTypes].
### Примеры
Обновление состояния с помощью вызова события:
```js
import { createStore, createEvent } from "effector";
const addNumber = createEvent();
const $counter = createStore(0);
$counter.on(addNumber, (state, number) => state + number);
$counter.watch((state) => {
console.log("state", state);
});
// => 0
addNumber(10);
// => 10
addNumber(10);
// => 20
addNumber(10);
// => 30
```
Запустить пример
Мы создали событие `addNumber` и стор `$counter`, после чего подписались на обновления стора.
Обратите внимание на вызов функции `addNumber(10)`. Всякий раз, когда вы будете вызывать `addNumber(10)`, вы можете посмотреть в консоль и увидеть, как меняется состояние.
Обработка данных с помощью производных событий:
```js
import { createEvent } from "effector";
const extractPartOfArray = createEvent();
const array = extractPartOfArray.map((arr) => arr.slice(2));
array.watch((part) => {
console.log(part);
});
extractPartOfArray([1, 2, 3, 4, 5, 6]);
// => [3, 4, 5, 6]
```
Запустить пример
### Основные ошибки
Ниже приведён список возможных ошибок, с которыми вы можете столкнуться при работе с событиями:
* call of derived event is not supported, use createEvent instead
* unit call from pure function is not supported, use operators like sample instead
### Связанные API и статьи
* **API**
* [`Event API`][eventApi] - API стора, его методы, свойства и описание
* [`createApi`][createApi] - Создание набора событий для стора
* [`merge`][merge] - Метод для объединения массива юнитов в одно новое событие
* [`sample`][sample] - Связывание событий с другими юнитами
* **Статьи**
* [Как работать с событиями][eventGuide]
* [Как мыслить в effector и почему события важны][mindset]
* [Гайд по типизации событий и других юнитов][typescript]
[eventApi]: /ru/api/effector/Event
[eventTypes]: /ru/api/effector/Event#event-types
[merge]: /ru/api/effector/merge
[eventGuide]: /ru/essentials/events
[mindset]: /ru/resources/mindset
[mindset]: /ru/resources/mindset
[typescript]: /ru/essentials/typescript
[sample]: /ru/api/effector/sample
[createApi]: /ru/api/effector/createApi
# createStore
## createStore
```ts
import { createStore } from "effector";
const $store = createStore();
```
Метод для создания [стора][storeApi].
### Формула
```ts
createStore(
defaultState: State, // Исходное состояние стора
config?: { // Объект конфигурации с дополнительными опциями
skipVoid?: boolean; // Контролирует обновления со значением undefined
name?: string; // Имя стора для отладки
sid?: string // Стабильный идентификатор для SSR
updateFilter?: (update: State, current: State) => boolean // Функция фильтрации обновлений
serialize?: // Конфигурация сериализации для SSR
| 'ignore'
| {
write: (state: State) => SerializedState
read: (json: SerializedState) => State
}
domain?: Domain; // Домен, к которому принадлежит стор
},
): StoreWritable
```
* **Аргументы**
1. **`defaultState`**: Исходное состояние
2. **`config`**: Опциональный объект конфигурации
* **`skipVoid`**: Опциональный аргумент. Определяет пропускает ли [стор][storeApi] `undefined` значения. По умолчанию `true`. В случае если передать в стор, у которого `skipVoid:true`, значение `undefined`, тогда вы получите [ошибку в консоль][storeUndefinedError].
* **`name`**: Опциональный аргумент. Имя стора. [Babel-plugin][babel] может определить его из имени переменной стора, если имя не передано явно в конфигурации.
* **`sid`**: Опциональный аргумент. Уникальный идентификатор стора. [Он используется для различения сторов между разными окружениями][storeSid]. При использовании [Babel-plugin][babel] проставляется автоматически.
* **`updateFilter`**:
Опциональный аргумент. [Чистая функция][pureFn], которая предотвращает обновление стора, если она возвращает `false`. Следует использовать для случаев, когда стандартного запрета на обновление (если значение, которое предполагается записать в стор, равняется `undefined` или текущему значению стора) недостаточно. Если вызывать юниты внутри, то можно столкнуться с [ошибкой][unitCallError].
* **`serialize`**: Опциональный аргумент отвечающий за сериализацию стора.
* `'ignore'`: исключает стор из сериализации при вызовах [serialize][serialize].
* Объект с методами `write` и `read` для кастомной сериализации. `write` вызывается при вызове serialize и приводит состояние стор к JSON-значению – примитив или простой объект/массив. `read` вызывается при fork, если предоставленные `values` – результат вызова [serialize][serialize].
* **Возвращаемое значение**
Возвращает новый [стор][storeApi].
### Примеры
Базовое использование стора:
```js
import { createEvent, createStore } from "effector";
const addTodo = createEvent();
const clearTodos = createEvent();
const $todos = createStore([])
.on(addTodo, (todos, newTodo) => [...todos, newTodo])
.reset(clearTodos);
const $selectedTodos = $todos.map((todos) => {
return todos.filter((todo) => !!todo.selected);
});
$todos.watch((todos) => {
console.log("todos", todos);
});
```
Запустить пример
Пример с кастомной конфигурацией `serialize`:
```ts
import { createEvent, createStore, serialize, fork, allSettled } from "effector";
const saveDate = createEvent();
const $date = createStore(null, {
// Объект Date автоматически приводится в строку ISO-даты при вызове JSON.stringify
// но не приводится обратно к Date при вызове JSON.parse – результатом будет та же строка ISO-даты
// Это приведет к расхождению состояния стора при гидрации состояния на клиенте при серверном рендеринге
//
// Кастомная конфигурация `serialize` решает эту проблему
serialize: {
write: (dateOrNull) => (dateOrNull ? dateOrNull.toISOString() : dateOrNull),
read: (isoStringOrNull) => (isoStringOrNull ? new Date(isoStringOrNull) : isoStringOrNull),
},
}).on(saveDate, (_, p) => p);
const serverScope = fork();
await allSettled(saveDate, { scope: serverScope, params: new Date() });
const serverValues = serialize(serverScope);
// `serialize.write` стор `$date` был вызван
console.log(serverValues);
// => { nq1e2rb: "2022-11-05T15:38:53.108Z" }
// Объект Date из стора сохранен как ISO-дата
const clientScope = fork({ values: serverValues });
// `serialize.read` стор `$date` был вызван
const currentDate = clientScope.getState($date);
console.log(currentDate);
// => Date 11/5/2022, 10:40:13 PM
// Строка ISO-даты приведена обратно к объекту Date
```
Запустить пример
### Типичные ошибки
Ниже приведен список возможных ошибок, с которыми вы можете столкнуться при работе со сторами:
* [`store: undefined is used to skip updates. To allow undefined as a value provide explicit { skipVoid: false } option`][storeUndefinedError].
* [`serialize: One or more stores dont have sids, their values are omitted`][serializeError].
* [`unit call from pure function is not supported, use operators like sample instead`][unitCallError].
### Связанные API и статьи
* **API**
* [`Store API`][storeApi] - API стора, его методы, свойства и описание
* [`createApi`][createApi] - Создание набора событий для стора
* [`combine`][combine] - Создание нового стора на основе других сторов
* [`sample`][sample] - Связывание сторов с другими юнитами
* **Статьи**
* [Как управлять состоянием][storeGuide]
* [Гайд по работе с SSR][ssr]
* [Что такое SID и зачем они нужны сторам][storeSid]
* [Как типизировать сторы и другие юниты][typescript]
[storeApi]: /ru/api/effector/Store
[storeUndefinedError]: /ru/guides/troubleshooting#store-undefined
[storeSid]: /ru/explanation/sids
[ssr]: /ru/guides/server-side-rendering
[storeGuide]: /ru/essentials/manage-states
[combine]: /ru/api/effector/combine
[sample]: /ru/api/effector/sample
[createApi]: /ru/api/effector/createApi
[serialize]: /ru/api/effector/serialize
[typescript]: /ru/essentials/typescript
[babel]: /ru/api/effector/babel-plugin
[pureFn]: /ru/explanation/glossary/#purity
[unitCallError]: /ru/guides/troubleshooting#unit-call-from-pure-not-supported
[serializeError]: /ru/guides/troubleshooting/#store-without-sid
# createWatch
Создает подписку на юнит (store, ивент или эффект).
## Методы
```ts
createWatch(config: {
unit: Unit
fn: (payload: T) => void
scope?: Scope
}): Subscription
```
**Аргументы**
1. `config` (*Object*): Конфигурация
* `unit` (*Unit*): Целевой юнит (store, ивент или эффект), за которым нужно наблюдать
* `fn` (*Function*): Функция, которая будет вызываться при каждом обновлении юнита. Первым аргументом получает содержимое обновления.
* `scope` (): Опциональный скоуп. Если передан, то функция будет вызываться только при обновлении юнита именно на этом скоупе.
**Возвращает**
: Функция отмены подписки
##### Пример (со скоупом)
```js
import { createWatch, createEvent, fork, allSettled } from "effector";
const changeName = createEvent();
const scope = fork();
const unwatch = createWatch({ unit: changeName, scope, fn: console.log });
await allSettled(changeName, { scope, params: "Иван" }); // output: Иван
changeName("Иван"); // no output
```
##### Пример (без скоупа)
```js
import { createWatch, createEvent, fork, allSettled } from "effector";
const changeName = createEvent();
const scope = fork();
const unwatch = createWatch({ unit: changeName, fn: console.log });
await allSettled(changeName, { scope, params: "Иван" }); // output: Иван
changeName("Иван"); // output: Иван
```
# debug traces
## Debug Trace import
```ts
import "effector/enable_debug_traces";
```
A special import that enables detailed traces for difficult-to-debug errors, such as a Store missing a proper SID during Scope serialization.
> WARNING Performance cost:
>
> Debug traces work by capturing additional information when Stores and Events are created.
> This introduces a performance overhead during module initialization.
>
> We do not recommend using this API in production environments.
To enable debug traces, add `import "effector/enable_debug_traces"` to the entrypoint of your bundle, like this:
```ts
// src/index.ts
import "effector/enable_debug_traces";
// ...rest of your code
```
### When to use it
If you encounter an error that can be diagnosed with this API, you will see a recommendation in the console: `Add "import 'effector/enable_debug_traces'" to your code entry module to see full stack traces`.
Don't forget to remove this import once the issue has been resolved.
# fork API
[scopeApi]: /ru/api/effector/Scope
[domainApi]: /ru/api/effector/Domain
[serializeApi]: /ru/api/effector/serialize
[allSettledApi]: /ru/api/effector/allSettled
[hydrateApi]: /ru/api/effector/hydrate
[sampleApi]: /ru/api/effector/sample
[storeApi]: /ru/api/effector/Store
[effectApi]: /ru/api/effector/Effect
## `fork` API
```ts
import { fork, type Scope } from "effector";
```
Метод `fork` создает изолированный [скоуп][scopeApi] приложения. Он нужен для SSR, тестирования и локальной изоляции состояния — вы запускаете вычисления в копии без влияния на глобальные юниты.
### Алгоритм работы
1. Вы вызываете `fork`, получая новый [скоуп][scopeApi].
2. Если переданы `values` или `handlers`, они применяются при создании этого [скоупа][scopeApi].
3. Юниты, вызванные с этим [скоупом][scopeApi], работают с изолированными значениями и обработчиками.
4. Состояние читается через `scope.getState(store)` или сериализуется через [`serialize`][serializeApi].
### Виды конфигураций `fork`
| Форма
| Описание |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| fork() | Создает новый чистый [скоуп][scopeApi] без предзаполненных данных и переопределений обработчиков. |
| fork({ values?, handlers? }) | Создает [скоуп][scopeApi] с начальными значениями сторов и пользовательскими обработчиками эффектов. |
| fork(domain, options?) | Устаревшая форма, требующая `domain`. Используйте `fork({ values?, handlers? })`, если нет зависимости от старой сигнатуры. |
### Конфигурации
#### `fork()`
Создает новый прикладной [скоуп][scopeApi] без дополнительных настроек.
* **Формула**
```ts
fork(): Scope
```
* **Тип**
```ts
type SerializedState = Record;
type StorePair = [StoreWritable, T];
export function fork(config?: {
values?: StorePair[] | SerializedState;
handlers?: Array<[Effect, Function]>;
}): Scope;
```
* **Особенности**
* Возвращает новый [скоуп][scopeApi] без предзаполненных сторов и без замены обработчиков.
* Подходит, когда данные и побочные эффекты должны остаться неизменными (например, первый рендер на сервере).
* **Примеры**
```ts
import { createStore, createEvent, fork, allSettled } from "effector";
const inc = createEvent();
const dec = createEvent();
const $counter = createStore(0);
$counter.on(inc, (value) => value + 1);
$counter.on(dec, (value) => value - 1);
const scopeA = fork();
const scopeB = fork();
await allSettled(inc, { scope: scopeA });
await allSettled(dec, { scope: scopeB });
console.log($counter.getState()); // => 0
console.log(scopeA.getState($counter)); // => 1
console.log(scopeB.getState($counter)); // => -1
```
* **Возвращаемое значение**
Новый [скоуп][scopeApi].
#### `fork({ values?, handlers? })`
Позволяет задать начальные значения для сторов и переопределить обработчики эффектов внутри [скоупа][scopeApi].
* **Формула**
```ts
fork({
values?, // например [[$store, value], ...] или сериализованный объект
handlers?, // например [[effect, handler], ...]
}): Scope
```
* **Тип**
```ts
type SerializedState = Record;
type StorePair = [StoreWritable, T];
export function fork(config?: {
values?: StorePair[] | SerializedState;
handlers?: Array<[Effect, Function]>;
}): Scope;
```
* **Особенности**
* `values` может быть массивом кортежей `[$store, value]` или объектом сериализованного состояния (обычно результат [`serialize`][serializeApi]); предпочтителен массив кортежей.
* `handlers` принимает только массив кортежей, замены работают только в пределах созданного [скоупа][scopeApi].
* Значения и обработчики применяются один раз при создании [скоупа][scopeApi] и не обновляются автоматически.
* **Примеры**
Задание начального состояния и подмена обработчика в тесте:
```ts
import { createEffect, createStore, fork, allSettled } from "effector";
const fetchFriendsFx = createEffect<{ limit: number }, string[]>(async ({ limit }) => {
return [];
});
const $user = createStore("guest");
const $friends = createStore([]);
$friends.on(fetchFriendsFx.doneData, (_, result) => result);
const testScope = fork({
values: [[$user, "alice"]],
handlers: [[fetchFriendsFx, () => ["bob", "carol"]]],
});
await allSettled(fetchFriendsFx, {
scope: testScope,
params: { limit: 10 },
});
console.log(testScope.getState($friends));
// => ['bob', 'carol']
```
Создание [скоупа][scopeApi] с сериализованным состоянием:
```ts
import { fork } from "effector";
const serialized = {
userSid: "alice",
ageSid: 21,
};
const scope = fork({ values: serialized });
```
* **Возвращаемое значение**
Новый [скоуп][scopeApi] с примененными `values` и `handlers`.
#### `fork(domain, options?)`
Устаревшая форма, требующая [domain][domainApi]; актуальна только для совместимости со старым кодом.
> ERROR Устарело:
>
> Используйте `fork({ values?, handlers? })`, так как `fork` отслеживает юниты автоматически без передачи `domain`.
* **Формула**
```ts
fork(domain, {
values?, // например [[$store, value], ...] или сериализованный объект
handlers?, // например [[effect, handler], ...]
}): Scope
```
* **Тип**
```ts
type SerializedState = Record;
export function fork(
domain: Domain,
config?: {
values?: SerializedState | Array<[StoreWritable, any]>;
handlers?: Array<[Effect, Function]>;
},
): Scope;
```
* **Особенности**
* Передача `domain` нужна только в проектах, где код еще зависит от старой сигнатуры.
* Допустимые форматы `values` и `handlers` совпадают с конфигурацией без `domain`.
* **Пример**
```ts
import { createDomain, createStore, fork } from "effector";
const app = createDomain();
const $flag = app.createStore(false);
const scope = fork(app, {
values: [[$flag, true]],
});
console.log(scope.getState($flag)); // => true
```
* **Возвращаемое значение**
Новый [скоуп][scopeApi], привязанный к указанному [domain][domainApi].
### Связанные API и статьи
* **API**
* Scope — структура изолированного состояния
* allSettled — выполнение эффекта внутри [скоупа][scopeApi] с ожиданием завершения
* serialize — сериализация состояния [скоупа][scopeApi]
* hydrate — восстановление состояния в [скоупе][scopeApi]
* **Статьи**
* SSR и работа со скоупом
* Тестирование с isolated скоупом
* Работа со скоупом и потеря контекста
# forward
> ERROR Устаревшее АПИ:
>
> Начиная с версии [effector 23.0.0](https://changelog.effector.dev/#effector-23-0-0).
>
> Используйте sample вместо `forward`.
Метод для создания связи между юнитами в декларативной форме. Отправляет обновления из одного набора юнитов в другой
## Методы
### Формула
```ts
declare const a: Event
declare const fxA: Effect
declare const $a: Store
declare const b: Event
declare const fxB: Effect
declare const $b: Store
forward({from: a, to: b})
forward({
from: fxA,
to: [b, fxB, $b]
})
forward({
from: [a, fxA, $a],
to: fxB
})
forward({
from: [a, fxA, $a],
to: [b, fxB, $b]
})
-> Subscription
```
```
from -> to
```
#### Аргументы
1. **`config`**: Объект конфигурации
* **`from`**: Юнит или массив юнитов
**Разновидности**:
* **событие или эффект**: срабатывание этого события/эффекта будет запускать юниты `to`
* **стор**: обновление этого стора будет запускать юниты `to`
* **массив юнитов**: срабатывание любого из юнитов будет запускать юниты `to`
* **`to`**: Юнит или массив юнитов
**Разновидности**:
* **событие или эффект**: при срабатывании `from` будет вызван данный юнит
* **стор**: при срабатывании `from` состояние юнита будет обновлено
* **массив юнитов**: при срабатывании `from` будут запущены все юниты
#### Возвращает
Subscription: Функция отмены подписки, после её вызова реактивная связь между `from` и `to` разрушается
> INFO:
>
> Массивы юнитов поддерживаются с [effector 20.6.0](https://changelog.effector.dev/#effector-20-6-0)
Для наилучшей типизации при использовании массивов юнитов, типы значений должны совпадать либо быть явно приведены к общему базису
### Примеры
#### Сохранение в сторе данных из события
```js
import { createStore, createEvent, forward } from "effector";
const $store = createStore(1);
const event = createEvent();
forward({
from: event,
to: $store,
});
$store.watch((state) => console.log("store changed: ", state));
// => store changed: 1
event(200);
// => store changed: 200
```
Запустить пример
#### Создание связи между массивами юнитов
```js
import { createEvent, forward } from "effector";
const firstSource = createEvent();
const secondSource = createEvent();
const firstTarget = createEvent();
const secondTarget = createEvent();
forward({
from: [firstSource, secondSource],
to: [firstTarget, secondTarget],
});
firstTarget.watch((e) => console.log("first target", e));
secondTarget.watch((e) => console.log("second target", e));
firstSource("A");
// => first target A
// => second target A
secondSource("B");
// => first target B
// => second target B
```
Запустить пример
# fromObservable
Создаёт событие, которое будет срабатывать при каждом обновлении переданного observable. Применяется для реализации взаимодействия с библиотеками на основе стримов, например `rxjs` и `most`
Для обратного действия подписки стримов на юниты эффектора можно воспользоваться методами вроде `from` из `rxjs`: юниты эффектора распознаются как сущности, на которые можно подписаться
## Методы
### Формула
```ts
function fromObservable(stream: Observable): Event;
```
#### Аргументы
1. **`observable`**: Observable
#### Возвращает
Новое событие
### Пример
```js
import { interval } from "rxjs";
import { fromObservable } from "effector";
//emit value in sequence every 1 second
const source = interval(1000);
const event = fromObservable(source);
//output: 0,1,2,3,4,5....
event.watch(console.log);
```
# guard
> INFO:
>
> C effector 22.2.0 предпочтительнее использовать sample
> INFO:
>
> Добавлен в effector 20.4.0
Метод для запуска юнитов по условию, условием может быть функция-предикат или отдельный стор. Позволяет описывать бизнес-правила независимо от других сущностей.
Типичный вариант использования – когда необходимо запускать события лишь когда в определённом сторе значение равно `true`. Тем самым обеспечивается управление потоками данных без их смешивания
### Формула
```ts
guard({clock?, source?, filter, target?}): target
```
> INFO:
>
> `clock` или `source` обязателен
При срабатывании `clock`, после проверки `filter` на [истинность](https://developer.mozilla.org/ru/docs/Glossary/Truthy), вызывается `target` с данными из `source`
* Если `clock` не передан, `guard` будет срабатывать при каждом обновлении `source`
* Если `source` не передан, `target` будет вызван с данными из `clock`
* Если `target` не передан, будет создано новое событие и возвращено в качестве результата
* Если `filter` это стор, то его значение будет проверено на [истинность](https://developer.mozilla.org/ru/docs/Glossary/Truthy)
* Если `filter` это функция-предикат, то она будет вызвана с данными из `source` и `clock`, а результат проверен на [истинность](https://developer.mozilla.org/ru/docs/Glossary/Truthy)
> INFO:
>
> `clock` добавлен в effector 21.8.0
### `guard({clock?, source?, filter, target?})`
Основная запись метода
**Аргументы**
`params` (*Object*): Объект конфигурации
* **`filter`**: Стор или функция-предикат
**Разновидности**:
* **стор**: `target` будет запущен только если в этом сторе [истинное значение](https://developer.mozilla.org/ru/docs/Glossary/Truthy)
* **функция-предикат** `(source, clock) => boolean`: `target` будет запущен только если эта функция вернёт [истинное значение](https://developer.mozilla.org/ru/docs/Glossary/Truthy). Функция должна быть
* **`clock?`**: Юнит или массив юнитов
**Разновидности**:
* **событие или эффект**: срабатывание этого события/эффекта, после проверки условия в `filter` будет запускать `target`
* **стор**: обновление этого стора, после проверки условия в `filter` будет запускать `target`
* **массив юнитов**: срабатывание любого из юнитов, после проверки условия в `filter` будет запускать `target`. Сокращение для вызова merge
* **поле отсутствует**: `source` будет использоваться в качестве `clock`
* **`source?`**: Юнит или массив/объект со сторами
**Разновидности**:
* **событие или эффект**: при срабатывании `clock` будет взято последнее значение с которым запускался этот юнит (перед этим он должен будет запуститься хотя бы раз)
* **стор**: при срабатывании `clock` будет взято текущее значение этого стора
* **массив или объект со сторами**: при срабатывании `clock` будут взяты текущие значения из заданных сторов, объединенных в объект или массив. Сокращение для вызова combine
* **поле отсутствует**: `clock` будет использоваться в качестве `source`
* **`target?`**: Юнит или массив юнитов
**Разновидности**:
* **событие или эффект**: при срабатывании `clock`, после проверки условия в `filter` будет вызван данный юнит
* **стор**: при срабатывании `clock`, после проверки условия в `filter` состояние юнита будет обновлено
* **массив юнитов**: при срабатывании `clock`, после проверки условия в `filter` будут запущены все юниты
* **поле отсутствует**: новое событие будет создано и возвращено в результате вызова `guard`
**Возвращает**
, событие, которое будет срабатывать после проверки условия в `filter`
#### Пример со стором в `filter`
```js
import { createStore, createEffect, createEvent, guard } from "effector";
const clickRequest = createEvent();
const fetchRequest = createEffect((n) => new Promise((rs) => setTimeout(rs, 2500, n)));
const clicks = createStore(0).on(clickRequest, (x) => x + 1);
const requests = createStore(0).on(fetchRequest, (x) => x + 1);
const isIdle = fetchRequest.pending.map((pending) => !pending);
/*
1. при срабатывании clickRequest
2. если значение isIdle равно true
3. прочитать значение из clicks
4. и вызвать с ним эффект fetchRequest
*/
guard({
clock: clickRequest /* 1 */,
filter: isIdle /* 2 */,
source: clicks /* 3 */,
target: fetchRequest /* 4 */,
});
```
Пример rate limiting
#### Пример с функцией-предикатом в `filter`
```js
import { createEffect, createEvent, guard } from "effector";
const searchUser = createEffect();
const submitForm = createEvent();
guard({
source: submitForm,
filter: (user) => user.length > 0,
target: searchUser,
});
submitForm(""); // ничего не произошло
submitForm("alice"); // ~> searchUser('alice')
```
Запустить пример
### `guard(source, {filter})`
Альтернативная запись метода
**Аргументы**
* **`source`**: Юнит
* **`filter`**: Стор или функция-предикат
**Разновидности**:
* **стор**: `target` будет запущен только если в этом сторе [истинное значение](https://developer.mozilla.org/ru/docs/Glossary/Truthy)
* **функция-предикат** `(source) => boolean`: `target` будет запущен только если эта функция вернёт [истинное значение](https://developer.mozilla.org/ru/docs/Glossary/Truthy). Функция должна быть
##### Пример со стором в `filter`
```js
import { createEvent, createStore, createApi, guard } from "effector";
const trigger = createEvent();
const $unlocked = createStore(true);
const { lock, unlock } = createApi($unlocked, {
lock: () => false,
unlock: () => true,
});
const target = guard(trigger, {
filter: $unlocked,
});
target.watch(console.log);
trigger("A");
lock();
trigger("B"); // ничего не произошло
unlock();
trigger("C");
```
Запустить пример
##### Пример с функцией-предикатом в `filter`
```js
import { createEvent, guard } from "effector";
const source = createEvent();
const target = guard(source, {
filter: (x) => x > 0,
});
target.watch(() => {
console.log("target вызван");
});
source(0);
// ничего не произошло
source(1);
// target вызван
```
Запустить пример
# hydrate
```ts
import { hydrate } from "effector";
```
Сопутствующий метод для . Гидрирует предоставленные значения в соответствующие сторы в рамках предоставленного домена или скоупа. Основная цель — гидрация состояния приложения на стороне клиента после SSR (Server-Side Rendering).
## Методы
#### `hydrate(domainOrScope, { values })`
> WARNING Важно:
>
> Необходимо убедиться, что стор создан заранее, иначе гидрация может завершиться неудачей. Это может произойти, если вы разделяете скрипты инициализации/гидрации сторов от их создания.
##### Формула
```ts
hydrate(domainOrScope: Domain | Scope, { values: Map, any> | {[sid: string]: any} }): void
```
##### Аргументы (methods-hydrate-domainOrScope-values-arguments)
1. **`domainOrScope`**: домен или область видимости, который будет заполнен предоставленными `values`.
2. **`values`**: отображение из sid (идентификаторов сторов) в значения сторов или `Map`, где ключи — это объекты сторов, а значения содержат начальное значение стора.
##### Возвращает
`void`
##### Примеры
Заполнение стора предопределенным значением:
```js
import { createStore, createDomain, fork, serialize, hydrate } from "effector";
const domain = createDomain();
const $store = domain.createStore(0);
hydrate(domain, {
values: {
[$store.sid]: 42,
},
});
console.log($store.getState()); // 42
```
Запустить пример
# effector
## Effector API
Перечень методов API, по группам:
### Типы юнитов
* Event\
* Effect\
* Store\
* Domain
* Scope
### Создание юнитов
* createEvent()
* createStore(default)
* createEffect(handler)
* createDomain()
### Основные методы библиотеки
* combine(...stores, f)
* attach({effect, mapParams?, source?})
* sample({clock, source, fn, target})
* merge(\[eventA, eventB])
* split(event, cases)
* createApi(store, api)
### Fork API
* fork()
* serialize(scope)
* allSettled(unit, { scope })
* scopeBind(event)
* hydrate(domain)
### Плагины для компилятора
* effector/babel-plugin
* @effector-swc-plugin
### Служебные функции
* is
* fromObservable(observable)
### Низкоуровневый API
* clearNode()
* withRegion()
* launch()
* inspect()
### Import Map
Пакет `effector` предоставляет несколько дополнительных модулей, которые могут быть полезны в различных сценариях:
* effector/compat
* effector/inspect
* effector/babel-plugin
### Устаревшие методы
* forward({from, to})
* guard({source, filter, target})
# inspect
```ts
import { inspect } from "effector/inspect";
```
Специальные методы API, предназначенные для обработки сценариев отладки и мониторинга, не предоставляя слишком много доступа к внутренностям вашего приложения.
Полезны для создания девтулз, мониторинга и наблюдения в production.
## Inspect API
Позволяет отслеживать любые вычисления, происходящие в ядре effector.
### `inspect()`
#### Пример
```ts
import { inspect, type Message } from "effector/inspect";
import { someEvent } from "./app-code";
function logInspectMessage(m: Message) {
const { name, value, kind } = m;
return console.log(`[${kind}] ${name} ${value}`);
}
inspect({
fn: (m) => {
logInspectMessage(m);
},
});
someEvent(42);
// выведет что-то вроде
// [event] someEvent 42
// [on] 42
// [store] $count 1337
// ☝️ допустим, что редьюсер добавляет 1295 к предоставленному числу
//
// и так далее, любые триггеры
```
Scope ограничивает область, в которой можно отслеживать вычисления. Если scope не предоставлен — будут отслеживаться вычисления вне scope.
```ts
import { fork, allSettled } from "effector";
import { inspect, type Message } from "effector/inspect";
import { someEvent } from "./app-code";
function logInspectMessage(m: Message) {
const { name, value, kind } = m;
return console.log(`[${kind}] ${name} ${value}`);
}
const myScope = fork();
inspect({
scope: myScope,
fn: (m) => {
logInspectMessage(m);
},
});
someEvent(42);
// ☝️ Нет логов! Это потому, что отслеживание было ограничено myScope
allSettled(someEvent, { scope: myScope, params: 42 });
// [event] someEvent 42
// [on] 42
// [store] $count 1337
```
### Трассировка
Добавление настройки `trace: true` позволяет просматривать предыдущие вычисления, которые привели к текущему. Это полезно для отладки конкретной причины возникновения некоторых событий.
#### Пример
```ts
import { fork, allSettled } from "effector";
import { inspect, type Message } from "effector/inspect";
import { someEvent, $count } from "./app-code";
function logInspectMessage(m: Message) {
const { name, value, kind } = m;
return console.log(`[${kind}] ${name} ${value}`);
}
const myScope = fork();
inspect({
scope: myScope,
trace: true, // <- явная настройка
fn: (m) => {
if (m.kind === "store" && m.sid === $count.sid) {
m.trace.forEach((tracedMessage) => {
logInspectMessage(tracedMessage);
// ☝️ здесь мы логируем трассировку обновления конкретного стора
});
}
},
});
allSettled(someEvent, { scope: myScope, params: 42 });
// [on] 42
// [event] someEvent 42
// ☝️ трассировки предоставляются в обратном порядке, так как мы смотрим назад во времени
```
### Ошибки
Effector не допускает исключений в чистых функциях. В таком случае вычисление ветви останавливается, и исключение логируется. Также в таком случае есть специальный тип сообщения:
#### Пример
```ts
inspect({
fn: (m) => {
if (m.type === "error") {
// сделать что-то с этим
console.log(`${m.kind} ${m.name} computation has failed with ${m.error}`);
}
},
});
```
## Inspect Graph
Позволяет отслеживать объявления юнитов, фабрик и регионов.
### Пример
```ts
import { createStore } from "effector";
import { inspectGraph, type Declaration } from "effector/inspect";
function printDeclaration(d: Declaration) {
console.log(`${d.kind} ${d.name}`);
}
inspectGraph({
fn: (d) => {
printDeclaration(d);
},
});
const $count = createStore(0);
// выведет "store $count" в консоль
```
### `withRegion`
Метаданные, предоставленные через корневой узел региона, доступны при объявлении.
#### Пример
```ts
import { createNode, withRegion, createStore } from "effector";
import { inspectGraph, type Declaration } from "effector/inspect";
function createCustomSomething(config) {
const $something = createStore(0);
withRegion(createNode({ meta: { hello: "world" } }), () => {
// какой-то код
});
return $something;
}
inspectGraph({
fn: (d) => {
if (d.type === "region") console.log(d.meta.hello);
},
});
const $some = createCustomSomething({});
// выведет "world"
```
# is
Объект с валидаторами юнитов
## Методы
### `is.store(value)`
Проверяет, является ли переданное значение
**Возвращает**
boolean
```js
import { is, createStore, createEvent, createEffect, createDomain } from "effector";
const store = createStore(null);
const event = createEvent();
const fx = createEffect();
is.store(store);
// => true
is.store(event);
// => false
is.store(fx);
// => false
is.store(createDomain());
// => false
is.store(fx.pending);
// => true
is.store(fx.done);
// => false
is.store(store.updates);
// => false
is.store(null);
// => false
```
Запустить пример
### `is.event(value)`
Проверяет, является ли переданное значение
**Возвращает**
boolean
```js
import { is, createStore, createEvent, createEffect, createDomain } from "effector";
const store = createStore(null);
const event = createEvent();
const fx = createEffect();
is.event(store);
// => false
is.event(event);
// => true
is.event(fx);
// => false
is.event(createDomain());
// => false
is.event(fx.pending);
// => false
is.event(fx.done);
// => true
is.event(store.updates);
// => true
is.event(null);
// => false
```
Запустить пример
### `is.effect(value)`
Проверяет, является ли переданное значение
**Возвращает**
boolean
```js
import { is, createStore, createEvent, createEffect, createDomain } from "effector";
const store = createStore(null);
const event = createEvent();
const fx = createEffect();
is.effect(store);
// => false
is.effect(event);
// => false
is.effect(fx);
// => true
is.effect(createDomain());
// => false
is.effect(null);
// => false
```
Запустить пример
### `is.domain(value)`
Проверяет, является ли переданное значение
**Возвращает**
boolean
```js
import { is, createStore, createEvent, createEffect, createDomain } from "effector";
const store = createStore(null);
const event = createEvent();
const fx = createEffect();
is.domain(store);
// => false
is.domain(event);
// => false
is.domain(fx);
// => false
is.domain(createDomain());
// => true
is.domain(null);
// => false
```
Запустить пример
### `is.scope(value)`
> INFO:
>
> Добавлен в effector 22.0.0
Проверяет, является ли переданное значение
**Возвращает**
boolean
```js
import { fork } from "effector";
const store = createStore(null);
const event = createEvent();
const fx = createEffect();
const scope = fork();
is.scope(scope);
// => true
is.scope(store);
// => false
is.scope(event);
// => false
is.scope(fx);
// => false
is.scope(createDomain());
// => false
is.scope(null);
// => false
```
Запустить пример
### `is.unit(value)`
Проверяет, является ли переданное значение юнитом: стором, эвентом, эффектом, доменом или скоупом
**Возвращает**
boolean
```js
import { is, createStore, createEvent, createEffect, createDomain, fork } from "effector";
const store = createStore(null);
const event = createEvent();
const fx = createEffect();
const scope = fork();
is.unit(scope);
// => true
is.unit(store);
// => true
is.unit(event);
// => true
is.unit(fx);
// => true
is.unit(createDomain());
// => true
is.unit(fx.pending);
// => true
is.unit(fx.done);
// => true
is.unit(store.updates);
// => true
is.unit(null);
// => false
```
Запустить пример
### `is.attached(value)`
> INFO:
>
> Добавлен в effector 22.4.0
Проверяет, что переданный был создан с помощью метода .
Если в качестве аргумента был передан не effect, возвращает `false`.
**Возвращает**
boolean
```js
import { is, createStore, createEvent, createEffect, createDomain, attach } from "effector";
const $store = createStore(null);
const event = createEvent();
const fx = createEffect();
const childFx = attach({
effect: fx,
});
is.attached(childFx);
// => true
is.attached(fx);
// => false
is.attached($store);
// => false
is.attached(event);
// => false
is.attached(createDomain());
// => false
is.attached(null);
// => false
```
Запустить пример
#### Пример использования
Иногда нужно добавить отображение ошибок на эффекты, но только на те, которые были "локализованы" через `attach`.
Если оставить `onCreateEffect` как есть, без проверок, то лог ошибки будет задублирован.
```js
import { createDomain, attach, is } from "effector";
const logFailuresDomain = createDomain();
logFailuresDomain.onCreateEffect((effect) => {
if (is.attached(effect)) {
effect.fail.watch(({ params, error }) => {
console.warn(`Effect "${effect.compositeName.fullName}" failed`, params, error);
});
}
});
const baseRequestFx = logFailuresDomain.createEffect((path) => {
throw new Error(`path ${path}`);
});
const loadDataFx = attach({
mapParams: () => "/data",
effect: baseRequestFx,
});
const loadListFx = attach({
mapParams: () => "/list",
effect: baseRequestFx,
});
loadDataFx();
loadListFx();
```
Запустить пример
# launch
Низкоуровневый метод для запуска вычислений в юнитах. В основном используется разработчиками библиотек для тонкого контроля вычислений
> INFO:
>
> Добавлен в effector 20.10.0
## Методы
### Формула
```ts
declare const $store: Store
declare const event: Event
declare const fx: Effect
launch({target: $store, params: T}): void
launch({target: event, params: T}): void
launch({target: fx, params: T}): void
```
# merge
Объединяет апдейты массива юнитов в новое событие, которое будет срабатывать при запуске любой из переданных сущностей
> INFO:
>
> Добавлено в effector 20.0.0
## Методы
### Формула
```ts
declare const $store: Store; // триггер
declare const event: Event; // триггер
declare const fx: Effect; // триггер
const result: Event = merge(/*clock*/ [$store, event, fx]);
```
#### Аргументы
* **`clock`**: Массив юнитов для объединения
#### Возвращает
: Новое событие
> TIP:
>
> В случае передачи стора, итоговое событие будет срабатывать при обновлении этого стора
### Примеры
##### Пример 1
```js
import { createEvent, merge } from "effector";
const foo = createEvent();
const bar = createEvent();
const baz = merge([foo, bar]);
baz.watch((v) => console.log("merged event triggered: ", v));
foo(1);
// => merged event triggered: 1
bar(2);
// => merged event triggered: 2
```
Запустить пример
##### Пример 2
```js
import { createEvent, createStore, merge } from "effector";
const setFoo = createEvent();
const setBar = createEvent();
const $foo = createStore(0).on(setFoo, (_, v) => v);
const $bar = createStore(100).on(setBar, (_, v) => v);
const anyUpdated = merge([$foo, $bar]);
anyUpdated.watch((v) => console.log(`state changed to: ${v}`));
setFoo(1); // => state changed to: 1
setBar(123); // => state changed to: 123
```
Запустить пример
##### Пример 3
```js
import { createEvent, createStore, merge } from "effector";
const setFoo = createEvent();
const otherEvent = createEvent();
const $foo = createStore(0).on(setFoo, (_, v) => v);
const merged = merge([$foo, otherEvent]);
merged.watch((v) => console.log(`merged event payload: ${v}`));
setFoo(999);
// => merged event payload: 999
otherEvent("bar");
// => merged event payload: bar
```
Запустить пример
# effector/babel-plugin
Поскольку Effector позволяет автоматизировать множество стандартных задач (например, задавание стабильных идентификаторов и предоставление отладочной информации для юнитов), существует встроенный плагин для Babel, который улучшает опыт разработчика при использовании библиотеки.
## Использование
Пожалуйста, обратитесь к документации Babel plugin для примеров использования.
# effector/compat
```ts
import {} from "effector/compat";
```
Библиотека предоставляет отдельный модуль с поддержкой совместимости до IE11 и Chrome 47 (браузер для устройств Smart TV).
> WARNING Бандлер, а не транспилятор:
>
> Поскольку сторонние библиотеки могут импортировать `effector` напрямую, вам **не следует** использовать транспиляторы, такие как Babel, для замены `effector` на `effector/compat` в вашем коде, так как по умолчанию Babel не преобразует сторонний код.
>
> **Используйте бандлер**, так как он заменит `effector` на `effector/compat` во всех модулях, включая модули из сторонних библиотек.
### Необходимые полифиллы
Вам нужно установить полифиллы для этих объектов:
* `Promise`
* `Object.assign`
* `Array.prototype.flat`
* `Map`
* `Set`
В большинстве случаев бандлер может автоматически добавить полифиллы.
#### Vite
Пример конфигурации Vite
```js
import { defineConfig } from "vite";
import legacy from "@vitejs/plugin-legacy";
export default defineConfig({
plugins: [
legacy({
polyfills: ["es.promise", "es.object.assign", "es.array.flat", "es.map", "es.set"],
}),
],
});
```
## Использование
### Ручная замена
Вы можете использовать `effector/compat` вместо пакета `effector`, если вам нужно поддерживать старые браузеры.
```diff
- import {createStore} from 'effector'
+ import {createStore} from 'effector/compat'
```
### Автоматическая замена
Однако вы можете настроить ваш бандлер для автоматической замены `effector` на `effector/compat` в вашем коде.
#### Webpack
Пример конфигурации Webpack
```js
module.exports = {
resolve: {
alias: {
effector: "effector/compat",
},
},
};
```
#### Vite
Пример конфигурации Vite
```js
import { defineConfig } from "vite";
export default defineConfig({
resolve: {
alias: {
effector: "effector/compat",
},
},
});
```
# effector/inspect
## `effector/inspect`
Effector предоставляет специальные методы API, предназначенные для обработки задач отладки и мониторинга, не предоставляя слишком много доступа к внутренней логике вашего приложения — Inspect API.
### Почему отдельный модуль?
Inspect API разработан как опциональный модуль. По задумке, любая функциональность, использующая Inspect API, может быть удалена из production-сборки без каких-либо побочных эффектов. Чтобы подчеркнуть это, Inspect API не включён в основной модуль. Вместо этого он доступен в отдельном модуле `effector/inspect`.
### Использование
Пожалуйста, обратитесь к документации Inspect API для примеров использования.
# restore
```ts
import { restore } from "effector";
```
## Методы
### `restore(event, defaultState)`
Создает из . Работает как сокращение для `createStore(defaultState).on(event, (_, payload) => payload)`.
> WARNING Это не производный стор:
>
> `restore` создает новый стор. Это не производный стор. Это означает, что вы можете изменять его состояние через события и использовать его как `target` в sample.
#### Формула
```ts
restore(event: Event, defaultState: T): StoreWritable
```
#### Аргументы
1. `event`
2. `defaultState` (*Payload*)
#### Возвращает
: Новый стор.
#### Примеры
##### Базовый пример
```js
import { createEvent, restore } from "effector";
const event = createEvent();
const $store = restore(event, "default");
$store.watch((state) => console.log("state: ", state));
// state: default
event("foo");
// state: foo
```
Запустить пример
### `restore(effect, defaultState)`
Создает из успешных результатов . Работает как сокращение для `createStore(defaultState).on(effect.done, (_, {result}) => result)`.
#### Формула
```ts
restore(effect: Effect, defaultState: Done): StoreWritable
```
#### Аргументы
1. `effect`
2. `defaultState` (*Done*)
#### Возвращает
: Новый стор.
#### Типы
Store будет иметь тот же тип, что и `Done` из `Effect`. Также `defaultState` должен иметь тип `Done`.
#### Примеры
##### Эффект
```js
import { createEffect, restore } from "effector";
const fx = createEffect(() => "foo");
const $store = restore(fx, "default");
$store.watch((state) => console.log("state: ", state));
// => state: default
await fx();
// => state: foo
```
Запустить пример
### `restore(shape)`
Создает объект с сторами из объекта с значениями.
#### Формула
TBD
#### Аргументы
1. `shape` (*State*)
#### Возвращает
: Новый стор.
#### Примеры
##### Объект
```js
import { restore } from "effector";
const { foo: $foo, bar: $bar } = restore({
foo: "foo",
bar: 0,
});
$foo.watch((foo) => {
console.log("foo", foo);
});
// => foo 'foo'
$bar.watch((bar) => {
console.log("bar", bar);
});
// => bar 0
```
Запустить пример
# sample API
[units]: /ru/explanation/glossary#common-unit
[eventApi]: /ru/api/effector/Event
[storeApi]: /ru/api/effector/Store
[effectApi]: /ru/api/effector/Effect
[purity]: /ru/explanation/glossary/#purity
## `sample` API
```ts
import { sample } from "effector";
```
Метод для связывания юнитов. Его главная задача - брать данные из одного места `source` и передавать их в другое место `target` при срабатывании определённого триггера `clock`.
Типичный вариант использования – когда необходимо обработать какое-либо событие используя данные из стора. Вместо использования `store.getState()`, которое может вызвать несогласованность состояния, лучше использовать метод `sample`.
> TIP как работать с sample:
>
> Узнайте как композировать юниты и работать с методом
### Алгоритм работы
* При срабатывании `clock` прочитать значение из `source`
* Если указан `filter`, и результат функции вернул `true` или стор со значением `true`, то продолжить
* Если указан `fn`, то преобразовать данные
* И передать данные в `target`.
### Особенности работы `sample`
* Если `clock` не передан, `sample` будет срабатывать при каждом обновлении `source`.
* Если `target` не передан, то `sample` создаст и вернёт новый производный юнит
### Возвращаемый юнит и значение
Если `target` не передан, то он будет создан при вызове. Тип создаваемого юнита описан в данной таблице:
| clock \ source | | | |
| ----------------------------------- | --------------------------------- | --------------------------------- | ----------------------------------- |
| | `Store` | `Event` | `Event` |
| | `Event` | `Event` | `Event` |
| | `Event` | `Event` | `Event` |
Использование таблицы:
1. Выбираем тип источника `clock`, это столбец
2. Тип `source` – это строка
3. Устанавливаем соответствие между столбцом и строкой
В случае, если `target` передан явно, то возвращаемым значением будет тот же самый `target`.
Например:
```ts
const event = createEvent();
const $store = createStore();
const $secondStore = createStore();
const $derivedStore = sample({
clock: $store,
source: $secondStore,
});
// Результатом будет производный стор,
// так как `source` и `clock` являются сторами
const derivedEvent = sample({
clock: event,
source: $store,
});
// Результатом будет производное событие, так как `clock` – событие
```
### Полная форма
* **Формула**
```ts
sample({
clock?, // триггер
source?, // источник данных
filter?, // фильтр
fn?, // функция-трансформатор
target?, // целевой юнит
batch?, // флаг батчинга
name? // имя sample юнита
})
```
#### `clock`
Аргумент `clock` является триггером, определяющий момент взятия данных из source.
Является опциональным.
* **Тип**
```ts
sample({
clock?: Unit | Unit[],
})
```
Может иметь сигнатуру:
* [`Event`][eventApi] - срабатывает при вызове события
* [`Store`][storeApi] - срабатывает при изменении стора
* [`Effect`][effectApi] - срабатывает при вызове эффекта
* `Unit[]`- массив [юнитов][units] срабатывает при активации любого из них
> INFO либо clock либо source:
>
> Хотя аргумент `clock` является опциональным, при использовании метода `sample` необходимо указать либо `clock`, либо source.
```ts
const clicked = createEvent();
const $store = createStore(0);
const fetchFx = createEffect();
// Event как clock
sample({
source: $data,
clock: clicked,
});
// Store как clock
sample({
source: $data,
clock: $store,
});
// Массив как clock
sample({
source: $data,
clock: [clicked, fetchFx.done],
});
```
***
#### `source`
Является источником данных, откуда берутся данные при срабатывании `clock`. Если `clock` не указан, тогда `source` используется как `clock`.
Является опциональным.
* **Тип**
```ts
sample({
source?: Unit | Unit[] | {[key: string]: Unit},
})
```
Может иметь сигнатуру:
* [`Store`][storeApi] - данные берутся из текущего значения стора
* [`Event`][eventApi] - возьмется последнее значение, с которым запускалось событие
* [`Effect`][effectApi] - возьмется последнее значение, с которым запускался эффект
* Объект с [юнитами][units] - для комбинирования нескольких источников
* Массив с [юнитами][units] - для комбинирования нескольких источников
> INFO либо source либо clock:
>
> Хотя аргумент `source` является опциональным, при использовании метода `sample` необходимо указать либо `source`, либо clock.
***
#### `filter`
Функция-предикат для фильтрации. Если возвращает `false` или стор со значением `false`, данные не будут переданы в `target`.
Является опциональным.
* **Тип**
```ts
sample({
filter?: Store | (source: Source, clock: Clock) => (boolean | Store),
})
```
Может иметь сигнатуру:
* [`Store`][storeApi] – стор с `boolean` значением, как производный так и базовый
* Функция-предикат – функция возвращающая `boolean` значение
```ts
const $isUserActive = createStore(false);
sample({
clock: checkScore,
source: $score,
filter: (score) => score > 100,
target: showWinnerFx,
});
sample({
clock: action,
source: $user,
filter: $isUserActive,
target: adminActionFx,
});
```
***
#### `fn`
Функция для трансформации данных перед передачей в `target`. Функция [**должна быть чистой**][purity].