feat(zero-react): add select option to useQuery for selective re-renders

[Karavil]

Summary

Adds select option to useQuery. Transforms the query result and uses deep equality to determine re-renders.

const [student] = useQuery(studentsQuery, {
  select: (students) => students.find(s => s.id === studentId),
});
// re-renders only when this student changes, not when other students change

Why

Rendering a list of 30 students today:

// Option A: prop drill, all 30 rows re-render when any student changes
function Roster() {
  const [students] = useQuery(allStudentsQuery);
  return students.map(s => <Row student={s} />);
}

// Option B: query per row, 30 views on the server
function Row({ id }) {
  const [student] = useQuery(studentQuery(id));
  return <tr>...</tr>;
}

// Option C: prefetch in layout.tsx, use in Row.tsx, keep them in sync manually

None of these are great. A gives you re-render problems, B gives you N views, C gives you maintenance burden.

You might think useMemo solves A:

function Row({ id }) {
  const [students] = useQuery(allStudentsQuery);
  const student = useMemo(() => students.find(s => s.id === id), [students, id]);
  return <tr>...</tr>;
}

But students is a new array reference on every update, so useMemo recalculates every time. The component still re-renders when any student changes. useMemo just memoizes the find, not the render.

In a perfect world, Zero's view syncer would recognize that 30 studentQuery(id) calls can be combined into one allStudentsQuery and handle it server-side. But Zero can't smush ASTs together like that today. So this is a client-side compromise.

What

function Row({ id }) {
  const [student] = useQuery(allStudentsQuery, {
    select: (students) => students.find(s => s.id === id),
  });
  return <tr>...</tr>;
}

select runs inside useSyncExternalStore's getSnapshot. When the query updates, we deep-compare the new selected value against the previous one. Same value? Return the cached snapshot. React never sees a change, no re-render. Different value? New snapshot, React re-renders.

Status changes (unknown → complete → error) always trigger re-renders regardless of the selected value. TypeScript infers the return type from your select function.

Still loads all students upfront, so not a silver bullet. But one view on the server, surgical re-renders on the client, and data requirements stay colocated with the component.

Testing

npm install
npm test -- packages/zero-react/src/use-query.test.tsx

48 tests. Covers primitives, objects, arrays, .one(), loading states, status transitions, type inference, backward compat.

[vercel]

Someone is attempting to deploy a commit to the Rocicorp Team on Vercel.

A member of the Team first needs to authorize it.

[aboodman]

Did you consider using React.memo to prevent the child row components from re-rendering? this is what we have done in the past.

You can use deepEquals to decide whether the props have changed.

[aboodman]

Alternately if we want to make a change in this area should just fix the underling bug:

https://bugs.rocicorp.dev/p/zero/issue/3036

[Karavil]

Did you consider using React.memo to prevent the child row components from re-rendering? this is what we have done in the past.

You can use deepEquals to decide whether the props have changed.

Using React.memo doesn't stop re-renders unless you perfectly structure your components using a parent useMemo + a component memo. It's a bit of a headache. And the parent still re-renders if they use this hook, even though useMemo technically memoizes the parsed section.

[Karavil]

Alternately if we want to make a change in this area should just fix the underling bug:

https://bugs.rocicorp.dev/p/zero/issue/3036

I think it'd be great to do both! More performance!

[Karavil]

Did you consider using React.memo to prevent the child row components from re-rendering? this is what we have done in the past.

You can use deepEquals to decide whether the props have changed.

// The crux: React.memo can't block re-renders triggered by hooks inside the component

function Row({ id }) {
  const [students] = useQuery(allStudentsQuery); // ← re-render triggered here
  const student = useMemo(
    () => students.find(s => s.id === id),
    [students, id]
  );
  // useMemo memoizes the find() result, but we've already re-rendered:
  // JSX diffing, effects, and child reconciliation all run
  return <tr>{student?.name}</tr>;
}

const MemoizedRow = React.memo(Row); // does nothing: re-render comes from inside, not props

The "perfect structure" requires lifting the query to a parent and passing deeply-compared props:

function Roster() {
  const [students] = useQuery(allStudentsQuery); // parent re-renders on every change
  return students.map(s => <MemoizedRow key={s.id} student={s} />);
}

const MemoizedRow = React.memo(Row, (a, b) => deepEquals(a.student, b.student));

This works, but fragments data requirements across components. With select, data stays colocated and re-renders are blocked at the source:

function StudentIdList({ classId }) {
  const [studentIds] = useQuery(classQuery(classId), {
    select: (cls) => cls?.students.map(s => s.id),
  });
  // Only re-renders when the list of IDs changes:
  // - Class name changes? No re-render
  // - Student name changes? No re-render  
  // - Student added/removed? Re-render
  return <ul>{studentIds?.map(id => <li key={id}>{id}</li>)}</ul>;
}

The deep equality check on the selected value means you only pay for what you use.

[Karavil]

Alternately if we want to make a change in this area should just fix the underlying bug:

https://bugs.rocicorp.dev/p/zero/issue/3036

Looking at that PR (#3688): it makes the React.memo approach more viable by giving individual rows stable references, but it doesn't change array reference behavior.

// Arrays still get new refs on any change
const newView = view.toSpliced(pos, 1);

So useEffect with [students] as a dependency still fires when any student changes. The granularity is at the row level, not the array level:

• students array: new reference on any change
• students[0]: same reference if that row didn't change

This means React.memo with shallow comparison works after that PR:

const MemoizedRow = React.memo(({ student }) => <tr>...</tr>);
// Only rows that changed re-render (row refs are stable)

But it doesn't help when you're deriving data from the query. If you just need a list of student IDs from a class:

const [cls] = useQuery(classQuery);
const studentIds = useMemo(() => cls?.students.map(s => s.id), [cls]);
// Re-renders when ANY class or student data changes, even though
// we only care about the list of IDs

With select:

const [studentIds] = useQuery(classQuery, {
  select: (cls) => cls?.students.map(s => s.id),
});
// Only re-renders when the actual list of IDs changes

Both PRs complement each other: #3688 makes prop-drilling + memo viable for row-level stability, select makes derived/projected data viable by blocking re-renders at the source.

[aboodman]

Thanks for this submission. I'm not sure about this from a feature POV and want to think about it some more.

I think it is possible to implement something like this in userland? So you're not blocked on us to do it.

[Karavil]

Thanks for this submission. I'm not sure about this from a feature POV and want to think about it some more.

I think it is possible to implement something like this in userland? So you're not blocked on us to do it.

Fair! I tried doing this in userland and it was quite buggy as I had to patch Zero to export some internal types to make it work as I couldn't use useQuery directly (you need to hook into the Zero client itself + re-implement useQuery the same way I did here if you want to prevent memo + useMemo infecting your whole codebase). FWIW this would drastically improve our table and grid performance as we recently refactored ~600 individual queries to use a top-down query (which then re-renders the whole grid).

[Karavil]

Thanks for this submission. I'm not sure about this from a feature POV and want to think about it some more.

I think it is possible to implement something like this in userland? So you're not blocked on us to do it.

Happy to make this an experimental_useSelectQuery too by the way if y'all are not sure about supporting this going forward.

[arv]

@Karavil Thanks for your work here. I've read up on the situation and it seems like a valuable addition.

Our main concern at the moment is more about how this fits into our API.

• Could this be done with select on Query

• We used to be able to refine "custom" queries with local refinements:

import {queries} from '...';
const q = queries.getAllStudents().select('id', 'name');
const [students] = useQuery(q);

The current thinking is that we should export the needed types and helper functions to allow something like this to be doable in user land.

Would you be interested in helping me understand what you need to achieve this?