useMutableSource → useSyncExternalStore

[acdlite]

Since experimental useMutableSource API was added, we’ve made changes to our overall concurrent rendering model that have led us to reconsider its design. Members of this Working Group have also reported flaws with the existing API contract that make it difficult for library maintainers to adopt useMutableSource in their implementations.

After additional research and discussions, here are our proposed changes to the API, which we intend to complete for React 18.

(For background, refer to the RFC for useMutableSource: https://github.com/reactjs/rfcs/blob/master/text/0147-use-mutable-source.md)

API overview

import {useSyncExternalStore} from 'react';

// We will also publish a backwards compatible shim
// It will prefer the native API, when available
import {useSyncExternalStore} from 'use-sync-external-store/shim';

// Basic usage. getSnapshot must return a cached/memoized result
const state = useSyncExternalStore(store.subscribe, store.getSnapshot);

// Selecting a specific field using an inline getSnapshot
const selectedField = useSyncExternalStore(store.subscribe, () => store.getSnapshot().selectedField);

getSnapshot is used to check if the subscribed value has changed since the last time it was rendered, so the result needs to be referentially stable. That means it either needs to be an immutable value like a string or number, or it needs to be a cached/memoized object.

As a convenience, we will provide a version of the API with automatic support for memoizing the result of getSnapshot:

// Name of API is not final
import {useSyncExternalStoreWithSelector} from 'use-sync-external-store/with-selector';
const selection = useSyncExternalStoreWithSelector(
  store.subscribe,
  store.getSnapshot,
  getServerSnapshot,
  selector,
  isEqual
);

Selectors no longer need to be memoized

Inline selectors are a common feature of state libraries, especially those that provide a hook-based API, such as Redux’s useSelector.

A selector is a function that accepts a state value and “selects” the subset that is needed by the component. It signals that React only needs to re-render if that subset has changed.

Because useMutableSource does not provide a built-in selector API, the only way to implement this behavior is to resubscribe to the store every time the inline selector changes. If the selector function is not memoized, this means resubscribing on every new render. This is not only a performance pitfall, it’s one that leaks into user code: the user of a state management library must take extra caution to memoize all of its selectors.

Refer to #84 for a detailed description of this problem.

The new API is designed so that React no longer needs to resubscribe when the getSnapshot function changes. So you can pass an unmemoized selector without degrading performance.

By default, React will detect changes to a selected value by comparing with Object.is. Some state libraries rely on comparing values with a custom comparison function, like shallowEqual. While we don’t necessarily recommend this pattern, it can be implemented in userspace. Since we expect this to be a common feature request, we will publish our own userspace implementation.

Concurrent reads, synchronous updates

Another flaw of the useMutableSource API is that it can sometimes cause visible parts of the UI to be replaced with a fallback, even when the update is wrapped with startTransition (the API that is meant to avoid this scenario).

The reason is that startTransition relies on the ability to maintain multiple versions of a UI simultaneously (“concurrently”): the current UI that’s visible on screen, and a work-in-progress UI that is prepared in the background while data progressively streams in. React can do this with its built-in state APIs — useState and useReducer — but not for state that lives outside React, because we only can access a single version of state at a time. (To illustrate with an example, Redux’s store has a getState method, but it doesn’t have a getBackgroundState method; we could theoretically implement a contract to support concurrent data stores, but that’s outside the scope of this proposal.)

Our original strategy was to provide partial support for concurrent features: start rendering concurrently, and only deopt back to synchronous when we detect an inconsistency. “Deopt" in this context can mean:

1. Disabling time-slicing and reverting to fully synchronous, blocking rendering
2. During a refresh transition, hiding the UI and replacing it with a fallback instead of waiting for the new data to load in the background

We went through great pains to preserve time-slicing as much as possible (1), even if it meant hiding already-visible UI with a fallback (2).

We’ve since concluded that this trade-off is backwards: Replacing visible content with a fallback is a significant regression in the user experience, especially if it happens unpredictably. By contrast, occasionally disabling time-slicing — while not ideal — has a much less dramatic effect on the end user experience.

Even worse is that useMutableSource can cause bad fallbacks during state updates that are completely unrelated, such as those triggered by a router, or a regular useState hook.

As we were brainstorming alternative strategies, a key revelation was that if you can’t rely on startTransition to always avoid bad fallbacks caused by a store update, then you shouldn’t ever rely on it — you should avoid the fallbacks in some other way. For example, you could do it the same way you would today without Suspense: by waiting for new data to load before triggering the update.

The next key revelation was that we can avoid deopts during updates triggered by React state transitions if updates triggered by external stores are always synchronous. That’s because if updates to stores are synchronous, they are guaranteed to be consistent.

So, in the new design:

• Updates triggered by a store change will always be synchronous, even when wrapped in startTransition
• In exchange, updates triggered by built-in React state will never deopt by showing a bad fallback, even if it reads from a store during the same render

We think this hits the sweet spot of feature compatibility, ease of adoption, and predictable user experience.

We will be renaming the API to useSyncExternalStore to reflect its updated behavior.

As a bonus, we can get rid of the source argument and the corresponding createMutableSource API.

Adoption strategy

Our goal is for all subscription-based libraries to migrate their implementations to useSyncExternalStore.

While it’s possible to implement a concurrent-compatible subscription in userspace, it’s very tricky to get right. Existing store implementations will continue to work as they do in React 17 until or unless a store update is wrapped with startTransition, at which point concurrency bugs may surface.

To encourage adoption by open source libraries, we will provide a shim that is compatible with older versions of React. The shim will prefer the built-in API when it is available, so that users get the correct implementation regardless of which version they’re running.

We are also considering a heuristic to detect when a userspace store update is wrapped with startTransition, so we can print advice to the console (in development mode) to use useSyncExternalStore instead. The heuristic is to count how many separate components are updated within a single startTransition call. If it’s greater than some arbitrary threshold, say 20, we can infer that it likely contains a subscription.

[dai-shi]

Thanks for the great news.

As a bonus, we can get rid of the source argument and the corresponding createMutableSource API.

Wow, this is huge. This changes our strategy to design API.

---

I have various questions, but I will read it again before making some of them.

Meanwhile, the first question in mind is: does the shim support >= react@16.8? Because otherwise, we'd need state libraries to hit major version update anyway.

[acdlite]

It'll work with any version that supports hooks, yeah.

[dai-shi]

Nice. Thanks.

[markerikson]

Half-serious question:

was it intentional that the abbrevation for this hook is going to change from uMS to uSES? :)

[acdlite]

Hmmm... let's say yes

[dai-shi]

The next key revelation was that we can avoid deopts during updates triggered by React state transitions if updates triggered by external stores are always synchronous. That’s because if updates to stores are synchronous, they are guaranteed to be consistent.

Is it correctly understood that if store update is in another micro task, it will deopt?

  const storeState = useSyncExternalStore(...);
  const [state, setState] = useState();
  const handleClick = () => {
    setState(...);
    Promise.resolve().then(() => setExternalStore(...));
  };

[rickhanlonii]

What do you mean by deopt here? The way this would work is that the setState would flush in a microtask, then the setExternalStore would flush in a different microtask, which is expected behavior so nothing is de-opting.

[dai-shi]

Thanks for clarification. Good to know that's expected behavior.

if updates triggered by external stores are always synchronous

My question is when this condition doesn't hold. Can this be explained in a small code snippet?

[rickhanlonii]

The condition always holds when using useSyncExternalStore, because it forces those updates to be sync. I think the sentence you're quoting is contrasting the behavior of what the old useMutableSource implementation was proposed to do, which is to try and be concurrent and then de-opt to sync mode, causing other updates to de-opt and fallbacks to show where they otherwise wouldn't.

[dai-shi]

Yeah, I thought it's comparing with uMS. Thanks. So far, it's clear.

[markerikson]

In case anyone's interested, I've got an initial prototype PR to migrate React-Redux's useSelector over to use useSyncExternalStore internally. I'm hopeful I'll be able to figure out a way to get connect working on top of that as well, but it'll require more research and effort:

reduxjs/react-redux#1808

[markerikson]

Following up on this, I just published https://github.com/reduxjs/react-redux/releases/tag/v8.0.0-alpha.0 , which migrates useSelector + connect over to call useSyncExternalStore internally, and also migrates our codebase to TypeScript!

You can see the actual uSES migration changes in the PR linked above.

[Andarist]

The next key revelation was that we can avoid deopts during updates triggered by React state transitions if updates triggered by external stores are always synchronous.

This kinda sounds scary to me. I mean - this might remove all of the benefits of the time-sliced rendering for applications that relies heavily on external stores (such as Redux). I understand how it simplifies the model but it also feels like, for a lot of apps, time-slicing might become less relevant since a lot of updates will just be simply synchronous. I don't have any data but it feels like most of the "heavy" updates that could actually benefit from the time-slicing might come from external stores.

[acdlite]

You can still use time-slicing, even with external stores, in combination with useDeferredValue. That has full compatibility.

It’s only the startTransition pattern that requires the state to be owned by React. And the idea is that nearly all transitions are triggered by a router.

So the main types of libraries that are affected are routers. And the solution there is to use useState or useReducer instead of an external store.

[Andarist]

I might have used an incorrect term but I've meant that with React state one can expect the app to stay interactive for slow updates that span many components since that update gets time-sliced. This is unrelated to both startTransition and useDeferredValue.

So If I understand correctly based on this:

Updates triggered by a store change will always be synchronous, even when wrapped in startTransition

then this, quite awesome, trait won't be available for external stores.

[acdlite]

What I'm saying is, you can still do that by passing the store value to useDeferredValue.

const syncValue = useSyncExternalStore(...);
const deferredValue = useDeferredValue(syncValue);

// This element only re-renders when the deferred value changes,
// so its rendering is time sliced even though it depends on an
// external store. You could also use `memo` or `PureComponent`.
const visualization = useMemo(
  () => <ExpensiveVisualization value={deferredValue} />,
  [deferredValue]
);

return ( 
  <>
    <Input value={syncValue} />
    {visualization}
  </>
);

The analogous pattern today would be something like useDebounceValue or useThrottledValue. Except instead of throttling or debouncing, useDeferredValue uses time slicing.

[Andarist]

Wow, I think I might need to digest how this fits into other pieces to internalize this knowledge. Thanks for sharing! Just to make myself sure - this can act as an opt-in to time-slicing for external stores but the time-slicing react-managed state doesn't require anything like that and it "just works", right?

In the context of react-managed state useDeferredValue can be used to "fork" the value so different values can be displayed on the screen simultaneously. The same thing probably happens with the given snippet for external store value but useDeferredValue also has that trait that it's always using time-slicing (which is something "new" for external stores). Whereas for react-managed state this is just how it works for everything already so the only new thing is this "forking" of the displayed value.

Sorry if my thought train here is a little bit confusing

[dai-shi]

I'm having a little issue migrating to uSES.
Our tests pass with useSyncExternalStore with custom getSnapshot, but with useSyncExternalStoreExtra some fails. The failed tests are throwing errors from selector and isEqual.

I dug into it and found where it comes from. The following patch fixes it. Does it make sense?

--- src/useSyncExternalStoreExtra_orig.js	2021-10-04 08:44:01.000000000 +0900
+++ src/useSyncExternalStoreExtra_new.js	2021-10-04 08:44:44.000000000 +0900
@@ -76,7 +76,6 @@
       }
 
       // The snapshot has changed, so we need to compute a new selection.
-      memoizedSnapshot = nextSnapshot;
       const nextSelection = selector(nextSnapshot);
 
       // If a custom isEqual function is provided, use that to check if the data
@@ -87,6 +86,7 @@
         return prevSelection;
       }
 
+      memoizedSnapshot = nextSnapshot;
       memoizedSelection = nextSelection;
       return nextSelection;
     };

[gaearon]

Send a PR to see if our tests pass? If they do please add a test that fails without the change.

[dai-shi]

Alright!

[dai-shi]

Done: facebook/react#22500

[eps1lon]

Our goal is for all subscription-based libraries to migrate their implementations to useSyncExternalStore.

Does this also apply to things like Media Queries or e.g. window.innerWidth? A popular pattern for reading these values is something like "read state during render, read (and update) state during effect, subscribe in effect" (e.g https://github.com/antonioru/beautiful-react-hooks/blob/1.0.0/src/useMediaQuery.ts).

It seems like something similar to the following implementation would work for Media Queries

function useMediaQuery(query: string, serverFallback?: boolean): boolean {
  const getServerSnapshot =
    serverFallback !== undefined ? () => serverFallback : undefined;

  const [getSnapshot, subscribe] = useMemo(() => {
    const mediaQueryList = window.matchMedia(query);

    return [
      () => mediaQueryList.matches,
      (notify: () => void) => {
        mediaQueryList.addEventListener("change", notify);
        return () => {
          mediaQueryList.removeEventListener("change", notify);
        };
      }
    ];
  }, [query]);

  return useSyncExternalStore(
    subscribe,
    // Fallback to getServerSnapshot only required for React 17
    typeof window !== "undefined" ? getSnapshot : getServerSnapshot,
    getServerSnapshot
  );
}

Example implementation and other examples (e.g. window.innerWidth): https://codesandbox.io/s/usesyncexternalstore-use-cases-next-js-ninnm?file=/pages/index.tsx

I think it would help if we could have a concrete example why we should use the uSES implementation over useState + useLayoutEffect to nudge people to migrate their implementations. Like an actual repro that results in a teared UI.

Also: Should we update the initial post with the addition of getServerSnapshot and how SSR makes use (or no use) of it in React 18 vs 17?

[brainkim]

Salaam alaikum! I’m currently the point person for making sure Apollo Client works with React 18, and I’ve been asked by the React team in emails to post my thoughts and questions in the working group, with the idea that sharing our findings might lead to more meaningful social interactions with the wider React developer community.

The current status for Apollo Client is that we have a PR which uses useSyncExternalStore waiting to be merged barring a couple blockers:

1. We rely on both react-testing-library and react-hooks-testing-library to test Apollo Client, and apparently there’s some hiccups with regard to the act() API that have yet to be resolved (fix: Don't trigger "missing act" warnings when using waitFor+real timers testing-library/react-testing-library#980, and Support React 18 testing-library/react-hooks-testing-library#655). I’m not too familiar with the changes necessary. I’m happy to help, but I’m hoping these issues can be resolved before React 18’s release.

2. The use-sync-external-store package still seems to require an alpha version of React in its peer dependencies (https://www.unpkg.com/browse/use-sync-external-store/package.json). Given that the package is meant to be a shim, I was wondering if the version range could be extended to ^the-one-with-hooks? For some reason, the peerDependencies in https://github.com/facebook/react/blob/main/packages/use-sync-external-store/package.json do not seem to be applying to the actual published NPM package.

3. Like @eps1lon asks, I’m wondering what the criteria for a “mutable source” is. What qualifies an API as needing useSyncExternalStore()? The original guide seems to imply that every stateful DOM API would necessitate a useSyncExternalStore() wrapper to prevent “tearing,” but this seems like a reductio ad absurdum argument against concurrent mode, right? Specifically, I’m wondering if APIs which update based on promises, like our useMutation() hook, would require a useSyncExternalStore() wrapper? Some guidance from the React team would be nice. Personally, I’m still reeling from the idea that reading/writing to refs during render is somehow unsafe, so I’m definitely hesitant to assume anything.

4. I’m still unclear about how useSyncExternalStore() mitigates tearing. To date, I have yet to see a test written in any React-adjacent repository which reliably tests for tearing and proves that useSyncExternalStore() works to mitigate it, so I’m not willing to say that Apollo Client provides “level 2 support.” I was recently dismayed to learn that @dai-shi’s will-this-react-global-state-work-in-concurrent-mode library might not actually prove “type 2 compliance” (Initial experimental React 18 compat prototyping reduxjs/react-redux#1808 (comment)) and am still waiting for guidance that any Apollo Client change prevents tearing. Specifically, it seems like the use of the useTransition() hook in @dai-shi’s test suite is incorrect, insofar as that hook, which is described as deferring non-critical state updates, induces “tearing” by design. So again I ask, is there a way to red-green test for tearing, because I’m very much the kind of programmer who does not believe in behavior which cannot be tested?

As always, thanks for all the hard work,
Brian Kim

[eps1lon]

Regarding 1:

Just merged testing-library/react-testing-library#980 so @testing-library/react@alpha should not have any issues with act() anymore.

I’m happy to help, but I’m hoping these issues can be resolved before React 18’s release.

Best way to help is to provide full reproductions.

[gaearon]

just to tie it together so it doesn't get lost, @acdlite responded to this here: #86 (comment)

[acdlite]

The original guide seems to imply that every stateful DOM API would necessitate a useSyncExternalStore() wrapper to prevent “tearing,” but this seems like a reductio ad absurdum argument against concurrent mode, right?

Even today, reading from a stateful DOM API requires setting up a subscription. This isn't even specific to React; that's how other frameworks work, too. So one definition of a "mutable source" is anything that requires a subscription to notify React of changes.

For example, a canonical example is a useMediaQuery hook that subscribes to a MediaQueryList change event.

Specifically, I’m wondering if APIs which update based on promises, like our useMutation() hook, would require a useSyncExternalStore() wrapper

Probably not. I would need to audit the Apollo implementation to be sure, but I would expect that you have a mutable store somewhere that the promises write to when they resolve. You would wrap subscriptions to that store in useSyncExternalStore, and then read the data through that, instead of subscribing directly to individual promises.

But the next step after that is to switch to a Suspense-based implementation. This is more complex topic, so I think a good next move would be to put you in contact with someone from the Relay team so they can provide advice on how they built their Suspense-based implementation. Let me know if you're open to this!

is there a way to red-green test for tearing

It's pretty easy to write a test that demonstrates a tearing bug, once you know what you're looking for. We have tons of them in the React test suite, including ones related to useSyncExternalStore. For example, here's a test that simulates when a store mutation happens between paint and when useEffect runs: https://github.com/facebook/react/blob/main/packages/use-sync-external-store/src/__tests__/useSyncExternalStoreShared-test.js#L269-L311

However, it's practically impossible to write a test that does the inverse: to exhaustively prove that a library/component contains zero tearing bugs. (Though I really wish there were — it would make my job easier!) To do that, you'd need to be able to prove that there are no unexpected side effects (reads or writes), which just isn't feasible in a highly dynamic language like JavaScript. You'd need some sort of formal, static verification like Rust's borrow checker.

So our approach to testing for tearing bugs is adversarial: we intentionally try to break the UI, write a red/green test that simulates that particular scenario, then fix the behavior and merge the test. We don't have tests for every possible scenario, but we do aim to cover as many representative scenarios as we can think of.

Libraries that build on top of React can use the same approach, of course, though our hope is that by using our official APIs, the scope issues they face is reduced: if React's APIs are thread-safe, and the libraries use React's API's in the recommended way, then those libraries should be thread safe, too.

However, if you were find a tearing bug in React, that would be a highly valuable bug report! Because by fixing the issue in useSyncExternalStore, we end up fixing it for all other libraries, too.

We already have a few examples of this happening:

• Redux's documented their "zombie child" problem, which is a kind of tearing bug that happens when a store snapshot is inconsistent props. The Relay team reported a variant of the same bug several years ago when they were initially adding support for concurrent rendering. Both of these examples were highly influential in the design of useSyncExternalStore — we have tests that simulate this scenario. By adopting useSyncExternalStore, Redux was able to remove their old workaround.
• @dai-shi found a bug related to selectors, which they fixed in this PR: fix: useSyncExternalStoreExtra facebook/react#22500

[acdlite]

Oops this was meant to be a reply to @brainkim, my bad!

[brainkim]

https://github.com/facebook/react/blob/main/packages/use-sync-external-store/src/__tests__/useSyncExternalStoreShared-test.js#L276

So, if we were to replace useSyncExternalStore() here with a test which only uses useState() and useEffect(), the test would fail right? I’m wondering if it might make sense to have the Scheduler assertions available via react-testing-library or react-hooks-testing-library.

[acdlite]

I’m wondering if it might make sense to have the Scheduler assertions available via react-testing-library or react-hooks-testing-library

We likely will publish a module to support this pattern but it would be a slightly different API than the one we use internally, and would be geared specifically for advanced users, like library authors.

(The pattern we use is available via the jest-react package but it's highly unstable and we don't commit to supporting the current API long term: https://unpkg.com/browse/jest-react@0.0.0-experimental-6bce0355c-20211031/cjs/jest-react.development.js)

[dai-shi]

#86 (comment)

Both of these examples were highly influential in the design of useSyncExternalStore — we have tests that simulate this scenario. By adopting useSyncExternalStore, Redux was able to remove their old workaround.

Oh! I didn't follow uSES fixes zombie children. cc @drcmda
This works only with the hook in React 18 and not with the use-sync-external-store shim in React 17, right?

[TkDodo]

Hi 👋

@gaearon kindly invited me to the WorkingGroup after a chat we had about uSES and react-query. I'm currently trying out migrating react-query towards uSES and would like to share my findings / thoughts with you:

1. I got infinite re-renders initially because I provided an inline function to subscribe, because I wasn't aware that subscribe must be referentially stable. It't totally understandable and possible to adhere to, I was just not aware of it. Maybe this could be documented a bit better?

2. In react-query, we trigger of a bunch of things when an observer subscribes, like starting timers for staleTime / refetchInterval, and also potentially initiate a the first fetch. @gaearon mentioned that there might be an assumption on your side that subscribing doesn't do anything other than subscribing and that it maybe doesn't make sense that subscribing alone would trigger something like a fetch. Just wanted to check if thats true and if so, what would be a good place to trigger side-effects when an observer subscribes?

3. I'm assuming that getSnapshot will never be called (and updates won't be triggered) on an unmounted component? We have a bunch of checks via refs that make sure that setState is never called on an unmounted component to avoid the infamous warning about it. Just wanted to make sure that I can safely remove those, but I guess one of the advantages of uSES is that these things are handled internally now, as we don't have our own effect and don't even call setState manually anymore :)

4. Is there a way to batch updates together coming from uSES ? For example, in react-query, if you subscribe to the same query twice, you'll have two subscriptions, but there will only be one re-render because they are batched together. I've gotten a test failure on this test after switching to uSES, and was wondering what to do about it 😅

Thank you for all the work on this - many things are working really well already with uSES and I'm really looking forward to v18 🎉

[acdlite]

1. Yeah we'll document this. We haven't started docs yet for new 18 features but that's definitely something we'll include.
2. You could put other side effects in subscribe, but it has the same caveats as useEffect: it doesn't correspond to the component lifetime. For example, in the future React will unsubscribe when the component is hidden by the Offscreen API, and resubscribe when it's brought back on screen.
3. You'll be delighted to learn we removed that infamous warning entirely: Remove the warning for setState on unmounted components facebook/react#22114
4. In React 18, the updates are batched automatically. If you use the use-sync-external-store shim for compatibility with 17 and below, you'll still need to wrap the change event with ReactDOM.unstable_batchedUpdates.

[TkDodo]

ad 2: Good to know thanks. re-fetching when it's brought back on screen sounds like something that could be a good feature, so it doing it on subscription would work. Maybe it's too early to tell, but will there be a way to distinguish between "initial" subscriptions and those being brought back by the offscreen api? Otherwise, we could also build that in user-land I guess.

ad 3: That's great, but if we remove all the mounted-refs now and use the shim, won't people using React 17 still get those warnings again? I guess it depends on what the shim is actually doing, but looking at the code it's also just an effect + forceUpdate via setState

ad 4: Thanks, but what exactly would be "the change event" when all we have is pretty much:

const result = useSyncExternalStore(observer.subscribe, () => observer.getCurrentResult())

previously, we did batch the calls to setState, but we don't have those anymore 🤔

Also, since I'm using React 18 and the latest alpha of react-testing-library, according to:

• Support for React 18 testing-library/react-testing-library#509 (comment)

I'm wondering why things are not batched or why the shim is actually used in the tests rather than the native version ...

[acdlite]

what exactly would be "the change event" when all we have is pretty much

It's the thing that the subscribe function calls.

function subscribe(listener) {
  addToReactListeners(listener);
  return () => removeFromReactListeners(listener);
}

// When the store changes
// This might require composing your store API
store.listen(() => {
  ReactDOM.unstable_batchedUpdates(() => notifyAllReactListeners());
});

I'm wondering why things are not batched or why the shim is actually used in the tests rather than the native version

Could you open an issue with an isolated repro? CodeSandbox ideally

[Andarist]

What's the purpose of such code? is unstable_batchedUpdates telling React here that this can be batched with other batched work? I'm slightly confused because I've only known that unstable_batchedUpdates can batch the work scheduled within it but this particular snipper only schedules a single update. So I wonder what it does in this context.

[acdlite]

I'm slightly confused because I've only known that unstable_batchedUpdates can batch the work scheduled within it but this particular snipper only schedules a single update. So I wonder what it does in this context.

Yeah my pseudocode example was bad, I updated it to something more realistic.

It sorta depends on whether your store API is React-specific (in which case you can put a batchedUpdates directly inside the store implementation) or if it's a framework-agnostic API like Redux's (in which case you'd need to compose it by registering a single listener that wraps all the others).

[acdlite]

This API is now available in the latest alphas (starting with 18.0.0-alpha-6bce0355c-20211031).

[TkDodo]

Thanks @acdlite - using that version of react makes the above mentioned tests regarding batching pass, so I guess the previous version was just always using the shim :)

This leaves me with another question regarding testing: What would be the ideal way to test code against v17 (picking up the shim) and v18 (using the native version)? Is there a way to force the shim being used in tests?

[acdlite]

The way use-sync-external-store/shim decides whether to use the native API or not is by checking if the react package exports useSyncExternalStore: https://github.com/facebook/react/blob/a0d991fe6587ad1cd1a97230f62f82c7cb6b9a40/packages/use-sync-external-store/src/useSyncExternalStoreShim.js#L13-L18

So the way to test the shim is to install react@17 and react-dom@17. To test the native API, install react@alpha and react-dom@alpha. You have to make sure both packages are in sync.

[dai-shi]

A small question when to use useSyncExternalStoreWithSelector in the case when we don't use custom equality function.

// a) normal hook from react 18
useSyncExternalStore(
  store.subscribe, // this is stable
  () => selector(store.getState()) // new reference in each render
)

// b) WithSelector from the package (not shim)
useSyncExternalStoreWithSelector(
  store.subscribe, // this is stable
  store.getState, // this is stable too
  null,
  selector, // new reference in each render
)

Is it correct that b) can be theoretically more efficient than a)? Even if it's a micro-optimization.