Architecture / pattern / conventions / best practices?

[maximelebreton]

Hello,
I would like to know if there is some official / unofficial best practices for architecturing our apps at scale?

Considering we have a user model

// Typescript
type User = {
  id: string
}

Store
Model name with a $ prefix?

const $user = createStore(null)

// Typescript
const $user = createStore<User>(null)

Events
Model name with a simple past verb suffix?

const userUpdated = createEvent('User updated')

// Typescript
const userUpdated = createEvent<User>('User updated')

Effect
Nothing special?

const fetchUser = createEffect().use(async (id) => {
  const response = await fetch(`https://example.com/users/${id}`);
  const user = await response.json()
  return user;
})

// Typescript
const fetchUser = createEffect<User['id'], User>().use(async (id) => {
  // ...
})

File name
Use the model name? user.js

Export (full example)

// user.js

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

export const $user = createStore<User>({
  id: 'John'
})

export const userUpdated = createEvent('User updated')

export const fetchUser = createEffect().use(async (id)=> {
  const response = await fetch(`https://example.com/users/${id}`);
  const user = await response.json()
  return user;
})

$user.on(userUpdated, (state, payload) => payload)

Import (full example)

// index.js

import  { $user, userUpdated, fetchUser   } from './user'

const suzanne = await fetchUser('Suzanne') // https://v8.dev/features/top-level-await
userUpdated(suzanne)
console.log($user.getState()) // { id: 'Suzanne' }

For simple apps, it's very easy to manage, but what about larger apps?

---

Namespacing?

Is createDomain can be a solution, or is it not his purpose? (it's not very clear for me)

Or is it ok to handle things like this:

Let's add a tracks model to the previous stuff

// Typescript
type Tracks = Array<number>

type User = {
  id: string,
  tracks: Tracks
}

// tracks.js

export const fetchTracksFromUser = (userId) => {
  // ...
  return [1, 2] // fake for example
}

1. First namespaced attempt

// index.js

import * as user from './user'
import * as tracks from './tracks'

const suzanne = await user.fetchUser('Suzanne')
const suzanneTracks = await tracks.fetchTracksFromUser('Suzanne')
user.userUpdated({  ...suzanne,  ...suzanneTracks })
console.log(user.$user.getState()) // { id: 'Suzanne', tracks: [1, 2] }

2. Second namespaced attempt

// index.js

import * as userStore from './user'
import * as tracksStore from './tracks'

const user = await userStore.fetchUser('Suzanne')
const tracks = await tracksStore.fetchTracksFromUser('Suzanne')
userStore.userUpdated({  ...user,  ...tracks})
console.log(userStore.$user.getState()) // { id: 'Suzanne', tracks: [1, 2] }

3. Third namespaced attempt

// store.js

import * as user from './user'
import * as tracks from './tracks'

export default {
  ...user,
  ...tracks
}

// index.js
import store from './store'

const user = await store.fetchUser('Suzanne')
const userTracks = await store.fetchTracksFromUser('Suzanne')
store.userUpdated({ ...user, ...userTracks })
console.log(store.$user.getState()) // { id: 'Suzanne', tracks: [1, 2] }

Thanks for your advices!

[zerobias]

Effector doesn't impose architectural techniques, so this list is only a recommendation

1. Stores are prefixed with $ (I personally prefer postfix)
2. Effects are postfixed with fx (this is a common term for effects in various industries)
3. You might call some of events with a simple past verb, but note that this not always a case:

const playerPosition = createStore(0)

const {moveLeft, moveRight} = createApi(playerPosition, {
  moveLeft: (x, amount) => x - amount,
  moveRight: (x, amount) => x + amount,
})

playerPosition.watch(x => {
  console.log(`player position: ${x}`)
})
// player position: 0

moveLeft(2)
// player position: -2
moveRight(4)
// player position: 2

Try example online

In this example, events are become an api to player movement, thus they are not "in the past" but rather intentions to future changes

Also note that you might not need the most of *Changed events at all: you might subscribe stores to effects directly:

const fetchUserFx = createEffect().use(() => 'alice')
const userName = createStore('guest')
  .on(fetchUserFx.done, (state, {result}) => result)

userName.watch(console.log)
// => guest
await fetchUserFx()
// => alice

Try example online

4. Domains are designed for applying operations to a group of entities:

const removeLast = createEvent()
const columns = createDomain()

columns.onCreateStore(store => {
  store.on(removeLast, list => list.slice(0, -1))
})

const names = columns.store(['alice', 'bob'])
const emails = columns.store([
  '[email protected]', '[email protected]'
])

Try example online

[zerobias]

Rather than naming conventions, effector itself suggests data conventions: how things are calculated in the application

For example, instead of spreads, you might use combine

const fetchUser = createEffect({
  handler: () => 'alice',
})
const fetchTracks = createEffect({
  handler: (userId) => [0, 5, 10],
})
const id = createStore('guest')
  .on(fetchUser.done, (_, {result}) => result)
const tracks = createStore<number[]>([])
  .on(fetchTracks.done, (_, {result}) => result)

// note also that user type will be inferred without explicit types
const user = combine({id, tracks})

fetchUser.done.watch(({result: userId}) => {
  fetchTracks(userId)
})
user.watch(console.log)
// => {id: guest, tracks: []}

await fetchUser()
// => {id: alice, tracks: []}
// => {id: alice, tracks: [0, 5, 10]}

Try example online

[maximelebreton]

Thanks a lot @zerobias!

[mikecann]

Just throwing my 2 cents in here as someone just coming to Effector. Im finding these naming conventions really confusing to be honest and the docs are extremely inconsistant about it.

IMO it would be easyier to learn this library by either having no convention (as mentioned above) or just using simple words such as "buttonClickedEvent" and "UsersStore" and "fetchDataEffect".

There are a few things to learn with this library and having to learn syntax such as what "$users" represents or "fxGetTodo" means ontop of that isnt helpful IMO..

[zerobias]

@mikecann we working on documentation consistency

#303