☄️ Effector

The state manager

npm version Codeship Status for zerobias/effector Build Status Join the chat at https://
.im/effector-js/community PRs welcome License

Table of Contents

Introduction

Effector is an effective multi-store state manager for Javascript apps (React/React Native/Vue/Node.js), that allows you to manage data in complex applications without the risk of inflating the monolithic central store, with clear control flow, good type support and high capacity API. Effector supports both TypeScript and Flow type annotations out of the box.

Effector follows five basic principles:

  • Application stores should be as light as possible - the idea of adding a store for specific needs should not be frightening or damaging to the developer.
  • Application stores should be freely combined - data that the application needs can be statically distributed, showing how it will be converted in runtime.
  • Autonomy from controversial concepts - no decorators, no need to use classes or proxies - this is not required to control the state of the application and therefore the api library uses only functions and simple js objects
  • Predictability and clarity of API - a small number of basic principles are reused in different cases, reducing the user’s workload and increasing recognition. For example, if you know how .watch works for events, you already know how .watch works for stores.
  • The application is built from simple elements - space and way to take any required business logic out of the view, maximizing the simplicity of the components.

Installation

npm install --save effector
# or
yarn add effector

React

npm install --save effector effector-react
# or
yarn add effector effector-react

Vue

npm install --save effector effector-vue
# or
yarn add effector effector-vue

Svelte

Svelte works with effector out from a box, no additional packages needed. See word chain game application written with svelte and effector.

CDN

Packages

Web frameworks

Package Version Dependencies Size
effector npm-effector deps-effector size-effector
effector-react npm-react deps-react size-react
effector-vue npm-vue deps-vue size-vue

Babel plugins

Package Version Dependencies
@effector/babel-plugin npm-babel deps-babel
@effector/babel-plugin-react npm-babel-react deps-babel-react

ReasonML/BuckleScript

Package Version Dependencies
bs-effector npm-bs deps-bs
bs-effector-react npm-bs-react deps-bs-react

Community

Press

Online playground

You can try effector in our repl

Code sharing, Typescript and react supported out of the box; and of course, it built with effector

Examples

Increment/decrement with React

import {createStore, createEvent} from 'effector'
import {useStore} from 'effector-react'

const increment = createEvent('increment')
const decrement = createEvent('decrement')
const resetCounter = createEvent('reset counter')

const counter = createStore(0)
  .on(increment, state => state + 1)
  .on(decrement, state => state - 1)
  .reset(resetCounter)

counter.watch(console.log)

const Counter = () => {
  const value = useStore(counter)
  return <div>{value}</div>
}

const App = () => {
  const value = useStore(counter)

  return (
    <>
      <Counter />
      <button onClick={increment}>+</button>
      <button onClick={decrement}>-</button>
      <button onClick={resetCounter}>reset</button>
    </>
  )
}

Run example


Hello world with events and nodejs

const {createEvent} = require('effector')

const messageEvent = createEvent()

messageEvent.watch(text => console.log(`new message: ${text}`))

messageEvent('hello world')
// => new message: hello world

Run example


Stores and events

const {createStore, createEvent} = require('effector')

const turnOn = createEvent()
const turnOff = createEvent()

const status = createStore('offline')
  .on(turnOn, () => 'online')
  .on(turnOff, () => 'offline')

status.watch(newStatus => {
  console.log(`status changed: ${newStatus}`)
})
// for store watchs callback invokes immediately
// "status changed: offline"

turnOff() // nothing has changed, callback is not triggered
turnOn() // "status changed: online"
turnOff() // "status changed: offline"
turnOff() // nothing has changed

Run example


More examples

API

Event

Event is an intention to change state.

import {createEvent} from 'effector'
const send = createEvent() // unnamed event
const onMessage = createEvent('message') // named event

const socket = new WebSocket('wss://echo.websocket.org')
socket.onmessage = msg => onMessage(msg)
socket.onopen = () => send('{"text": "hello"}')

const onMessageParse = onMessage.map(msg => JSON.parse(msg.data))

onMessageParse.watch(data => {
  console.log('Message from server ', data)
})

send.watch(data => {
  socket.send(data)
})

Run example

Effect

Effect is a container for async function. It can be safely used in place of the original async function.

import {createEffect} from 'effector'

const fetchUserReposFx = createEffect({
  async handler({name}) {
    const url = `https://api.github.com/users/${name}/repos`
    const req = await fetch(url)
    return req.json()
  },
})

// subscribe to pending store status
fetchUserReposFx.pending.watch(pending => {
  console.log(pending) // false
})

// subscribe to handler resolve
fetchUserReposFx.done.watch(({params, result}) => {
  console.log(params) // {name: 'zerobias'}
  console.log(result) // resolved value
})

// subscribe to handler reject or throw error
fetchUserReposFx.fail.watch(({params, error}) => {
  console.error(params) // {name: 'zerobias'}
  console.error(error) // rejected value
})

// subscribe to both cases
fetchUserReposFx.finally.watch(data => {
  if (data.status === 'done') {
    const {params, result} = data
    console.log(params) // {name: 'zerobias'}
    console.log(result) // resolved value
  } else {
    const {params, error} = data
    console.error(params) // {name: 'zerobias'}
    console.error(error) // rejected value
  }
})

// you can replace handler anytime
fetchUserReposFx.use(requestMock)

// calling effect will return a promise
const result = await fetchUserReposFx({name: 'zerobias'})

Run example

Store

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

// `getUsers` - is an effect
// `addUser` - is an event
const users = createStore([{ name: Joe }])
  // subscribe store reducers to events
  .on(getUsers.done, (oldState, payload) => payload)
  .on(addUser, (oldState, payload) => [...oldState, payload]))

// subscribe to store updates
users.watch(state => console.log(state)) // `.watch` for a store is triggered immediately: `[{ name: Joe }]`
// `callback` will be triggered each time when `.on` handler returns the new state

Store composition/decomposition

Most profit thing of stores.

Get smaller part of the store:

// `.map` accept state of parent store and return new memoized store. No more reselect ;)
const firstUser = users.map(list => list[0])
firstUser.watch(newState => console.log(`first user name: ${newState.name}`)) // "first user name: Joe"

addUser({name: Joseph}) // `firstUser` is not updated
getUsers() // after promise resolve `firstUser` is updated and call all watchers (subscribers)

Compose stores:

import {createStore, combine} from 'effector'

const a = createStore(1)
const b = createStore('b')

const c = combine({a, b})

c.watch(console.log)
// => {a: 1, b: "b"}

See combine in docs

Run example

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(to handle nested domains) methods.

import {createDomain} from 'effector'
const mainPage = createDomain('main page')
mainPage.onCreateEvent(event => {
  console.log('new event: ', event.getType())
})
mainPage.onCreateStore(store => {
  console.log('new store: ', store.getState())
})
const mount = mainPage.createEvent('mount')
// => new event: main page/mount

const pageStore = mainPage.createStore(0)
// => new store: 0

See Domain in docs

Run example

See also worker-rpc example, which uses shared domain for effects

Learn more

Effector Diagram

Support us

Tested with browserstack

Tested with browserstack

Contributors

Dmitry
Dmitry

💬 💻 📖 💡 🤔 🚇 ⚠️
andretshurotshka
andretshurotshka

💬 💻 📖 📦 ⚠️
Sergey Sova
Sergey Sova

📖 💡
Arutyunyan Artyom
Arutyunyan Artyom

📖 💡
Ilya
Ilya

📖
Arthur Irgashev
Arthur Irgashev

📖 💻 💡
Igor Ryzhov
Igor Ryzhov

📖
Egor Guscha
Egor Guscha
📖
bakugod
bakugod
📖 💡
Ruslan
Ruslan
📖 💻 🤔 ⚠️
Maxim Alyoshin
Maxim Alyoshin
📖
Andrey Gopienko
Andrey Gopienko
📖
Vadim Ivanov
Vadim Ivanov
📖
Aleksandr Anokhin
Aleksandr Anokhin
💻
Anton Kosykh
Anton Kosykh
💻
Konstantin Lebedev
Konstantin Lebedev
💡
Pavel Tereschenko
Pavel Tereschenko
💻
Satya Rohith
Satya Rohith
📖
Vladislav Melnikov
Vladislav Melnikov
💻
Grigory Zaripov
Grigory Zaripov
💻
Marina Miyaoka
Marina Miyaoka
💻
Evgeny Zakharov
Evgeny Zakharov
📖
Viktor
Viktor

💻 📖 ⚠️ 🤔
Ivan Savichev
Ivan Savichev

💻 🤔
Nikita Nafranets
Nikita Nafranets

📖 💡
Tauyekel Kunzhol
Tauyekel Kunzhol

📖
Andrew Laiff
Andrew Laiff

📖
Illia Osmanov
Illia Osmanov

💻 🤔
Yan
Yan

📖
Egor Aristov
Egor Aristov

📖
Sozonov
Sozonov

📖
Rafael Fakhreev
Rafael Fakhreev

💻 🤔 ⚠️

License

MIT