feat(react): investigate latest React primitives for performance and capability enhancements

[ctrlplusb]

Summary

Investigate the latest React library primitives (React 18/19) that could be leveraged to enhance easy-peasy's performance and capabilities.

Areas to Investigate

• useSyncExternalStore — already adopted, but review if usage can be optimized further
• useTransition / startTransition — potential for non-blocking state updates in thunks or actions
• useDeferredValue — could benefit computed properties or expensive selectors
• use() hook (React 19) — potential for async state resolution, e.g. thunk results or persistence hydration
• useOptimistic (React 19) — potential for optimistic UI patterns alongside actions/thunks
• useActionState (React 19) — review if this could complement or simplify action dispatching
• React.cache / React.memo enhancements — potential improvements for computed property memoization
• React Server Components compatibility — ensure easy-peasy works correctly in RSC environments

Goals

• Identify primitives that could improve rendering performance (fewer re-renders, better batching)
• Identify primitives that unlock new capabilities or simplify existing patterns
• Ensure continued compatibility with React 18 and 19
• Document findings and propose concrete changes if applicable

[ctrlplusb]

Investigation: React Primitives for easy-peasy

Detailed analysis of each area from the issue, with concrete findings and recommendations.

---

1. useSyncExternalStore — Current Usage & Optimization

Current state (src/index.js:5, src/hooks.js:7-9):

• Imports useSyncExternalStoreWithSelector from use-sync-external-store/shim/with-selector — a polyfill shim originally added for React 16/17 backward compatibility.
• Dynamically injected into hooks via initializeUseStoreState().

Problem: The shim exists only for React <18 support, but peerDependencies already requires ^18.0 || ^19.0. The polyfill is dead weight.

Recommendation — HIGH IMPACT:

• Drop the shim, import useSyncExternalStore natively from react and useSyncExternalStoreWithSelector from use-sync-external-store/with-selector (non-shim path), or implement selector support manually.
• Remove the initializeUseStoreState indirection — no longer needed without React 16/17 support.
• Bundle size savings + removes a dependency.

---

2. useTransition / startTransition — Non-blocking Updates

Current state: All actions dispatch synchronously and trigger immediate re-renders. Thunks are async but their internal dispatch() calls are still urgent updates.

Opportunity — MEDIUM IMPACT:

• Expose a startTransition-wrapped dispatch variant, e.g. a useStoreTransition() hook or an option on thunks to mark dispatches as non-urgent.
• Best fit: thunks that dispatch multiple incremental state updates (e.g. loading → data → complete). Wrapping in startTransition prevents intermediate renders from blocking user input.
• Could also wrap the persistence rehydration's replaceState call (create-store.js:53) in startTransition since it's a large state swap that shouldn't block the UI.

Caveat: This is opt-in behavior — not all dispatches should be transitions. A new hook or helper parameter is the right API shape.

---

3. useDeferredValue — Expensive Selectors

Current state: Computed properties (computed-properties.js) use closure-based memoization with fast-deep-equal. They're lazy (computed on access via Object.defineProperty getters) but still synchronous.

Opportunity — LOW-MEDIUM IMPACT:

• useDeferredValue could wrap the result of useStoreState for expensive selectors, letting React show stale state while computing the new one.
• This is a consumer-side optimization — easy-peasy could provide a useStoreDeferredState hook:

  function useStoreDeferredState(selector) {
    const state = useStoreState(selector);
    return useDeferredValue(state);
  }

• Computed property memoization itself is store-level, not hook-level, so useDeferredValue doesn't directly apply there.

---

4. use() Hook (React 19) — Async State Resolution

Current state (hooks.js:81-90):

function useStoreRehydrated() {
  const [rehydrated, setRehydrated] = useState(false);
  useEffect(() => {
    store.persist.resolveRehydration().then(() => setRehydrated(true));
  }, []);
  return rehydrated;
}

This is the classic "async → state" pattern that use() was designed to replace.

Recommendation — HIGH IMPACT:

• Replace useStoreRehydrated with a use()-based implementation that integrates with Suspense:

  function useStoreRehydrated() {
    const store = useContext(Context);
    use(store.persist.resolveRehydration());
    return true;
  }

• Enables <Suspense fallback={<Loading/>}> around rehydrating stores instead of manual if (!rehydrated) checks.
• Compatibility concern: use() is React 19 only. Would need either a React version check at runtime, a separate export (easy-peasy/react19), or bumping minimum to React 19 (breaking change).
• The current store.persist.resolveRehydration() already returns a stable Promise (create-store.js:169), which is exactly what use() requires.

---

5. useOptimistic (React 19)

Opportunity — MEDIUM IMPACT:

• Natural fit for thunk-based patterns: optimistically apply the action's result, then reconcile when the thunk resolves.
• Could provide a useStoreOptimistic(selector, rollbackAction) hook.
• Deep integration would require easy-peasy to expose a way to "preview" state changes without committing — not trivially compatible with the current Redux dispatch model.
• Verdict: Useful as a documented pattern or utility hook, but deep integration would require significant architecture changes.

---

6. useActionState (React 19)

Opportunity — LOW IMPACT:

• useActionState is designed for form actions with server/client transitions. It returns [state, formAction, isPending].
• easy-peasy thunks could be wrapped in useActionState for form submission patterns, but this is a consumer-side concern, not a library-level change.
• Verdict: Document as a pattern; no library changes needed.

---

7. React.cache / Memoization Enhancements

Current state (computed-properties.js):

• Manual closure memoization: hasRunOnce, prevInputs, prevValue, prevStoreState
• Uses fast-deep-equal for value comparison
• Stack trace inspection for Immer's shallowCopy edge case (line 41) — fragile

Opportunity — LOW IMPACT:

• React.cache is for server-side request deduplication — not applicable here.
• Computed properties are store-level, not component-level, so React hooks/memoization doesn't apply.
• The existing memoization is already efficient. The Immer stack trace hack (line 41) should be investigated separately as a bug risk.

---

8. React Server Components (RSC) Compatibility

Current state:

• useContext is used in all hooks — not compatible with Server Components (context is client-only).
• StoreProvider uses context → must be a Client Component.
• createStore() uses Redux which has no RSC awareness.

Findings:

• easy-peasy is fundamentally a client-side state management library. RSC compatibility means ensuring it doesn't break when imported in a server context, not making it work in server components.
• getBrowserStorage in persistence.js already guards against window being undefined — good for SSR.
• getServerSnapshot is set to store.getState (hooks.js:46) — correct for SSR hydration.

Recommendation — MEDIUM IMPACT:

• Add 'use client' directive to src/index.js.
• Optionally provide an easy-peasy/server export with just createStore (no hooks) for server-side store initialization in RSC apps.

---

Bonus: useLocalStore Concurrent Mode Bug

While investigating, found that useLocalStore (use-local-store.js:29-36) uses a raw useState + subscribe pattern instead of useSyncExternalStore:

useEffect(() => {
  setCurrentState(store.getState());
  return store.subscribe(() => {
    const nextState = store.getState();
    if (currentState !== nextState) {
      setCurrentState(nextState);
    }
  });
}, [store]);

This is the pre-React 18 pattern and can cause tearing in concurrent mode. Should be migrated to useSyncExternalStore for consistency with useStoreState.

---

Prioritized Recommendations

Priority	Change	Impact	Breaking?
P0	Drop use-sync-external-store shim, use native React 18 API	Bundle size, fewer deps	No (React 18+ already required)
P0	Fix useLocalStore to use useSyncExternalStore	Prevents concurrent mode tearing	No
P1	Add 'use client' directive for RSC/Next.js compat	Prevents RSC breakage	No
P1	use() hook for useStoreRehydrated (Suspense support)	Better async UX	Yes (React 19 only) or optional export
P2	startTransition wrapper for rehydration's replaceState	Non-blocking hydration	No
P2	New useStoreDeferredState hook	Expensive selector opt-in	No (additive)
P2	New useStoreTransition hook	Non-blocking dispatch opt-in	No (additive)
P3	useOptimistic patterns	Optimistic UI for thunks	No (additive)
P3	Document useActionState integration	Form action patterns	No (docs only)