Overview

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

In an offline-first application, the client keeps a local copy of the data. Changes are queued locally and synced when connectivity is available.

Offline-First App:
┌─────────────────────────────────────┐
│            Client                   │
│  ┌─────────────┐  ┌──────────────┐  │
│  │ Local State │  │ Mutation     │  │
│  │             │  │ Queue        │  │
│  └─────────────┘  └──────────────┘  │
│         │                │          │
│         │                │          │
└─────────│────────────────│──────────┘
          │   Background   │
          ▼    Sync        ▼
     ┌─────────┐
     │ Server  │
     └─────────┘

     If server is unreachable = App still works!

Benefits:

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

These provide fine-grained reactivity similar to SolidJS or Vue’s Composition API.

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

View Engine

Live (Realtime)

Sync (State)

What is Offline-First?

What the Sync Package Provides

Reactive Primitives

Synchronized State

The Sync Protocol

Reactive Primitives

Signal

Computed

Effect

Collections and Entities

Quick Example

Architecture

When to Use Sync

What’s Next?

​What is Offline-First?

​What the Sync Package Provides

​Reactive Primitives

​Synchronized State

​The Sync Protocol

​Reactive Primitives

​Signal

​Computed

​Effect

​Collections and Entities

​Quick Example

​Architecture

​When to Use Sync

​What’s Next?

What is Offline-First?

What the Sync Package Provides

Reactive Primitives

Synchronized State

The Sync Protocol

Reactive Primitives

Signal

Computed

Effect

Collections and Entities

Quick Example

Architecture

When to Use Sync

What’s Next?