Glossary

This is a glossary of the core terms in Effector, along with their type signatures. The types are documented using TypeScript notation.

Event

Event is a function you can subscribe to. It can be an intention to change the store, indication of something happening in the application, a command to be executed, aggregated analytics trigger and so on.

Event in api documentation

function createEvent<E>(eventName?: string): Event<E>

• createEvent(eventName) creates event

type Event<Payload> = {

(payload: Payload): Payload

watch(watcher: (payload: Payload) => any): Subscription

map<T>(fn: (payload: Payload) => T): Event<T>

filter(options: {fn(payload: Payload): boolean}): Event<Payload>

filterMap<T>(fn: (payload: Payload) => T | void): Event<T>

prepend<Before>(fn: (params: Before) => Payload): Event<Before>

}

• (payload) calls Event with payload
• watch(watcher) listens to the event and calls provided watcher
• map(fn) creates a new event, which will be trigger after the original event was triggered, transforming the payload with provided fn
• filter({fn}) creates a new event that will tigger only if provided fn function returns true
• filterMap(fn) creates a new event that will be triggered with the result of fn applied to the payload, but only if the result is not undefined. Use cases: extract value from react's refs; statically typed filters;
• prepend(fn) creates a new event that will trigger the original event with a payload transformed by fn

Store

Store is an object that holds state. There can be multiple stores.

Store in api documentation

function createStore<State>(defaultState: State): Store<State>

• createStore(defaultState) creates a new store
• combine(stores) combines multiple stores into one

type Store<State> = {

on<E>(

trigger: Event<E> | Effect<E, any, any> | Store<E>,

reducer: (state: State, payload: E) => State | void,

): this

map<T>(fn: (_: State) => T): Store<T>

reset(

...triggers: Array<Event<any> | Effect<any, any, any> | Store<any>>

): this

watch<E>(watcher: (state: State) => any): Subscription

updates: Event<State>

defaultState: State

}

• on(event, reducer) calls reducer on store whenever an event occurs
• map(fn) creates computed store from given one
• reset(...triggers) resets state to default whenever any of the triggers occur
• watch(watcher) registers a watcher to be called with the new state when the store is updated
• updates is an event that triggers when the store is updated
• defaultState initial state of the given store

Effect

Effect is a container for (possibly async) side effects. It exposes special events and stores, such as pending, done, fail, finally, etc...

It can be safely used in place of the original async function.

It returns promise with result of a function call

The only requirement for the function:

• Must have zero or one argument

Effect in api documentation

function createEffect<Params, Done, Fail>(config?: {

handler?: (params: Params) => Promise<Done> | Done

}): Effect<Params, Done, Fail>

• createEffect(config) creates an effect

type Effect<Params, Done, Fail = Error> = {

(payload: Params): Promise<Done>

doneData: Event<Done>

failData: Event<Fail>

done: Event<{params: Params; result: Done}>

fail: Event<{params: Params; error: Fail}>

pending: Store<boolean>

inFlight: Store<number>

use: {

(asyncFunction: (params: Params) => Promise<Done>): this

getCurrent(): (params: Params) => Promise<Done>

}

watch(watcher: (payload: Params) => any): Subscription

}

• (payload) starts the Effect with payload and returns a Promise
• use(function) replaces the handler in the effect (can be called multiple times)
• watch(watcher) listens to the effect and calls provided watcher when effect starts

Domain

Domain is a namespace for your events, stores and effects.

Domains are notified when events, stores, effects, or nested domains are created via onCreateEvent, onCreateStore, onCreateEffect, onCreateDomain methods.

It is useful for logging or other side effects.

Domain in api documentation

function createDomain(domainName?: string): Domain

• createDomain(domainName) creates a new domain

type Domain = {

onCreateEvent(hook: (newEvent: Event<unknown>) => any): Subscription

onCreateEffect(

hook: (newEffect: Effect<unknown, unknown, unknown>) => any,

): Subscription

onCreateStore(hook: (newStore: Store<unknown>) => any): Subscription

onCreateDomain(hook: (newDomain: Domain) => any): Subscription

createEvent<Payload>(name?: string): Event<Payload>

createEffect<Params, Done, Fail>(name?: string): Effect<Params, Done, Fail>

createStore<State>(defaultState: State): Store<State>

createDomain(name?: string): Domain

}

• onCreateEvent(hook) calls the hook when nested Event is created
• onCreateEffect(hook) calls the hook when nested Effect is created
• onCreateStore(hook) calls the hook when nested Store is created
• onCreateDomain(hook) calls the hook when nested Domain is created
• createEvent(name) creates a domain-bound Event
• createEffect(name) creates a domain-bound Effect
• createStore(defaultState) creates a domain-bound Store
• createDomain(name) creates a nested, domain-bound Domain

Reducer

type StoreReducer<State, E> = (state: State, payload: E) => State | void

type EventOrEffectReducer<T, E> = (state: T, payload: E) => T

Reducer calculates a new state given the previous state and an event's payload. For stores, if reducer returns undefined or the same state (===), then there will be no update for a given store.

Watcher

type Watcher<T> = (update: T) => any

Watcher is used for side effects. Accepted by event.watch, store.watch and domain.onCreate* hooks. Return value of a watcher is ignored.

Subscription

type Subscription = {

(): void

unsubscribe(): void

}

Function, returned by forward, event.watch, store.watch and some others methods. Used for cancelling a subscription. After first call, subscription will do nothing

Purity

Most of functions in api must not call other events or effects: it's easier to reason about application's data flow when imperative triggers are grouped inside watchers and effect handlers rather than spread across entire business logic.

Correct, imperative:

import {createStore, createEvent} from 'effector'

const login = createStore('guest')

const loginSize = login.map(login => login.length)

const submitLoginSize = createEvent()

loginSize.watch(size => {

submitLoginSize(size)

})

Try it

store.map in docs

store.watch in docs

Correct, declarative:

import {createStore, createEvent, forward} from 'effector'

const login = createStore('guest')

const loginSize = login.map(login => login.length)

const submitLoginSize = createEvent()

forward({

from: loginSize,

to: submitLoginSize,

})

Try it

forward in docs

Incorrect:

import {createStore, createEvent, forward} from 'effector'

const submitLoginSize = createEvent()

const login = createStore('guest')

const loginSize = login.map(login => {

// no! use forward or watch instead

submitLoginSize(login.length)

return login.length

})