[RFC] useAtomValue and useSetAtom APIs in core

[dai-shi]

When we designed the API, we wanted to make it small and the core provides only three functions: atom, useAtom, and Provider.
Later, Provider becomes optional.

Now, we have useAtomValue and useUpdateAtom exported from jotai/utils.

Implementation-wise, having them in core makes more sense.

We want to keep claiming that jotai has small API surfaces, but adding those two in core should be fine.
There will be two basic APIs and three additional APIs.

• Basic APIs: atom, useAtom
• Additional APIs: Provider, useAtomValue, useSetAtom

---

notes:

• The name change from useUpdateAtom to useSetAtom is intentional. Should have done this from the beginning.
• We will keep exporting useAtomValue and useUpdateAtom from jotai/utils for backward compatibility.

[Thisen]

Happy to work on this @dai-shi

[dai-shi]

@Thisen No rush. It will still take time. The src part is trivial. The docs part is bigger.

[loganvolkers]

@dai-shi I'd prefer useAtomSetter or useAtomCallback or useAtomUpdater or useAtomDispatcher or anything such as useAtom* instead of useUpdateAtom or useSetAtom or anything such as use*Atom

It's because it translates to plain English.

"Use the atoms value"
"Use the atoms setter"

Versus

"Use an update atom"
"Use a set of atoms"

useSetAtom sounds like useMapAtom, possible referring to Set and Map.

To help illustrates my point the API shouldn't be useGetAtom and useSetAtom.

[dai-shi]

Hm, that useSetAtom can be confusing with Set is convincing. Technically, it means useAtomDispatcher but I'm not a fan of it.
All that considered, I still think my options are useUpdateAtom and useSetAtom, at this moment.

Any other comments from someone else?

[justjake]

useWriteAtom seems worse than useSetAtom or useUpdateAtom.

I think useSetAtom is fine, it seems Jotai is moving away from util hooks that produce atoms, eg, we go from useAtomWithDefault to useAtom(atomWithDefault(...)), I think useSetAtom reads okay thaking that into account.

[dai-shi]

It seems like there will be none that everyone would be happy with.
At Poimandres, if we have options, we prefer something shorter/compact.
So, I'm leaning towards useSetAtom. But, still open for comments. Anyone else?

@Thisen If you would really like to work on it, you can start working on a draft pr. Note that there's no ETA, and the pr will be long lived, like for months.

[sandren]

So, I'm leaning towards useSetAtom. But, still open for comments. Anyone else?

I favor it for its brevity as well. 🙂

[dai-shi]

Found an RFC in recoil: facebookexperimental/Recoil#804

Community-wise, it's not a bad idea to follow with useAtomSetter.

It's unfortunate, we had internally Getter and Setter types, though.

My current options are: useUpdateAtom, useSetAtom, useAtomSetter.

Anyone has/change a vote?

[alex-cory]

useSetAtom

[loganvolkers]

@dai-shi I retract my original opposition.

I changed my mind because the React hooks community is firmly behind naming these functions as set____ such as const [,setName] = useState("Dai shi").

✓ common	✗ uncommon
setName	nameSetter
setState	stateSetter
setAge	ageUpdater
setAge	updateAge

I think the Jotai API documentation should also make sure to continue that convention, and keep naming consistent across both sides of the assignment.

• const setAtom = useSetAtom(nameAtom)
• const setName = useSetAtom(nameAtom)
• const setAge = useSetAtom(ageAtom)

👍 for useSetAtom

[dai-shi]

Looks like reaching to an agreement.

---

Just a note why I didn't choose useSetAtom in the first place is it's technically dispatching an action. I thought about useDispatch but it's more weird for primitive atoms. So, I chose useUpdateAtom.

const countAtom = atom(0, (get, set, action) => {
  if (action === 'INC') {
    set(countAtom, get(countAtom) + 1))
  } else {
    set(countAtom, 0)
  }
})

// in component
  const [count, dispatch] = useAtom(countAtom)
  const dispatch = useDispatch(countAtom) // weird for `useState` case
  const dispatch = useUpdateAtom(countAtom) // so, chose this
  const dispatch = useSetAtom(countAtom) // probably, this looks okay

[dai-shi]

@Thisen may not be available soon, I'll create a PR only for code meanwhile. (we want to include it in the next minor.)