RFC: New Jotai v2 API

[dai-shi]

(This description will be updated over time. Please quote sentences when you add comments.)

Background

Jotai is designed to fully support Concurrent React and Suspense for data fetching.
Despite of the simple api, the implementation has hacky things internally. If you ever see src/core/store.ts, you know them.
Otherwise, it would have been a lot simpler.

Other than the implementation complexity, there are some issues:

• useReducer behavior is confusing with derived atoms. We explain "extra re-renders with no commits" behavior is intentional, but not super comfortable, and we rely on useMemo for heavy computation.
• unstable_createStore feat(core): unstable_createStore #922 has very weird API for async values.
• Atoms are framework-agnostic, and most utils are too, but the library is tied to React.
• (maybe some more)

Furthermore, the biggest change recently is the use RFC. It indicates that throwing promises in a library is no longer supported (which is never supported), and needs use. However, it's not usable everywhere. Our current implementation will probably break.

Why this change

When we released Jotai v1, we knew Suspense for data fetching is unstable. Our hope was, when it's finalized, we update our implementation with keeping Jotai v1 API.

It might be still possible, but as we see the use RFC, the general preference we should follow is async/await, not throwing promises behind the scene.

So, we propose new Jotai v2 API.

It will become more compatible with use and will technically get less benefit from Concurrent React.

What will be breaking

After spending days and weeks, our conclusion is that this API is breaking change for async usage.

// Current API
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom((get) => get(asyncAtom).toUppercase())

// New API
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom(async (get) => (await get(asyncAtom)).toUppercase())

This can be said a behavioral change, but the new type definition is different and incompatible with the current one.

By the way, there's a big benefit with the current API. Not only it can skip async/await syntax, it can skip extra computation. It should perform well with Concurrent React too. But, for most cases, the new API should work well. We will also make abortableAtom first class in the new API, because otherwise there's no way to cancel computation after await. (There might still be room for improvements with caching, anyways.)

Even though the current atom and new atom works the same for sync atoms, for async atoms, the change is breaking. So, our plan is to provide a new entry point. And, hope users migrate to the new API gradually.

// Current API
import { atom } from 'jotai'

// New API
import { atom } from 'jotai/vanilla'

(We might be able to expose the new API from jotai once all migration is done, and it may not be breaking for sync atoms.)

Other major changes

• Split /vanilla and /react entry points for jotai/utils, jotai/devtools in addition to jotai
• Move other integrations out of this repo, like feat(query): new implementation with peer dep #1435 and feat(urql): new implementation with peer dep #1473
• Stable createStore API
• Drop "scope" which has been confusing in usage and is unnecessary with createStore API
• Drop "versioned write" experiment as it won't be realized...

Release plan

• v1.11.0 pre-release v2 API (v1 API and v2 API coexist)
• v1.12.0 deprecate integrations (jotai/query and so on)
• v2.0.0 remove deprecated integrations and APIs, making all entry points with v2 API (minimal react version will be 17.0.0)

Open problems

• How and when should we update the docs for this change?
  • 👉 feat(vanilla/react): New Jotai v2 API #1515 has a migration guide.
• It may trigger more re-renders with async atoms. (Unconfirmed)
  • At least, it invokes more read functions, technically.
  • Maybe we could consider adding unwrap to simulate the current behavior?
  • 👉 feat(vanilla/react): New Jotai v2 API #1515 has unstable_unwrapAtom for experimenting.

Alternatives

• Drop the whole idea of "Async" API and just do others.
  • 👉 We'll move forward with "Async" API.
• Simply move to v2 with breaking changes without migration period.
  • 👉 We'll mostly do so.

[benrandja-akram]

Building for the future is always better since React is taking a big move here with "use" and async/await, so moving directly to v2 is a better option i guess while the changes are not that big.

[dai-shi]

Thanks for your comment. Yes, it's one good alternative. Let's see how the change will cause troubles during phase 1 and 2. We can then consider not deprecating some of them in phase 3.

[dai-shi]

I start to assume that the gradual migration is not very good in DX (especially with 3rd-party libraries), because two APIs are really incompatible with types (even without async atoms).

[dai-shi]

[Phase 1] (v1.x) unstable_ Async API

Hm, it might not be a good idea to have the prefix, because people have to modify it again. Probably, we should simply document it while it's "unstable".

[edongashi]

I wonder if it will be possible to use(atom) via the standard api. They mention that use will be applicable to multiple "wrapper" types, most obvious being promises.

[dai-shi]

My first trial: https://twitter.com/dai_shi/status/1569802927476457472
My current conclusion: https://twitter.com/dai_shi/status/1581856998085140480

[edongashi]

Interesting ideas. So AsyncIterable would represent a sequence of state transitions where we re-render at each step?

to allow reading a cache from React context.

You mean use(SomeContext) or something else?

[dai-shi]

AsyncIterable

yeah, I'd expect so.

use(SomeContext)

It's not allowed to use it internally. They require it to be used only in hooks.

[MrHBS]

Moving directly to v2 is a better option in my opinion as well.

[dai-shi]

Thanks for the comment. I still want to add the new api in v1, so that we have some period to migrate 3rd-party libs, but I get your point from the app developer perspective.

[Aslemammad]

Atoms are framework-agnostic, and most utils are too, but the library is tied to React.

That's the problem with the current library, what we can do with the gradual API changes, is provide utils (in jotai-labs hopefully) for other component libraries, so we can gradually remove the notion of jotai being tied to React. So we would achieve the title of "Jotai: the framework-agnostic state-management library".
The recent trend around Signals can indeed inspire us in frameworks.

[dante01yoon]

Can you imagine when would be v2 release?
I guess after use RFC closed or data fetching with suspense guide released?

[dai-shi]

v1.10.0 pre-release v2 API (v1 API and v2 API coexist)

I imagine to pre-release it in this year, hopefully soon.
#1515 is almost ready.
You can try it with codesandbox build.
https://ci.codesandbox.io/status/pmndrs/jotai/pr/1515
☝️ Find "Local Install Instructions"

I guess after use RFC closed or data fetching with suspense guide released?

It's not tied to them. BUT, if they take down the RFC and take another route, we might need to re-consider. It's unlikely. We will go with Jotai v2 anyways, because there are many other benefits.

[dante01yoon]

thank you for quick respond. I'll look into it.

[11bit]

One problem I found when experimenting with v2 api is that:

1. I have to make any derived atom async if any dependency is async
2. it will suspend on every write even if async dependency is not used

One example is an in-memory cache that loads something and then operates on it synchronously:

const asyncAtom = atom(Promise.resolve("test"));

const derivedAtom = atom(async (get) => {
  return get(asyncAtom)
}, (get, set, update) => {
  // every write will suspend for a fraction of a second although asyncAtom doesn't have a promise anymore
  set(asyncAtom, update)
})

What is the correct way to make mixed atoms that may or may not suspend?

[dai-shi]

@11bit Thanks for the feedback!

If it's conditionally async, you want to avoid "async function" and use native promise instead.

In your simple case, it's easy.

const asyncAtom = atom(Promise.resolve("test"));

const derivedAtom = atom((get) => {
  return get(asyncAtom)
}, (get, set, update) => {
  set(asyncAtom, update)
})

Let me know you have more complex examples.

[11bit]

Thanks for the quick answer! What if have to use a value somehow (like filter through array fetched from somewhere)?

[dai-shi]

The loadable util should help to read async atom in sync.
We have also new unstable_unwrap util. This is still somewhat research field.

[11bit]

By the way, will the suspense behavior of useAtom change after react's use hook is released? As far as I understand currently there are some differences:

1. use doesn't suspend if a promise is resolved within a microtask
2. useAtom currently always suspend if the value is a promise

[dai-shi]

It should basically be the same:

jotai/src/react/useAtomValue.ts

Lines 12 to 41 in b3964f4

	const use =
	ReactExports.use ||
	(<T>(
	promise: Promise<T> & {
	status?: 'pending' | 'fulfilled' | 'rejected'
	value?: T
	reason?: unknown
	}
	): T => {
	if (promise.status === 'pending') {
	throw promise
	} else if (promise.status === 'fulfilled') {
	return promise.value as T
	} else if (promise.status === 'rejected') {
	throw promise.reason
	} else {
	promise.status = 'pending'
	promise.then(
	(v) => {
	promise.status = 'fulfilled'
	promise.value = v
	},
	(e) => {
	promise.status = 'rejected'
	promise.reason = e
	}
	)
	throw promise
	}
	})

[wobsoriano]

Thanks for this! Was able to experiment on a solid port with suspense working- https://github.com/wobsoriano/solid-jotai

[dai-shi]

Nice!

[csantos1113]

I'm giving v2 a try and I would love to know how can I initialize the Provider store with some data, within the react render cycle?

All examples I see in https://github.com/pmndrs/jotai/blob/main/tests/react/provider.test.tsx are setting the values outside of the rendering:

const store = createStore()
store.set(countAtom, 0)
store.set(petAtom, 'dog')

render(
  <Provider store={store}>
    <Display />
  </Provider>
)

But I'd love to do something like:

const uniqueStore = createStore();

const MyProvider = ({ count, children }: { count: number }) => {
  // but obviously this is bad
  uniqueStore.set(countAtom, count);
  return (
    <Provider store={uniqueStore}>
      {children}
    </Provider>
  );
}

render(
  <>
    <MyProvider count={2}><Display /></MyProvider>
    <MyProvider count={5}><Display /></MyProvider>
  </>
)

[dai-shi]

If you are migrating from v1, which has initialValues prop, then useRef is the equivalent solution.

const MyProvider = ({ count, children }) => {
  const storeRef = useRef();
  if (!storeRef.current) {
    // lazy initialization of a ref is concurrent safe.
    storeRef.current = createStore();
    uniqueStore.set(countAtom, count);
  }
  return (
    <Provider store={storeRef.current}>
      {children}
    </Provider>
  );
}

[gsanta]

Hi the documentation suggests to use Provider with initialValues for setting up atoms for testing. Now to do this store setup for each test component seems to be quite overkill for me, and it would mean a lot of refactoring for bigger projects.

[dai-shi]

I updated the migration guide for a little easier pattern. How about creating a test provider?

const TestHydrate = ({ initialValues, children }) => {
  useHydrateAtoms(initialValues)
  return children
}
const TestProvider = ({ initialValues, children }) => (
  <Provider>
    <TestHydrate initialValues={initialValues}>
      {children}
    </TestHydrate>
  </Provider>
)

[gsanta]

Thank you! This pattern is quite clear so I think it's a good replacement of the old behaviour!

[dai-shi]

#1744

[edongashi]

Hi @dai-shi. I have a question about the result of an atom writer:

The write function can accept multiple arguments, and return a value.

In a discussion a few weeks ago you said that the setter is not guaranteed to run in the same frame.
Does this change mean that atom writers will always run immediately upon calling them?

[dai-shi]

Yes, v1 has experimental "versioned write", in which writers don't run immediately.

Drop "versioned write" experiment as it won't be realized...

We dropped the experimental feature, so now it's guaranteed in v2.

[edongashi]

Thanks! I like this change, allows creating much more flexible "actions".

[dai-shi]

#1515 The first PR
#1671 Probably the last

[hackwaly]

Glad to see this. What i proposed here #1219 (comment)

[dai-shi]

Yeah, thanks for the discussion. My hesitation was that this is a big breaking change. Hope it goes well!

[katrinacodes]

I don't see it mentioned anywhere that atomWithHash was removed. Could you mention that in the migration guide and maybe provide a way to work around that?

[dai-shi]

Sorry for confusion.
We deprecated atomWithHash in jotai/utils in v1.10.0.
https://github.com/pmndrs/jotai/releases/tag/v1.10.0
Please use the one in jotai-location.
https://jotai.org/docs/integrations/location