Documentation Index
Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
Use this file to discover all available pages before exploring further.
The sync package provides a client-side runtime for building offline-first applications. It combines reactive state primitives (Signals, Computed values, Effects) with synchronized collections that stay in sync with a server.
What is Offline-First?
In a traditional web application, the server is the source of truth. When you’re offline, the app doesn’t work.
Traditional App:
┌─────────┐ Request ┌─────────┐
│ Client │ ────────────> │ Server │
│ │ <──────────── │ │
└─────────┘ Response └─────────┘
If server is unreachable = App broken
Offline-First App:
┌─────────────────────────────────────┐
│ Client │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ Local State │ │ Mutation │ │
│ │ │ │ Queue │ │
│ └─────────────┘ └──────────────┘ │
│ │ │ │
│ │ │ │
└─────────│────────────────│──────────┘
│ Background │
▼ Sync ▼
┌─────────┐
│ Server │
└─────────┘
If server is unreachable = App still works!
- App works without internet
- Instant UI updates (no loading spinners)
- Better user experience on slow connections
- Resilience to network failures
What the Sync Package Provides
Reactive Primitives
| Type | Description |
|---|
Signal[T] | A reactive value container |
Computed[T] | A derived value that updates automatically |
Effect | A side effect that runs when dependencies change |
Synchronized State
| Type | Description |
|---|
Client | Manages server sync, mutation queue, and connection state |
Collection[T] | A reactive set of entities that syncs with the server |
Entity[T] | A single synchronized record |
The Sync Protocol
The client and server communicate using a simple protocol:
┌────────────┐ ┌────────────┐
│ Client │ │ Server │
└────────────┘ └────────────┘
│ │
│──── Push(mutations) ─────────────>│
│ │
│<─── Pull(cursor) ─────────────────│
│ Returns changes since cursor │
│ │
│<─── Snapshot(scope) ──────────────│
│ Returns full state │
│ │
- Push: Client sends queued mutations to server
- Pull: Client requests changes since last sync point (cursor)
- Snapshot: Client requests full state (initial load or resync)
Reactive Primitives
Signal
A Signal holds a value and notifies subscribers when it changes:
import "github.com/go-mizu/mizu/view/sync"
// Create a signal with initial value
count := sync.NewSignal(0)
// Read the value
fmt.Println(count.Get()) // 0
// Update the value
count.Set(5)
fmt.Println(count.Get()) // 5
// Update with a function
count.Update(func(v int) int {
return v + 1
})
fmt.Println(count.Get()) // 6
Computed
A Computed value derives from other signals and updates automatically:
count := sync.NewSignal(10)
price := sync.NewSignal(5.0)
// Automatically tracks dependencies
total := sync.NewComputed(func() float64 {
return float64(count.Get()) * price.Get()
})
fmt.Println(total.Get()) // 50.0
count.Set(20)
fmt.Println(total.Get()) // 100.0 (auto-updated!)
Effect
An Effect runs a function whenever its dependencies change:
count := sync.NewSignal(0)
effect := sync.NewEffect(func() {
fmt.Printf("Count is now: %d\n", count.Get())
})
// Prints: "Count is now: 0"
count.Set(1)
// Prints: "Count is now: 1"
count.Set(2)
// Prints: "Count is now: 2"
// Stop the effect
effect.Stop()
Collections and Entities
Collections manage groups of entities that sync with a server:
// Define your data type
type Todo struct {
Title string `json:"title"`
Completed bool `json:"completed"`
}
// Create a client
client := sync.New(sync.Options{
BaseURL: "http://localhost:8080/_sync",
Scope: "user:123",
})
// Create a collection
todos := sync.NewCollection[Todo](client, "todo")
// Create an entity
todo := todos.Create("todo-1", Todo{
Title: "Buy groceries",
Completed: false,
})
// Read (reactive - tracks dependencies)
fmt.Println(todo.Get().Title)
// Update
todo.Set(Todo{
Title: "Buy groceries",
Completed: true,
})
// Delete
todo.Delete()
// Query the collection
all := todos.All() // All entities (reactive)
count := todos.Count() // Entity count (reactive)
found := todos.Find(func(t Todo) bool {
return !t.Completed
})
Quick Example
Here’s a complete example showing the sync system:
package main
import (
"context"
"fmt"
"time"
"github.com/go-mizu/mizu/view/sync"
)
type Todo struct {
Title string `json:"title"`
Completed bool `json:"completed"`
}
func main() {
// Create client
client := sync.New(sync.Options{
BaseURL: "http://localhost:8080/_sync",
Scope: "user:demo",
OnSync: func(cursor uint64) {
fmt.Printf("Synced to cursor %d\n", cursor)
},
OnOnline: func() {
fmt.Println("Connected!")
},
OnOffline: func() {
fmt.Println("Offline - changes will sync later")
},
})
// Start sync
ctx := context.Background()
client.Start(ctx)
defer client.Stop()
// Create a collection
todos := sync.NewCollection[Todo](client, "todo")
// Create a todo (works offline!)
todo := todos.Create("todo-1", Todo{
Title: "Learn sync",
})
// Create an effect to react to changes
sync.NewEffect(func() {
t := todo.Get()
status := "pending"
if t.Completed {
status = "done"
}
fmt.Printf("Todo: %s [%s]\n", t.Title, status)
})
// Update the todo
todo.Set(Todo{
Title: "Learn sync",
Completed: true,
})
// Wait a bit to see sync happen
time.Sleep(2 * time.Second)
}
Architecture
┌─────────────────────────────────────────────────────┐
│ Client │
│ │
│ ┌───────────────┐ ┌──────────────────────────┐ │
│ │ Reactive │ │ Sync Engine │ │
│ │ Layer │ │ │ │
│ │ │ │ ┌────────────────────┐ │ │
│ │ Signal[T] │ │ │ Mutation Queue │ │ │
│ │ Computed[T] │ │ │ (offline-safe) │ │ │
│ │ Effect │ │ └────────────────────┘ │ │
│ │ │ │ │ │
│ └───────────────┘ │ ┌────────────────────┐ │ │
│ │ │ │ Store │ │ │
│ ▼ │ │ (local state) │ │ │
│ ┌───────────────┐ │ └────────────────────┘ │ │
│ │ Collections │ │ │ │
│ │ │◄───┤ ┌────────────────────┐ │ │
│ │ Entity[T] │ │ │ Cursor │ │ │
│ │ │ │ │ (sync position) │ │ │
│ └───────────────┘ │ └────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────┘ │
│ │ │
└──────────────────────────────────│──────────────────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
Push/Pull Live Updates
(HTTP) (WebSocket)
│ │
└──────────────┬──────────────┘
│
▼
┌─────────────┐
│ Server │
└─────────────┘
When to Use Sync
Use sync when:
- Building offline-capable applications
- You need instant UI updates without loading states
- Multiple clients need to see synchronized data
- You want fine-grained reactivity in Go
Consider alternatives when:
- Building server-side only applications
- You don’t need offline support
- Simple request/response patterns are sufficient
What’s Next?
- Quick Start - Build your first synced app
- Client - Client configuration and lifecycle
- Reactive - Deep dive into Signal, Computed, Effect
- Collections - Working with synchronized data
- Integration - Combining sync with live for real-time updates