Deferred Persistence

Gluonic separates optimistic updates (in memory) from confirmed data (in storage). This is the secret to clean optimistic UI with simple rollback.

The Problem

Traditional optimistic updates require complex rollback:


// Traditional approach
const handleSave = async () => {
  // 1. Save to database optimistically
  await db.update('posts', '123', { title: 'New Title' })
  
  // 2. Update UI
  setPosts(...)
  
  // 3. Try server
  try {
    await fetch('/api/posts/123', { ... })
  } catch (error) {
    // 4. Rollback database ⚠️ Complex!
    await db.update('posts', '123', { title: oldTitle })
    
    // 5. Rollback UI
    setPosts(...)
    
    // 6. What if rollback fails? 💥
  }
}

Issues:

Database writes are slow
Rollback is complex and error-prone
What if rollback fails?
Storage might be inconsistent

The Gluonic Solution

Three separate data layers with clear responsibilities:


┌─────────────────────────────────────────┐
│  In-Memory Pool (Observable)            │
│  - Current state (optimistic + confirmed)│
│  - UI reads from here                   │
│  - Instant updates                      │
│  - Easy to rollback (just replace)      │
└─────────────────────────────────────────┘
         ↕ Synced via MobX
┌─────────────────────────────────────────┐
│  Transaction Queue (Persistent)         │
│  - Pending changes only                 │
│  - Survives app restart                 │
│  - Replayed on startup                  │
└─────────────────────────────────────────┘
         ↕ Confirmed changes flow down
┌─────────────────────────────────────────┐
│  Local Storage (Authoritative)          │
│  - Confirmed server data ONLY           │
│  - Never rolled back                    │
│  - Source of truth on restart           │
└─────────────────────────────────────────┘

How It Works

Write Path


// User saves a post
await store.save('post', '123', { title: 'New Title' })
 
// Step 1: Update pool (instant)
store.pool.upsert({
  t: 'post',
  id: '123',
  p: { ...existingData, title: 'New Title' }
})
// UI updates immediately ✓
 
// Step 2: Queue transaction (persistent)
storage.enqueueTx({
  id: 'tx-789',
  type: 'post',
  modelId: '123',
  patch: { title: 'New Title' },
  op: 'u',
  prev: { title: 'Old Title' }
})
// Survives app restart ✓
 
// Step 3: Send to server (background)
POST /sync/v1/tx { ... }
 
// Step 4a: If success
// - Persist to storage
storage.putRow({ t: 'post', id: '123', p: { title: 'New Title' } })
// - Dequeue transaction
storage.dequeueTx('tx-789')
// Pool already has the data ✓
 
// Step 4b: If error
// - Rollback pool (easy!)
store.pool.upsert({
  t: 'post',
  id: '123',
  p: { title: 'Old Title' }  // Just replace
})
// - Dequeue transaction
storage.dequeueTx('tx-789')
// Storage unchanged ✓

Read Path


// Component reads data
const post = useModel<Post>('post', '123')
console.log(post.title)
 
// Behind the scenes:
// 1. Proxy GET trap intercepts access
// 2. Reads from pool: store.pool.get('post', '123').p.title
// 3. MobX tracks this access
// 4. Returns current value (optimistic or confirmed)
 
// Pool might have: "New Title" (optimistic)
// Storage has: "Old Title" (confirmed)
// UI sees: "New Title" ✓

Why This Design?

1. Simple Rollback

Rollback is just a memory update:


// Rollback (easy)
store.pool.upsert({ t, id, p: previousData })
 
// vs Traditional rollback (hard)
await db.transaction(async (tx) => {
  await tx.update('posts', id, previousData)
  await tx.update('related_table', ...)
  // What if this fails mid-way? 💥
})

2. Clean State Separation

Each layer has one responsibility:

Pool: Current UI state (fast, volatile)
Queue: Pending operations (persistent, replay-able)
Storage: Confirmed data (authoritative, never rolled back)

3. Queue Replay Works Correctly

On app restart:


await store.init()
 
// 1. Restore lastSyncId from storage
lastSyncId = await storage.getLastSyncId()
 
// 2. Load authoritative data via bootstrap
rows = await fetchBootstrap()
storage.putRows(rows)  // Storage = confirmed
 
// 3. Replay queue to restore optimistic state
queue = await storage.listTx()
for (const tx of queue) {
  // Re-apply optimistic updates to pool
  store.pool.upsert({
    t: tx.type,
    id: tx.modelId,
    p: { ...poolData, ...tx.patch }
  })
}
// Pool = confirmed + optimistic ✓
 
// 4. User sees pending edits immediately ✓

Why this works: Storage has clean confirmed data. Queue correctly reconstructs optimistic layer on top.

Example Scenario

User Journey


// 1. User goes offline
// 2. User edits 3 posts
await store.save('post', '1', { title: 'Edit 1' })
await store.save('post', '2', { title: 'Edit 2' })
await store.save('post', '3', { title: 'Edit 3' })
 
// Pool state:
// - post:1 → title: "Edit 1" (optimistic)
// - post:2 → title: "Edit 2" (optimistic)
// - post:3 → title: "Edit 3" (optimistic)
 
// Storage state:
// - post:1 → title: "Original 1" (confirmed)
// - post:2 → title: "Original 2" (confirmed)
// - post:3 → title: "Original 3" (confirmed)
 
// Queue:
// - tx-1: update post:1
// - tx-2: update post:2
// - tx-3: update post:3
 
// 3. User closes app
 
// 4. User reopens app (still offline)
await store.init()
// Queue replays → Pool restored ✓
// User sees all 3 edits ✓
 
// 5. Network comes back
// Queue processes:
// - tx-1: Success → persisted, dequeued
// - tx-2: Conflict → rolled back, dequeued
// - tx-3: Success → persisted, dequeued
 
// Final state:
// Pool:    Edit 1 ✓, Original 2 (rolled back), Edit 3 ✓
// Storage: Edit 1 ✓, Original 2 ✓, Edit 3 ✓
// Queue:   (empty)

Data Flow Diagram


┌─────────────────────────────────────────────────────┐
│              USER ACTION                             │
│         store.save('post', '123', patch)            │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│  POOL UPDATE (Instant - In Memory)                  │
│  ✓ Apply patch to observable pool                   │
│  ✓ MobX triggers component re-render                │
│  ✓ UI shows new value immediately                   │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│  QUEUE TRANSACTION (Persistent)                     │
│  ✓ Write to SQLite transaction table                │
│  ✓ Survives app restart                             │
└──────────────────┬──────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│  SERVER SYNC (Background)                           │
│  → POST /tx with mutation                           │
│  ← Response (success or error)                      │
└──────────────────┬──────────────────────────────────┘
                   │
           ┌───────┴────────┐
           ▼                ▼
    ┌──────────┐    ┌──────────────┐
    │ SUCCESS  │    │ ERROR        │
    └────┬─────┘    └──────┬───────┘
         │                 │
         ▼                 ▼
┌────────────────┐  ┌─────────────────┐
│ PERSIST        │  │ ROLLBACK        │
│ storage.putRow │  │ pool.upsert     │
│ storage.dequeue│  │ storage.dequeue │
└────────────────┘  └─────────────────┘

Implementation Benefits

For Developers

✅ No manual optimistic UI code
✅ No complex rollback logic
✅ No state management boilerplate
✅ Automatic conflict handling

For Users

✅ Instant UI responsiveness
✅ Offline editing works
✅ Pending changes survive restarts
✅ Graceful error recovery

For System

✅ Storage is always consistent
✅ Queue replay is deterministic
✅ No partial writes to handle
✅ Clean separation of concerns

Comparison

Approach	Optimistic Storage	Rollback Complexity	Queue Replay
Traditional	✅ Yes	⚠️ High (rollback DB)	❌ Broken
Gluonic	❌ No	✅ Low (replace memory)	✅ Perfect

Next Steps

Optimistic Updates - How updates work
Reactive Models - How UI updates automatically
Architecture - Complete data flow