Family
atomFamily
Ref: https://github.com/pmndrs/jotai/issues/23
Usage
atomFamily(initializeAtom, areEqual): (param) => Atom
This will create a function that takes param
and returns an atom.
If it's already created, it will return it from the cache.
initializeAtom
is function that can return any kind of atom (atom()
, atomWithDefault()
, ...).
Note that areEqual
is optional, which tell
if two params are equal (defaults to Object.is
).
To reproduce the similar behavior to Recoil's atomFamily/selectorFamily,
specify a deepEqual function to areEqual
. For example:
import { atom } from 'jotai'import { atomFamily } from 'jotai/utils'import deepEqual from 'fast-deep-equal'const fooFamily = atomFamily((param) => atom(param), deepEqual)
TypeScript
The atom family types will be inferred from initializeAtom. Here's a typical usage with a primitive atom.
import type { PrimitiveAtom } from 'jotai'/*** here the atom(id) returns a PrimitiveAtom<number>* and PrimitiveAtom<number> is a WritableAtom<number, SetStateAction<number>>*/const myFamily = atomFamily((id: number) => atom(id)).
You can explicitly declare the type of parameter, value, and atom's setState function using TypeScript generics.
atomFamily<Param, Value, Update>(initializeAtom: (param: Param) => WritableAtom<Value, Update>, areEqual?: (a: Param, b: Param) => boolean)atomFamily<Param, Value>(initializeAtom: (param: Param) => Atom<Value>, areEqual?: (a: Param, b: Param) => boolean)
If you want to explicitly declare the atomFamily for a primitive atom, you need to use SetStateAction
.
type SetStateAction<Value> = Value | ((prev: Value) => Value)const myFamily = atomFamily<number, number, SetStateAction<number>>((id: number) => atom(id),)
Caveat: Memory Leaks
Internally, atomFamily is just a Map whose key is a param and whose value is an atom config. Unless you explicitly remove unused params, this leads to memory leaks. This is crucial if you use infinite number of params.
There are two ways to remove params.
myFamily.remove(param)
allows you to remove a specific param.myFamily.setShouldRemove(shouldRemove)
is to registershouldRemove
function which runs immediately and when you are to get an atom from a cache.- shouldRemove is a function that takes two arguments
createdAt
in milliseconds andparam
, and returns a boolean value. - setting
null
will remove the previously registered function.
- shouldRemove is a function that takes two arguments
Examples
import { atom } from 'jotai'import { atomFamily } from 'jotai/utils'const todoFamily = atomFamily((name) => atom(name))todoFamily('foo')// this will create a new atom('foo'), or return the one if already created
import { atom } from 'jotai'import { atomFamily } from 'jotai/utils'const todoFamily = atomFamily((name) =>atom((get) => get(todosAtom)[name],(get, set, arg) => {const prev = get(todosAtom)set(todosAtom, { ...prev, [name]: { ...prev[name], ...arg } })},),)
import { atom } from 'jotai'import { atomFamily } from 'jotai/utils'const todoFamily = atomFamily(({ id, name }) => atom({ name }),(a, b) => a.id === b.id,)