Local first write support

[lukvermeulen]

As far as my current understanding goes, we can sync data with electric-sql from an online postgres database into our client either

• into shapes
• into a local pglite database.

e.g. like this:

import { ShapeStream, Shape } from '@electric-sql/client'

const stream = new ShapeStream({
  url: `http://localhost:3000/v1/shape/foo`,
})
const shape = new Shape(stream)

Is this correct?

As a developer, it would be awesome if local first writes would be possible with the same ease.

Changes could look like this, given a stream has already been created like in the above example:

// create data
shape.create({
...
})

// update data
shape.updateOne(id, {
...
})

Another awesome approach would probably be writing to the pglite directly, with updates being synced with the online db in the backgorund.

Additional ideas:

• changes would be reflected locally without internet and
• persisted in a queue and synced when coming back online again

---

Currently updates are possible with a normal backend like in this official example:
https://github.com/electric-sql/electric/blob/main/examples/tanstack-example/

This appears to handle optimistic updates with a dependency to react-query / tanstack, which would require to let tanstack handle not only optimistic writes but handle persistence of changes. Also the role of the match-stream function is not obvious to me personally.
https://github.com/electric-sql/electric/blob/main/examples/tanstack-example/src/match-stream.ts

[KyleAMathews]

Another awesome approach would probably be writing to the pglite directly, with updates being synced with the online db in the background.

We definitely want to make this an option but there are tradeoffs vs. just handling writes yourself. Server authoritative writes make a lot of things easier — https://bricolage.io/announcing-trpc-crdt/#sometimes-you-just-need-a-server

Also the role of the match-stream function is not obvious to me personally

When you do a client or optimistic write, it's tentative until the server has confirmed the write. How tanstack/query works out of the box is that you do the API call and when it returns successfully, tanstack query then re-fetches all the data to update the UI. With Electric in the mix, we don't need to refetch to get the new data, we need to wait for the data to be synced from Electric. So match-stream is a helper class to make it easy to watch the shape stream for when our write comes back across. When we've seen the write and the mutation is successful, that's when we can drop the optimistic state and go back to just reading the synced state.