Vue: useSyncStatus

useSyncStatus reports what the engine is doing: how many writes wait in the outbox, where the durable pull cursor stands, whether the device is online, and what the automatic sync loop is up to. It re-reads on every engine event and returns one action, syncNow, for a button.

Examples#

Basic#

<!-- src/components/SyncBar.vue -->
<script setup lang="ts">
import { useSyncStatus } from 'kizunasync/vue'

const { outboxDepth, isOnline, isSyncing, syncNow } = useSyncStatus()
</script>

<template>
  <p>
    {{ isOnline ? 'Online' : 'Offline' }}, {{ outboxDepth }} waiting.
    <button type="button" :disabled="isSyncing" @click="syncNow">Sync now</button>
  </p>
</template>

Show reconnecting state#

// src/components/SyncBanner.vue (script setup)
import { computed } from 'vue'
import { useSyncStatus } from 'kizunasync/vue'

const { isStalled, nextRetryAt, outboxDepth } = useSyncStatus()

const banner = computed(() => {
  if (isStalled.value) {
    return `Reconnecting. ${outboxDepth.value} writes are waiting.`
  }
  if (nextRetryAt.value !== null) {
    return `Retrying at ${new Date(nextRetryAt.value).toLocaleTimeString()}.`
  }
  return null
})

Parameters#

Returns#

IUseSyncStatusResult. Every state field is a ref, isStalled, nextRetryAt, needsReset, and softBlockReason are computed refs, and syncNow is a plain function.

Errors#

syncNow never rejects. It clears lastError, awaits sync(), and puts any failure in lastError, so a component reads the outcome from the ref. A failed snapshot read lands in lastError the same way and leaves the previous depth and checkpoint in place.

A composable that runs outside the provide scope and passes no { client } override throws from useKizunaSync instead.

MUTATION_REJECTED, BATCH_ABORTED, and DEAD_LETTER also reach lastError, worded by the shared verdict mapping: Write rejected, Batch aborted, and Sync gave up. The durable record of the same events is the journal that useRejections reads, and lastError holds only the most recent one.

Notes#

isSyncing and health answer different questions. The first tracks your own syncNow() call, the second tracks the loop that runs between your calls, which is what separates a queued retry from a blocked request from an offline device. A banner reads health; a button reads isSyncing.

isStalled and nextRetryAt are computed refs over health, so they track it without a second subscription. The second name differs from the snapshot's nextAttemptAt, which Sync health documents.

syncNow is not wrapped in a ref, so destructuring it is safe. The state fields are refs and lose their reactivity if you spread the result into a plain object; pass the result around whole, or keep the refs.

Sync goes quiet after sleep, background, or a token expiry diagnoses an outboxDepth that stays put while isOnline is true. A failure streak that starts after a long spell in the background often begins with an expired access token. The refresh timer runs throttled while the app sits in the background. Supabase sizes those lifetimes in Recommended values for access token expiration. Kizuna adds the foreground refresh before the next run. The retry therefore never carries an expired token.

onScopeDispose releases the engine, connectivity, and health subscriptions with the owning component, so a route change leaves no listener behind.

Related reference#

• useKizunaSync
• useRejections
• JavaScript: Sync health
• JavaScript: Outbox depth
• JavaScript: Subscribe to events
• React: useSyncStatus