DeltaResult

Return type from delta sync (incremental updates since last sync).

Import


import type { DeltaResult } from '@gluonic/client'

Type Definition

Exact definition from implementation:


export type DeltaResult = {
  sid: number
  frames?: SyncFrame[]
  rows?: WireRow[]
} | (WireRow & { sid: number })

Two formats supported: Object format with frames/rows, or single row with sid (for single-item deltas).

Format 1: Object with Frames


type DeltaResult = {
  sid: number            // Latest sync ID
  frames?: SyncFrame[]   // Array of sync operations
  rows?: WireRow[]      // Alternative: complete rows
}

Fields

sid


sid: number

Description: Latest sync ID in this delta

Purpose: Client updates lastSyncId to this value after applying

Example: 1003, 5432

frames


frames?: SyncFrame[]

Description: Array of sync operations (preferred format)

Optional: Either frames or rows is present

Example:


[
  { sid: 1001, t: 'task', id: 'abc', op: 'u', p: { done: true } },
  { sid: 1002, t: 'task', id: 'def', op: 'i', p: { title: 'New' } },
  { sid: 1003, t: 'task', id: 'ghi', op: 'd' }
]

rows


rows?: WireRow[]

Description: Array of complete rows (alternative format)

Optional: Used instead of frames for simpler delta format

Example:


[
  { t: 'task', id: 'abc', v: 2, p: { title: 'Task', done: true } }
]

Format 2: Single Row


type DeltaResult = WireRow & { sid: number }

For single-item deltas (less common):


{
  sid: 1001,
  t: 'task',
  id: 'abc-123',
  v: 2,
  p: { title: 'Updated Task', done: true }
}

Complete Examples

With Frames (Preferred)


const deltaResult: DeltaResult = {
  sid: 1003,
  frames: [
    {
      sid: 1001,
      t: 'task',
      id: 'task-1',
      op: 'u',
      p: { done: true },
      at: 1699564800000
    },
    {
      sid: 1002,
      t: 'task',
      id: 'task-2',
      op: 'i',
      p: { title: 'New Task', done: false },
      at: 1699564850000
    },
    {
      sid: 1003,
      t: 'task',
      id: 'task-3',
      op: 'd',
      at: 1699564900000
    }
  ]
}

With Rows (Alternative)


const deltaResult: DeltaResult = {
  sid: 1002,
  rows: [
    {
      t: 'task',
      id: 'task-1',
      v: 2,
      p: { title: 'Task 1', done: true, updatedAt: 1699564800000 }
    },
    {
      t: 'task',
      id: 'task-2',
      v: 1,
      p: { title: 'Task 2', done: false, createdAt: 1699564850000 }
    }
  ]
}

Usage

In DownsyncAdapter


import type { DownsyncAdapter, DeltaResult } from '@gluonic/client'
 
const downsyncAdapter: DownsyncAdapter = {
  async fetchDelta(since, token, onUnauthenticated): Promise<DeltaResult> {
    const response = await fetch(
      `/sync/v1/delta?since=${since}`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    )
    
    if (response.status === 401) {
      await onUnauthenticated()
      throw new Error('Unauthenticated')
    }
    
    return await response.json()  // Returns DeltaResult
  },
  
  async fetchBootstrap(token, onUnauthenticated) {
    // ...
  }
}

In Store FastForward


async fastForward() {
  const delta: DeltaResult = await downsyncAdapter.fetchDelta(
    this.lastSyncId,
    token,
    onUnauthenticated
  )
  
  // Apply frames if present
  if ('frames' in delta && delta.frames) {
    await this.applyFrames(delta.frames)
  }
  // Or apply rows
  else if ('rows' in delta && delta.rows) {
    await this.applyMany(delta.rows, { persist: true })
  }
  
  // Update sync position
  const maxSid = 'frames' in delta ? delta.sid : delta.sid
  this.lastSyncId = maxSid
  await storage.setLastSyncId(maxSid)
}

Server Response Format

Server endpoint returns DeltaResult:


GET /sync/v1/delta?since=1000
Authorization: Bearer <token>
 
Response (with frames):
{
  "sid": 1003,
  "frames": [
    { "sid": 1001, "t": "task", "id": "1", "op": "u", "p": { "done": true } },
    { "sid": 1002, "t": "task", "id": "2", "op": "i", "p": { "title": "New" } },
    { "sid": 1003, "t": "task", "id": "3", "op": "d" }
  ]
}

Empty Delta

When no changes since last sync:


const delta: DeltaResult = {
  sid: 1000,  // Same as requested (no new changes)
  frames: []   // Empty array
}
 
// Or
{
  sid: 1000,
  rows: []
}