std-sync

Offline queue and conflict resolution helpers

Package: std.sync Version: 0.1.0 Capabilities required: net.fetch

Overview

std-sync tracks local-vs-remote divergence and manages an offline edit queue inside framework apps. All conflict-resolution logic is pure; only sync_effect produces a network Effect. Use it to build apps that continue working offline and flush pending changes when connectivity is restored.

Installation

Add to your package.ax.json dependencies:

"std.sync": "0.1.0"

Your policy must grant net.fetch for sync_effect calls to succeed.

API Reference

Types

Effect

type Effect { kind: String, payload: String, callback_tag: String }

SyncState

type SyncState {
    online: Int,
    pending_count: Int,
    synced_count: Int,
    status: String,
    local_version: Int,
    remote_version: Int,
    conflicts: Int,
    resolved: Int
}

• online — 1 when connected, 0 when offline
• pending_count — number of local edits not yet synced
• synced_count — cumulative count of successfully synced operations
• status — one of "idle", "queued", "syncing", "synced", "offline", "conflict", "resolving"
• local_version / remote_version — monotonic counters; divergence indicates pending changes
• conflicts / resolved — total conflicts detected vs resolved

Functions

Initialization

sync_init() -> SyncState

Returns a fresh sync state: online, no pending edits, version 0.

State transitions

sync_queue_edit(state: SyncState) -> SyncState

Records one new local edit. Increments pending_count and local_version. Sets status to "syncing" if online, "queued" if offline.

sync_mark_synced(state: SyncState) -> SyncState

Acknowledges one successfully synced edit. Decrements pending_count and advances remote_version to match local_version. Status becomes "synced" when the queue is drained.

sync_go_offline(state: SyncState) -> SyncState

Marks the state as offline and sets status to "offline".

sync_go_online(state: SyncState) -> SyncState

Marks the state as online. Status becomes "syncing" if there are pending edits, "synced" otherwise.

sync_detect_conflict(state: SyncState) -> SyncState

Increments the conflict counter and sets status to "conflict". Call when the server rejects an edit due to a version mismatch.

sync_resolve_conflict(state: SyncState, strategy: String) -> SyncState

Increments resolved, bumps local_version, and sets status to "resolving". strategy is passed for audit purposes; conflict resolution logic is app-specific.

Predicates

sync_needs_push(state: SyncState) -> Int

Returns 1 if there are pending edits and the device is online — the signal to fire a sync effect.

sync_is_idle(state: SyncState) -> Int

Returns 1 if status is "idle" or "synced".

sync_has_conflicts(state: SyncState) -> Int

Returns 1 if any unresolved conflicts remain.

Effects

sync_effect(endpoint: String, callback_tag: String) -> Effect

Produces an HTTP request effect targeting endpoint. Return this from update when sync_needs_push is true.

Example

fn main() -> Int {
  let s0: SyncState = sync_init()
  let s1: SyncState = sync_queue_edit(s0)
  let s2: SyncState = sync_go_offline(s1)
  let s3: SyncState = sync_queue_edit(s2)
  let s4: SyncState = sync_go_online(s3)
  s4.pending_count
}

Capabilities

Requires net.fetch for sync_effect. All state-transition functions are pure and require no capability.

Notes / Limitations

• sync_resolve_conflict records a resolution but does not merge data. The calling app is responsible for choosing and applying the correct value before calling this function.
• sync_needs_push checks connectivity and pending count only; rate-limiting and retry backoff are not built in. Combine with std-http’s RetryConfig for production use.

Edit this page on GitHub