dynamodb-reactive 0.1.3 → 0.1.5

package/README.md

@@ -124,35 +124,125 @@ export async function POST(request: Request) {
 }
 ```
 
-### **Step 4: Call from Client**
+### **Step 4: Set Up React Provider**
 
 ```typescript
-// Query
-const response = await fetch('/api/reactive', {
-  method: 'POST',
-  body: JSON.stringify({
-    type: 'subscribe',
-    subscriptionId: 'sub-1',
-    path: 'todos.list',
-    input: {},
-  }),
+// app/layout.tsx or providers.tsx
+'use client';
+
+import { ReactiveClientProvider } from 'dynamodb-reactive/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ReactiveClientProvider
+      config={{
+        url: process.env.NEXT_PUBLIC_WS_URL!,
+        httpUrl: '/api/reactive',
+      }}
+    >
+      {children}
+    </ReactiveClientProvider>
+  );
+}
+```
+
+### **Step 5: Use React Hooks**
+
+```typescript
+'use client';
+
+import type { Todo } from './types';
+import type { AppRouter } from './router';
+import { useClient, useConnectionState } from 'dynamodb-reactive/client';
+
+export function TodoList() {
+  const connectionState = useConnectionState();
+  const client = useClient<AppRouter>();
+
+  // Subscribe to todos - receives real-time updates via WebSocket
+  const { data: todos, loading, error } = client.todos.list.useQuery({});
+
+  // Mutations with automatic optimistic updates
+  const createMutation = client.todos.create.useMutation();
+  const toggleMutation = client.todos.toggle.useMutation();
+  const deleteMutation = client.todos.delete.useMutation();
+
+  const handleCreate = async (text: string) => {
+    await createMutation.mutate({ text });
+  };
+
+  const handleToggle = async (id: string) => {
+    await toggleMutation.mutate({ id });
+  };
+
+  const handleDelete = async (id: string) => {
+    await deleteMutation.mutate({ id }); // Removes instantly from UI
+  };
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <p>WebSocket: {connectionState}</p>
+      {todos?.map((todo) => (
+        <div key={todo.id}>
+          <input
+            type="checkbox"
+            checked={todo.completed}
+            onChange={() => handleToggle(todo.id)}
+          />
+          <span>{todo.text}</span>
+          <button onClick={() => handleDelete(todo.id)}>Delete</button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## **5. Optimistic Updates**
+
+All mutations apply **instant** optimistic updates (before HTTP request):
+
+| Update Type | Behavior | Example Input |
+| :--- | :--- | :--- |
+| `'merge'` | Find item by `input.id`, merge input fields | `{ id: '123', completed: true }` |
+| `'remove'` | Remove item by `input.id` | `{ id: '123' }` |
+| Custom function | Apply custom logic | `(data, input) => [...]` |
+
+**Convention:** `<namespace>.<action>` mutations auto-invalidate `<namespace>.list` subscriptions.
+
+**Example - Instant Toggle:**
+```typescript
+// For instant optimistic updates, include the fields you want to change
+const handleToggle = async (todo: Todo) => {
+  await updateMutation.mutate({
+    id: todo.id,
+    completed: !todo.completed  // Include new value for instant UI update
+  });
+};
+```
+
+**Custom options:**
+```typescript
+const mutation = client.todos.update.useMutation({
+  invalidates: 'todos.list',           // Override auto-detection
+  optimisticUpdate: 'merge',           // 'merge' | 'remove' | custom function
 });
-const { data } = await response.json();
-
-// Mutation
-const response = await fetch('/api/reactive', {
-  method: 'POST',
-  body: JSON.stringify({
-    type: 'call',
-    callId: 'call-1',
-    path: 'todos.create',
-    input: { text: 'New todo' },
+
+// For creates (no id), provide optimisticData
+const createMutation = client.todos.create.useMutation({
+  optimisticData: (input) => ({
+    id: `temp-${Date.now()}`,
+    ...input,
+    completed: false,
+    createdAt: Date.now(),
   }),
 });
-const { data } = await response.json();
 ```
 
-## **5. Database Context Methods**
+## **6. Database Context Methods**
 
 The `ctx.db` object provides these methods:
 
@@ -164,11 +254,11 @@ The `ctx.db` object provides these methods:
 | `update(table, key, updates)` | Update item fields |
 | `delete(table, key)` | Delete item |
 
-## **6. Requirements**
+## **7. Requirements**
 
 * Node.js >= 18.0.0
 * TypeScript >= 5.3.0
 
-## **7. License**
+## **8. License**
 
 MIT