DEV Community: Effector

effector-storage v6

Victor Didenko — Mon, 08 May 2023 12:25:35 +0000

Wow, that was a long jump! But now effector-storage version 6 is landed.

So, whats new?

Contracts support

This could be a minuscule change for a majority of this library users, but I consider this like a big step toward serious business. "Contract" sounds serious, doesn't it?

Like any source, which your code has no full control on, localStorage values should never be trusted and needs to be validated. Any script kiddie can open DevTools and change localStorage value, thus breaking your big-money application. In order to prevent it, data should be validated in two levels — structurally and businessly. effector-storage library cannot help you with your business logic, but at least, it can validate values against contracts now.

In a simple case, contract could be just a simple type guard:

persist({
  store: $counter,
  key: 'counter',
  contract: (raw): raw is number => typeof raw === 'number',
  fail: failed
})

So, if localStorage somehow will contain a string now — persist will fail restoring store $counter, and trigger failed event with operation: "validate".

Note though, that contracts are working after parsing (deserializing), so if localStorage value is not a valid JSON string at all — persist will fail, triggering failed event with operation: "get".

In more complex cases, when you need to validate data against some complex structure with complex rules — effector-storage fully supports Farfetched contracts, so you can use any adapter from Farfetched — runtypes, zod, io-ts, superstruct, typed-contracts:

import { Record, Literal, Number } from 'runtypes'
import { runtypeContract } from '@farfetched/runtypes'

const Asteroid = Record({
  type: Literal('asteroid'),
  mass: Number,
})

persist({
  store: $asteroid,
  key: 'asteroid',
  contract: runtypeContract(Asteroid),
  fail: failed
})

There are two gotchas with contracts:

From effector-storage point of view it is absolutely normal, when there is no persisted value in the storage yet. So, undefined value is always valid, even if contract does not explicitly allow it.
effector-storage does not prevent persisting invalid data to the storage, but it will validate it nonetheless, after persisting, so, if you write invalid data to the storage, fail will be triggered, but data will be persisted.

Exported adapters

Sometimes it is required to persist different stores within different storages within the same module. And to avoid names clashes in version 5 you have to write something like this:

import { persist as localPersist } from 'effector-storage/local'
import { persist as queryPersist } from 'effector-storage/query'

localPersist({ store: $session })
queryPersist({ store: $page })

In version 6 all adapters now are exported alongside with persist function, and could be used on their own. More over, all (major) adapters are exported from the root package as well, so you can use them all in once with a single import statement:

import { persist, local, query } from 'effector-storage'

persist({ adapter: local, store: $session })
persist({ adapter: query, store: $page })

Strictly speaking, imported local and query in the example above are not adapters, but adapter factories. So you can call factory to create an adapter instance, if you need some adapter adjustments:

persist({
  store: $date,
  adapter: local({
    serialize: (date) => String(date.getTime()),
    deserialize: (timestamp) => new Date(Number(timestamp)),
  }),
})

Or you can pass any adapter factory arguments right into persist!

persist({
  store: $date,
  adapter: local,
  serialize: (date) => String(date.getTime()),
  deserialize: (timestamp) => new Date(Number(timestamp)),
})

Adapter utilities

With exported adapters new idea has crossed my mind: what if you could write a high order function, which will accept adapter (or adapter factory), and slightly change it behaviour?

So, I made a few:

`async` utility function

It takes any synchronous storage adapter (or factory) and makes it asynchronous:

persist({
  adapter: async(local),
  store: $counter,
  done: doneEvent,
})

This could be useful, when you need to postpone store restoring a bit. If you don't use pickup option, persist begins restoring store state right at the moment. So, in case of synchronous localStorage, right after persist is executed — store value already be restored from the storage (of course, if it was persisted beforehand). Sometimes it can affect your business logic, for example, if you need to react on store restoring, you need to take that behaviour into account, and define all connections (like samples) before you call persist.

async utility function can help you with that, freeing you from that burden of keeping declarations order in mind.

`either` utility function

It takes two adapters (or factories), and returns first of them, which is not "no-op".

What the heck is "no-op" adapter?

Version 6 introduces two separate "terms", or "states" for adapters:

Supported — this means, that storage is supported by environment, for example, localStorage is supported in browsers, but not supported in Nodejs.
Available — this means, that storage is supported and available, for example, localStorage could be forbidden by browser security policies.

So, if adapter is doing nothing (like nil adapter), or it is not supported — this is "no-op" adapter.

persist({
  store: $store,
  adapter: either(local, log),
  key: 'store'
})

In the example above store $store will be persisted in localStorage in the browser, and will use new log adapter, which just prints operations, in Nodejs.

Breaking change❗️ In version 5 local adapter was behaving like not supported (and did nothing) when localStorage is forbidden by browser security policies. In version 6 this considered like not available, thus, local adapter will trigger security error on each operation. You can handle this and ask user to enable localStorage, for example.

`farcached` utility function

It takes any cache adapter from Farfetched and converts it to be used as persist adapter :)

This one I made mostly out of fun and to show possibilities, which opens with utility functions approach.

From real usage point of view, using Farfetched cache adapters could be useful, when you need logic for cache invalidation, because all of its adapters have maxAge option out of the box.

Also, you could use Farfetched cache adapters to inject different cache adapters with fork using cache.__.$instance internal store.

import { localStorageCache } from '@farfetched/core'

persist({
  store: $counter3,
  adapter: farcached(localStorageCache({ maxAge: '15m' })),
})

Adapter context

This is an experimental feature, and I think it will be like dark horse for a while 🤫 But I plan to show it fully in next minor releases.

In a few words, context is aimed for two main purposes:

Asynchronous updates from storage in scope
Using different environments in adapter

You can pass context in two ways:

As pickup event payload
As new context event payload

persist will remember scope, in which you have called pickup or context, and will use this scope for any asynchronous updates from storage (like on "storage" event).

Also, context will be passed as a second argument in adapter's get and set functions, and adapter can use it as it pleases.

Force sync mode

Due to minor performance optimizations, when local adapter receives "storage" event — it takes new storage value from this event's payload. Obviously, there is no need to read (relatively slow) localStorage when new value is right here, inside the already received event.

But in some cases this approach could lead to stores desynchronization with simultaneous or almost simultaneous updates from different tabs. You can call this race condition.

This happens because "storage" event is happening only when storage is modified from another tab/window. So, in any situation with simultaneous or almost simultaneous localStorage updates from more than one tab — there always will be a loser tab, which will become unsynchronized. I've drawn an image with two tabs: each tab receives update from another tab, and one of the tabs inevitably become unsynchronized with localStorage:

I consider this very rare case, so, version 6 does not change default behaviour (with using new value from event), but adds new possible value for sync option instead — 'force':

persist({
  store: $balance,
  key: 'balance',
  sync: 'force'
})

This will ignore new value from "storage" event, and will forcibly read new value from localStorage instead, thus eliminating desynchronization issue.

Throttle/batch writes

Version 6 adds new option timeout for three adapters: local, session and query. It behaves slightly differently for them, but meaning is plain — postpone writes to a storage.

For local and session (and base storage) adapters timeout option behaves like throttle for the single persist (without leading write). So, if you have store, which updates frequently and persisted in the localStorage, you can slightly improve performance by throttling access to the localStorage with this option.

For query adapter timeout option behaves like throttle (without leading write) and batch. So, if you have many stores, which are persisted in a query string, you can use this option to throttle and batch the query string updates.

Drop Effector v21 support

Version 5 fully supports Effector v21, which was out on July 6, 2020 — almost three years ago. This is possible, because effector-storage uses only base Effector's functionality, and because Effector has an excellent backward compatibility.

But times go on, and Effector v22 has been out on August 31, 2021 — almost two years ago. effector-storage already has some small tweaks to support different versions and new features, so, I think, it is time to stop supporting version 21.

Also, Nodejs v14 has reached end-of-life on April 30, 2023 — so, version 6 also drops it. And so should you ;)

That is all I got for you today, stay tuned ;)

classList API in forest

Sergey Sova — Mon, 04 Apr 2022 11:20:39 +0000

Forest is a reactive JavaScript/TypeScript rendering engine based on an effector — business logic manager.
The main idea of the forest is "initialize once, never render". Here we don't have such things as to render calls like in React.

Let's show you an example:

import { h, using } from 'forest'

function App() {
  h('div', {
    text: 'Hello',
    fn() {
      h('span', { text: 'World' })
    },
  })
}

using(document.querySelector('#root'), App)

I need to highlight 3 things:

There is no JSX or another specific syntax
Forest doesn't require return from components
Each function/component is called only once

Let's explain:

There is no JSX or another specific syntax

JSX looks like HTML, but do more with javascript embeds. But, when we trying to pass something that not looks like attributes, we need to build tricks:

function ReactComponent(props) {
  return <div
      onClick={handleClick}
      data-someid={props}
      style={{ height: props.height }}
      {...props.extras}
    >content</div>
}

Please note that we also have CSS custom attributes accessible from javascript. We can customize handlers setup (capture, preventDefault, stopPropagation, and so on). DOM API also supports setting many text nodes.

But JSX doesn't support them and for already solved tasks we have a very strange API.
Also, JSX requires passing all kinds of properties to the same place, to the same object, and it shifts responsibility to solve conflicts on end developers.
Also, any specific language requires installing specific tools and learning how to solve specific issues with the new language.

Data-attributes

JSX has anti-DX:

<div data-first={1} data-second={2} />
// instead of, ex:
<div data={{ first: 1, second: 2 }} />

Look at the DOM API:

element.dataset.first = 1
element.dataset.second = 2

Forest:

h('div', {
  data: { first: 1, second: 2 },
})

Event handlers

JSX compels libraries to invent the wheel with the naming of the props:

<div onClick={fn1} onClickCapture={fn2} />

But we have beautiful DOM API:

element.addEventListener('click', fn2, { capture: true })

Forest:

h('div', {
  handler: { click: fn1 },
})
h('div', {
  handler: { config: { capture: true }, on: { click: fn2 } },
})
// or in the same element
h('div', () => {
  spec({ handler: { click: fn1 } })
  spec({ handler: { config: { capture: true }, on: { click: fn2 } } })
})

Style properties

Ok, inline styles are not the best practice, but we have cases for them. What JSX can offer us?

<div style={{ height: 'auto', maxHeight: '100px' }} />

I need to remind, that inline styles allows to pass css custom properties:

<div style="height: auto; max-height: 100px; --color: black"></div>

Forest:

h('div', {
  style: { height: 'auto', maxHeight: '100px' },
  styleVar: { color: 'black' },
})

But JSX in React with TypeScript doesn't allow passing CSS custom properties without tears.

Whole picture

function ForestComponent({ fn, someId, height }) {
  h('div', {
    handler: { click: handleClick },
    data: { someId },
    style: { height: height },
    text: 'content',
    fn,
  })
}

Note, that each kind of properties and attributes is separated from each other, we don't need to solve conflicts. But also, in the forest way in the most cases we don't need props at all, just call spec() inside fn(){}:

function ForestComponent({ fn }) {
  h('div', {
    text: 'content',
    fn,
  })
}

ForestComponent({
  fn() {
    spec({
      handler: { click: handleClick },
      data: { someId },
      style: { height: height },
    })
  },
})

Yep, we like OCP from SOLID, and props allow it. But as you can see, you HAVE a choice.

Forest doesn't require `return` from components

React and JSX requires returning some elements from components because this library builds a diff-tree to compare with the previous view-state. Forest uses the same mechanism as react-hooks to solve the same problem.

It is called declarative stack-based DOM API. Proof of concept implementation.

When you called using with some App function, forest saves each call of h, spec, list, and other methods to the stack, it looks like virtual DOM, but you don't need to compare tree with each other. There is no render. Forest knows each point where is reactivity is applied: the user just passed effector Store instead of a literal value. When the store is updated, forest batches change and apply it to a DOM with 60 frames per second rate. Concurrent rendering out from the box.

This is why each function/component is called only once. And this is why you as a forest user need to change your habits to design forest components. You can't just put if where you want, you need to use reactive Store and visible properties to declaratively show/hide any element you want.

What was before `classList`

I need to explain how the spec() method works.

h("input", {
  attr: { type: "number" },
  fn() {
    spec({ attr: { class: "w-full" } })
  },
})

All method called inside fn(){} property applies on the input element created by h(). So, we can create children elements if we call h() inside fn(){}.

spec() just add new properties, handlers, and so on on the already created element. In our case we should have <input type="number" class="w-full" />.

But with string attributes, we will have some problems.

h("input", {
  attr: { class: "first" },
  fn() {
    spec({ attr: { class: "second" } })
  },
})

What value we should set for the class attribute? First or Second? Or we should merge? If merge, what if I need to override or disable some classes?

function Component({ fn }) {
  h("input", {
    attr: { class: "w-full text-red" },
    fn() { fn() },
  })
}

Component({ fn() {
  spec({ attr: { class: "w-20 text-blue" } }) // Oops! We already set w-full and text-red
}})

There we have the same problem with reactivity:

function Component({ $enabled }) {
  const $class = val`w-full ${$enabled.map(is => is ? 'text-red' : 'text-gray')}`;
  h('input', {
    attr: {
      class: $class,
      type: 'number',
    },
  })
}

What do we have now?

New API allows to set up each class independently. Proposal. It is based on browser API classList.

h("input", {
  classList: ["first"],
  fn() {
    spec({ classList: ["second"] })
  },
})

Now classes can be combined, because forest operates each class independently, instead of a string of something inside.
Also, you have reactivity out from the box:

function Component({ $enabled }) {
  h('input', {
    attr: {
      class: "w-full",
      type: 'number',
    },
    classList: {
      'text-red': $enabled,
      'text-gray': $enabled.map(is => !is),
    },
  })
}

Attribute class and classList will be merged. And nested spec() call also supported:

function Component({ fn }) {
  h("input", {
    classList: ["w-full", "text-red"],
    fn() { fn() },
  })
}

Component({ fn() {
  spec({
    classList: {
      "w-full": false,
      "w-20": true,
      "text-red": false,
      "text-blue": true,
    },
  })
}})

Thank you for the reading! 🧡 ☄️
Forest is still in the development stage, you can help us improve its API or ecosystem: github.com/effector ⭐️

Using GQty with effector

Sergey Sova — Mon, 22 Nov 2021 14:32:56 +0000

Introduction

GQTY suggests using integration with React in the form of useQuery, useMutation hooks, and so on.

But when using a state manager, we face the problem of where to store data and a natural desire to move everything about the data and their loading to the state manager, but this creates a second problem - we have to manually transfer data from gqty hooks to the state manager.

Since our projects use effector as a state manager, we will consider the integration with it. First, you need to configure your local gqty instance. Please follow the original instructions at https://gqty.dev/docs/getting-started.

The differences will be in the Configuring Codegen section, the react property should be switched to false, this will not load your bundle with unused hooks, yes, I propose to completely abandon all gqty hooks. After that, you need to delete the generated files, including index.ts

Integration with effector comes down to using a standalone client inside the effects, documentation, and example at https://gqty.dev/docs/client/fetching-data and in the Core Client section of the gqty documentation. The effects already have load markers and load end events, both successful and error events.

Using with effector

Let's start with an example code to retrieve data (query):

import { query, resolved } from '../../api';

const readUserFx = createEffect((userId: string) => resolved(() => {
  const user = query.readUser({ userId })
  if (!user) return null;
  return {
    id: user.id!,
    username: user.username!,
    avatarUrl: user.avatarUrl!,
    tags: user.tags!.map(tag => tag),
    posts: user.posts!.map(post => ({
      id: post.id!,
      title: post.title!,
      content: post.content!,
    })),
  }
}))

Now we can figure out what's going on here and why.

query.readUser({ userId }) doesn't send a query to the server the first time, it only returns a Proxy object so that we can gather the list of fields we need to make a valid query.

In the return expression, we list the fields that we want to get from the query; this is how we describe fields when writing a regular graphQL query.

Exclamation marks in expressions like user.username! are needed to prove to the typescript that the value in the field is certain, otherwise, it will be a string | undefined, which is not the case. https://github.com/gqty-dev/gqty/issues/261

resolved() is a magic function that helps gqty gather the fields the user needs to execute the query. The first time, before executing a query, resolved sets a Proxy instance in the query variable, which collects all the fields accessed by the developer inside the resolved(callback). After the callback is executed, resolved sends the request to the server and returns Promise to the developer. When the server returns the response, resolved substitutes it in the query variable and calls the callback again, already with real data, and then resolves the promise. Note that this is a rough description of the process necessary to explain what's going on.

Any nested data, you also need to select, as well as arrays, even if they are simple, otherwise, you will fall into the data Proxy-objects, which, to put it mildly, are not very pleasant to work with.

But it doesn't look like a convenient solution! Yes, and there are a few ways to simplify life:

Step 1: Create type-caster functions

import { query, resolved, User, Post } from '../../api';

function getPost(post: Post) {
  return {
      id: post.id!,
      title: post.title!,
      content: post.content!,
    }
}

function getUser(user: User) {
  return {
    id: user.id!,
    username: user.username!,
    avatarUrl: user.avatarUrl!,
    tags: user.tags!.map(tag => tag),
    posts: user.posts!.map(getPost),
  }
}

const readUserFx = createEffect((userId: string) => resolved(() => {
  const user = query.readUser({ userId })
  if (!user) return null;
  return getUser(user)
}))

Here it's simple, just put the repeated object getters into functions and reuse them, it's better to put such getters next to the API definition.

Step 2. Use helper functions from gqty

https://gqty.dev/docs/client/helper-functions

import { selectFields } from 'gqty'
import { query, resolved, User } from '../../api'

function getUser(user: User) {
  return selectFields(user, [
    'id',
    'username',
    'avatarUrl',
    'tags',
    'posts.id',
    'posts.title',
    'posts.content',
  ])
}

const readUserFx = createEffect((userId: string) =>
  resolved(() => {
    const user = query.readUser({userId})
    if (!user) return null
    return getUser(user)
  })
)

It is important to read the documentation and carefully check the operation of gqty methods under different conditions.

Step 3. Put all the effects in a separate API layer.

// api.layer.ts
import { selectFields } from 'gqty'
import { query, resolved, User } from './index'

export function getUser(user: User) {
  return selectFields(user, [
    'id',
    'username',
    'avatarUrl',
    'tags',
    'posts.id',
    'posts.title',
    'posts.content',
  ])
}

export const readUserFx = createEffect((userId: string) =>
  resolved(() => {
    const user = query.readUser({userId})
    if (!user) return null
    return getUser(user)
  })
)

// pages/users/model.ts
import { attach } from 'effector'
import * as api from '../../api/api.layer'

const readUserFx = attach({ effect: api.readUserFx })

Now all models can reuse graphQL queries in the same way, without even thinking about how exactly the query is run and what fields get under the hood. But if they need to query additional fields or perform the query differently, they can easily build their query by reusing getUser-like getters.

Why we need `attach`

In the example, I used the attach method instead of using api.readUserFx directly, for one very important reason:

// pages/users/model.ts
import * as api from '../../api/api.layer'

sample({
  clock: api.readUserFx.done,
  target: showNotification,
})

If we write code without attach, subscribing directly to any effect events, these events will be triggered every time any other model triggers that effect. And since in an application different models can subscribe to the same effect, all the scripts in which the effect is involved will be triggered, without regard to whether the page is open now or not, or whether a certain script triggered the effect or not.

// pages/users/model.ts
import * as api from '../../api/api.layer'

const readUserFx = attach({ effect: api.readUserFx })

sample({
  clock: readUserFx.done,
  target: showNotification,
})

Using attach we create a local copy of the original effect. If each model creates a local effect, and only subscribes and runs its local copy, there won't be any problems with overlapping different scripts.

But keep in mind that running the local effect still triggers events and triggers the parent effect, and if someone subscribes to the global api.readUserFx, they will get all the reactions from all the models, this is useful when building an error handling system.

The best part of Effector

Igor Kamyshev — Mon, 04 Oct 2021 03:59:09 +0000

Effector is a lightweight and performant state manager. It is UI frameworks agnostic, predictable and easy to use. Almost half a year ago, Aviasales team has started migration from RxJS to Effector. While I was investigating this library, I found a completely unexpected feature. It changed my mind about Effector.

Disclaimer

In my opinion, in modern applications, we have to write domain-specific logic with reactive primitives. Such primitives do not exist in JavaScript, so we must use a library for it. I prefer to use a state manager as a dependency zero and bound it with core application logic.

The Problem

Creating complex business scenarios frequently includes waiting for all computations to be completed. Moreover, if an application is built over event-oriented architecture, it will be quite difficult to define the end of events processing. In the common case, we need this opportunity in two situations. The first one is widely used, any good application requires it. The second one is more specific, but it is pretty important too.

Tests

In my everyday work, I write two types of tests: unit tests and domain-logic tests. Unit tests do not relate to state managers and the business logic of the application. However, the domain logic tests can lead to a problem.

In domain-specific scenarios we commonly use the same pattern — emit some event, wait for application reactions and relay on result state, e.g., 👇

describe('User flow', () => {
  test('should set default currency after login', async () => {
    emitEvent('Login', { login, password })

    // ... wait

    expect(userSettings.currency).toBe('THB')
  }) 
})

If the whole authorization flow is synchronous, we do not have any problems — scenarios will end right after the first event emitting. Nonetheless, in real applications, almost all scenarios are completely asynchronous.

Furthermore, even in simple cases we can find a situation where simple waiting for some promise is impossible, e.g., 👇

async function fetchCurrency({ token }) {
  const { currency } = await request('/settings', { token })

  return currency ?? 'THB'
}

async function login({ login, password }) {
  const token = await request('/login', { login, password })

  // can't wait for resolve
  // it's a domain-specific logic 🤷‍♂️
  fetchCurrency({ token })
    .then(currency => setLocalCurrency(currency))

  return token
}

Many business scenarios contain asynchronous operations, and some of these operations can cause other asynchronous operations, etc.

The only solution for this case to wait for the end of scenario is to emit a special event. Thereafter, we can rewrite our tests this way 👇

describe('User flow', () => {
  test('should set default currency after login', async () => {
    emitEvent('Login', { login, password })

    await waitForEvent('Login/Finished')

    expect(userSettings.currency).toBe('THB')
  }) 
})

But this solution prevents us from writing complex and well-designed scenarios. We will not be able to inverse dependencies and remove knowledge of the outer world from the scenario. It leads to gigantic scenarios, and engineers cannot keep it in their heads.

In an ideal case, I would not like to edit the source code of my scenario to satisfy tests.

describe('User flow', () => {
  test('should set default currency after login', async () => {
    emitEvent('Login', { login, password })

    await waitForAllComputationsFinished()

    expect(userSettings.currency).toBe('THB')
  }) 
})

👆 this test case knows nothing about the internal structure of the login process. When you read it, you immediately understand what is happening — the user starts the login flow, and after the whole all process currency is changed to Thai bahts.

SSR

SSR (Server-side rendering) is a process of creating an HTML string based on current state of the application. The HTML is sent to the browser and the user can start using the site before JS loads. It is a good way to improve user experience and SEO.

Let us dive into the rendering process. Right after the user has opened a page, the application should request data, wait for the end of computation and pass the whole state to a UI-framework to create an HTML-string. This process looks very similar to the test of domain-specific scenarios (here we recognize “the user has opened a page” as a scenario).

async function renderAppOnServer(route) {
  const store = createStore()

  emitEvent('Route/changed', { route })

  // ... wait

  return renderAppToString(store)
}

All modern UI frameworks have an opportunity to create an interface as a function of the state. In this article, I will not dive deep into the details of a particular UI framework, let us use the magical generic function renderAppToString. It accepts the application state and returns an HTML-string. Implementation of this function is trivial for any popular UI framework.

So, let us imagine the ideal world again! In the ideal world, the application ought to wait till the computations are completed on state and render a string 👇

async function renderAppOnServer(route) {
  const store = createStore()

  emitEvent('Route/changed', { route })

  await waitForAllComputationsFinished()

  return renderAppToString(store)
}

Classic Solutions

We have identified a problem of waiting for computations to be completed, so let us see how classic state managers solve it. I have an experience with redux and MobX, so I will talk about it. If your favourite state manager can handle this case simpler, please tell me about it on Twitter.

Redux

First, redux itself does not have any mechanism to handle asynchronous actions and side effects. A common application uses something like redux-saga or redux-thunk (now it is a part of @reduxjs/toolkit) for it.

The simplest way to detect the end of computations is to add the new action “computations is ended”. It is a simple and working solution, but it has a fatal problem — you (as an engineer) should think about “end-of-computations” actions in any scenario, you should adopt a domain-specific logic to it. Moreover, if the scenario becomes more complex, this approach can destroy its readability.

Another option is to put the whole scenario logic to a single entity (thunk, saga, whatever). In this case, we can just wait for the end of the entity. E.g., thunk returns a simple promise from a dispatch-call, so we can wait for resolve. Sagas are based on generators and for handling this case they have a special library — redux-saga-test-plan.

In conclusion, redux-world has a solution. However, this solution is not simple and enjoyable 🤷‍♂️ also, it does not work in complex cases.

MobX

Actually, MobX uses the same techniques as Redux for the solution of our problem. E.g., we can just add a boolean property to the store and wait for its changes 👇

describe('User flow', () => {
  test('should set default currency after login', async () => {
    userStore.login({ login, password })

    await when(() => userStore.done)

    expect(userStore.currency).toBe('THB')
  }) 
})

So, it is working, except for one thing. We cannot use this solution for a complex scenario, if it works with many stores.

Moreover, we can put the whole scenario in single asynchronous function, it will simplify the tests 👇

describe('User flow', () => {
  test('should set default currency after login', async () => {
    await userStore.login({ login, password })

    expect(userStore.currency).toBe('THB')
  }) 
})

But it cannot cover complex scenarios.
In conclusion, MobX-world has a solution. However, this solution is not simple and enjoyable 🤷‍♂️ also, it does not work in complex cases.

Effector-world

To understand this part of the article, it is better to read Effector’s documentation first.
Effector has a game-changer feature — Fork API. To understand it, we should talk about one important concept — scope.

The scope is an independent copy of the whole application. You can run any logic over a specific scope, and it will not affect any other scope. Let us read some code 👇

const loginFx = createEffect(/* e.g., request to backend */)

// Event of currency change
const changeCurrency = settings.createEvent()

// Currency store
const $currency = createStore()
  // just save the payload of event to a store
  .on(changeCurrency, (_, newCurrency) => newCurrency)

sample({
  // After login request successfully ends
  source: loginFx.doneData,
  // get a currency from a result
  fn: ({ settings }) => settings.currency ?? 'thb',
  // and can event changeCurrency with it
  target: changeCurrency,
})

Now, we can fork this application and get an independent copy of the application — scope.

Tests

Let us write a test for this scenario — after a user has logged in without specified currency, they should get Thai bahts as a currency.

describe('User flow', () => {
  test('should set default currency after login', () => {
    loginFx({ login, password })

    expect($currency.getState()).toBe('THB')
  }) 
})

👆this test will fail, of course. It does not include waiting of the computation end.

In Effector-world, we can fix it with a special function allSettled. It starts a unit (event or effect) and waits for end of computations on the specified scope. To get a state of store in particular scope, we can use scope.getState method.

describe('User flow', () => {
  test('should set default currency after login', async () => {
    // Fork application and create an isolated scope
    const scope = fork()

    // Start logixFx on the scope
    // and wait for computations env
    await allSettled(loginFx, {
      params: { login, password },
      scope,
    })

    // Check a store state on the scope
    expect(scope.getState($currency)).toBe('THB')
  }) 
})

So, we have written a test for domain-specific scenarios, and we did not edit the scenario for it. In my opinion, it is the most important feature of Effector.

One more thing

Yeah, you can notice that this test case executes a real effect-handler. It is a good note, we should mock the handler of loginFx and return some test data.

We can do this with test-runner mechanisms, e.g., replace imports or monkey-patch internal state of loginFx. I dislike these ways. It is too fragile because tests get a knowledge of internal structure of scenario.

Fork API helps us in this case, too. It has a built-in mechanism to replace any effect-handler in a specific scope. Let us improve our test-case 👇

describe('User flow', () => {
  test('should set default currency after login', async () => {
    const scope = fork({
      handlers: new Map([
        // Replace original handler in this scope
        [loginFx, jest.fn(() => ({ settings: null }))]
      ])
    })

    await allSettled(loginFx, {
      params: { login, password },
      scope,
    })

    expect(scope.getState($currency)).toBe('THB')
  }) 
})

This feature helps us to replace any handlers without runtime modifications in specific test-case.

Be careful! To use this feature, you should set up official babel-plugin.

SSR

The second use-case of Fork API is an SSR. There are two reasons for it.

First, for SSR, the application executes in the Node.js environment. This environment can handle a huge amount of parallel requests. It means that we should isolate different instances of application between requests. If Effector-world, we should just fork application for any requests. So, each of the requests has a personal scope.

The second reason is allSettled. After requests, the application should start data-fetching and after the finish, it ought to render an interface based on specific scope.

E.g., this small application must load the counter from the internet and show it on the page:

const routeChanged = createEvent()

const fetchUsersFx = createEffect(/* some request */)

const $userCount = stats.createStore()
  .on(fetchUsersFx.doneData, (_, newCount) => newCount)

guard({
  // When route changed
  clock: routeChanged,
  // if the new route is main page
  filter: (route) => route === 'main',
  // load users data
  target: fetchUsersFx,
})

👆 this scenario knows nothing about context. An application does not care whether it is executed in the user’s browser or in the Node.js environment on the server.

In this case, we can easily add SSR to the application. We have to fork the application on every request and execute computations using the isolated scope 👇

async function renderAppOnServer(route) {
  // Create a scope for a specific request
  const scope = fork()

  // Emit an event about route changes
  // and wait for all computations
  await allSettled(routeChanged, {
    params: route,
    scope,
  })

  // All UI-framework's job
  return renderAppToString(scope)
}

Effector has adapters for UI-frameworks to simplify scope-based rendering. Read the documentation for details.

So, we have added an SSR to the application without changing the code. And, in my opinion, it’s the second great feature of Effector.

So?

So, we decided to use Effector because it is based on multi-stores. It helps to create more solid applications and develop them in large teams. I thought, that it was a nice and interesting tool, but I was not a zealot of Effector.

However, after a month of development I had found Fork API, and it changed everything. Now I am confident that it is the best way to write applications without much effort.

Waiting for your comments and feedback 🤗

Effector's beginner guide

Yan — Wed, 04 Nov 2020 16:10:43 +0000

In this article, I will answer repetitive questions and resolve common misunderstandings about the state manager effector.js

Why do you need it at all? Because it's a tool that can actually help ease frontend engineer's routine. After all, it will be possible to forget almost completely about props, its types, business logic inside components, learning a dozen other operators, using proxies or decorators, and at the same time to get the most powerful tool on the market for data flow management, providing only functions and objects.

The only problem is to get the available introduction to technology because you need to rebuild the mindset a bit. I believe I have found the way to a softer introduction, so I released a complete instruction in this post.

The application is a system

Yes, this is a really important detail in understanding and why all this is necessary.

Let's try to get to this thesis step by step:

1) Are the applications whole by nature? Yes

2) Can applications be divided according to a certain feature? Yes

3) Which one? Responsibility scopes

4) Are responsibility scopes connected to each other? Yes, definitely, as these are parts of a particular application. Moreover, they interact with each other

5) And what is a system? A set of related things (areas of responsibility) that interact with each other

Just 5 steps and led to this thesis. Good!

Back to effector

I specifically highlighted the word dataflow in the beginning. Since state-management is a more familiar one in the JavaScript ecosystem. This leads to misunderstandings. A state is just a unit for building business logic.

Speaking of units. The Effector provides four units that you can use to build business logic of any complexity: event, store, effect, and domain.

Units:Event

The first and most important. The fact is that we, as frontline operators, live in an event-driven environment (DOM). When building the business logic of web applications (those next to DOM) it would be strange to focus on a different model.

Even during the planning with management(PO's, CEO's, etc), we could hear phrasing like: "User enters the page and our cool new feature HAPPENS!" (implicit meaning events)

Determination of the event from the dictionary.

Units:Store

An object for storing values. The default value has to be set (any value except undefined). When a repeated value (equivalent to the previous one) arrives, store will not trigger an update.

The handler for incoming events is a reducer (we do not mutate the current state), in case of an undefined return in the handler, the update will not trigger.

Taking into account the previous approach with the responsibility scopes, the following recommendation can be made:

No single stores for the entire application. I am serious.

Independent easy stores for each responsibility scope.

Combining will not be difficult if necessary.

Units:Effect

The most difficult unit to understand

Technically, effect has at least one of these attributes:

-influence on the environment outside the system (server requests, local storage, etc.)

being influenced by the environment (process.env)

But, conceptually, if an event is a thing that successfully triggers every time, then the effect also provides a way to handle exceptions (i.e. no guarantee that the handler will be completed successfully).

When could we catch exceptions?

-network requests

-work from localStorage

-interaction with third-party API

-a random code fragment where a developer needs to write an explicit throw

The effect provides us with a handler in which all such questionable code fragments will be stored.

Thus, by executing the handler function, the effect emits an event about success (.done) or about failure (.fail). During the execution, a Boolean .pending field is also available, which will clearly indicate whether or not the effect is in progress.

For those who don't care about the outcome, the .finally event is kindly provided and is always emitted.

Regular units

All three units mentioned above are regular.

This is an important clarification as this term will be used for the short term from now.

Units:Domain

Domain is a namespace for all regular units.

It provides hooks for creating regular units that are linked to this domain. This is useful for bulk operations.
A domain can be freely created within a domain. All units within a domain can be output through domain.history.

P.S. domains are required for SSR, as well as when writing tests that cover most of our system scenarios.

Data preparation

Events distribute data on our system.
From time to time we need to prepare this data: add some static value to the data or multiply the number that came into the data by two.

For such tasks there are three things that can be needed:

1) Perhaps the most "flat" version for data preparation between the regular unit which is a sender and the regular unit which is a receiver is the fn field in the sample operator. But I will return to it in a couple of chapters because everything is in order.

2) The other options are methods of the event itself. The first of them, event.map, allows to transform the payload, which came to the event as you like with only one limitation: the function-transformer must be clean (i.e., it does not contain side effects). This event method will return a new event, which will be directly related to the original immediate call as soon as the original was triggered.

3) And the last option is event.prepend. If we interact with .map as a post-processor, then .prepend, on the contrary, will be the pre-processor to the original event. Accordingly, it will return an event that will execute a transformer function and then immediately call the original event. What is the use for this?

For example, the effect of getting the balance of a certain currency. The handler is the same for all currencies, the difference will only be in the static code of the currency. Thus, it is possible to create a set of "prepended" events, the function-transformer of which pushes the static values of the currency in the call argument and solve the problem.

Store data preparation

Data from stores are also worth to be prepared sometimes. Store like an event has a store.map method, where you can transform the store data according to the function inside. Such a store is called a computed store.

It will be calculated only if the original one is updated. No more and no less.

Usecase? For example, you need a store in the form of an associative array (key-value) and an ordinary array of objects.

Dataflow. Beginning

We have managed to touch upon how to process data within one regular unit. What about when there is more than one unit?

That's where the most interesting part starts - declarative connection of the units!
The first simplest operator is forward.
Its API is quite clear: fields from and to, receiving any regular unit. Its execution means that the to field is explicitly subscribed to a trigger (change of value in the store or event call) of the field from and will be triggered respectively afterward.

Dataflow. Filtering

We have data processing, as well as a simple unit connection. What if units do not want to connect without following some rules? Here comes to the guard. An operator with three fields: source, filter, target.

Source is a regular unit that initiates communication.

Filter is the rule in their communication. It either accepts a predicate function that checks the data coming from the source is truthy. In addition to the predicate function can take a Boolean store.

Target is a regular unit that receives data from the source as soon as the filter returns truthy values.

But what if the filtering is not enough and you need not only filter but transform payload in some way in case of truthy? The event.filterMap will help you here.

Okay, this is all cool, but you're looking at 1-to-1 unit links, but what if one event needs to connect to many events with different conditions depending on the recipient?

And there is a recipe here! The split operator is at your service.

Dataflow. Signals

A frequent case when units need to be linked not just directly or even not by a condition, but by a signal! Or, to be more precise, by the trigger of any regular unit.

The most obvious example is a component mount (a mount is suddenly an event) to take data from a certain store and call an effect.

sample({
  source: $store,
  clock: mount,
  fn: someCombinatorFn,
  target: effectFx
})

Clock is the key field. This is where the necessary signal is placed.

As I promised before, we will return to the way of data preparation through sample.

The thing is that besides these three fields, there is an optional field fn in the sample - combinator function. It accepts two arguments. payload from source and payload from clock (if not - undefined). Further, we are free to combine and transform these values according to the task at hand, without going beyond the purity of this function, of course.

Dataflow organization

We learned how to build data routes of any complexity through the system. But dataflow organization is still questionable. I propose the simplest and most naive option - the division by responsibility scopes.

Accordingly, we have a folder with all the business logic. It is divided into folders by corresponding responsibility scopes.

Each responsibility scope contains 2 files (less often than 3, when the store(s) are in a separate file).

The first is an index file with declarations of all the units of the effector (createEvent, createStore, createEffect).

The second one is an init file, which will not export anything, but only import it. The content of this file is the following:

1) Effect handlers

2) Store handlers of the respective scope

3) Interaction between units from the neighboring responsibility scopes (forward, guard, split, sample). When you think about which responsibility scope to place the connection, just ask yourself the question: "Who initiated this connection? Place it there.

So, in the root of the folder with all business logic, we create a root init-file, import into it init files from all responsibility scopes. Then we import this root file into the root of the application and initialize the graph of the entire application statically!

Have we built a graph? It turns out that we have.

P.S. If you feel that the responsibility scope files are starting to grow a lot, it's not a bad approach, but rather you missed the moment when the responsibility scope turned into several ones.

P.P.S I also described in a more detailed way here

Reuse and environment-dependent code

From time to time, there are situations where we may use some features for our dataflow or even events for multiple responsibility scopes.

What can we do? Where to put it? In utils?
No way!
We have a responsibility scope called app! Just like the others, it stores a code specific to the responsibility scope called the application.

The same story with bindings. Bindings for React provide such a thing as Gate. Where to create them? In a specific responsibility scope or in a view?

You should create them in your responsibility scope, called an application as well. Because this is a specific code for a particular application.

Same story with the init file. Those links where the trigger of a gate (mount, component annuity, or component renderer, where the gate has updated its properties) is the initiator should be placed there(/app/init).

Thus, during testing, you will see clearly which events should be called explicitly (there is no view layer like react in business logic tests).

Testing

I purposely used the word combination "responsibility scope" instead of the short word domain, so as not to confuse you. As a domain is an effector unit.

Talking about business logic testing with normal coverage rather than single tests, a domain becomes necessary.

1) We, as developers, can create one domain for the whole system.

2) Replace the explicit imports of createEvent, createStore, createEffect with myDomain.createEvent, and so on. This way the whole system becomes patronized by a single domain and can be forked - fork(domain, config)

3) This function takes on the domain and the optional config, where you can explicitly specify handlers for which effects you want to mock the handlers key, as well as explicitly specify the values of stores for tests with the values key

4) Calling the fork function will return the scope (const scope = fork(domain, config)) - the virtual instance of your domain.

5) Now all we have to do is to select the initial event of the scenario, which we want to test by passing it to the function allSettled with the first argument, and with the second argument before payload with which this script should start. Since the whole scenario chain can take more time than one tick, the call to allSettled needs to be done

6) Through scope.getState($store) we check the state of our system after the script under test, probably check the event/effect calls by our testing library (e.g. jest).

7) You can test your entire system!

Project to start with

I think without practical examples it was a bit difficult for you to take it.
For such purposes, at the end of the summer, I made a workshop application for Odessa.js and everyone. It is broken down into branches. In the master of the boilerplate, and then you can navigate through the chapters, looking into the pull requests, looking at what has changed.

E~wee~ctor: writing tiny Effector from scratch #4 — Effect

Victor Didenko — Fri, 10 Apr 2020 18:12:36 +0000

Hey, all!

Upon this moment we've implemented two main Effector's entities – an event and a store – and were avoiding an effect. So, let's accept this challenge!

First of all, according to documentation, an effect is a container for async function. It is used for side-effects, like interaction with a server, or any timeouts and intervals. Actually, you can use any function inside an effect, it doesn't need to be asynchronous in general, but it is so in most cases. But it is important in the Effector ecosystem to use effects for side-effects.

An effect is a complex entity, and contains of a dozen nodes and other entities:

done – is an event triggered when handler is resolved
fail – is an event triggered when handler is rejected or throws error
finally – is an event triggered when handler is resolved, rejected or throws error
doneData – is an event triggered with result of effect execution
failData – is an event triggered with error thrown by effect
pending – is a boolean store containing a true value until the effect is resolved or rejected
inFlight – is a store showing how many effect calls aren't settled yet

Here is what we will start with:

export const createEffect = ({ handler }) => {
  const effect = payload => launch(effect, payload)
  effect.graphite = createNode()
  effect.watch = watch(effect)

  effect.prepend = fn => {
    const prepended = createEvent()
    createNode({
      from: prepended,
      seq: [compute(fn)],
      to: effect,
    })
    return prepended
  }

  // TODO

  effect.kind = 'effect'
  return effect
}

This stub looks exactly like part of an event. In fact, Effector uses an event under the hood as a base for an effect, but we will create it from scratch for simplicity.

The only differences from an event here yet is that createEffect function accepts an object with the handler field. And effect.kind is "effect", so we can distinguish effects from other entities.

Now let's add a method use to change handler:

  effect.use = fn => (handler = fn)
  effect.use.getCurrent = () => handler

And create bunch of child events for the effect:

  const anyway = createEvent()
  const done = anyway.filterMap(({ status, ...rest }) => {
    if (status === 'done') return rest
  })
  const fail = anyway.filterMap(({ status, ...rest }) => {
    if (status === 'fail') return rest
  })
  const doneData = done.map(({ result }) => result)
  const failData = fail.map(({ error }) => error)

  effect.finally = anyway
  effect.done = done
  effect.fail = fail
  effect.doneData = doneData
  effect.failData = failData

Hereby we've created all the events for our effect. Base event is effect.finally (finally is a reserved word, so we can't name a variable like this, so we use name anyway for it). All other events are derived from this base event:

Looking at the code above I feel urgent desire to extract common logic to helper functions:

const status = name => ({ status, ...rest }) =>
  status === name ? rest : undefined

const field = name => object => object[name]

// --8<--

  const anyway = createEvent()
  const done = anyway.filterMap(status('done'))
  const fail = anyway.filterMap(status('fail'))
  const doneData = done.map(field('result'))
  const failData = fail.map(field('error'))

Now let's add stores pending and inFlight:

  effect.inFlight = createStore(0)
    .on(effect, x => x + 1)
    .on(anyway, x => x - 1)
  effect.pending = effect.inFlight.map(amount => amount > 0)

That is simple: store inFlight subscribes to the effect itself and its finally event. And boolean store pending is true when inFlight has positive value.

And now we've come close to the main part of the effect – running our side-effect function handler. We will just add a single step to our main effect's node, where the handler will be launched:

  effect.graphite.seq.push(
    compute(params => {
      try {
        const promise = handler(params)
        if (promise instanceof Promise) {
          promise
            .then(result => launch(anyway, { status: 'done', params, result }))
            .catch(error => launch(anyway, { status: 'fail', params, error }))
        } else {
          launch(anyway, { status: 'done', params, result: promise })
        }
      } catch (error) {
        launch(anyway, { status: 'fail', params, error })
      }
      return params
    })
  )

we run the handler inside try-catch block, so if we get a synchronous exception – it will be caught
if handler returns a Promise, we wait for it to settle
if handler returns not a Promise, we just use returned value as a result
in any case we launch result (either successful or failed) to the finally event, so it will be processed to the done/fail/doneData/failData events automatically

Here is one important thing left though, without which this code will not work properly:

Steps are executed during the computation cycle inside the kernel
We use function launch inside the step, while we are inside the computation cycle
Function launch starts the computation cycle

Do you see the problem?

We have one single queue to process, and secondary run of the computation cycle inside the already running computation cycle will mess it all around! We don't want this, so let's add a guard to protect from this situation in our kernel:

let running = false
const exec = () => {
  if (running) return
  running = true

  // --8<--

  running = false
}

After this fix step inside effect's node will work perfectly.

But there is one more thing to fix: effect should return a Promise, so it can be awaited. For now our effect's function, which is tied to the node, is exactly the same as function for an event – it just launches given payload to the node (and returns nothing):

  const effect = payload => launch(effect, payload)

But it should return a Promise, as was said. And we should be able to somehow resolve or reject this Promise from inside step.

And here we need so called Deferred object. This is a common pattern to have a Promise, which can be settled from outside. Here is a nice explanation of this approach, read this, if you didn't meet deferred objects yet.

A Promise represents a value that is not yet known.
A Deferred represents work that is not yet finished.

export const defer = () => {
  const deferred = {}

  deferred.promise = new Promise((resolve, reject) => {
    deferred.resolve = resolve
    deferred.reject = reject
  })

  // we need this to avoid 'unhandled exception' warning
  deferred.promise.catch(() => {})

  return deferred
}

defer function creates a deferred object. Now we can use this deferred object to return a Promise from an effect, and settle it from inside a step. But we also need to consider a situation, when the effect is called not directly, but from the other graph node, for example like forward({ from: event, to: effect }). In that case we don't need to create useless Deferred object.

Let's use helper class to distinguish direct and indirect call cases. We could use simple object, but we can't be sure, that one day effect will not receive exactly this shape of an object as a payload. So we use internal class and instanceof check, to be sure, that only our code can create class instance.

⚠️ Effector checks this differently, using call stack, provided by the kernel, but we will go simple way :)

function Payload(params, resolve, reject) {
  this.params = params
  this.resolve = resolve
  this.reject = reject
}

Now we need to change main function, and then add one more step to check use case:

  const effect = payload => {
    const deferred = defer()
    launch(effect, new Payload(payload, deferred.resolve, deferred.reject))
    return deferred.promise
  }

  // --8<--

    compute(data =>
      data instanceof Payload
        ? data // we get this data directly
        : new Payload( // we get this data indirectly through graph
            data,
            () => {}, // dumb resolve function
            () => {} // dumb reject function
          )
    )

After this step next one will get a Payload instance in both cases, either effect was called directly or indirectly. We need to change our existing step to handle this new Payload instance instead of plain params.

// helper function to handle successful case
const onDone = (event, params, resolve) => result => {
  launch(event, { status: 'done', params, result })
  resolve(result)
}

// helper function to handle failed case
const onFail = (event, params, reject) => error => {
  launch(event, { status: 'fail', params, error })
  reject(error)
}

// --8<--

    compute(({ params, resolve, reject }) => {
      const handleDone = onDone(anyway, params, resolve)
      const handleFail = onFail(anyway, params, reject)
      try {
        const promise = handler(params)
        if (promise instanceof Promise) {
          promise.then(handleDone).catch(handleFail)
        } else {
          handleDone(promise)
        }
      } catch (error) {
        handleFail(error)
      }
      return params
    })

And that's it, our effect shines and ready!

I am slightly worried, that reading this chapter could be difficult, and someone could not glue code pieces together. As always, you can find whole changes in this commit, so feel free to check it out!

Thank you for reading!
To be continued...

E~wee~ctor: writing tiny Effector from scratch #3 — Simple API methods

Victor Didenko — Sat, 04 Apr 2020 09:46:01 +0000

Hi, folks!

In this article I want to implement some simple Effector API functions. But before we start, let's improve one thing.

You might have noticed, that we create auxiliary node and add it to the next array of other node quite often, like this:

  event.map = fn => {
    const mapped = createEvent()

    // create new node
    const node = createNode({
      next: [mapped.graphite],
      seq: [compute(fn)],
    })

    // add it to the event's next nodes
    event.graphite.next.push(node)

    return mapped
  }

Let's improve createNode function, so it will do it for us:

export const getGraph = unit => unit.graphite || unit

const arrify = units =>
  [units]
    .flat()          // flatten array
    .filter(Boolean) // filter out undefined values
    .map(getGraph)   // get graph nodes

export const createNode = ({ from, seq = [], to } = {}) => {
  const node = {
    next: arrify(to),
    seq,
  }
  arrify(from).forEach(n => n.next.push(node))
  return node
}

I've renamed parameter next to to, and added new parameter from, accepting previous nodes.
getGraph helper function gives us ability to pass both units and nodes, without taking care of field .graphite. Also, with arrify helper function we can pass single unit or array of units to the from and to parameters.

Now any createNode call should be more readable:

from node → sequence of steps → to node

With this change we can rewrite example above as following:

  event.map = fn => {
    const mapped = createEvent()

    // create new node
    // and automatically add it to the event's next nodes
    createNode({
      from: event,
      seq: [compute(fn)],
      to: mapped,
    })

    return mapped
  }

I wont show you all diffs of all createNode function occurrences, the changes are trivial, you can make them yourself, or check commit by the link in the end of the article, as usual :)

Let's move on to the API methods!

forward

export const forward = ({ from, to }) => {
  createNode({
    from,
    to,
  })
}

That's simple :)

⚠️ Well, not quite so, Effector's Forward returns so called Subscription, to be able to remove connection. We will implement subscriptions in later chapters.

Remember we can pass array of units/nodes to createNode function, so forward can handle arrays automatically!

merge

export const merge = (...events) => {
  const event = createEvent()
  forward({
    from: events.flat(), // to support both arrays and rest parameters
    to: event,
  })
  return event
}

merge creates new event and forwards all given events to that new one.

⚠️ Effector's merge supports only arrays. I've added rest parameters support just because I can ^_^

split

const not = fn => value => !fn(value) // inverts comparator function

export const split = (event, cases) => {
  const result = {}

  for (const key in cases) {
    const fn = cases[key]
    result[key] = event.filter(fn)
    event = event.filter(not(fn))
  }

  result.__ = event
  return result
}

split function splits event into several events, which fire if source event matches corresponding comparator function.

"It may seem difficult at first, but everything is difficult at first."
— Miyamoto Musashi

So, take your time understanding this function.
And here is diagram of split:

Or in a less detailed, but more beautiful form of a tree, split is actually looks like a recursive binary splitting:

createApi

export const createApi = (store, setters) => {
  const result = {}

  for (const key in setters) {
    const fn = setters[key]
    result[key] = createEvent()
    store.on(result[key], fn)
  }

  return result
}

createApi function is just a simple factory for events, and it auto-subscribes given store on each one of them.

is

We can distinguish events and stores by doing typeof (events are functions and stores are plain objects). But this approach has a flaw – when we will implement effects it will fail, because effects are functions too. We could go further and check all properties – this is called duck typing. But Effector does that very simple – each unit has a special field kind:

export const createEvent = () => {
  // --8<--
+  event.kind = 'event'
  return event
}

export const createStore = defaultState => {
  // --8<--
+  store.kind = 'store'
  return store
}

And with this field kind we can easily check our units:

const is = type => any =>
  (any !== null) &&
  (typeof any === 'function' || typeof any === 'object') &&
  ('kind' in any) &&
  (type === undefined || any.kind === type)

export const unit = is()
export const event = is('event')
export const store = is('store')

restore

restore behaves differently on different inputs, so we will need our brand new is functionality:

export const restore = (unit, defaultState) => {
  if (is.store(unit)) {
    return unit
  }

  if (is.event(unit)) {
    return createStore(defaultState).on(unit, (_, x) => x)
  }

  const result = {}
  for (const key in unit) {
    result[key] = createStore(unit[key])
  }
  return result
}

restore function can also handle effects, but we don't have them yet.

Other API functions, like sample, guard and combine, we will describe in later chapters.

And as always, you can find all this chapter changes in this commit.

Thank you for reading!
To be continued...

E~wee~ctor: writing tiny Effector from scratch #2 — Maps and Filters

Victor Didenko — Thu, 02 Apr 2020 19:07:29 +0000

Hi, all!

In the previous article we've made minimal implementation of our new E~wee~ctor library, which could run "counter" example from Effector website. But, honestly, this example is all it could do, nothing more. So, let's add some more features.

In this chapter I want to add maps and filters.

Steps

Last time we decided to use functions as steps. That was good and simple for the start, but unfortunately we can't go further with this approach. In some cases kernel needs to make different decisions depending on steps. Like filter functionality – in case filter function returns false, kernel should stop execution for the current graph branch.

So we need to introduce step types:

const step = type => fn => ({
  type,
  fn,
})

export const compute = step('compute')

Function step creates step object, containing fields type and fn. Let's begin with single step compute and change our existing code.

// change `watch` node

export const watch = unit => fn => {
  const node = createNode({
-    seq: [fn],
+    seq: [compute(fn)],
  })
  unit.graphite.next.push(node)
}

// --8<--

// change `store` unit

  store.graphite = createNode({
-    seq: [value => (currentState = value)],
+    seq: [compute(value => (currentState = value))],
  })

  store.on = (event, fn) => {
    const node = createNode({
      next: [store.graphite],
-      seq: [value => fn(currentState, value)],
+      seq: [compute(value => fn(currentState, value))],
    })
    event.graphite.next.push(node)
    return store
  }

We also need to change kernel with following requirements:

Kernel should be able to do different actions depending on a step type
For the filter functionality we should be able to stop execution of current branch

In the first version we've used .forEach to traverse through all node steps. But it is impossible to stop and quit .forEach, so we have to rewrite it with good old for cycle:

const exec = () => {
  while (queue.length) {
    let { node, value } = queue.shift()

    for (let i = 0; i < node.seq.length; i++) {
      const step = node.seq[i]
      switch (step.type) {
        case 'compute':
          value = step.fn(value)
          break
      }
    }

    node.next.forEach(node => queue.push({ node, value }))
  }
}

Now our steps preparations are done, let's go with maps first.

Event.map

export const createEvent = () => {
  // --8<--

  event.map = fn => {
    const mapped = createEvent()
    const node = createNode({
      next: [mapped.graphite],
      seq: [compute(fn)],
    })
    event.graphite.next.push(node)
    return mapped
  }

  // --8<--
}

.map method accepts map function. It creates new event unit, and ties two events, old and new one, with new auxiliary node map. And given map function is executed inside this auxiliary node, to modify data.

Event.prepend

Prepend is kind of like reverse map – it prepends event with new event.

export const createEvent = () => {
  // --8<--

  event.prepend = fn => {
    const prepended = createEvent()
    const node = createNode({
      next: [event.graphite],
      seq: [compute(fn)],
    })
    prepended.graphite.next.push(node)
    return prepended
  }

  // --8<--
}

.prepend method behaves almost exactly like .map, just in an opposite direction:

Store.map

export const createStore = defaultState => {
  // --8<--

  store.map = fn => {
    const mapped = createStore(fn(currentState))
    const node = createNode({
      next: [mapped.graphite],
      seq: [compute(fn)],
    })
    store.graphite.next.push(node)
    return mapped
  }

  // --8<--
}

.map method accepts map function. It creates new store unit, and ties two stores, old and new one, with new auxiliary node map. And given map function is executed inside this auxiliary node, to modify data.
Additionally, to compute new store initial state, this method calls map function once with current store state.

⚠️ It should be noted, that this implementation doesn't follow Effector API completely – map function doesn't receive mapped store state as a second argument. We will fix this in later chapters.

Event.filter

Filter functionality is a bit different beast. This is the first place, where we need new step type:

export const filter = step('filter')

We also need to teach our kernel to support this new step filter:

const exec = () => {
-  while (queue.length) {
+  cycle: while (queue.length) {
    let { node, value } = queue.shift()

    for (let i = 0; i < node.seq.length; i++) {
      const step = node.seq[i]
      switch (step.type) {
        case 'compute':
          value = step.fn(value)
          break
+        case 'filter':
+          if (!step.fn(value)) continue cycle
+          break
      }
    }

    node.next.forEach(node => queue.push({ node, value }))
  }
}

If we meet a step with type filter, and its filter function returns falsy value – we just skip all other execution in this branch.
If you are unfamiliar with this strange syntax continue cycle – this is called label, you can read about it here.

Next let's add .filter method to event:

export const createEvent = () => {
  // --8<--

  event.filter = fn => {
    const filtered = createEvent()
    const node = createNode({
      next: [filtered.graphite],
      seq: [filter(fn)],
    })
    event.graphite.next.push(node)
    return filtered
  }

  // --8<--
}

As you can see, it looks exactly like .map method, with only difference – instead of step compute we use step filter.

⚠️ This implementation doesn't follow Effector API also – due to historical reasons Effector's Event.filter accepts not function, but object {fn}.

Event.filterMap

export const createEvent = () => {
  // --8<--

  event.filterMap = fn => {
    const filtered = createEvent()
    const node = createNode({
      next: [filtered.graphite],
      seq: [compute(fn), filter(value => value !== undefined)],
    })
    event.graphite.next.push(node)
    return filtered
  }

  // --8<--
}

.filterMap method is like .map and .filter combined together. This is the first place, where we've created auxiliary node filterMap, containing two steps – compute, to execute given function, and filter, to check, if we have undefined or not value.

And that's it for today!
You can see all this chapter changes in this commit.
I've also added automated testing, so we can be sure, that we will not break old functionality with new one.

Thank you for reading!
To be continued...

E~wee~ctor: writing tiny Effector from scratch #1 — Counter

Victor Didenko — Wed, 01 Apr 2020 21:11:15 +0000

Hi, all!

I really like "Implement something from scratch" type of articles, for example:

Lost with Redux and sagas? Implement them yourself!
Building Redux from scratch
Build your own React – this one is particularly awesome

It is a good way to learn how things work, and to unveil magic behind the black box of a library.

I plan to write a small Effector ☄️-like library called E~wee~ctor. This will be an educational-only purpose project.

Name "eweector" is derived from "effector" and "wee", meaning "little, small, tiny"
Second meaning of "wee" is also fit
Also my name is Victor and I like how "eweector" sounds :)

Good and simple place to start is a "counter" example from Effector website:

import {createStore, createEvent} from 'effector'

const add = createEvent()
const sub = createEvent()
const reset = createEvent()

const counter = createStore(0)
  .on(add, (count, n) => count + n)
  .on(sub, (count, n) => count - n)
  .reset(reset)

counter.watch(n => console.log('counter:', n))
// counter: 0
add.watch(n => console.log('add', n))
sub.watch(n => console.log('subtract', n))
reset.watch(() => console.log('reset counter'))

add(5)
// add 5
// counter: 5
sub(1)
// subtract 1
// counter: 4
reset()
// reset counter
// counter: 0

Thus we need to implement two main entities – event and store – and some of their methods.

I will not dive deeply into Effector right now, if you want to do it, check this article out. But here are some highlights from Effector's architecture:

Effector internally creates a graph of nodes
Nodes has (obviously) links to next nodes = edges of the graph
Any node can contain sequence of steps to run
A step can modify input data somehow, or stop branch computation, or launch some side-effect function
Upon some event Effector's kernel passes input data to a node and starts executing steps, using the breadth-first search algorithm
Any high-level Effector's unit (Event, Store, Effect, Domain) is a some object, attached to a node or bunch of nodes.

Here is the logical relationship graph for the code above:

And here is what Effector creates, structural graph of nodes:

Node

Let's start with the core thing of a graph – a node. A node should contain links to the next nodes – edges of a graph, and sequence of steps – where we will describe logic.

export const createNode = ({ next = [], seq = [] } = {}) => ({
  next,
  seq,
})

createNode factory function is very simple, it just creates a node object and nothing else. We could even go without it, and describe nodes in-place, like plain objects. But factory function gives us two benefits:

Each and every node it returns has same structure, so we will not miss some fields, defining them manually
ES6 syntax has very handy default parameters and destructuring assignment, and they can take burden of assigning default field values for node

Steps

Next thing we need is steps. There are six types of steps in Effector, but we will start from a single one. And we will not even create factory for it :) Let's just use function as a step. So out nodes will contain a sequence of functions to execute.

Event

Event is the simplest Effector unit. It is a function, attached to a graph node. The only purpose of an event as a high-level entity is to place input data into the node and to start computation cycle.

export const createEvent = () => {
  const event = payload => launch(event, payload)
  event.graphite = createNode()
  return event
}

createEvent factory creates function and attaches graph node into its graphite field. Created event-function accepts input data and executes function launch. This launch function will start a computation cycle, and we will describe it later, when we write a kernel.

As you can see, a node, attached to an event, doesn't have any next nodes, nor steps.

Watch

Before writing a kernel, let's implement watch functionality.

Watch is an auxiliary node, which runs side-effect. In case of our counter example this side-effect is console.log.

export const watch = unit => fn => {
  const node = createNode({
    seq: [fn],
  })
  unit.graphite.next.push(node)
}

watch function accepts two arguments (in a functional programming meaning) – unit to attach watch node, and function to execute.

As we decided to use simple functions as steps (for now) – we will just use given side-effect function as a step for watch node.

And after creating watch node, we put this node to the next array for the given unit.

And now let's add .watch method to our event:

export const createEvent = () => {
  const event = payload => launch(event, payload)
  event.graphite = createNode()
+  event.watch = watch(event)
  return event
}

So we will be able to watch events:

const event = createEvent()
event.watch(data => console.log(data))

Kernel

And here we go :) The kernel. It is not that frightening as it sounds, really.
There are two main parts of the kernel: queues and computation cycle.

Effector utilises five queues. We will start with single one:

// contains objects { node, value }
const queue = []

Computation cycle traverses graph and executes each step from each node:

const exec = () => {
  while (queue.length) {
    let { node, value } = queue.shift()
    node.seq.forEach(step => (value = step(value)))
    node.next.forEach(node => queue.push({ node, value }))
  }
}

In simple words function exec can be described as following steps:

While queue is not empty, take element from queue
Execute each step from node, with initial value from queue element
Put each node from next array to the queue, with new value
Go to 1.

One more thing – we need function launch for our events:

export const launch = (unit, value) => {
  queue.push({ node: unit.graphite, value })
  exec()
}

launch function just puts node and value into the queue, and starts computation cycle. Thats it.

Store

And last, but not least – a store.

export const createStore = defaultState => {
  let currentState = defaultState
  const store = {}

  store.graphite = createNode({
    seq: [value => (currentState = value)],
  })

  return store
}

createStore factory creates object, and attaches graph node into its graphite field, just like with an event. But store node has one step – it saves input data into an enclosured variable currentState.

We also need to implement few store's methods, like .on, .reset and .watch. Let's start with last one:

  store.watch = fn => {
    fn(currentState)
    return watch(store)(fn)
  }

.watch method for store is a bit different, than for an event – first time it is called it executes given function with current state, and then creates watch node.

  store.on = (event, fn) => {
    const node = createNode({
      next: [store.graphite],
      seq: [value => fn(currentState, value)],
    })
    event.graphite.next.push(node)
    return store
  }

.on method accepts an event (or any unit) and reducer function. Like .watch method it creates a new on node, with one step, where reducer is called. And places this new node before store node in the graph, so new value from reducer will be saved in the store node. Also it puts this new node to the next array for the given event (or unit).

  store.reset = event => store.on(event, () => defaultState)

.reset method is just shortcut to set initial state.

And we've done our first step in this journey. If we combine all these pieces together, we will get minimal working "eweector", which could run counter example. And what is more important – it follows Effector's architecture!

In next chapters we will grow up our infant. I'll try to cover all Effector's API in reasonable limits, so stay tuned ;)

I've created project on GitHub to help you follow the source code.
All code, described in this chapter, is committed in this commit.

Thank you for reading!

Effector: we need to go deeper

Victor Didenko — Thu, 19 Mar 2020 19:42:34 +0000

This is a script of my talk for the Effector meetup #1
You can find the slides here, and the video from the meetup here

⚠️ Note! Information in this article has been outdated a bit, and could be not specifically accurate. But overall architecture view is still relevant.

Hi, folks!

So, Effector. Why does anyone even need to look under the hood? Why go deeper? As you know, it can be dangerous, and you may get stuck in Limbo.

I'll tell you why I needed this knowledge and why it can be useful for you.

This is a photo from the 1966 24 Hours of Le Mans. Three Ford GT40s are finishing almost at the same time. Ford management wanted all three cars to cross the finish line together because this would make a perfect advertising photo.

When I create an effect and run it three times, I imagine it this way:

This effect launches three parallel asynchronous operations that work independently of each other. However, in some cases, it may be useful to coordinate them somehow, just like Ford management coordinated the cars at the 1966 24 Hours of Le Mans.

Let's say, you have an effect that submits a form to the server. When the user clicks the button, the effect is launched. But if the user clicks the button again, it's undesirable that the effect be launched for the second time. You have to either block the button or ignore any further clicks/effects.

A more interesting example is the auto-suggest function. When the user types in four letters, the effect launches to get suggestions from the server. However, if the user types in the fifth letter, the previous request is not relevant anymore. You have to cancel (or ignore) it and launch the effect again to get suggestions for a five-letter string.

It occurred to me that this is quite a frequent use case, so I wrote my own library called ReEffect, which slightly extends the effects from Effector adding a run strategy to them. I fully covered the code with tests, but when I tried to use my ReEffect with forward – it didn't work.

(Hey! I've written ReEffect. Yeah, but it doesn't work with forward. But… the tests…)
Just in case you’re curious, it works now, you can use it :)

I was in despair and asked Dmitry Boldyrev, the author of Effector, for help. He briefly told me about its internals and operation in general. And when I started to dig deeper, I began to realize that my understanding of Effector was like a pile of non-related pieces of a puzzle. It seemed simple, just four entities (event, store, effect, and domain) and 10-15 API methods. I could combine those pieces, glue them together by two or three, and use this Frankenstein's monster somehow. However, I didn't have the whole picture in my head, and the pieces didn't fit into the solved puzzle. Until I started to dig deeper.

I also hope that knowing how Effector works under the hood will help you to do this puzzle, if you have a similar pile of scattered puzzle pieces in your head as I did. It will help you to gain a clear understanding of Effector, or, at least, build the foundation for its understanding.

Let's start from afar. From the 18^th century :)

This is Leonhard Euler, mathematician, engineer, and scientist, who lived in the 18^th century. Once Euler was asked to solve a problem known as the Seven Bridges of Königsberg.

The city of Königsberg in Prussia (now Kaliningrad, Russia) was situated on both sides of the Pregel River and included two large islands – Kneiphof and Lomse – which were connected to each other, or to the two mainland portions of the city, by seven bridges. The problem was to devise a walk through the city that would cross each of those bridges once and only once.

If you don't know anything about this problem, you can stop here and try to find a solution :)

Euler found a solution and this solution is considered to be the first theorem of what now is called the graph theory.

Do you know what a graph is?

Imagine that each small circle in the image above is an object. Each structure in this image is called a graph. One object represents one vertex (or node) of the graph. The so-called list or bidirectional list is also a graph. A tree is a graph. Actually, any set of vertexes/nodes somehow connected with a set of edges (or links) is called a graph. There is nothing scary here.

I dare say you have already worked with graphs. A DOM tree is a graph. A database is a graph of tables and relations. Your friends and the friends of your friends on Facebook or VK form a graph. A file system is a graph (many modern file systems support hard links, and thus become "true" graphs, not trees). Wikipedia pages with internal links form a graph.

The whole human population of the Earth forms a huge graph of relationships, where you (yes, you, reader!) are just six (or fewer) social connections away from Donald Trump (as well as from Vladimir Putin). This is known as the 6 handshakes rule.

You may ask, how is all this related to Effector?

All Effector entities are connected in a graph! That's how!

If you think a bit and try to make logical connections between different entities, you will see it yourself.

Check out the following code:

const change = createEvent()
const onclick = change.prepend(
  e => e.target.innerText
)

const { increment, decrement } = split(change, {
  increment: value => value === '+',
  decrement: value => value === '-'
})

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

const foo = counter.map(state => state % 3 ? '' : 'foo')
const bar = counter.map(state => state % 5 ? '' : 'bar')
const foobar = combine(foo, bar,
  (foo, bar) => foo && bar ? foo + bar : null
)

sample({
  source: change,
  clock: foobar.updates.filterMap(value => value || undefined),
  target: change
})

Here is a working REPL, where you can try out this code online

Let's draw logical connections between different entities in this code:

In a slightly better way, the result looks as follows:

As you can see, this is a graph.

I'd like to emphasize that we haven't even looked under the hood yet, all we've done so far is draw logical connections between the Effector entities. And now we've got a graph.

The most exciting part is that Effector actually works this way!

Any entity generated by Effector creates a node (or nodes) in a structural graph. And any Effector API creates and/or connects different nodes in this structural graph.

And I think it is great! We have a logical graph of relationships between different entities. Why not implement it using a physical structural graph of some nodes?

And now, we will open the hood and look under it!

This is what an Effector node looks like:

You can check out this interface here. I just rewrote it from Flow to Typescript and renamed a little

An Effector node is just an object with the following fields:

next – links to the next nodes. These are the edges of our graph.
seq (from "sequence") – a sequence of steps for that node. The sequence of steps is what makes the types of nodes unique. We will take a closer look at the steps in a few minutes.
scope – arbitrary data necessary for the steps. This object will be passed to the step during the node execution.
reg (an unstable field that can be removed) – references to the stores necessary for the steps.
meta – arbitrary metadata, for example, the name of an entity is stored here.
family – describes the ownership graphs:
- type – the role of this node in each ownership graph.
- links – links to the nodes that belong to the given node. In other words, they indicate the nodes we need to delete when we delete this node.
- owners – links to the nodes that own the given node. That is to say, these links indicate the nodes from which we have to remove the link to the given node when we delete this node.

Thus you can see that we have more than one graph here: a computation graph (by links in the next field), two ownership graphs (by links in family.links and family.owners), and a graph of links to the stores (in the reg field).

Below, I will concentrate on fields next and seq, because these are the two main fields, where the logic of the whole process is described.

So, how does the Effector kernel work in a simple case?

Here are five nodes connected in a graph (in a tree configuration, but that's not the point). And at some moment, the data appears!

When the data is put in the node, this node is added to a queue, and the main cycle begins.
In each cycle iteration, the Effector kernel takes a node from the queue and executes all its steps.
Then the kernel adds all the nodes from next to the queue.
Then it repeats stages 2, 3 and 4 until there is nothing in the queue.

By the way, this graph transversal algorithm is called the breadth-first search. Effector uses a slightly modified breadth-first search algorithm with priorities. We will see it later.

Let's have a closer look at these three points:

What kind of data is it and how does it get into the node?
Various kinds of steps and how they differ
Queue

So, what kind of data is it and how does it get into the node?

The answer is events!

When you call an event (a simple function), all it does is send the payload to the graph and launch a computation cycle.

Also, of course, there are effects and stores.

You call an effect the same way you call an event (like a simple function) and thus send data into the graph. And when the operation is over, the resulting data also gets into the graph (into events/nodes .finally/.done/.fail).

The store has undocumented method .setState() that also transmits the payload to the graph. In fact, this doesn't differ much from the event.

But what exactly is an event?

An event is a simple function that receives the payload and calls function launch with itself and the received data. What is launch? launch is the only function exported by the Effector kernel and the only way to put data into the graph and launch a computation cycle.

"But what the heck, I can't see any nodes or graphs here!", – you might say. Well, that's because I haven't shown you the main thing:

Field .graphite:

This is where our node is located. It's a communication point and a bridge from the event function to the graph.

Any Effector API works with field .graphite (or if there is no such field, the Effector API thinks that it works with the node directly).

So, an event is a function with a node in field .graphite. A store is an object with a node in field .graphite. And an effect is also a function with a node in field .graphite (an effect is a complex entity that contains other nodes, but the main node – the bridge from the function and the entry point – is located in the .graphite field).

And here is an interesting thing – the Effector API doesn't care what exactly is connected to the node. It can be a function, like events and effects, or a plain object like a store, or an async generator, which yields values when its node receives the given value. Or this can be a field in a prototype chain, then all instances of a class will be connected to the same graph node (I don't know how this can be useful, though).

What are steps and how do they differ?

A step is just an object with field .type. Inside the Effector kernel, there is a big switch (step.type) that decides what to do depending on the type of the step. For convenience, the Effector package exports the step object to create different types of steps.

There are six types of steps:

compute – a step to do pure computations. It accepts input data and returns new transformed data. For example, the reducer function in store.on is launched inside the compute step. The map function in store.map also runs inside this step.
run – the same as compute, although aimed to execute side-effects. When the kernel meets step run, the computation for the node is postponed (I will show it later). Thus, any side-effects are executed after any pure computation. This step is used, for example, in watch nodes (yes, the .watch method creates a new node).
filter – a step to stop computations. It accepts input data and returns true or false values. And in case it's false, the branch of computation stops here, i.e. no further steps will be executed and the nodes from the next field will not be added to the queue. This step is used, for example, in .filter and .filterMap nodes.
barrier – a step with no logic, but this step either postpones the execution of the node or cancels it if the execution has already been postponed. This step is used in combine and sample.
check – a step with two checks:
- defined – checks that the input data is not undefined
- changed – checks that the input data is different from the data saved in the store
mov – a step with almost internal logic. I will not describe it here, but long story short, this step copies data from/to the store and/or internal stack fields. I call them registers, like registers in CPU, e.g. AX or BX.

Now, the queue. Or queues, because there are five of them in the Effector kernel :) Here is the difference from the usual breadth-first search algorithm – the nodes can be moved to a different queue under some conditions.

child – the nodes from field next are placed in this queue.
pure – the launch function will add a node/nodes to this queue.
barrier and sampler – two queues where the nodes with step barrier are placed.
effect – a queue where the nodes with step run are placed.

Queues have different priorities. In each iteration of the computation cycle, the kernel gets a node to process from the queue, depending on priority. So, top priority queue child is emptied first, and least priority queue effect is emptied last. Thus, the side-effects are always executed after pure computations.

Why do we even need different queues and priorities? Let's have a look at a common problem called the diamond dependency problem.

Another name for this problem is the glitches problem.

A glitch – is a temporary inconsistency in the observable state.

In essence, the problem is when there are many stores connected in a complex way, and a single update of one store can cause multiple updates of another store. Stores are frequently used in views, and fast multiple updates of one store cause useless view re-renders, and this looks like glitches, hence the name.

Here is a simple analogy with the Redux world: why do we even need to use memoized selectors? Because if we don't use them, any store update will cause the update of all the components, even if their data (part of the store) has not been updated.

Another example is from Rx world:

--a------b------c------d--------e--------
--1-------------2---------------3--------
           combineLatest
--a1-----b1-----(c1c2)-d2-------(e2e3)---

The events in parentheses happen "simultaneously". In practice, they happen at slightly different time periods separated only by a couple of nanoseconds. That's why people consider them to be simultaneous. Events (c1c2) are called glitches and sometimes thought to be a problem because one usually expects only c2 to happen.

So, what does Effector do to avoid this problem? This is one of the reasons why barriers and different priority queues exist.

Here is an example code:

const setName = createEvent()

const fullName = createStore('')
  .on(setName, (_, name) => name)

const firstName = fullName.map(
  first => first.split(' ')[0] || ''
)

const lastName = fullName.map(
  last => last.split(' ')[1] || ''
)

const reverseName = combine(
  firstName,
  lastName,
  (first, last) => `${last} ${first}`
)

reverseName.watch(
  name => console.log('reversed name:', name)
)

setName('Victor Didenko')

Event setName accepts the full name
The full name is set to store fullName
Two derived stores firstName and lastName are set automatically to the first and last name (the map function divides the full name with a space)
The combined store reverseName depends on stores firstName and lastName and joins their values in reverse order

Here is a question: will store reverseName be updated once (correctly) or twice (glitch)?

If you've checked the REPL, you already know the right answer. The store will be updated only once. But how does this happen?

Let's unfold this logical graph of relationships into a structural graph of Effector nodes:

Here is a full static view of the Effector graph:

Here you can see a few auxiliary nodes like .on between the event and the store, .map between the store and the derived store, and combine between the stores and the combined store. And that is where the beauty of Effector lies, in my opinion. You can perform any operation between entities/nodes by adding one or more auxiliary nodes with some logic. For example, forward just adds one node between two nodes. .watch only adds one new node. .on adds one auxiliary node between the event and the store. And if you want to perform operation .off, you just remove this intermediate node! Fascinating, isn't it?

The edges in this computation graph are drawn only by the links in field next. I didn't draw the ownership graphs, nor the graphs of links to the stores.

I will not explain each step in this graph (moreover, the implementation can be changed), but I want you to pay attention to a few things:

When you use API store.on(event, reduce) – the reduce function is executed inside intermediate node .on by the second step compute.
The current store value is copied to the intermediate node by the first step mov.
Intermediate nodes .map look exactly like node .on – in other words, this literally means that the derived store subscribes to the updates of the parent store. Just like the store subscribes to the event. There is one difference though – the map function gets a new value (from the parent store) as the first argument, as opposed to the reduce function, which gets a new value (from the event) as the second argument, and the current store value as the first one.
Any store has check.defined as the first step, so it is impossible to set an undefined value to the store.
Also there is a step check.changed in each store, so if the store value has not been changed by the new data, there will be no update to the next nodes in the graph.

And I'd like to describe step barrier in node combine in more detail. Here is the animation of solving the diamond problem:

What is going on, step by step:

At some point, we have two nodes in the child queue – firstName and lastName.
The kernel gets firstName and executes the node steps. Then it adds node combine to the child queue. Node .updates is also added, but it's a trivial process, so I'll ignore it here.
The kernel gets the next node lastName and executes the node steps. Then it also adds node combine (the same node) to the child queue. So, now we have two links to the same node in the queue.
The kernel gets node combine and executes the node steps until it meets step barrier.
When the kernel meets step barrier, it pauses the node execution and places this node to the barrier queue. The kernel also saves the barrier ID and the step index where the execution was paused.
Then the kernel gets node combine (the same node) from the child queue (because the child queue has higher priority than the barrier queue) and executes the node steps until it meets step barrier.
When the kernel meets step barrier, it pauses the node execution, but now it knows that there already is one postponed node in the barrier queue with the same barrier ID. So, instead of placing this node to the barrier queue again, the execution of this branch just stops here.
Please note that the execution stop is not throwing all computation results away. Node combine saves both the firstName value and the lastName value for this moment.
Now the child queue is empty, so the kernel gets node combine from the barrier queue and continues the execution from the step where it was paused.
Thus, only one execution branch of two gets through step barrier. So, this is how the diamond problem is solved. Store reverseName will get only one update.
If you are interested, the combine function is executed in step compute after step barrier – both values already exist here.

In Effector telegram chat, I saw a beautiful comparison of the computation cycle with lightning: calculations branch, diverge, converge, get cut and so on, but all these are parts of one single discharge.

And returning to the very beginning, why do you need to know the Effector internals?

If you search through the Effector documentation, you will not find any mention of the graphs (except for the Prior Art section). That is because you don't need to know the internal implementation to use Effector effectively. Sorry for the tautology. Your decision to choose one tool over another should be motivated by the task this tool aims to solve, and not by the tool's internal implementation. Effector solves any state manager problems like a boss, by the way ;)

But! There are always buts :)

Knowing what is going on under the hood, you can clean up the mess in your head if you do have it as I did. Imagine the whole picture, solve the puzzle, and build that racing car out of a pile of scattered pieces.

By the way, if you have some irrational fear of the word "graph", I can show you a mental lifehack for that:

You see the word "graph", you hear the word "network".

I'm serious, it is the same thing. But historically the term "network" is more widespread among engineers, not mathematicians.

This knowledge also gives you a bonus: you can create your own entities with your own logic that will work alongside with native Effector entities :)

I won't show you anything complex, but just a simple example: node future (I also call it a "porter"). It accepts any data and passes it further to the graph if it is not Promise. But if it is, the node holds it until Promise is resolved.

function createFuture () {
  const future = createEvent()
  future.graphite.seq.push(
    step.filter({
      fn(payload) {
        const isPromise = payload instanceof Promise
        if (isPromise) {
          payload
            .then(result => launch(future, { result }))
            .catch(error => launch(future, { error }))
        }
        return !isPromise
      }
    })
  )
  return future
}

const future = createFuture()
future.watch(_ => console.log('future:', _))

future(1)
future(new Promise(resolve => setTimeout(resolve, 100, 2)))
future(Promise.resolve(3))
future(Promise.reject(4))
future(5)

As you see, I took an ordinary event and modified its seq field, i.e. added one step filter. It is possible to create an entity with a node from scratch, but in that case, you should also think about implementing useful methods like .watch, .map, .prepend and so on. The event has them by default, so why not use them :)

The above code will print the following:

future: 1
future: 5
future: {result: 3}
future: {error: 4}
future: {result: 2}

And to finish, I'd like to put here an out-of-context quote by Linus Torvalds:

Bad programmers worry about the code. Good programmers worry about data structures and their relationships.

So, think about your tools.
Worry about data structures.

Thank you.

DEV Community: Effector

effector-storage v6

Contracts support

Exported adapters

Adapter utilities

async utility function

either utility function

farcached utility function

Adapter context

Force sync mode

Throttle/batch writes

Drop Effector v21 support

classList API in forest

There is no JSX or another specific syntax

Data-attributes

Event handlers

Style properties

Whole picture

Forest doesn't require return from components

What was before classList

What do we have now?

Using GQty with effector

Introduction

Using with effector

Step 1: Create type-caster functions

Step 2. Use helper functions from gqty

Step 3. Put all the effects in a separate API layer.

Why we need attach

The best part of Effector

Disclaimer

The Problem

Tests

SSR

Classic Solutions

Redux

MobX

Effector-world

Tests

One more thing

SSR

So?

Effector's beginner guide

The application is a system

Back to effector

Units:Event

Units:Store

Units:Effect

Regular units

Units:Domain

Data preparation

Store data preparation

Dataflow. Beginning

Dataflow. Filtering

Dataflow. Signals

Dataflow organization

Reuse and environment-dependent code

Testing

Project to start with

E~wee~ctor: writing tiny Effector from scratch #4 — Effect

E~wee~ctor: writing tiny Effector from scratch #3 — Simple API methods

forward

merge

split

createApi

is

restore

E~wee~ctor: writing tiny Effector from scratch #2 — Maps and Filters

Steps

Event.map

Event.prepend

Store.map

Event.filter

Event.filterMap

E~wee~ctor: writing tiny Effector from scratch #1 — Counter

Node

Steps

Event

Watch

Kernel

Store

`async` utility function

`either` utility function

`farcached` utility function

Forest doesn't require `return` from components

What was before `classList`

Why we need `attach`