Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

README.md

301 lines8.0 KB

1# @TanStack/optimistic
2​
3A library for creating fast optimistic updates with flexible backend support that pairs seamlessly with sync engines (like [ElectricSQL](https://electric-sql.com/)).
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- **Framework Integration**: Seamless integration with frontend frameworks
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
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​
71- `data`: An array of all items in the collection
72- `state`: A Map containing all items in the collection with their internal keys
73- `insert`: Function to add new items to the collection
74- `update`: Function to modify existing items
75- `delete`: Function to remove items from the collection
76​
77#### `preloadCollection`
78​
79Preloads data for a collection before rendering components.
80​
81```typescript
82await preloadCollection({
83 id: 'todos',
84 sync: { /* sync configuration */ },
85 mutationFn: { /* mutation functions */ },
86 schema: /* optional schema */
87});
88```
89​
90Features:
91​
921. Returns a promise that resolves when the first sync commit is complete
932. Shares the same collection instance with `useCollection`
943. Handles already-loaded collections by returning immediately
954. Avoids duplicate initialization when called multiple times with the same ID
96​
97### Data Operations
98​
99#### Insert
100​
101```typescript
102// Insert a single item
103insert({ text: "Buy groceries", completed: false })
104​
105// Insert multiple items
106insert([
107 { text: "Buy groceries", completed: false },
108 { text: "Walk dog", completed: false },
109])
110​
111// Insert with custom key
112insert({ text: "Buy groceries" }, { key: "grocery-task" })
113```
114​
115#### Update
116​
117We use a proxy to capture updates as immutable draft optimistic updates.
118​
119```typescript
120// Update a single item
121update(todo, (draft) => {
122 draft.completed = true
123})
124​
125// Update multiple items
126update([todo1, todo2], (drafts) => {
127 drafts.forEach((draft) => {
128 draft.completed = true
129 })
130})
131​
132// Update with metadata
133update(todo, { metadata: { reason: "user update" } }, (draft) => {
134 draft.text = "Updated text"
135})
136```
137​
138#### Delete
139​
140```typescript
141// Delete a single item
142delete todo
143​
144// Delete multiple items
145delete [todo1, todo2]
146​
147// Delete with metadata
148delete (todo, { metadata: { reason: "completed" } })
149```
150​
151### Schema Validation
152​
153Collections can optionally include a [standard schema](https://github.com/standard-schema/standard-schema) for data validation:
154​
155```typescript
156const todoCollection = useCollection({
157 id: "todos",
158 sync: {
159 /* sync config */
160 },
161 mutationFn: {
162 /* mutation functions */
163 },
164 schema: todoSchema, // Standard schema interface
165})
166```
167​
168## Transaction Management
169​
170The library includes a robust transaction management system:
171​
172- `TransactionManager`: Handles transaction lifecycle, persistence, and retry logic
173- `TransactionStore`: Provides persistent storage for transactions using IndexedDB
174​
175Transactions progress through several states:
176​
1771. `pending`: Initial state when a transaction is created
1782. `persisting`: Transaction is being persisted to the backend
1793. `completed`: Transaction has been successfully persisted
1804. `failed`: An error was thrown while persisting or syncing back the Transaction
181​
182## Implementing Backend Integration with ElectricSQL
183​
184The `mutationFn` property is where you define how your application interacts with your backend. Here's a comprehensive example of integrating with ElectricSQL:
185​
186```typescript
187import { useCollection } from "@TanStack/optimistic/useCollection"
188import { createElectricSync } from '@TanStack/optimistic/electric';
189​
190// Create a collection configuration for todos
191const todosConfig = {
192 id: 'todos',
193 // Create an ElectricSQL sync configuration
194 sync: createElectricSync(
195 {
196 // ShapeStream options
197 url: `http://localhost:3000/v1/shape`,
198 params: {
199 table: 'todos',
200 },
201 },
202 {
203 // Primary key for the todos table
204 primaryKey: ['id'],
205 }
206 ),
207 mutationFn: {
208 // Persist mutations to ElectricSQL
209 persist: async (mutations, transaction) => {
210 const response = await fetch(`http://localhost:3001/api/mutations`, {
211 method: `POST`,
212 headers: {
213 "Content-Type": `application/json`,
214 },
215 body: JSON.stringify(transaction.mutations),
216 })
217 if (!response.ok) {
218 // Throwing an error will rollback the optimistic state.
219 throw new Error(`HTTP error! Status: ${response.status}`)
220 }
221​
222 const result = await response.json()
223​
224 return {
225 txid: result.txid,
226 }
227 },
228 // Wait for a transaction to be synced
229 awaitSync: async ({ config, persistResult: { txid: number } }) => {
230 try {
231 // Use the awaitTxid function from the ElectricSync configuration
232 // This waits for the specific transaction to be synced to the server
233 // The second parameter is an optional timeout in milliseconds
234 await config.sync.awaitTxid(persistResult.txid, 10000)
235 return true;
236 } catch (error) {
237 console.error('Error waiting for transaction to sync:', error);
238 // Throwing an error will rollback the optimistic state.
239 throw error;
240 }
241 },
242 },
243};
244​
245// In a route loader
246export async function loader() {
247 // Preload todos before rendering
248 await preloadCollection(todosConfig);
249 return null;
251​
252// Example usage in a component
253function TodoList() {
254 const { data, insert, update, delete: remove } = useCollection(todosConfig);
255​
256 const addTodo = () => {
257 insert({ title: 'New todo', completed: false });
258 };
259​
260 const toggleTodo = (todo) => {
261 update(todo, (draft) => {
262 draft.completed = !draft.completed;
263 });
264 };
265​
266 const removeTodo = (todo) => {
267 remove(todo);
268 };
269​
270 return (
271 <div>
272 <button onClick={addTodo}>Add Todo</button>
273 <ul>
274 {data.map(todo => (
275 <li key={todo.id}>
276 <input
277 type="checkbox"
278 checked={todo.completed}
279 onChange={() => toggleTodo(todo)}
280 />
281 {todo.title}
282 <button onClick={() => removeTodo(todo)}>Delete</button>
283 </li>
284 ))}
285 </ul>
286 </div>
287 );
289```
290​
291This implementation:
292​
2931. **Creates an ElectricSQL sync configuration** using the `createElectricSync` helper
2942. **Handles mutations** by POSTing them to a backend API.
2953. **Uses transactions** to ensure data consistency
2964. **Tracks sync status** with the `awaitTxid` function
2975. **Provides proper error handling** throughout the process
298​
299## License
300​
301MIT