ctrodb 1.4: Offline Sync for the Browser, Zero Dependencies

#typescript #database #opensource #react

ctrodb is a client-side database for TypeScript. Schema validation, MongoDB-like queries, full-text search, relations — all in about 8KB gzipped with zero runtime dependencies.

v1.4 is the biggest release yet. It adds offline sync.

npm install ctrodb

GitHub: github.com/ctrotech-tutor/ctrodb
Docs: ctrodb.vercel.app/docs

What's in v1.4

Sync engine with change tracking. Every create, update, and delete is recorded in a local change log and pushed to your server when connectivity returns.

import { Database, syncPlugin, HttpTransport } from "ctrodb"

const transport = new HttpTransport({
  url: "https://api.myapp.com/sync",
})

const db = new Database({
  name: "my-app",
  schema: { ... },
  plugins: [syncPlugin({ transport })],
})

await db.connect()

Three conflict strategies out of the box — last-write-wins, client-wins, server-wins — plus a custom resolver hook. Field-level merge isn't built in as a strategy but you can implement it in the custom resolver.

const db = new Database({
  name: "my-app",
  schema: { ... },
  plugins: [syncPlugin({
    transport,
    strategy: "custom",
    conflictResolver: (conflict) => {
      return { resolution: "merged", merged: { ...conflict.local, ...conflict.remote } }
    },
  })],
})

HTTP transport works with any backend. WebSocket transport for real-time push. Trigger sync manually, on interval, or let the auto-sync handle it.

await db.sync()

React hooks for sync status and queue inspection:

import { useSyncStatus, useSyncQueue } from "ctrodb/react"

function SyncIndicator() {
  const { isSyncing, pendingChanges } = useSyncStatus()
  if (isSyncing) return <span>Syncing...</span>
  if (pendingChanges > 0) return <span>{pendingChanges} pending</span>
  return <span>All changes saved</span>
}

Devtools component for debugging:

import { SyncDevPanel } from "ctrodb/react"

// Shows queue, event log, manual sync trigger
if (import.meta.env.DEV) <SyncDevPanel />

Devtools utilities — inspect, retry, compact, stats — all take the database instance:

import { inspectSyncQueue, retryFailedSync, getSyncStats, compactSyncQueue } from "ctrodb"

const queue = await inspectSyncQueue(db)
const stats = await getSyncStats(db)
await retryFailedSync(db)