@jcbuisson/express-x-plugins 4.1.1 → 5.0.0

package/README.md

@@ -44,8 +44,8 @@ import { reloadPlugin } from '@jcbuisson/express-x-plugins/reload-server'
 
 ## Local-first Postgres plugin
 
-The smallest useful ElectricSQL integration for Express-X. Express-X handles authorized PostgreSQL mutations;
-Electric's Shape API streams those changes to clients: Electric is the sync engine.
+Express-X handles authorized PostgreSQL mutations; Electric streams committed rows to clients.
+For durable offline writes, use sync mode with a shared PGlite database.
 
 ### Server
 
@@ -56,15 +56,15 @@ npm install pg
 ```js
 import { Pool } from 'pg'
 import { expressX } from '@jcbuisson/express-x/server'
-import { electricOfflinePlugin } from '@jcbuisson/express-x-plugins/electric-server'
+import { electricOfflinePlugin, prepareElectricSyncSchema } from '@jcbuisson/express-x-plugins/electric-server'
 
 const app = expressX()
 const db = new Pool({ connectionString: process.env.DATABASE_URL })
 
 app.configure(electricOfflinePlugin, db, [
-  'todos',
-  { name: 'projects', table: 'projects', primaryKey: 'uid' },
+  { name: 'todos', tombstoneData: { title: '' } },
 ], {
+  sync: true,
   electricUrl: process.env.ELECTRIC_URL, // ElectricSQL sync service, e.g. http://localhost:3000/v1/shape
   sourceId: process.env.ELECTRIC_SOURCE_ID,
   sourceSecret: process.env.ELECTRIC_SOURCE_SECRET,
@@ -73,9 +73,12 @@ app.configure(electricOfflinePlugin, db, [
     return Boolean(context.request?.user || context.socket?.data?.user)
   },
 })
+
+// Run this during startup, before serving sync mutations:
+await prepareElectricSyncSchema(db, [{ name: 'todos' }])
 ```
 
-This registers one Express-X service per model with the familiar API:
+This registers one Express-X service per model. In direct mode, it has the familiar API:
 
 - `findUnique(where)`
 - `findMany(where, queryOptions)`
@@ -88,7 +91,22 @@ The client model provides synchronized reads through `findMany(where)` and
 `getObservable(where)`. The service also exposes direct one-shot server reads
 when synchronization is not required.
 
-Mutation methods return the created, updated, or deleted row directly.
+In sync mode, create requires a client-generated UUID and every mutation requires
+`{ clientId, revision }` as its last argument. The returned row includes `version`.
+The server records the latest revision per client and row in the same transaction
+as the write. Retries replay the saved result; older requests cannot overwrite a
+newer edit from that client. Deletes write versioned tombstones instead of removing
+rows. Configure `tombstoneData` for required columns without defaults, such as a
+required title. Keep the cursor table and tombstones to protect delayed retries and
+offline clients. This does not resolve concurrent edits by different clients.
+
+Import `prepareElectricSyncSchema` alongside `electricOfflinePlugin`. It adds
+`version` and `deleted` columns and creates the shared version sequence and cursor
+table. The primary key must be UUID in sync mode. All writes to synced tables must
+advance `version`; hard deletes bypass tombstone confirmation.
+
+Without `sync: true`, the existing direct service methods remain available and
+return created, updated, or deleted rows directly.
 
 ### Client
 
@@ -98,6 +116,8 @@ Install the optional client dependencies in the browser application:
 npm install @electric-sql/client rxjs
 ```
 
+For a server configured without `sync: true`, the direct client API is:
+
 ```js
 import { electricClientPlugin } from '@jcbuisson/express-x-plugins/electric-client'
 
@@ -105,7 +125,7 @@ app.configure(electricClientPlugin, {
   shapePath: '/electric/v1/shape',
 })
 
-// Client-generated UUID stored in the default `uid` primary key:
+// Client-generated UUID stored in the default `id` primary key:
 const todo = app.createElectricModel('todos')
 
 // Or, for a database-generated primary key such as SERIAL/IDENTITY:
@@ -119,10 +139,10 @@ const subscription = todo.getObservable({ completed: false }).subscribe(rows =>
   console.log(rows)
 })
 
-// Mutations use the matching Express-X service and are reflected by Electric.
+// Direct mutations use the matching Express-X service and are reflected by Electric.
 await todo.create({ title: 'Learn Shapes', completed: false })
-await todo.update(uid, { completed: true })
-await todo.remove(uid)
+await todo.update(id, { completed: true })
+await todo.remove(id)
 
 const created = await numberedTodo.create({ title: 'Assigned by PostgreSQL' })
 console.log(created.id)
@@ -130,6 +150,32 @@ console.log(created.id)
 subscription.unsubscribe()
 ```
 
+For offline writes, install `@electric-sql/pglite`, pass a shared PGlite database
+as `localDb`, and use the sync
+server mode above. `PGliteWorker` with an IndexedDB data directory is recommended
+for multiple tabs. Only one worker should use `ownsSync: true`; use a shared
+`BroadcastChannel` so other tabs receive change notifications.
+
+```js
+const todo = app.createElectricModel('todos', {
+  localDb: db, // PGliteWorker with a persistent idb:// data directory
+  channel: new BroadcastChannel('todos-sync'),
+})
+await todo.prepare() // creates local rows, mutation queue, client ID, revision sequence
+todo.start()         // starts Electric and mutation retries
+await todo.create({ title: 'Works offline' })
+await todo.update(id, { title: 'Still offline' })
+await todo.remove(id)
+const rows = await todo.findMany()
+const status = await todo.getStatus() // pending, failed, online
+```
+
+Local edits and queue entries commit together. Successful service responses leave
+queue entries in place until Electric sends the acknowledged `version` or newer.
+Rows with `deleted = true` confirm deletes but stay hidden locally. Network errors
+remain queued for retry; permanent HTTP 4xx errors are marked failed. The local
+database, including its identity and revision sequence, must remain persistent.
+
 `findMany(where)` resolves with all matching rows from the first synchronized Shape emission.
 
 It unsubscribes after the first emission; if called within a Vue scope, it also
@@ -143,7 +189,7 @@ configured table, and Electric source credentials stay server-side.
 
 ### Model configuration
 
-Server models may be strings (table, service name, and default `uid` key) or objects:
+Server models may be strings (table, service name, and default `id` key) or objects:
 
 ```js
 { name: 'todo', table: 'todos', primaryKey: 'id' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x-plugins",
-  "version": "4.1.1",
+  "version": "5.0.0",
   "description": "Plugins for express-x",
   "type": "module",
   "main": "./src/electric-server-plugin.mjs",
@@ -35,6 +35,7 @@
   },
   "peerDependencies": {
     "@electric-sql/client": "^1.5.24",
+    "@electric-sql/pglite": "^0.5.8",
     "rxjs": "^7.8.2",
     "vue": "^3.5.0"
   },
@@ -42,6 +43,9 @@
     "@electric-sql/client": {
       "optional": true
     },
+    "@electric-sql/pglite": {
+      "optional": true
+    },
     "rxjs": {
       "optional": true
     },
@@ -51,6 +55,7 @@
   },
   "devDependencies": {
     "@electric-sql/client": "^1.5.24",
+    "@electric-sql/pglite": "^0.5.8",
     "rxjs": "^7.8.2",
     "vue": "^3.5.0"
   }

package/src/electric-client-plugin.mjs

@@ -1,7 +1,7 @@
 import { Shape, ShapeStream } from '@electric-sql/client'
-import { Observable } from 'rxjs'
-// import { firstValueFrom, Subject, takeUntil } from 'rxjs'
-// import { getCurrentScope, onScopeDispose } from 'vue'
+import { Observable, firstValueFrom, Subject, takeUntil } from 'rxjs'
+import { getCurrentScope, onScopeDispose } from 'vue'
+import { createOfflineElectricModel } from './electric-offline-model.mjs'
 
 /**
  * Add Electric-backed reactive models to an Express-X client.
@@ -23,11 +23,22 @@ export function electricClientPlugin(app, options = {}) {
       quoteIdentifier(modelName)
       const service = app.service(modelName)
       const url = modelOptions.url ?? modelPath(shapePath, modelName)
+      if (modelOptions.localDb) return createOfflineElectricModel({
+         db: modelOptions.localDb, service, modelName, url,
+         primaryKey: modelOptions.primaryKey ?? 'id',
+         ShapeStreamClass, ShapeClass,
+         ownsSync: modelOptions.ownsSync ?? true,
+         channel: modelOptions.channel,
+         network: modelOptions.network ?? globalThis.navigator,
+         retryMs: modelOptions.retryMs ?? 5000,
+      })
       const streamOptions = modelOptions.streamOptions ?? {}
-      // const idGeneration = modelOptions.idGeneration ?? 'client'
-      // if (!['client', 'server'].includes(idGeneration)) {
-      //    throw new TypeError("idGeneration must be 'client' or 'server'")
-      // }
+      const idGeneration = modelOptions.idGeneration ?? 'client'
+      const primaryKey = modelOptions.primaryKey ?? 'id'
+      quoteIdentifier(primaryKey)
+      if (!['client', 'server'].includes(idGeneration)) {
+         throw new TypeError("idGeneration must be 'client' or 'server'")
+      }
 
       function getObservable(where = {}) {
          // Validate eagerly
@@ -53,35 +64,31 @@ export function electricClientPlugin(app, options = {}) {
          })
       }
 
-      // function findMany(where = {}) {
-      //    const observable = getObservable(where)
-      //    if (!getCurrentScope()) return firstValueFrom(observable)
-
-      //    const scopeDisposed = new Subject()
-      //    onScopeDispose(() => {
-      //       scopeDisposed.next()
-      //       scopeDisposed.complete()
-      //    })
-      //    return firstValueFrom(observable.pipe(takeUntil(scopeDisposed)))
-      // }
-
-      // async function create(data) {
-      //    assertPlainObject(data, 'mutation data')
-      //    if (idGeneration === 'server') return service.create(data)
-      //    const uid = globalThis.crypto?.randomUUID?.()
-      //    if (!uid) throw new Error('crypto.randomUUID() is required')
-      //    return service.create(uid, data)
-      // }
+      function findMany(where = {}) {
+         const observable = getObservable(where)
+         if (!getCurrentScope()) return firstValueFrom(observable)
+         const scopeDisposed = new Subject()
+         onScopeDispose(() => {
+            scopeDisposed.next()
+            scopeDisposed.complete()
+         })
+         return firstValueFrom(observable.pipe(takeUntil(scopeDisposed)))
+      }
+
+      async function findUnique(where) {
+         const rows = await findMany(where)
+         return rows[0] ?? null
+      }
 
       async function create(uidOrData, data) {
          const hasUid = data !== undefined
          const mutationData = hasUid ? data : uidOrData
          assertPlainObject(mutationData, 'mutation data')
-         if (hasUid) {
-            return service.create(uidOrData, data)
-         } else {
-            return service.create(data)
-         }
+         if (hasUid) return service.create(uidOrData, data)
+         if (idGeneration === 'server') return service.create(mutationData)
+         const uid = globalThis.crypto?.randomUUID?.()
+         if (!uid) throw new Error('crypto.randomUUID() is required')
+         return service.create(uid, data)
       }
 
       async function update(id, data) {
@@ -92,7 +99,7 @@ export function electricClientPlugin(app, options = {}) {
          return service.delete(id)
       }
 
-      return { getObservable, /*findMany,*/ create, update, remove }
+      return { getObservable, findMany, findUnique, create, update, remove }
    }
 
    return Object.assign(app, { createElectricModel })

package/src/electric-offline-model.mjs

@@ -0,0 +1,311 @@
+import { Observable } from 'rxjs'
+
+/** Offline model backed by a shared PGlite database (normally PGliteWorker). */
+export function createOfflineElectricModel({ db, service, modelName, url, primaryKey, ShapeStreamClass, ShapeClass, ownsSync, channel, network, retryMs }) {
+   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(primaryKey)) throw new TypeError('primaryKey must be a simple SQL identifier')
+   let snapshot = null
+   let operation = Promise.resolve()
+   let flushing = false
+   let started = false
+   let connected = false
+   let timer
+   let stream
+   const listeners = new Set()
+
+   async function prepare() {
+      await db.exec(`
+         CREATE SEQUENCE IF NOT EXISTS electric_mutation_revision_seq;
+         CREATE TABLE IF NOT EXISTS electric_sync_client (
+            singleton BOOLEAN PRIMARY KEY DEFAULT true CHECK (singleton),
+            id UUID NOT NULL DEFAULT gen_random_uuid()
+         );
+         INSERT INTO electric_sync_client (singleton) VALUES (true) ON CONFLICT DO NOTHING;
+         CREATE TABLE IF NOT EXISTS electric_local_rows (
+            model_name TEXT NOT NULL, row_id TEXT NOT NULL, data JSONB NOT NULL,
+            PRIMARY KEY (model_name, row_id)
+         );
+         CREATE TABLE IF NOT EXISTS electric_mutation_queue (
+            model_name TEXT NOT NULL, row_id TEXT NOT NULL,
+            action TEXT NOT NULL CHECK (action IN ('create', 'update', 'delete')),
+            data JSONB, revision BIGINT NOT NULL DEFAULT nextval('electric_mutation_revision_seq'),
+            acknowledged_version NUMERIC,
+            status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'failed')),
+            failure_reason TEXT,
+            PRIMARY KEY (model_name, row_id)
+         );
+      `)
+   }
+
+   function notify() {
+      channel?.postMessage({ modelName })
+      for (const listener of listeners) queueMicrotask(() => { try { listener() } catch (error) { console.error(error) } })
+   }
+
+   function subscribe(listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+   }
+
+   async function findMany(where = {}) {
+      const { rows } = await db.query('SELECT data FROM electric_local_rows WHERE model_name = $1 ORDER BY row_id', [modelName])
+      return rows.map(row => row.data).filter(row => matchesWhere(row, where))
+   }
+
+   async function findUnique(where) {
+      return (await findMany(where))[0] ?? null
+   }
+
+   function getObservable(where = {}) {
+      return new Observable(subscriber => {
+         let active = true
+         const emit = () => { void findMany(where).then(rows => { if (active) subscriber.next(rows) }, error => subscriber.error(error)) }
+         const unsubscribe = subscribe(emit)
+         emit()
+         return () => { active = false; unsubscribe() }
+      })
+   }
+
+   async function create(data) {
+      assertData(data)
+      if ('version' in data || 'deleted' in data) throw new TypeError('version and deleted are managed by sync')
+      const id = data[primaryKey] ?? globalThis.crypto?.randomUUID?.()
+      if (!id) throw new Error('crypto.randomUUID() is required')
+      assertId(id)
+      const row = { ...data, [primaryKey]: id }
+      await db.transaction(async tx => {
+         await tx.query('INSERT INTO electric_local_rows (model_name, row_id, data) VALUES ($1, $2, $3::jsonb)', [modelName, String(id), JSON.stringify(row)])
+         await queueMutation(tx, id, 'create', row)
+      })
+      notify()
+      if (started) void flushQueue()
+      return row
+   }
+
+   async function update(id, data) {
+      assertId(id)
+      assertData(data)
+      if (primaryKey in data || 'version' in data || 'deleted' in data) throw new TypeError('sync-managed columns cannot be updated')
+      let row
+      await db.transaction(async tx => {
+         const current = await tx.query('SELECT data FROM electric_local_rows WHERE model_name = $1 AND row_id = $2', [modelName, String(id)])
+         if (!current.rows[0]) throw new Error('row not found')
+         row = { ...current.rows[0].data, ...data }
+         await tx.query('UPDATE electric_local_rows SET data = $3::jsonb WHERE model_name = $1 AND row_id = $2', [modelName, String(id), JSON.stringify(row)])
+         const queued = await tx.query('SELECT action, acknowledged_version FROM electric_mutation_queue WHERE model_name = $1 AND row_id = $2', [modelName, String(id)])
+         if (queued.rows[0]?.action === 'delete') throw new Error('row has a pending delete')
+         const action = queued.rows[0]?.action === 'create' && queued.rows[0].acknowledged_version == null ? 'create' : 'update'
+         await queueMutation(tx, id, action, row)
+      })
+      notify()
+      if (started) void flushQueue()
+      return row
+   }
+
+   async function remove(id) {
+      assertId(id)
+      await db.transaction(async tx => {
+         await tx.query('DELETE FROM electric_local_rows WHERE model_name = $1 AND row_id = $2', [modelName, String(id)])
+         await queueMutation(tx, id, 'delete', null)
+      })
+      notify()
+      if (started) void flushQueue()
+   }
+
+   async function queueMutation(tx, id, action, data) {
+      await tx.query(`INSERT INTO electric_mutation_queue (model_name, row_id, action, data)
+         VALUES ($1, $2, $3, $4::jsonb)
+         ON CONFLICT (model_name, row_id) DO UPDATE SET
+            action = EXCLUDED.action, data = EXCLUDED.data,
+            revision = nextval('electric_mutation_revision_seq'),
+            acknowledged_version = NULL, status = 'pending', failure_reason = NULL`,
+      [modelName, String(id), action, data == null ? null : JSON.stringify(data)])
+   }
+
+   function ordered(task) {
+      const current = operation.then(task)
+      operation = current.catch(() => {})
+      return current
+   }
+
+   function applySnapshot(rows) {
+      return ordered(async () => {
+         snapshot = rows
+         await reconcileSnapshot(rows)
+      })
+   }
+
+   function reconcile() {
+      return ordered(async () => {
+         if (snapshot !== null) await reconcileSnapshot(snapshot)
+      })
+   }
+
+   function resetSnapshot() {
+      return ordered(() => { snapshot = null })
+   }
+
+   async function reconcileSnapshot(rows) {
+      await db.transaction(async tx => {
+         for (const row of rows) {
+            const id = String(row[primaryKey])
+            if (row.version != null) {
+               await tx.query(`DELETE FROM electric_mutation_queue
+                  WHERE model_name = $1 AND row_id = $2 AND acknowledged_version <= $3::numeric`,
+               [modelName, id, String(row.version)])
+            }
+            if (row.deleted) continue
+            await tx.query(`INSERT INTO electric_local_rows (model_name, row_id, data)
+               SELECT $1, $2, $3::jsonb WHERE NOT EXISTS
+                  (SELECT 1 FROM electric_mutation_queue WHERE model_name = $1 AND row_id = $2)
+               ON CONFLICT (model_name, row_id) DO UPDATE SET data = EXCLUDED.data`,
+            [modelName, id, JSON.stringify(row)])
+         }
+         const activeIds = rows.filter(row => !row.deleted).map(row => String(row[primaryKey]))
+         await tx.query(`DELETE FROM electric_local_rows AS local
+            WHERE local.model_name = $1 AND NOT (local.row_id = ANY($2::text[]))
+              AND NOT EXISTS (SELECT 1 FROM electric_mutation_queue AS pending
+                 WHERE pending.model_name = local.model_name AND pending.row_id = local.row_id)`,
+         [modelName, activeIds])
+      })
+      notify()
+   }
+
+   async function flushQueue() {
+      if (!ownsSync || flushing || network?.onLine === false) return
+      flushing = true
+      try {
+         while (true) {
+            const { rows } = await db.query(`SELECT * FROM electric_mutation_queue
+               WHERE model_name = $1 AND status = 'pending' AND acknowledged_version IS NULL
+               ORDER BY revision LIMIT 1`, [modelName])
+            const mutation = rows[0]
+            if (!mutation) break
+            try {
+               await sendMutation(mutation)
+            } catch (error) {
+               if (!isPermanent(error)) break
+               await db.query(`UPDATE electric_mutation_queue SET status = 'failed', failure_reason = $3
+                  WHERE model_name = $1 AND row_id = $2 AND revision = $4`,
+               [modelName, mutation.row_id, error.message, mutation.revision])
+               notify()
+            }
+         }
+      } finally {
+         flushing = false
+      }
+   }
+
+   async function sendMutation(mutation) {
+      const client = await db.query('SELECT id FROM electric_sync_client WHERE singleton = true')
+      const metadata = { clientId: client.rows[0].id, revision: String(mutation.revision) }
+      const { row_id: id, data, action } = mutation
+      const result = action === 'create'
+         ? await service.create(id, withoutKey(data), metadata)
+         : action === 'update'
+            ? await service.update(id, withoutKey(data), metadata)
+            : await service.delete(id, metadata)
+      if (result?.version == null) throw new Error('sync mutation did not return a version')
+      await db.transaction(async tx => {
+         const current = await tx.query('SELECT action, revision, data FROM electric_mutation_queue WHERE model_name = $1 AND row_id = $2', [modelName, id])
+         const queued = current.rows[0]
+         if (!queued) return
+         if (String(queued.revision) === String(mutation.revision) && queued.action === action) {
+            await tx.query(`UPDATE electric_mutation_queue SET acknowledged_version = $3::numeric
+               WHERE model_name = $1 AND row_id = $2`, [modelName, id, String(result.version)])
+         } else if (action === 'create' && queued.action === 'create') {
+            // The create was sent, then edited locally. Its next request is an update.
+            await tx.query(`UPDATE electric_mutation_queue SET action = 'update',
+               revision = nextval('electric_mutation_revision_seq') WHERE model_name = $1 AND row_id = $2`, [modelName, id])
+         }
+      })
+      await reconcile()
+      notify()
+   }
+
+   function withoutKey(data) {
+      const copy = { ...data }
+      delete copy[primaryKey]
+      delete copy.version
+      delete copy.deleted
+      return copy
+   }
+
+   function start() {
+      if (started) return
+      started = true
+      channel?.addEventListener('message', sharedChange)
+      globalThis.addEventListener?.('online', online)
+      if (!ownsSync) return
+      stream = new ShapeStreamClass({ url })
+      stream.subscribe(messages => {
+         if (messages.some(message => message.headers?.control === 'must-refetch')) void resetSnapshot()
+         connected = stream.isConnected?.() ?? true
+         notify()
+      }, () => { connected = false; notify() })
+      const shape = new ShapeClass(stream)
+      shape.subscribe(({ rows }) => { connected = true; void applySnapshot([...rows]) })
+      timer = setInterval(() => { void flushQueue() }, retryMs)
+      void flushQueue()
+   }
+
+   function stop() {
+      if (!started) return
+      started = false
+      clearInterval(timer)
+      stream?.unsubscribeAll()
+      channel?.removeEventListener('message', sharedChange)
+      globalThis.removeEventListener?.('online', online)
+      connected = false
+   }
+
+   function online() { void flushQueue() }
+   function sharedChange(event) {
+      if (event.data?.modelName !== modelName) return
+      for (const listener of listeners) queueMicrotask(() => { try { listener() } catch (error) { console.error(error) } })
+      if (ownsSync) void flushQueue()
+   }
+
+   async function getStatus() {
+      const { rows } = await db.query(`SELECT
+         count(*) FILTER (WHERE status = 'pending')::int AS pending,
+         count(*) FILTER (WHERE status = 'failed')::int AS failed
+         FROM electric_mutation_queue WHERE model_name = $1`, [modelName])
+      return { ...rows[0], online: network?.onLine !== false && connected }
+   }
+
+   return { prepare, start, stop, subscribe, findMany, findUnique, getObservable,
+      create, update, remove, flushQueue, getStatus }
+}
+
+function assertData(data) {
+   if (!data || typeof data !== 'object' || Array.isArray(data)) throw new TypeError('mutation data must be a plain object')
+}
+
+function assertId(id) {
+   if (typeof id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) {
+      throw new TypeError('sync id must be a UUID')
+   }
+}
+
+function matchesWhere(row, where) {
+   return Object.entries(where).every(([key, constraint]) => {
+      if (constraint === undefined) return true
+      const value = row[key]
+      if (constraint && typeof constraint === 'object' && !(constraint instanceof Date)) {
+         return Object.entries(constraint).every(([operator, limit]) => {
+            if (operator === 'gt') return value > limit
+            if (operator === 'gte') return value >= limit
+            if (operator === 'lt') return value < limit
+            if (operator === 'lte') return value <= limit
+            throw new TypeError(`unsupported where constraint for '${key}'`)
+         })
+      }
+      return value === constraint
+   })
+}
+
+function isPermanent(error) {
+   const status = error?.status ?? error?.response?.status
+   return error?.code === 'forbidden' || error instanceof TypeError ||
+      status >= 400 && status < 500 && ![408, 425, 429].includes(status)
+}

package/src/electric-server-plugin.mjs

@@ -12,6 +12,8 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
    //    throw new TypeError('electricOfflinePlugin requires an authorize(context, operation) policy')
    // }
    const configuredModels = normalizeModels(models)
+   const sync = options.sync === true
+   if (sync && typeof db.connect !== 'function') throw new TypeError('sync requires a pg Pool with connect()')
    const electricUrl = new URL(options.electricUrl ?? process.env.ELECTRIC_URL ?? 'http://localhost:3000/v1/shape')
    const shapePath = options.shapePath ?? '/electric/v1/shape/:model'
    const fetchImpl = options.fetch ?? globalThis.fetch
@@ -55,15 +57,21 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
          },
 
          // create(data): the primary key is server-generated
-         // create(uid, data): uid (the primary key) is provided by the client
-         create: async function(uidOrData, data) {
+         // create(id, data): id (the primary key) is provided by the client
+         create: async function(idOrData, data, mutation) {
             const hasClientId = data !== undefined
-            const mutationData = hasClientId ? data : uidOrData
-            await authorize(this, model.name, 'create', hasClientId ? [uidOrData, mutationData] : [mutationData])
+            const mutationData = hasClientId ? data : idOrData
+            await authorize(this, model.name, 'create', hasClientId
+               ? (sync ? [idOrData, mutationData, mutation] : [idOrData, mutationData])
+               : [mutationData])
             assertPlainObject(mutationData, 'mutation data')
             const safeData = hasClientId
-               ? { ...mutationData, [model.primaryKey]: uidOrData }
+               ? { ...mutationData, [model.primaryKey]: idOrData }
                : { ...mutationData }
+            if (sync) {
+               if (!hasClientId) throw new TypeError('sync mutations require a client-generated id')
+               return syncMutation(db, model, 'create', idOrData, safeData, mutation)
+            }
             const entries = Object.entries(safeData).filter(([, value]) => value !== undefined)
             const columns = entries.map(([column]) => quoteIdentifier(column, 'data column'))
             const values = entries.map(([, value]) => value)
@@ -91,8 +99,9 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
             })
          },
 
-         update: async function(id, data) {
-            await authorize(this, model.name, 'update', [id, data])
+         update: async function(id, data, mutation) {
+            await authorize(this, model.name, 'update', sync ? [id, data, mutation] : [id, data])
+            if (sync) return syncMutation(db, model, 'update', id, data, mutation)
             const set = buildSet(data, model.primaryKey)
             return withTransaction(db, async client => {
                const result = await client.query(
@@ -103,8 +112,9 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
             })
          },
 
-         delete: async function(id) {
-            await authorize(this, model.name, 'delete', [id])
+         delete: async function(id, mutation) {
+            await authorize(this, model.name, 'delete', sync ? [id, mutation] : [id])
+            if (sync) return syncMutation(db, model, 'delete', id, null, mutation)
             return withTransaction(db, async client => {
                const result = await client.query(
                   `DELETE FROM ${model.quotedTable} WHERE ${model.quotedPrimaryKey} = $1 RETURNING *`, [id],
@@ -139,11 +149,81 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
       }
    })
 
-   return { shapePath, models: configuredModels.map(({ name, table, primaryKey }) => ({ name, table, primaryKey })) }
+   return { shapePath, sync, models: configuredModels.map(({ name, table, primaryKey }) => ({ name, table, primaryKey })) }
+}
+
+/** Run once before accepting sync mutations. Existing rows receive a version. */
+export async function prepareElectricSyncSchema(db, models) {
+   const configuredModels = normalizeModels(models)
+   await db.query('CREATE SEQUENCE IF NOT EXISTS electric_sync_version_seq')
+   await db.query(`CREATE TABLE IF NOT EXISTS electric_mutation_cursor (
+      table_name TEXT NOT NULL, client_id UUID NOT NULL, row_id TEXT NOT NULL,
+      revision BIGINT NOT NULL DEFAULT 0, result JSONB,
+      PRIMARY KEY (table_name, client_id, row_id)
+   )`)
+   for (const model of configuredModels) {
+      await db.query(`ALTER TABLE ${model.quotedTable} ADD COLUMN IF NOT EXISTS version BIGINT NOT NULL DEFAULT nextval('electric_sync_version_seq')`)
+      await db.query(`ALTER TABLE ${model.quotedTable} ADD COLUMN IF NOT EXISTS deleted BOOLEAN NOT NULL DEFAULT false`)
+   }
+}
+
+async function syncMutation(db, model, action, id, data, mutation) {
+   if (!mutation || typeof mutation !== 'object') throw new TypeError('sync mutation metadata is required')
+   const { clientId, revision } = mutation
+   if (typeof clientId !== 'string' || !UUID.test(clientId)) throw new TypeError('clientId must be a UUID')
+   if (!/^[1-9][0-9]*$/.test(String(revision)) || BigInt(revision) > 9223372036854775807n) {
+      throw new TypeError('revision must be a positive bigint')
+   }
+   if (typeof id !== 'string' || !UUID.test(id)) throw new TypeError('sync id must be a UUID')
+   if (action !== 'delete') assertPlainObject(data, 'mutation data')
+   if (data && ('version' in data || 'deleted' in data)) throw new TypeError('version and deleted are managed by sync')
+   return withTransaction(db, async tx => {
+      const key = [model.table, clientId, String(id)]
+      await tx.query(`INSERT INTO electric_mutation_cursor (table_name, client_id, row_id)
+         VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`, key)
+      const { rows } = await tx.query(`SELECT revision, result FROM electric_mutation_cursor
+         WHERE table_name = $1 AND client_id = $2 AND row_id = $3 FOR UPDATE`, key)
+      const cursor = rows[0]
+      if (BigInt(revision) <= BigInt(cursor.revision)) return cursor.result
+      let result
+      if (action === 'create') {
+         const entries = Object.entries({ ...data, [model.primaryKey]: id }).filter(([, value]) => value !== undefined)
+         const columns = entries.map(([column]) => quoteIdentifier(column, 'data column'))
+         const values = entries.map(([, value]) => value)
+         const parameters = values.map((_, index) => `$${index + 1}`)
+         const inserted = await tx.query(`INSERT INTO ${model.quotedTable} (${columns.join(', ')}) VALUES (${parameters.join(', ')})
+            ON CONFLICT (${model.quotedPrimaryKey}) DO UPDATE SET ${model.quotedPrimaryKey} = EXCLUDED.${model.quotedPrimaryKey}
+            RETURNING *`, values)
+         result = inserted.rows[0]
+      } else if (action === 'update') {
+         const set = buildSet(data, model.primaryKey)
+         const updated = await tx.query(`UPDATE ${model.quotedTable} SET ${set.sql}, version = nextval('electric_sync_version_seq')
+            WHERE ${model.quotedPrimaryKey} = $${set.values.length + 1} AND NOT deleted RETURNING *`, [...set.values, id])
+         result = updated.rows[0] ?? await writeTombstone(tx, model, id)
+      } else {
+         result = await writeTombstone(tx, model, id)
+      }
+      await tx.query(`UPDATE electric_mutation_cursor SET revision = $4, result = $5::jsonb
+         WHERE table_name = $1 AND client_id = $2 AND row_id = $3`, [...key, String(revision), JSON.stringify(result ?? null)])
+      return result
+   })
+}
+
+async function writeTombstone(tx, model, id) {
+   const tombstone = Object.entries(model.tombstoneData)
+   const columns = [model.quotedPrimaryKey, ...tombstone.map(([column]) => quoteIdentifier(column, 'tombstone column')), 'deleted']
+   const values = [id, ...tombstone.map(([, value]) => value)]
+   const parameters = values.map((_, index) => `$${index + 1}`)
+   const clearFields = tombstone.map(([column]) => `${quoteIdentifier(column, 'tombstone column')} = EXCLUDED.${quoteIdentifier(column, 'tombstone column')}`)
+   const { rows } = await tx.query(`INSERT INTO ${model.quotedTable} (${columns.join(', ')}) VALUES (${parameters.join(', ')}, true)
+      ON CONFLICT (${model.quotedPrimaryKey}) DO UPDATE SET ${clearFields.length ? clearFields.join(', ') + ', ' : ''}deleted = true, version = nextval('electric_sync_version_seq')
+      RETURNING *`, values)
+   return rows[0]
 }
 
 
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
 const RANGE_OPERATORS = { gt: '>', gte: '>=', lt: '<', lte: '<=' }
 
 function quoteIdentifier(value, label) {
@@ -164,12 +244,19 @@ function normalizeModels(models) {
       }
       const name = config.name
       const table = config.table ?? name
-      const primaryKey = config.primaryKey ?? 'uid'
+      const primaryKey = config.primaryKey ?? 'id'
       quoteIdentifier(name, 'model name')
+      const tombstoneData = config.tombstoneData ?? {}
+      assertPlainObject(tombstoneData, 'tombstoneData')
+      for (const column of Object.keys(tombstoneData)) {
+         quoteIdentifier(column, 'tombstone column')
+         if ([primaryKey, 'version', 'deleted'].includes(column)) throw new TypeError('tombstoneData contains a sync-managed column')
+      }
       return {
          name,
          table,
          primaryKey,
+         tombstoneData,
          quotedTable: quoteIdentifier(table, `table for '${name}'`),
          quotedPrimaryKey: quoteIdentifier(primaryKey, `primary key for '${name}'`),
       }

package/test/electric-offline-model.test.mjs

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { PGlite } from '@electric-sql/pglite'
+import { electricClientPlugin } from '../src/electric-client-plugin.mjs'
+
+class Stream {
+   subscribe() { return () => {} }
+   isConnected() { return true }
+   unsubscribeAll() {}
+}
+
+class Shape {
+   static current
+   constructor() { Shape.current = this }
+   subscribe(callback) { this.emit = callback; return () => {} }
+}
+
+test('offline writes stay local until the acknowledged Electric version arrives', async () => {
+   const db = new PGlite()
+   const calls = []
+   const service = {
+      async create(id, data, metadata) {
+         calls.push({ id, data, metadata })
+         return { id, ...data, version: '42' }
+      },
+      async delete(id, metadata) {
+         calls.push({ id, metadata, action: 'delete' })
+         return { id, deleted: true, version: '43' }
+      },
+   }
+   const app = { service: () => service }
+   electricClientPlugin(app, { ShapeStream: Stream, Shape })
+   const model = app.createElectricModel('todos', { localDb: db, network: { onLine: false }, retryMs: 60_000 })
+   try {
+      await model.prepare()
+      const local = await model.create({ title: 'offline' })
+      assert.match(local.id, /^[0-9a-f-]{36}$/)
+      assert.equal((await model.findMany())[0].title, 'offline')
+      assert.equal((await model.getStatus()).pending, 1)
+      assert.equal(calls.length, 0)
+
+      // Simulate reconnect, then an old Shape snapshot followed by confirmation.
+      const onlineModel = app.createElectricModel('todos', { localDb: db, network: { onLine: true }, retryMs: 60_000 })
+      await onlineModel.flushQueue()
+      assert.equal(calls.length, 1)
+      assert.equal(calls[0].metadata.revision, '1')
+      assert.equal((await onlineModel.getStatus()).pending, 1)
+      onlineModel.start()
+      Shape.current.emit({ rows: [{ id: local.id, title: 'older', version: '41', deleted: false }] })
+      await new Promise(resolve => setTimeout(resolve, 10))
+      assert.equal((await onlineModel.findMany())[0].title, 'offline')
+      Shape.current.emit({ rows: [{ id: local.id, title: 'offline', version: '42', deleted: false }] })
+      await new Promise(resolve => setTimeout(resolve, 10))
+      assert.equal((await onlineModel.getStatus()).pending, 0)
+      await onlineModel.remove(local.id)
+      await onlineModel.flushQueue()
+      assert.equal((await onlineModel.findMany()).length, 0)
+      Shape.current.emit({ rows: [{ id: local.id, title: 'offline', version: '42', deleted: false }] })
+      await new Promise(resolve => setTimeout(resolve, 10))
+      assert.equal((await onlineModel.findMany()).length, 0)
+      Shape.current.emit({ rows: [{ id: local.id, title: '', version: '43', deleted: true }] })
+      await new Promise(resolve => setTimeout(resolve, 10))
+      assert.equal((await onlineModel.getStatus()).pending, 0)
+      onlineModel.stop()
+   } finally {
+      await db.close()
+   }
+})

package/test/electric-server-plugin.test.mjs

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
 
-import { electricOfflinePlugin } from '../src/electric-server-plugin.mjs'
+import { electricOfflinePlugin, prepareElectricSyncSchema } from '../src/electric-server-plugin.mjs'
 
 function fixture({ authorize = async () => true, fetch } = {}) {
    const services = new Map()
@@ -10,7 +10,7 @@ function fixture({ authorize = async () => true, fetch } = {}) {
    const db = {
       async query(sql, values = []) {
          queries.push({ sql, values })
-         return { rows: [{ uid: values.at(-1) ?? 'one', label: 'row' }] }
+         return { rows: [{ id: values.at(-1) ?? 'one', label: 'row' }] }
       },
    }
    const app = {
@@ -25,14 +25,18 @@ test('registers the mutation API', async () => {
    const { services, queries } = fixture()
    const service = services.get('todos')
    assert.deepEqual(Object.keys(service), [
-      'create', 'update', 'delete',
+      'findUnique', 'findMany', 'create', 'update', 'delete',
    ])
 
    const value = await service.create.call({}, 'one', { label: 'new' })
-   assert.equal(value.uid, 'one')
+   assert.equal(value.id, 'one')
 
    await service.create.call({}, 'only-id', {})
-   assert.match(queries[1].sql, /DO UPDATE SET "uid" = EXCLUDED\."uid"/)
+   assert.match(queries[1].sql, /DO UPDATE SET "id" = EXCLUDED\."id"/)
+   assert.equal(queries[1].values[0], 'only-id')
+   assert.deepEqual(fixture().registration.models, [
+      { name: 'todos', table: 'todos', primaryKey: 'id' },
+   ])
    await assert.rejects(service.create.call({}, 'bad', []), /plain object/)
 })
 
@@ -150,3 +154,72 @@ test('rejects unsafe SQL identifiers', () => {
       /simple SQL identifier/,
    )
 })
+
+test('sync mode commits a versioned write and rejects replayed or stale revisions', async () => {
+   const queries = []
+   let cursor = { revision: '0', result: null }
+   let inserts = 0
+   const client = {
+      async query(sql, values = []) {
+         queries.push({ sql, values })
+         if (sql.includes('SELECT revision, result FROM electric_mutation_cursor')) return { rows: [cursor] }
+         if (sql.includes('INSERT INTO "todos"')) {
+            inserts++
+            return { rows: [{ id: values.at(-1), version: '42', deleted: false }] }
+         }
+         if (sql.includes('UPDATE electric_mutation_cursor')) cursor = { revision: values[3], result: JSON.parse(values[4]) }
+         return { rows: [] }
+      },
+      release() {},
+   }
+   const db = { query: client.query.bind(client), async connect() { return client } }
+   const services = new Map()
+   electricOfflinePlugin({ createService(name, methods) { services.set(name, methods) }, get() {} }, db,
+      [{ name: 'todos', tombstoneData: { title: '' } }], { sync: true })
+   const service = services.get('todos')
+   const id = '64d76168-775f-481e-8974-18d31d835d9e'
+   const clientId = '5e199e1c-23a4-473e-9989-14d4a1fb857e'
+   const metadata = { clientId, revision: '2' }
+
+   const result = await service.create.call({}, id, { title: 'first' }, metadata)
+   assert.equal(result.version, '42')
+   assert.equal((await service.create.call({}, id, { title: 'first' }, metadata)).version, '42')
+   assert.equal((await service.create.call({}, id, { title: 'stale' }, { clientId, revision: '1' })).version, '42')
+   assert.equal(inserts, 1)
+   assert.equal(queries.filter(({ sql }) => sql === 'COMMIT').length, 3)
+   await assert.rejects(service.create.call({}, id, { title: 'bad' }), /metadata is required/)
+})
+
+test('sync schema prepares version and tombstone columns', async () => {
+   const queries = []
+   await prepareElectricSyncSchema({ query: async sql => { queries.push(sql) } }, ['todos'])
+   assert.equal(queries.length, 4)
+   assert.match(queries[2], /ADD COLUMN IF NOT EXISTS version BIGINT/)
+   assert.match(queries[3], /ADD COLUMN IF NOT EXISTS deleted BOOLEAN/)
+})
+
+test('sync delete writes a versioned tombstone and clears configured fields', async () => {
+   const queries = []
+   const id = '64d76168-775f-481e-8974-18d31d835d9e'
+   const client = {
+      async query(sql, values = []) {
+         queries.push({ sql, values })
+         if (sql.includes('SELECT revision, result FROM electric_mutation_cursor')) return { rows: [{ revision: '0', result: null }] }
+         if (sql.includes('INSERT INTO "todos"')) return { rows: [{ id, title: '', deleted: true, version: '7' }] }
+         return { rows: [] }
+      },
+      release() {},
+   }
+   const db = { query: client.query.bind(client), async connect() { return client } }
+   const services = new Map()
+   electricOfflinePlugin({ createService(name, methods) { services.set(name, methods) }, get() {} }, db,
+      [{ name: 'todos', tombstoneData: { title: '' } }], { sync: true })
+   const result = await services.get('todos').delete.call({}, id, {
+      clientId: '5e199e1c-23a4-473e-9989-14d4a1fb857e', revision: '1',
+   })
+   assert.equal(result.deleted, true)
+   const tombstone = queries.find(({ sql }) => sql.includes('INSERT INTO "todos"'))
+   assert.match(tombstone.sql, /"title" = EXCLUDED\."title"/)
+   assert.match(tombstone.sql, /version = nextval/)
+   assert.deepEqual(tombstone.values, [id, ''])
+})