Network adapters

Network adapters provide online/offline signals to FFDB sync in runtimes where browser events are unavailable or insufficient.

Interface

type NetworkAdapter = {
  isOnline(): boolean | Promise<boolean>
  subscribe(listener: (online: boolean) => void): () => void
}

Where this is used

NetworkAdapter is part of OfflineConfig:

type OfflineConfig = {
  adapter: OfflineAdapter
  network?: NetworkAdapter
  syncOnReconnect?: boolean
  syncOnFocus?: boolean
  syncInterval?: number
  // ...other fields
}

If network is omitted, FFDB falls back to browser online/offline behavior where available.

End-to-end usage

import { createClient } from 'ffdb-client'
import type { Database } from './ffdb.types'

const netAdapter = {
  async isOnline() {
    return await checkConnectivity()
  },
  subscribe(listener: (online: boolean) => void) {
    const off = subscribeConnectivity((status) => listener(status.online))
    return () => off()
  },
}

const { sync } = await createClient<Database>({
  config: {
    apiUrl: import.meta.env.VITE_FFDB_API_URL,
  },
  offline: {
    adapter: offlineAdapter,
    network: netAdapter,
    syncOnReconnect: true,
  },
})

await sync?.run()

Runtime guidance

Name
Browser
Description
Usually no custom adapter needed.
Name
React Native / Expo
Description
Provide a NetInfo-backed adapter for reliable connectivity state.
Name
Node.js
Description
Provide a custom reachability probe if your process should pause sync while disconnected.
Name
Desktop / native shells
Description
Provide an adapter when runtime network signals differ from browser assumptions.

Practical guidance

Keep isOnline fast and stable to avoid flapping sync state.
Ensure subscribe always returns a cleanup function.
Combine adapter signals with sync.status in UI for user-visible network state.
Test reconnect behavior under real network interruptions.