Offline sync

Give the hook an onSync handler — typically the network write that was unavailable offline. It receives one queued payload at a time.

import { useOfflineSync } from '@zoharyandrianome/crosshooks';

function TodoComposer() {
  const sync = useOfflineSync<{ title: string }>({
    onSync: async (todo) => {
      await fetch('/api/todos', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(todo),
      });
    },
  });

  // Render your UI here.
}

Resolve from onSync to mark an item synced; throw (or reject) to keep it queued for a later retry.

Call enqueue whenever the user performs a write. If the device is online, a flush is scheduled automatically; if it is offline, the item waits in the persisted queue.

<button onClick={() => sync.enqueue({ title: 'Buy milk' })}>
  Add todo
</button>

enqueue returns the created item, including the id you can later pass to remove.

Read isOnline, pending, and isSyncing to keep your UI honest about unsynced work. All three are SSR-safe: the first render is optimistically online with an empty queue, then resolves after mount.

{!sync.isOnline && (
  <p>You are offline. {sync.pending.length} change(s) will sync when you reconnect.</p>
)}
{sync.isSyncing && <Spinner />}

A flush processes items in enqueue order. When onSync throws, the item stays queued with a bumped attempts count and the pass stops — so a failed write never lets a later one jump ahead of it. The failure is exposed on error and cleared once the queue fully drains.

{sync.error && (
  <button onClick={() => sync.flush()}>
    Retry ({sync.pending.length}) — {sync.error.message}
  </button>
)}

A flush retries the whole queue from the head. Auto-flush on reconnect is on by default; pass autoFlushOnReconnect: false to drive it yourself.

On web the queue is persisted to localStorage automatically, so it survives a reload or a closed tab. Set a storageKey to keep separate queues apart:

const sync = useOfflineSync({
  onSync,
  storageKey: 'todos:pending', // defaults to 'crosshooks:offline-sync'
});

Writes are best-effort — a full or unavailable store (private mode, quota) degrades to an in-memory queue rather than throwing.

React Native has no localStorage or navigator.onLine, and crosshooks stays dependency-free, so you inject both. Pass storage to persist across app launches and connectivity to react to the network. Omit them and the queue lives in memory with the device assumed online — the return shape is identical to web, so shared components work unchanged.

import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';
import type { ConnectivitySource } from '@zoharyandrianome/crosshooks';

const netInfo: ConnectivitySource = {
  getSnapshot: () => lastKnownOnline, // seed from a NetInfo.fetch() at startup
  subscribe: (onChange) =>
    NetInfo.addEventListener((state) => onChange(state.isConnected ?? false)),
};

const sync = useOfflineSync({
  onSync,
  storage: AsyncStorage,
  connectivity: netInfo,
});

storage only has to match a small getItem / setItem / removeItem shape (sync or async), which AsyncStorage already satisfies.