pwa-sync

Offline-first data caching and mutation queue for PWAs, backed by Dexie (IndexedDB).

Install

pnpm add pwa-sync dexie

For React hooks, also install:

pnpm add dexie-react-hooks react

Usage

Define your database

Use a Dexie subclass for typed table properties:

// db.ts
import Dexie, { type Table } from 'dexie'
import type { SyncMeta, PendingSubmission } from 'pwa-sync'

interface Item {
  id: string
  name: string
}

class AppDB extends Dexie {
  items!: Table<Item, string>
  syncMeta!: Table<SyncMeta, string>
  queue!: Table<PendingSubmission<any>, string>

  constructor() {
    super('app-db')

    this.version(1).stores({
      items: 'id',
      syncMeta: 'endpoint',
      queue: '++id,createdAt',
    })
  }
}

export const db = new AppDB()

OfflineData

Caches a list of entities from a remote endpoint in IndexedDB. get() always tries the network first and replaces the cache on success. If the request fails at the network level (fetch throws — offline, captive portal, dead WiFi), it serves the cache, or rethrows if there is none. A non-ok HTTP response is always thrown and never masked by the cache.

import { OfflineData } from 'pwa-sync'
import { db } from './db'

const offlineData = new OfflineData(db.items, db.syncMeta, '/api/items')

const result = await offlineData.get()
// result.source → 'network' | 'cache'
// result.data   → Item[]
// result.lastUpdate → Date

const status = await offlineData.status()
// status.lastUpdate → Date | null

Pass timeoutMs to stop waiting on a slow network when a cache is available:

const offlineData = new OfflineData(db.items, db.syncMeta, '/api/items', { timeoutMs: 3000 })

If the response hasn't arrived within timeoutMs and a cache exists, get() resolves with the cache (source: 'cache'). The request is not aborted — it finishes in the background and updates the cache, so the next get() is fresh. With no cache, get() keeps waiting for the network. Without timeoutMs, get() always waits for the network.

OfflineSnapshot

Like OfflineData, but for an endpoint that returns a single blob (any JSON value) rather than a list of keyed entities. The whole response is stored as one row keyed by endpoint, so one table can hold snapshots for several endpoints. Same network-first, cache-fallback and timeoutMs behaviour.

// db.ts — add a table: snapshots!: Table<Snapshot<any>, string>  →  snapshots: 'endpoint'
import { OfflineSnapshot } from 'pwa-sync'

const settings = new OfflineSnapshot<Settings>(db.snapshots, db.syncMeta, '/api/settings', { timeoutMs: 3000 })

const result = await settings.get()
// result.data → Settings

OfflineQueue

A persistent mutation queue with automatic retries, exponential backoff, and online/offline awareness. Mutations are stored in IndexedDB and processed in FIFO order.

import { OfflineQueue } from 'pwa-sync'
import { db } from './db'

const queue = new OfflineQueue(db.queue, '/api/submit')

// Add a mutation — it will be sent immediately if online, or queued for later
await queue.add({ name: 'New item' })

// Manually retry a failed item
await queue.retry(itemId)

// Remove an item from the queue
await queue.remove(itemId)

Items retry up to 3 times (configurable) with exponential backoff (max 5 minutes). 5xx and network errors retry. 4xx errors (except 429) are treated as fatal and won't retry. 401/403 (auth) errors are a special case: the item is marked failed (not retried, since the same expired session would fail again) but is recoverable — call retry(id) after the user signs in. Subscribe with the onAuthError option to prompt a sign-in flow. The last HTTP status is stored on the item as lastStatus, and the response body as lastResponseBody (parsed JSON, or raw text). lastError uses the body's error/message string when present, falling back to the status text.

const queue = new OfflineQueue(db.queue, '/api/submit', {
  maxAttempts: 5,
  onAuthError: item => {
    // session expired while `item` was queued — prompt sign-in, then retry(item.id)
  }
})

React Hooks

import { useQueueLength, useQueueItems } from 'pwa-sync/react'

function PendingBadge() {
  const count = useQueueLength(queue)
  return <span>{count ?? 0} pending</span>
}

function PendingList() {
  const items = useQueueItems(queue)
  // items is a live-updating array of PendingSubmission<T>
}

API

OfflineData<T>

• constructor(table, metaTable, endpoint, options?) — Dexie tables for data and sync metadata, the fetch URL, and { timeoutMs? }
• get() — Fetches fresh data, falling back to the cache on network failure or timeout
• status() — Returns { lastUpdate: Date | null }
• clear() — Clears cached data and metadata

OfflineSnapshot<T>

• constructor(table, metaTable, endpoint, options?) — Dexie table of Snapshot<T> rows (keyed by endpoint), sync metadata table, the fetch URL, and { timeoutMs? }
• get() — Fetches the snapshot, falling back to the cache on network failure or timeout
• status() — Returns { lastUpdate: Date | null }
• clear() — Removes this endpoint's snapshot and metadata

OfflineQueue<T>

• constructor(queue, endpoint, options?) — Dexie table, POST endpoint, and either maxAttempts (number, default 3) or { maxAttempts?, onAuthError? }. onAuthError(item) fires when a submission fails with 401/403.
• add(payload) — Enqueue a mutation
• remove(id) — Remove an item by ID
• retry(id) — Reset a failed item for retry
• clear() — Clear the entire queue
• length() — Returns the number of queued items
• process() — Manually trigger queue processing

React (pwa-sync/react)

• useQueueLength(queue) — Live count of queued items
• useQueueItems(queue) — Live array of PendingSubmission<T>

License

MIT