Open History to see the last commit
1# @TanStack/optimistic
2
3A library for creating fast optimistic updates with flexible backend support that pairs seamlessly with sync engines like ElectricSQL.
4
5This library is still under design! Please let us know what you think.
6
7Checkout the [example todo app](todo-app/).
8
9## Installation
10
11```bash
12npm i @TanStack/optimistic
13```
14
15## Overview
16
17`@TanStack/optimistic` provides a robust solution for managing data synchronization between your frontend application and backend services. It offers:
18
19- **Optimistic Updates**: Apply changes instantly in the UI while syncing in the background
20- **Flexible Backend Support**: Works with any backend or sync engine
21- **Immutable Snapshots**: Create immutable snapshots of updates that can be persisted and rolled back
22- **React Integration**: Seamless integration with React applications
23
24## Core Concepts
25
26### Collections
27
28Collections are the central concept in `@TanStack/optimistic`. A collection represents a set of data that can be synchronized, queried, and modified. Each collection:
29
30- Has a unique identifier
31- Contains data items accessible via keys
32- Provides CRUD operations (insert, update, delete)
33- Manages its own sync and persistence logic
34
35### Transactions
36
37All mutations in `@TanStack/optimistic` are handled through transactions. Transactions:
38
39- Group related changes together
40- Track the state of mutations (pending, persisting, completed, failed)
41- Support rollback in case of errors
42- Provide optimistic updates to the UI
43
44### Proxies
45
46The library uses proxies to create immutable snapshots and track changes:
47
48- Deep change tracking at any level of object nesting
49- Special handling for various types (Date, RegExp, Map, Set)
50- Circular reference handling with WeakMap cache
51
52## API Reference
53
54### React Hooks
55
56#### `useCollection`
57
58The primary hook for interacting with collections in React components.
59
60```typescript
61const { data, insert, update, delete: deleteFn } = useCollection({
62 id: 'todos',
63 sync: { /* sync configuration */ },
64 mutationFn: { /* mutation functions */ },
65 schema: /* optional schema */
66});
67```
68
69Returns:
70- `data`: An array of all items in the collection
71- `state`: A Map containing all items in the collection with their keys
72- `insert`: Function to add new items to the collection
73- `update`: Function to modify existing items
74- `delete`: Function to remove items from the collection
75
76#### `preloadCollection`
77
78Preloads data for a collection before rendering components.
79
80```typescript
81await preloadCollection({
82 id: 'todos',
83 sync: { /* sync configuration */ },
84 mutationFn: { /* mutation functions */ },
85 schema: /* optional schema */
86});
87```
88
89Features:
901. Returns a promise that resolves when the first sync commit is complete
912. Shares the same collection instance with `useCollection`
923. Handles already-loaded collections by returning immediately
934. Avoids duplicate initialization when called multiple times with the same ID
94
95### Data Operations
96
97#### Insert
98
99```typescript
100// Insert a single item
101insert({ text: "Buy groceries", completed: false });
102
103// Insert multiple items
104insert([
105 { text: "Buy groceries", completed: false },
106 { text: "Walk dog", completed: false }
107]);
108
109// Insert with custom key
110insert({ text: "Buy groceries" }, { key: "grocery-task" });
111```
112
113#### Update
114
115We use a proxy to capture updates as immutable draft optimistic updates.
116
117```typescript
118// Update a single item
119update(todo, (draft) => { draft.completed = true });
120
121// Update multiple items
122update([todo1, todo2], (drafts) => {
123 drafts.forEach(draft => { draft.completed = true });
124});
125
126// Update with metadata
127update(todo, { metadata: { reason: "user update" } }, (draft) => {
128 draft.text = "Updated text";
129});
130```
131
132#### Delete
133
134```typescript
135// Delete a single item
136delete(todo);
137
138// Delete multiple items
139delete([todo1, todo2]);
140
141// Delete with metadata
142delete(todo, { metadata: { reason: "completed" } });
143```
144
145### Schema Validation
146
147Collections can optionally include a schema for data validation:
148
149```typescript
150const todoCollection = useCollection({
151 id: 'todos',
152 sync: { /* sync config */ },
153 mutationFn: { /* mutation functions */ },
154 schema: todoSchema // Standard schema interface
155});
156```
157
158## Transaction Management
159
160The library includes a robust transaction management system:
161
162- `TransactionManager`: Handles transaction lifecycle, persistence, and retry logic
163- `TransactionStore`: Provides persistent storage for transactions using IndexedDB
164
165Transactions progress through several states:
1661. `pending`: Initial state when a transaction is created
1672. `persisting`: Transaction is being persisted to the backend
1683. `completed`: Transaction has been successfully persisted
1694. `failed`: An error was thrown while persisting or syncing back the Transaction
170
171## Implementing Backend Integration with ElectricSQL
172
173The `mutationFn` property is where you define how your application interacts with your backend. Here's a comprehensive example of integrating with ElectricSQL:
174
175```typescript
176import { useCollection } from "@TanStack/optimistic/useCollection"
177import { createElectricSync } from '@TanStack/optimistic/electric';
178
179// Create a collection configuration for todos
180const todosConfig = {
181 id: 'todos',
182 // Create an ElectricSQL sync configuration
183 sync: createElectricSync(
184 {
185 // ShapeStream options
186 url: `http://localhost:3000/v1/shape`,
187 params: {
188 table: 'todos',
189 },
190 },
191 {
192 // Primary key for the todos table
193 primaryKey: ['id'],
194 }
195 ),
196 mutationFn: {
197 // Persist mutations to ElectricSQL
198 persist: async (mutations, transaction) => {
199 const response = await fetch(`http://localhost:3001/api/mutations`, {
200 method: `POST`,
201 headers: {
202 "Content-Type": `application/json`,
203 },
204 body: JSON.stringify(transaction.mutations),
205 })
206 if (!response.ok) {
207 // Throwing an error will rollback the optimistic state.
208 throw new Error(`HTTP error! Status: ${response.status}`)
209 }
210
211 const result = await response.json()
212
213 return {
214 txid: result.txid,
215 }
216 },
217 // Wait for a transaction to be synced
218 awaitSync: async ({ config, persistResult: { txid: number } }) => {
219 try {
220 // Use the awaitTxid function from the ElectricSync configuration
221 // This waits for the specific transaction to be synced to the server
222 // The second parameter is an optional timeout in milliseconds
223 await config.sync.awaitTxid(persistResult.txid, 10000)
224 return true;
225 } catch (error) {
226 console.error('Error waiting for transaction to sync:', error);
227 // Throwing an error will rollback the optimistic state.
228 throw error;
229 }
230 },
231 },
232};
233
234// In a route loader
235export async function loader() {
236 // Preload todos before rendering
237 await preloadCollection(todosConfig);
238 return null;
239}
240
241// Example usage in a component
242function TodoList() {
243 const { data, insert, update, delete: remove } = useCollection(todosConfig);
245 const addTodo = () => {
246 insert({ title: 'New todo', completed: false });
247 };
249 const toggleTodo = (todo) => {
250 update(todo, (draft) => {
251 draft.completed = !draft.completed;
252 });
253 };
255 const removeTodo = (todo) => {
256 remove(todo);
257 };
259 return (
260 <div>
261 <button onClick={addTodo}>Add Todo</button>
262 <ul>
263 {data.map(todo => (
264 <li key={todo.id}>
265 <input
266 type="checkbox"
267 checked={todo.completed}
268 onChange={() => toggleTodo(todo)}
269 />
270 {todo.title}
271 <button onClick={() => removeTodo(todo)}>Delete</button>
272 </li>
273 ))}
274 </ul>
275 </div>
276 );
277}
278```
279
280This implementation:
281
2821. **Creates an ElectricSQL sync configuration** using the `createElectricSync` helper
2832. **Handles mutations** by POSTing them to a backend API.
2843. **Uses transactions** to ensure data consistency
2854. **Tracks sync status** with the `awaitTxid` function
2865. **Provides proper error handling** throughout the process
287
288## License
289
290MIT