Simple, type-safe data fetching and optimistic updates for React

A lightweight wrapper around TanStack Query that provides a cleaner API for defining queries, mutations, and handling optimistic updates with full TypeScript inference.

---

Why query-optimistic?

TanStack Query is powerful but optimistic updates can get complex fast. This library gives you:

| Feature | TanStack Query | query-optimistic |
|---------|---------------|------------------|
| Define data sources | Inline in each component | Once, reuse everywhere |
| Optimistic updates | Manual cache manipulation | Intuitive channel API |
| Type safety | Manual type annotations | Automatic inference |
| Multi-query updates | Complex cache logic | Simple method chaining |
| Rollback on error | Manual implementation | Automatic |

``tsx
// Before: TanStack Query optimistic update
useMutation({
mutationFn: createTodo,
onMutate: async (newTodo) => {
await queryClient.cancelQueries({ queryKey: ['todos'] })
const previous = queryClient.getQueryData(['todos'])
queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
return { previous }
},
onError: (err, newTodo, context) => {
queryClient.setQueryData(['todos'], context.previous)
},
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['todos'] })
}
})

// After: query-optimistic
useMutation(createTodo, {
optimistic: (channel, todo) => {
channel(todosCollection).append(todo, { reconcile: true })
}
})
`

---

Installation

`bash
npm install query-optimistic @tanstack/react-query
`

`bash
yarn add query-optimistic @tanstack/react-query
`

`bash
pnpm add query-optimistic @tanstack/react-query
`

---

Quick Start

$3

`typescript
import { defineCollection, defineEntity, defineMutation } from 'query-optimistic'

// A collection is an array of items
const todosCollection = defineCollection({
name: 'todos',
id: (todo) => todo.id,
fetch: () => api.get('/todos')
})

// An entity is a single item
const userEntity = defineEntity({
name: 'currentUser',
fetch: () => api.get('/me')
})

// Define mutations separately
const createTodo = defineMutation({
mutate: (params: { title: string }) => api.post('/todos', params)
})
`

$3

`tsx
import { useQuery, useMutation } from 'query-optimistic'

function TodoApp() {
const [todos, { isLoading }] = useQuery(todosCollection)
const [user] = useQuery(userEntity)

const { mutate: addTodo, isPending } = useMutation(createTodo, {
optimistic: (channel, params) => {
channel(todosCollection).append({
id: temp-${Date.now()},
title: params.title,
completed: false,
}, { reconcile: true })
}
})

if (isLoading) return

return (


`tsx
import { defineCollection, defineMutation, useQuery, useMutation } from 'query-optimistic'

interface Todo {
id: string
title: string
completed: boolean
createdAt: string
}

// Define the collection
const todosCollection = defineCollection({
name: 'todos',
id: (todo) => todo.id,
fetch: () => fetch('/api/todos').then(r => r.json())
})

// Define mutations
const createTodo = defineMutation<{ title: string }, Todo>({
mutate: (params) => fetch('/api/todos', {
method: 'POST',
body: JSON.stringify(params)
}).then(r => r.json())
})

const toggleTodo = defineMutation<{ id: string; completed: boolean }, Todo>({
mutate: ({ id, completed }) => fetch(/api/todos/${id}, {
method: 'PATCH',
body: JSON.stringify({ completed })
}).then(r => r.json())
})

const deleteTodo = defineMutation<{ id: string }, void>({
mutate: ({ id }) => fetch(/api/todos/${id}, { method: 'DELETE' })
})

// Component
function TodoList() {
const [todos, { isLoading }] = useQuery(todosCollection)

const { mutate: create } = useMutation(createTodo, {
optimistic: (channel, params) => {
channel(todosCollection).append({
id: temp-${Date.now()},
title: params.title,
completed: false,
createdAt: new Date().toISOString()
}, { reconcile: true })
}
})

const { mutate: toggle } = useMutation(toggleTodo, {
optimistic: (channel, params) => {
channel(todosCollection).update(params.id, todo => ({
...todo,
completed: params.completed
}))
}
})

const { mutate: remove } = useMutation(deleteTodo, {
optimistic: (channel, params) => {
channel(todosCollection).delete(params.id)
}
})

return (


`tsx
interface CartItem {
id: string
productId: string
name: string
price: number
quantity: number
}

interface CartSummary {
itemCount: number
total: number
}

const cartCollection = defineCollection({
name: 'cart',
id: (item) => item.id,
fetch: () => api.get('/cart/items')
})

const cartSummaryEntity = defineEntity({
name: 'cartSummary',
fetch: () => api.get('/cart/summary')
})

const updateQuantity = defineMutation<{ id: string; quantity: number }, CartItem>({
mutate: ({ id, quantity }) => api.patch(/cart/items/${id}, { quantity })
})

const removeFromCart = defineMutation<{ id: string }, void>({
mutate: ({ id }) => api.delete(/cart/items/${id})
})

function Cart() {
const [items] = useQuery(cartCollection)
const [summary] = useQuery(cartSummaryEntity)

const { mutate: updateQty } = useMutation(updateQuantity, {
optimistic: (channel, params) => {
// Update the item quantity
channel(cartCollection).update(params.id, item => ({
...item,
quantity: params.quantity
}))

// Update the summary
channel(cartSummaryEntity).update(s => {
const item = items?.find(i => i.id === params.id)
const diff = params.quantity - (item?.quantity ?? 0)
return {
itemCount: s.itemCount + diff,
total: s.total + (item?.price ?? 0) * diff
}
})
}
})

const { mutate: remove } = useMutation(removeFromCart, {
optimistic: (channel, params) => {
const item = items?.find(i => i.id === params.id)

channel(cartCollection).delete(params.id)

channel(cartSummaryEntity).update(s => ({
itemCount: s.itemCount - (item?.quantity ?? 0),
total: s.total - (item?.price ?? 0) * (item?.quantity ?? 0)
}))
}
})

return (


`tsx
interface Post {
id: string
author: { name: string; avatar: string }
content: string
likes: number
likedByMe: boolean
createdAt: string
}

const feedCollection = defineCollection({
name: 'feed',
id: (post) => post.id,
fetch: ({ page = 1 }) => api.get(/feed?page=${page})
})

const likePost = defineMutation<{ postId: string }, void>({
mutate: ({ postId }) => api.post(/posts/${postId}/like)
})

const unlikePost = defineMutation<{ postId: string }, void>({
mutate: ({ postId }) => api.delete(/posts/${postId}/like)
})

function Feed() {
const [posts, query, pagination] = useQuery(feedCollection, {
paginated: true,
getPageParams: ({ pageParam = 1 }) => ({ page: pageParam })
})

const { mutate: like } = useMutation(likePost, {
optimistic: (channel, params) => {
channel(feedCollection).update(params.postId, post => ({
...post,
likes: post.likes + 1,
likedByMe: true
}))
}
})

const { mutate: unlike } = useMutation(unlikePost, {
optimistic: (channel, params) => {
channel(feedCollection).update(params.postId, post => ({
...post,
likes: post.likes - 1,
likedByMe: false
}))
}
})

return (


{posts?.map(post => (

{post.author.name}

{post.content}

))}

{pagination.hasNextPage && (
onClick={() => pagination.fetchNextPage()}
disabled={pagination.isFetchingNextPage}
>
{pagination.isFetchingNextPage ? 'Loading...' : 'Load More'}

)}

`tsx
interface Document {
id: string
title: string
content: string
lastEditedBy: string
updatedAt: string
}

const documentEntity = defineEntity({
name: 'document',
fetch: (docId) => api.get(/documents/${docId})
})

const updateDocument = defineMutation<{ id: string; content: string }, Document>({
mutate: ({ id, content }) => api.patch(/documents/${id}, { content })
})

function DocumentEditor({ docId }: { docId: string }) {
const [doc, { isLoading }] = useQuery(documentEntity, { params: docId })
const [localContent, setLocalContent] = useState('')

useEffect(() => {
if (doc) setLocalContent(doc.content)
}, [doc?.content])

const { mutate: save, isPending } = useMutation(updateDocument, {
optimistic: (channel, params) => {
channel(documentEntity).update(d => ({
...d,
content: params.content,
updatedAt: new Date().toISOString(),
lastEditedBy: 'You'
}))
}
})

// Auto-save with debounce
const debouncedSave = useMemo(
() => debounce((content: string) => save({ id: docId, content }), 1000),
[docId, save]
)

if (isLoading) return

return (


`tsx
interface Task {
id: string
title: string
order: number
}

const tasksCollection = defineCollection({
name: 'tasks',
id: (task) => task.id,
fetch: () => api.get('/tasks')
})

const reorderTask = defineMutation<{ id: string; newOrder: number }, Task[]>({
mutate: ({ id, newOrder }) => api.post(/tasks/${id}/reorder, { order: newOrder })
})

function TaskBoard() {
const [tasks] = useQuery(tasksCollection)
const sortedTasks = useMemo(
() => tasks?.slice().sort((a, b) => a.order - b.order),
[tasks]
)

const { mutate: reorder } = useMutation(reorderTask, {
optimistic: (channel, params) => {
channel(tasksCollection).updateWhere(
() => true, // Update all tasks
(task) => {
if (task.id === params.id) {
return { ...task, order: params.newOrder }
}
// Shift other tasks
if (task.order >= params.newOrder) {
return { ...task, order: task.order + 1 }
}
return task
}
)
}
})

const handleDrop = (draggedId: string, targetIndex: number) => {
reorder({ id: draggedId, newOrder: targetIndex })
}

return (