feat: SyncAgent #557
Open
feat: SyncAgent #557
+3,974
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This document outlines a comprehensive design for implementing bi-directional sync between Durable Objects (Agents) and React clients using dedicated hooks: - useDurableQuery for subscribing to database queries - useDurableMutation for executing mutations Key features: - Real-time synchronization across all connected clients - Hibernation-aware with automatic re-subscription - Query/mutation registry pattern on the server - Type-safe client hooks - SQL-based subscription persistence The design leverages existing Agent infrastructure (SQL, WebSocket, broadcasting) while adding a structured query/mutation layer similar to React Query/tRPC.
- Cursor-based pagination (recommended) with useDurableInfiniteQuery hook - Offset-based pagination for traditional page navigation - Complete implementation examples for both patterns - Real-time update strategies for paginated data - Subscription persistence details for multi-page scenarios - Marked pagination question as resolved in discussion section
- Create comprehensive TanStack Query integration guide - Update main design document to reference TanStack Query foundation - Simplify hook implementations by leveraging TanStack Query - Add benefits: caching, deduplication, optimistic updates, DevTools - Include setup instructions and QueryClientProvider configuration - Document migration path and advanced patterns Key improvements: - Built on battle-tested React Query infrastructure - Automatic request deduplication and caching - Rich DevTools for debugging - Optimistic updates with rollback support - Framework-agnostic core for future extensions
- Support both local SQLite (10GB limit) and D1 (shared database) - Use Drizzle ORM for type-safe database operations - Automatic userId filtering for shared databases (D1) - No filtering needed for local SQLite (already isolated per DO) - userId filter uses this.name from Durable Object - Complete schema definition and configuration examples - Storage limits table and migration recommendations - Dependencies: drizzle-orm, drizzle-kit Key features: - Flexible storage backend selection via environment variable - Type-safe queries with Drizzle's inferSelect/inferInsert - Automatic multi-tenancy support for D1 - Same query API regardless of backend
- Implements a classic TodoMVC-style todo list application - Demonstrates real-time state synchronization using Cloudflare Agents sync layer - Features: - Add, edit, complete, and delete todos - Filter by all, active, or completed todos - Clear all completed todos - Toggle all todos at once - Real-time state sync across multiple browser windows - Uses useAgent hook for seamless client-server state management - All state changes via setState() automatically broadcast to connected clients - Includes comprehensive README with usage instructions
- Add 15 tests covering all TodoAgent functionality - Test state management, todo operations, filters, and persistence - Add getState() method to TodoAgent for test access - Configure Vitest with proper Wrangler test setup - All tests passing successfully
- Add client.test.tsx with 5 comprehensive React test cases - Test state initialization and rendering - Test state updates via onStateUpdate callback - Test agent.call() for add, toggle, delete, and filter operations - Test client-side filtering logic - Add vitest.react.config.ts for browser-based testing with Playwright - All tests passing successfully
…mple Add Todo List example demonstrating sync layer
- Add new MessageType enums for query/mutation operations - Create QuerySubscriptionManager for subscription tracking - Add registerQuery and registerMutation methods to Agent class - Implement query execution and broadcasting with versioning - Add message handlers for subscribe/unsubscribe/mutation - Create React hooks: useDurableQuery, useDurableMutation, useDurableInfiniteQuery - Update todo-list example to use new query/mutation sync system - Add SQL tables for subscriptions, query updates, and mutations
…tion-sync Research: Bi-directional Sync with useDurableQuery and useDurableMutation Hooks
|
commit: |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
SyncAgentis a replica ofAgent(without the MCP client) that has bidirectional sync capabilities while using theuseAgenthook on the frontend to receive data and execute mutations.Example in
examples/todo-listdemonstrates isolation for user data usingthis.sqlpackages/syncor something