Valtio v2 Roadmap

[dai-shi]

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

Why do we need v2?

When we released v1, we had some assumption about supporting suspense.
However, as the use RFC implies, the assumption wasn't correct. (The library can't throw promises internally without hooks.)

We need a new breaking API to follow the proposed way.

When will v2 be released?

It will be after the RFC is finalized. We may prepare some pre-releases.
(If it takes too long for the RFC to be finalized, we will re-consider.)

What will be breaking?

Unfortunately, APIs are not fully compatible with v1. (Some existing tests will fail.)

In v2, Valtio doesn't resolve promises, and users have to explicitly use use to unwrap promises.

// v1
import { proxy, useSnapshot } from 'valtio'

const state = proxy({ data: fetch(...).then((res) => res.json()) })

const Component = () => {
  const snap = useSnapshot(state)
  return <>{JSON.stringify(snap.data)}</>
}

// v2
import { use } from 'react'
import { proxy, useSnapshot } from 'valtio'

const state = proxy({ data: fetch(...).then((res) => res.json()) })

const Component = () => {
  const snap = useSnapshot(state)
  return <>{JSON.stringify(use(snap.data))}</>
  // If `data` is not an object, you can directly embed it in JSX.
  // return <>{snap.data}</>
}

What are other changes?

React version

v2 will require at least React 18.
This will allow to drop use-sync-external-store package.
#698 (comment)

Use of initial object (copying behavior in v1)

v1 copies initial object that is passed to proxy() (even internally).
This is a big design decision to avoid confusion. It has been working well for most cases.
But, some people reported edge cases that the copying behavior is more confusing.
As this behavior is really hard to disable, we make it opt-in in v2.

// v1
import { proxy } from 'valtio';

const state = proxy({ count: 1, obj: { text: 'hi' } })
state.obj = { text: 'hello' }

To get the same behavior in v2:

// v2
import { proxy } from 'valtio';
import { deepClone } from 'valtio/utils';

const state = proxy(deepClone({ count: 1, obj: { text: 'hi' } }))
state.obj = deepClone({ text: 'hello' })

But, that's a rare case. Unless you re-use the initial object, which is not recommended (the strong recommendation is to throw it right away), you don't need deepClone.

Deprecated features

All features marked as deprecated in v1 will be removed in v2.

Possible better snapshot cache invalidation

#712, but I'm not sure if it's resolvable.

derive-valtio will be removed from the dependency

It has to be manually installed.

[Aslemammad]

The use of the initial object is more reasonable I believe since deepClones may be unexpected for some users and they may not prefer it! While for the rest, using the initial object is not something unexpected and weird! So big up for this one. Thank you.

[lovetingyuan]

why not offer option for proxy
const state = proxy(deepClone({ count: 1, obj: { text: 'hi' } })) => const state = proxy({ count: 1, obj: { text: 'hi' } }, { deepClone: true })

[dai-shi]

You can open a new discussion about v2 docs and draft some contents, or you can directly open a PR to v2 branch, where we can discuss too. Thanks for your contribution!

[dai-shi]

btw, we can technically release Valtio v2.0.0 right after React 19 is released. And, what's blocking then is v2 docs. So, contributions are very welcome.

[ScreamZ]

I'll work on a PR on V2 in the next days

[dai-shi]

@ScreamZ Just curious if you are still interested in it.

[ScreamZ]

yes, I'm on it :)

[texastoland]

In v2, Valtio doesn't resolve promises, and users have to explicitly use use to unwrap promises.

I think your solution is nearly as nice taking advantage of React's status, value, and reason props even outside Suspense!

1. Any reason not to set status = 'pending' initially?
   

   valtio/src/vanilla.ts

   Lines 273 to 284 in 9e6868c

   	if (value instanceof Promise) {
   	value
   	.then((v) => {
   	value.status = 'fulfilled'
   	value.value = v
   	notifyUpdate(['resolve', [prop], v])
   	})
   	.catch((e) => {
   	value.status = 'rejected'
   	value.reason = e
   	notifyUpdate(['reject', [prop], e])
   	})

2. I'm not sure but I think you could also pass use to snapshot implicitly:

   type PromiseResult<Value> = 
     | { status: 'pending' }
     | { status: 'fulfilled', value: Value }
     | { status: 'rejected', reason: unknown }
   
   // in a React utility
   const suspend = (target) => use(snapshot(target))
   
   // infer PromiseResult<Data>
   const result = suspend(proxy.api.promise)

[texastoland]

Yeah, but then it depends on React, while snapshot is pure JS function. And again, this feature will be removed in v2.

Correct it would be a single line utility imported in https://github.com/pmndrs/valtio/blob/main/src/react/utils.ts.

But, please remember that this code will be removed in v2.

I'm confused why this specific code would be removed? The only React behavior that's changing is throwing promises. That part is limited to defaultHandlePromise which should become optional instead:

valtio/src/vanilla.ts

Lines 89 to 104 in 9e6868c

	defaultHandlePromise = <P extends Promise<any>>(
	promise: P & {
	status?: 'pending' | 'fulfilled' | 'rejected'
	value?: Awaited<P>
	reason?: unknown
	}
	) => {
	switch (promise.status) {
	case 'fulfilled':
	return promise.value as Awaited<P>
	case 'rejected':
	throw promise.reason
	default:
	throw promise
	}
	},

By returning the promise object with status, value, and reason props you'd be providing DX like most query libraries (compared to current behavior):

const { status, value: data, reason: error } = snapshot(proxy.api.promise)

if (status === 'rejected') {
  // with the type from my snippet
  // TypeScript will even know
  // data is undefined
  // and error isn't!
}

The Valtio implementation in my previous comment is (not accidentally?) exactly what React does internally:
https://github.com/facebook/react/blob/fdb368d9e7430b50b9c506e76ccd46bf0576ef9b/packages/react-reconciler/src/ReactFiberThenable.js#L136-L151

I was investigating your implementation for Legend. It's similar to Valtio without the read/write separation. Here's my full writeup about use:
LegendApp/legend-state#162 (comment)

[dai-shi]

React will be forcing to use use in the future. If you throw a promise without using use, React will warn you.
So, Valtio v2 will completely change. It will no longer do anything with promises, to follow the React recommendation. Valtio users have to explicitly use use.
snapshot in Valtio is a pure JS function which has nothing to do with React hooks, so we can't/shouldn't use use internally.

[texastoland]

@dai-shi We're saying the same thing 🤓

The code I originally linked is where you set status on promise objects. If you return these enhanced promises in v2 you'll provide better DX. React also uses these exact properties to optimize use internally. Are you planning to remove status too?

I'm not suggesting you change snapshot except to remove defaultHandlePromise which throws promises. You could export a React utility (similar to useProxy) to not have to wrap snapshot in use:

const { value } = use(snapshot(target))

I'll leave it at that. Love your work!

[dai-shi]

If you return these enhanced promises in v2 you'll provide better DX.

Ah, I see what you mean. I don't think it will change DX, but it will be a little more efficient so theoretically better UX.
But, I'll first probably remove it. It helps to reduce code which is also very important.

BTW, Jotai return those enhanced promises. So, I'd say they are slightly different design decisions.

[texastoland]

I previously read part of the source for Jotai too. It's beautiful (much simpler as you've said on Twitter) 😲 I love the ecosystem you've built around it too. But I use Vue whenever possible and and prefer the more "magical" API.

[dai-shi]

#810 is work in progress.
We will release alpha version first.

[hrsh7th]

I suggest customizing promises so that users can choose between two common types of state handling.

1. use(snapshot.fetched)
2. const { status, data } = snapshot.fetched

What do you think about this?

[dai-shi]

We generally don't deal with promises and especially v2 goes further away.

I think loading status is out of the scope of Valtio itself, but it might be interesting to have a solution as a third party library in the ecosystem.

[dai-shi]

Actually, Valtio follows React convention, so properties such as status and value are available.

[ayoubkhan558]

I just wanted to express my immense appreciation for the outstanding work you've done with Valtio Version 1. It's so seamless that I often forget I'm using an external library.
As I eagerly await Version 2, I'm curious to see if you'll maintain the same seamless experience or introduce any changes. ✨

[dai-shi]

Thanks.

I highly recommend you to test v2-beta right now. #810

https://twitter.com/dai_shi/status/1786556901507105009

As noted, unless we receive any feedback, v2 will be finalized.

[dai-shi]

#810 is merged.