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, some occurence in application, 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 new event, which will be called after the original event is called, applying the result of a fn as a payload
• filter({fn}) creates new event that will receive update only when given fn returns true
• filterMap(fn) creates new event that will receive value, returned by given fn, but only when it returns anything but undefined. Use cases: extract value from react's refs; statically typed filters;
• prepend(fn) creates new event that preprocesses payload before calling the original event

Effect

Effect is a container for async function.

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 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) calls Effect with payload and returns a Promise
• use(asyncFunction) injects async function into the effect (can be called multiple times)
• watch(watcher) listens to the effect and calls provided watcher when effect starts

Store

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

Store in api documentation

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

• createStore(defaultState) creates 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 when event occurs
• map(fn) creates computed store from given one
• reset(...triggers) resets state to default when event occurs
• watch(watcher) calls given watcher with current state
• updates is event for watch store changes only
• defaultState initial state of given store

Domain

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

Domain can subscribe to event, effect, store or nested domain creation with 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 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 hook when nested Event created
• onCreateEffect(hook) calls hook when nested Effect created
• onCreateStore(hook) calls hook when nested Store created
• onCreateDomain(hook) calls hook when nested Domain created
• createEvent(name) is the function that creates Event
• createEffect(name) is the function that creates Effect
• createStore(defaultState) is the function that creates Store
• createDomain(name) creates nested 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. For stores, if reducer returns undefined or the same state (===), then there will be no update for 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

Pureness

Most of functions in api mustn't call other events or effects: it's easier to reason about application dataflow 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
})