React docs out of date: still rely on retired `isUpToDate`

[robacourt]

The react docs reference isUpToDate which was retired in this PR to be superseded by lastSyncedAt. Please expose lastSyncedAt in the react hooks and update the docs.

[thruflo]

Looking at the code:

1. lastSyncedAt was added as a private property of the shape; the shape also provides a public lastSynced() method which returns the time in ms since the shape was last synced
2. the shape instance is in the UseShapeResult return value of useShape; do we want to read lastSyncedAt from the shape and put it up a level into the useShape result, or could the user unpack the shape in their useShape result?

To illustrate, do we want this:

// lastSyncedAt is a unix timestamp if synced or undefined if never synced
const { data, lastSyncedAt } = useShape({...})

This:

// lastSynced is ms since last synced or infinity if never synced
const { data, lastSynced } = useShape({...})

This:

const { data, shape: { lastSyncedAt } } = useShape({...})

Or this:

const { data, shape: { lastSynced } } = useShape({...})

[KyleAMathews]

Hmm yeah we didn't update that usage. And now I'm wandering if removing isUpToDate was a good idea as there's no other property which crisply indicates whether you should render or not. You could use lastSyncedAt but you'd have to check if it doesn't equal infinity — which isn't very intuitive.

Though the current code sample is also weird as you only want to block rendering if the initial sync hasn't completed. E.g. if you go offline, you don't want to stop rendering the UI even if the shape isn't synced fully anymore.

So perhaps a isReady property is all we want — false when there's no data and true when there is data. lastSyncedAt is good too for more advanced users that might want to not show data if the last synced time is too long ago.

[KyleAMathews]

isLoading is another option that matches tanstack/query so would have some familiarity in the ecosystem — perhaps better anyways because it's less ambiguous — "ready" could mean several things but "I'm loading a shape" is pretty clear https://tanstack.com/query/latest/docs/framework/react/reference/useQuery

[KyleAMathews]

Yeah let's just go with isLoading — it's well known and clear. The only downside is it'd be false when an app comes back from being offline for a while so the app would immediately render before the shape could catch-up with the server. But this is fairly harmless edge case & also the developer can address this if they like by also checking how long ago was the last sync.

[kevin-dp]

@KyleAMathews The React docs are updated and isLoading is now exposed. Do we also want lastSynced/lastSyncedAt to be exposed on the hooks or we leave it our for now?

[KyleAMathews]

yeah, let's also expose lastSyncedAt — that'll be useful for folks

[kevin-dp]

lastSyncedAt is now exposed as of #1724.
Closing this issue as solved.