Provide example usage with mutations in Tanstack query

[onyedikachi23]

I'm really interested in understanding the need for this project, as optimistic updates have never been a problem for me using Tanstack Query.

The README only gave an example implementation in ElectricSQL. In which I was really expecting an example with actual Tanstack stuffs like Tanstack Query. In most cases, I only happen to perform optimistic updates during mutations ( with useMutation). So please, give an example.

[KyleAMathews]

The mutations are done in the mutationFn. The example in the readme show doing fetch calls to a backend API. There's also a full example in the repo you can look at. This isn't meant to be used with Tanstack/query, it's rather a replacement for when you're building with a sync engine

The goal here is to make optimistic updates very easy -- not everyone will need it but if you're building an app with extensive optimistic updates and lots of backend changes (especially unpredictable ones or in multi-user or agentic apps) then this will be really helpful.

[onyedikachi23]

I reviewed the full React example and understand it now.

I posted this discussion because someone on X mentioned rewriting their optimistic updates in the useMutation hook to use this library when it's ready.

I was looking for an example and a compelling reason to migrate from the already simple useMutation setup.

[KyleAMathews]

Which discussion btw?

[onyedikachi23]

Here's the X post

[DaliborHomola]

I’m trying to wrap my head around TanStack DB collections and live queries, and I’d love some guidance on my example below.
Assume /api/library returns:

{
  "library": {
    "id": "lib-001",
    "name": "Central Public Library",
    "address": "123 Main Street, Downtown",
    "books": [
      {
        "id": "book-001",
        "title": "The Great Gatsby",
        "author": "F. Scott Fitzgerald"
      }
    ]
  }
}

❓ My questions
Collections (via createQueryCollection) should map to individual entity types. Does it means that I should split my endpoint into 2 separate ones /api/library and /api/books and use a live query to join books into the library view on frontend?

How do transactions work client-side agains API? If I’m updating several books and one update fails, will TanStack DB rollback (call DELETE API) for the earlier ones?

[KyleAMathews]

Collections can have anything in them so you don't need to change your API. Our argument with DB is that it's much nicer now to have normalized data coming into the client & there's some advantages to it but it still works great without it.

DB's transactions are client only — so rollbacks are only to the optimistic mutations. So typically if you want to modify several books in a transaction, you'd send one API call to the backend which uses a backend DB transaction as well. You could manually send DELETEs but... that sounds scary to me 😆 Here are the docs about your options for transactions https://tanstack.com/db/latest/docs/overview#transactional-mutators

[DaliborHomola]

Thank you, I think I understand now.

[mustafa-hanif]

[thruflo]

https://tanstack.com/db/latest/docs/reference/interfaces/collection#insert

[KyleAMathews]

https://tanstack.com/db/latest/docs/overview

@mustafa-hanif this is your warning — one more comment like that and you're banned from this repo.