Document the use of a function as the second parameter of set

[mon-jai]

Summary

While exploring the atom page, I discovered that it's possible to pass a function as the second parameter of set. This function will be automatically invoked, receiving the atom's current value as its first parameter.

const countAtom = atom(1)
const derivedAtom = atom(
  (get) => get(countAtom),
  (get, set, action) => {
    set(countAtom, (c) => c + 1)
  },
)

It would be better if we document the behavior explicitly in the "derived atoms" section of the page.

https://github.com/pmndrs/jotai/blob/234dff9/docs/core/atom.mdx#L26-L50

const writeOnlyAtom = atom(
  null, // it's a convention to pass `null` for the first argument
  (get, set, update) => {
    // `update` is any single value we receive for updating this atom
    set(priceAtom, get(priceAtom) - update.discount)
+   // We can also pass a function as the second parameter
+   // The function will be invoked, receiving the atom's current value as its first parameter
+   set(priceAtom, (price) => price - update.discount)
  },
)

Link to reproduction

https://jotai.org/docs/core/atom

[mon-jai]

I can open a PR if you like the idea.

[dai-shi]

Are you still around?

[dai-shi]

I discovered that it's possible to pass a function as the second parameter of set.

Internally, it will simply invoke the target atom's write function. So, it is possible because countAtom accepts such a function.

I can open a PR if you like the idea.

Yes, feel free to open a PR please.

[dai-shi]

#2271

[PetrusAsikainen]

I wonder if it would be possible to type Setter or PrimitiveAtom such that primitive atoms with a function type would warn correctly if you accidentally try to set them to a function. This is quite an easy gotcha to hit:

const handlerAtom = atom<(() => void) | null>(null);
// ...

// sets anAtom to undefined
set(handlerAtom, () => { /* do stuff */ });

Something like this might avoid many erroneous cases:

type SetStateAction<Value> = Value extends ((...args: never[]) => unknown)
  ? (prev: Value) => Value
  : Value | ((prev: Value) => Value);

(That exact code breaks with some wide value types, though, so I'm not exactly sure how it would be implemented.)

[dai-shi]

primitive atoms with a function type

I think, if possible, such primitive atoms should not be allowed in TypeScript.

There are many ways to work around the limitation (for example, specify the custom write function), but the easiest is not to use the function type.