@jcbuisson/express-x-plugins 5.0.4 → 5.0.7

package/README.md

@@ -1,24 +1,6 @@
 
 # express-x-plugins
 
-
-IMPORTANT FOR ELECTRIC
-
-# set lc_messages=C for the PostgreSQL role so Electric receives recognizable English errors
-ALTER ROLE chris SET lc_messages = 'C';
-
-# ALLOW POSTGRES LOGICAL REPLICATION
-ALTER SYSTEM SET wal_level = 'logical';
-ALTER SYSTEM SET max_replication_slots = 10;
-ALTER SYSTEM SET max_wal_senders = 10;
-ALTER ROLE chris WITH REPLICATION;
-
-(restart postgres)
-
-## Use HTTP2
-nginx: `listen 443 ssl http2;`
-
-
 Currently includes:
 
 - a plugin which preserves room membership and socket data across page reloads
@@ -33,19 +15,39 @@ npm install @jcbuisson/express-x-plugins
 ```
 
 
-## Reload plugin
+## Electric plugin: local-first Postgres
 
-### Server
+Express-X handles authorized PostgreSQL mutations; Electric streams committed rows to clients.
 
-```js
-import { reloadPlugin } from '@jcbuisson/express-x-plugins/reload-server'
+The electric plugin has two separate elections:
+
+- PGlite leader: owns the local database engine. IndexedDB shares the stored data, but it doesn’t share the running PostgreSQL engine.
+Each PGlite instance has its own in-memory state: caches, transaction state, and buffers.
+- Sync owner: chosen by a separate Web Lock per model; runs the Electric stream and sends queued mutations to the server.
+
+They prevent duplicate database engines and duplicate synchronization across tabs. The database leader and sync owner can be different tabs.
+
+
+### Settings
+```bash
+# set lc_messages=C for the PostgreSQL role so Electric receives recognizable English errors
+ALTER ROLE chris SET lc_messages = 'C';
+
+# ALLOW POSTGRES LOGICAL REPLICATION
+ALTER SYSTEM SET wal_level = 'logical';
+ALTER SYSTEM SET max_replication_slots = 10;
+ALTER SYSTEM SET max_wal_senders = 10;
+ALTER ROLE chris WITH REPLICATION;
+
+(restart postgres)
 ```
 
+(?
+## Use HTTP2
+nginx: `listen 443 ssl http2;`
+)
 
-## Local-first Postgres plugin
 
-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
 
@@ -148,11 +150,12 @@ app.configure(electricClientPlugin, {
   shapePath: '/electric/v1/shape',
 })
 
-// Client-generated UUID stored in the default `id` primary key:
+// Client-generated UUID stored in the default `uid` primary key:
 const todo = app.createElectricModel('todos')
 
 // Or, for a database-generated primary key such as SERIAL/IDENTITY:
 const numberedTodo = app.createElectricModel('numberedTodos', {
+  primaryKey: 'id',
   idGeneration: 'server',
 })
 
@@ -190,7 +193,7 @@ app.configure(electricClientPlugin, {
   onError: (error, { modelName }) => console.error(modelName, error),
 })
 
-const ranges = app.createElectricModel('range', { primaryKey: 'uid' })
+const ranges = app.createElectricModel('range')
 const subscription = ranges.getObservable().subscribe(rows => console.log(rows))
 await ranges.create({ label: 'Works offline' })
 await ranges.update(uid, { label: 'Edited offline' })
@@ -343,3 +346,32 @@ volumes:
 docker compose pull electric
 docker compose up electric
 ```
+
+
+
+## Reload plugin
+
+### Server
+
+```js
+import { reloadPlugin } from '@jcbuisson/express-x-plugins/reload-server'
+```
+
+
+Managed sync automatically pauses network ownership when `navigator.onLine` is
+false and resumes active models on the browser's `online` event. Local reads,
+writes, queued edits, and cross-tab notifications remain available while offline.
+A model explicitly stopped with `model.stop()` stays stopped after reconnection.
+Disposing a model removes its network listeners. Browser connectivity is a hint;
+requests can still fail while reported online and retain the usual retry behavior.
+For custom runtimes/tests, plugin options `network` and `networkEvents` can supply
+the connectivity state and an EventTarget respectively.
+
+
+Models default to `primaryKey: 'uid'` on both client and server. Set
+`primaryKey: 'id'` explicitly for tables that use `id`.
+
+With `sync: true`, the sync owner's Electric stream stays active when its tab is
+hidden because it serves other tabs too. To customize this behavior, pass
+`streamOptions.runtimeVisibility` to `createElectricModel`. Other stream options
+are preserved. Independent streams retain Electric's normal visibility behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x-plugins",
-  "version": "5.0.4",
+  "version": "5.0.7",
   "description": "Plugins for express-x",
   "type": "module",
   "main": "./src/electric-server-plugin.mjs",

package/src/electric-client-plugin.mjs

@@ -9,7 +9,7 @@ import { createManagedSync } from './electric-managed-sync.mjs'
  *
  * Usage:
  *   electricClientPlugin(app)
- *   const todoModel = app.createElectricModel('todos') // primary key is automatically provided by server (auto-increment)
+ *   const todoModel = app.createElectricModel('todos') // client-generated UUID in the default uid primary key
  *   const todoMilk = await todoModel.create({ label: "Buy milk" })
  *   todoMilk.update({ completed: true })
  *   todoModel.getObservable({ completed: false }).subscribe(...) // subscribe to an observable for todos with completed===false
@@ -26,7 +26,7 @@ export function electricClientPlugin(app, options = {}) {
 
    function createElectricModel(modelName, modelOptions = {}) {
       quoteIdentifier(modelName)
-      quoteIdentifier(modelOptions.primaryKey ?? 'id')
+      quoteIdentifier(modelOptions.primaryKey ?? 'uid')
       if (managed) {
          if (modelOptions.idGeneration === 'server') throw new TypeError('sync models require client-generated UUIDs')
          return managed.model(modelName, modelOptions)
@@ -39,7 +39,7 @@ export function electricClientPlugin(app, options = {}) {
       const url = modelOptions.url ?? modelPath(shapePath, modelName)
       if (modelOptions.localDb) return createOfflineElectricModel({
          db: modelOptions.localDb, service, modelName, url,
-         primaryKey: modelOptions.primaryKey ?? 'id',
+         primaryKey: modelOptions.primaryKey ?? 'uid',
          ShapeStreamClass, ShapeClass,
          ownsSync: modelOptions.ownsSync ?? true,
          channel: modelOptions.channel,
@@ -50,7 +50,7 @@ export function electricClientPlugin(app, options = {}) {
       })
       const streamOptions = modelOptions.streamOptions ?? {}
       const idGeneration = modelOptions.idGeneration ?? 'client'
-      const primaryKey = modelOptions.primaryKey ?? 'id'
+      const primaryKey = modelOptions.primaryKey ?? 'uid'
       quoteIdentifier(primaryKey)
       if (!['client', 'server'].includes(idGeneration)) {
          throw new TypeError("idGeneration must be 'client' or 'server'")

package/src/electric-managed-sync.mjs

@@ -47,7 +47,7 @@ export function createManagedSync(options, createModel) {
       if (closed) throw new Error('Electric sync has been disposed')
       const existing = models.get(name)
       if (existing) {
-         if (existing.primaryKey !== (modelOptions.primaryKey ?? 'id')) throw new TypeError('A cached sync model cannot change primaryKey')
+         if (existing.primaryKey !== (modelOptions.primaryKey ?? 'uid')) throw new TypeError('A cached sync model cannot change primaryKey')
          return existing.api
       }
       let active = true
@@ -58,13 +58,23 @@ export function createManagedSync(options, createModel) {
       let channel
       let offline
       let error = null
+      const network = modelOptions.network ?? options.network ?? globalThis.navigator
+      const networkEvents = options.networkEvents ?? globalThis
       function report(cause) {
          error = cause
          try { (modelOptions.onError ?? options.onError)?.(cause, { modelName: name }) } catch (callbackError) { console.error(callbackError) }
       }
       const ready = getDatabase().then(async db => {
          channel = new Channel(`express-x:${databaseName}:${name}`)
-         offline = createModel(name, { ...modelOptions, localDb: db, channel, ownsSync: false, onError: report })
+         // The sync owner serves every tab, even while its own tab is hidden.
+         const streamOptions = {
+            ...modelOptions.streamOptions,
+            runtimeVisibility: modelOptions.streamOptions?.runtimeVisibility ?? {
+               getCurrentState: () => 'visible',
+               subscribe: () => () => {},
+            },
+         }
+         offline = createModel(name, { ...modelOptions, streamOptions, network, localDb: db, channel, ownsSync: false, onError: report })
          const prepared = preparation.then(() => offline.prepare())
          preparation = prepared.catch(() => {})
          await prepared
@@ -78,10 +88,11 @@ export function createManagedSync(options, createModel) {
       function startOwnership() {
          if (controller || disposed || !active) return
          offline.start()
+         if (network?.onLine === false) return
          controller = new AbortController()
          const ownerGeneration = ++generation
          void locks.request(`express-x:${databaseName}:${name}`, { signal: controller.signal }, async () => {
-            if (!active || disposed || generation !== ownerGeneration) return
+            if (!active || disposed || network?.onLine === false || generation !== ownerGeneration) return
             try {
                offline.setSyncOwner(true)
                await new Promise(resolve => { release = resolve })
@@ -91,16 +102,26 @@ export function createManagedSync(options, createModel) {
             }
          }).catch(cause => { if (cause.name !== 'AbortError') report(cause) })
       }
-      function stop() {
-         active = false
+      function releaseOwnership() {
          ++generation
          controller?.abort()
          controller = undefined
          release?.()
          release = undefined
          offline?.setSyncOwner(false)
+      }
+      function stop() {
+         active = false
+         releaseOwnership()
          offline?.stop()
       }
+      function updateNetwork() {
+         if (disposed) return
+         if (network?.onLine === false) releaseOwnership()
+         else if (active) void ready.then(startOwnership).catch(report)
+      }
+      networkEvents.addEventListener?.('offline', updateNetwork)
+      networkEvents.addEventListener?.('online', updateNetwork)
       function start() {
          if (disposed) throw new Error('Electric model has been disposed')
          active = true
@@ -115,6 +136,8 @@ export function createManagedSync(options, createModel) {
          async dispose() {
             if (disposed) return
             disposed = true
+            networkEvents.removeEventListener?.('offline', updateNetwork)
+            networkEvents.removeEventListener?.('online', updateNetwork)
             stop()
             try { await ready; await offline.waitForIdle() } finally { channel?.close(); models.delete(name) }
          },
@@ -138,7 +161,7 @@ export function createManagedSync(options, createModel) {
          flushQueue: () => invoke('flushQueue'),
          getStatus: async () => ({ ...await invoke('getStatus'), error: error?.message ?? null }),
       }
-      models.set(name, { api, primaryKey: modelOptions.primaryKey ?? 'id' })
+      models.set(name, { api, primaryKey: modelOptions.primaryKey ?? 'uid' })
       return api
    }
    async function dispose() {

package/src/electric-offline-model.mjs

@@ -284,6 +284,9 @@ export function createOfflineElectricModel({ db, service, modelName, url, primar
       if (!started) return
       started = false
       ++streamGeneration
+      // Drain previously queued snapshots, then invalidate this stream's view
+      // before a later flush can reconcile against another owner's shared rows.
+      background(resetSnapshot())
       clearInterval(timer)
       stream?.unsubscribeAll()
       channel?.removeEventListener('message', sharedChange)

package/src/electric-server-plugin.mjs

@@ -152,7 +152,8 @@ export function electricServerPlugin(app, db, models, options = {}) {
    return { shapePath, sync, models: configuredModels.map(({ name, table, primaryKey }) => ({ name, table, primaryKey })) }
 }
 
-/** Run once before accepting sync mutations. Existing rows receive a version. */
+// Run once before accepting sync mutations: adds columns 'version' and 'deleted' to each table
+// 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')
@@ -185,8 +186,12 @@ async function syncMutation(db, model, action, id, data, mutation) {
          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
+      // A committed create may have lost its response. Later local edits still
+      // arrive as create, but must update the row this client already wrote.
+      const editedCreate = action === 'create' && BigInt(cursor.revision) > 0n
+         && Object.entries(data).some(([column, value]) => column !== model.primaryKey && value !== undefined)
       let result
-      if (action === 'create') {
+      if (action === 'create' && !editedCreate) {
          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)
@@ -195,7 +200,7 @@ async function syncMutation(db, model, action, id, data, mutation) {
             ON CONFLICT (${model.quotedPrimaryKey}) DO UPDATE SET ${model.quotedPrimaryKey} = EXCLUDED.${model.quotedPrimaryKey}
             RETURNING *`, values)
          result = inserted.rows[0]
-      } else if (action === 'update') {
+      } else if (action === 'update' || editedCreate) {
          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])
@@ -248,7 +253,7 @@ function normalizeModels(models) {
       }
       const name = config.name
       const table = config.table ?? name
-      const primaryKey = config.primaryKey ?? 'id'
+      const primaryKey = config.primaryKey ?? 'uid'
       quoteIdentifier(name, 'model name')
       const tombstoneData = config.tombstoneData ?? {}
       if (typeof tombstoneData !== 'function') validateTombstoneData(tombstoneData, primaryKey)

package/test/electric-managed-sync.test.mjs

@@ -76,13 +76,26 @@ test('managed models initialize automatically, share one database, and cache mod
       assert.equal(dataDir, 'idb://test-db'); created++; return db
    } })
    try {
-      const users = app.createElectricModel('users', { primaryKey: 'uid' })
-      const ranges = app.createElectricModel('ranges', { primaryKey: 'uid' })
+      const users = app.createElectricModel('users')
+      const customVisibility = { getCurrentState: () => 'hidden', subscribe: () => () => {} }
+      const ranges = app.createElectricModel('ranges', { streamOptions: { runtimeVisibility: customVisibility, params: { test: 'preserved' } } })
       assert.equal(app.createElectricModel('users', { primaryKey: 'uid' }), users)
-      assert.throws(() => app.createElectricModel('users'), /primaryKey/)
+      assert.equal(app.createElectricModel('users'), users)
+      assert.throws(() => app.createElectricModel('users', { primaryKey: 'id' }), /primaryKey/)
       const row = await users.create({ name: 'Works before prepare' })
       await ranges.prepare()
       assert.equal(created, 1)
+      await until(() => Stream.instances.some(stream => stream.options.url.endsWith('/users')))
+      const visibility = Stream.instances.findLast(stream => stream.options.url.endsWith('/users')).options.runtimeVisibility
+      assert.equal(visibility.getCurrentState(), 'visible')
+      let notified = false
+      const cleanup = visibility.subscribe(() => { notified = true })
+      cleanup()
+      assert.equal(notified, false)
+      await until(() => Stream.instances.some(stream => stream.options.url.endsWith('/ranges')))
+      const rangeOptions = Stream.instances.findLast(stream => stream.options.url.endsWith('/ranges')).options
+      assert.equal(rangeOptions.runtimeVisibility, customVisibility)
+      assert.deepEqual(rangeOptions.params, { test: 'preserved' })
       assert.equal((await users.findUnique({ uid: row.uid })).name, row.name)
    } finally {
       await app.disposeElectricSync()
@@ -100,8 +113,8 @@ test('only one tab streams and flushes; follower edits broadcast and ownership t
    const before = Stream.instances.length
    let subscription
    try {
-      const owner = first.createElectricModel('todos')
-      const follower = second.createElectricModel('todos')
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
       await owner.prepare()
       await follower.prepare()
       await until(() => Stream.instances.length === before + 1)
@@ -137,8 +150,8 @@ test('stopping a waiting follower cancels takeover; restart can acquire ownershi
    const second = configure(db, locks)
    const before = Stream.instances.length
    try {
-      const owner = first.createElectricModel('todos')
-      const follower = second.createElectricModel('todos')
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
       await owner.prepare(); await follower.prepare()
       await until(() => Stream.instances.length === before + 1)
       follower.stop()
@@ -152,6 +165,56 @@ test('stopping a waiting follower cancels takeover; restart can acquire ownershi
    }
 })
 
+test('a returning sync owner preserves shared rows until its new snapshot arrives', async () => {
+   const db = new PGlite()
+   const locks = new Locks()
+   const calls = []
+   const service = {
+      async create(id, data) {
+         calls.push(id)
+         return { id, ...data, version: '3', deleted: false }
+      },
+   }
+   const first = configure(db, locks, service)
+   const second = configure(db, locks, service)
+   const before = Stream.instances.length
+   const original = { id: crypto.randomUUID(), title: 'original', version: '1', deleted: false }
+   const changed = { ...original, title: 'updated by next owner', version: '2' }
+   const added = { id: crypto.randomUUID(), title: 'added by next owner', version: '2', deleted: false }
+   try {
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
+      await owner.prepare(); await follower.prepare()
+      await until(() => Stream.instances.length === before + 1)
+      Stream.instances.at(-1).shape.emit({ rows: [original] })
+      await until(async () => (await owner.findMany()).length === 1)
+      owner.stop()
+      await until(() => Stream.instances.length === before + 2)
+      Stream.instances.at(-1).shape.emit({ rows: [changed, added] })
+      await until(async () => (await follower.findMany()).length === 2)
+
+      follower.stop()
+      await owner.start()
+      await until(() => Stream.instances.length === before + 3)
+      // Flush before the returning owner's stream delivers any snapshot.
+      const created = await owner.create({ title: 'created after restart' })
+      await until(async () => {
+         const { rows } = await db.query('SELECT acknowledged_version FROM electric_mutation_queue WHERE row_id = $1', [created.id])
+         return rows[0]?.acknowledged_version != null
+      })
+      assert.equal(calls.length, 1)
+      assert.deepEqual(await owner.findUnique({ id: original.id }), changed)
+      assert.deepEqual(await owner.findUnique({ id: added.id }), added)
+      assert.equal((await owner.getStatus()).pending, 1)
+
+      Stream.instances.at(-1).shape.emit({ rows: [changed, added, { ...created, version: '3', deleted: false }] })
+      await until(async () => (await owner.getStatus()).pending === 0)
+      assert.equal((await owner.findMany()).length, 3)
+   } finally {
+      await first.disposeElectricSync(); await second.disposeElectricSync(); await db.close()
+   }
+})
+
 test('initialization errors reject writes and observable reads and call onError', async () => {
    const error = new Error('Worker could not load assets')
    const reported = []
@@ -159,7 +222,7 @@ test('initialization errors reject writes and observable reads and call onError'
       createDatabase: async () => { throw error },
       onError: cause => reported.push(cause),
    })
-   const model = app.createElectricModel('todos')
+   const model = app.createElectricModel('todos', { primaryKey: 'id' })
    await assert.rejects(model.create({ title: 'No silent failure' }), /load assets/)
    await new Promise(resolve => model.getObservable().subscribe({ error: cause => {
       assert.equal(cause, error); resolve()
@@ -189,7 +252,7 @@ test('default worker errors and timeouts reject preparation instead of hanging',
          terminate() { terminated = true }
       }
       const app = configure(undefined, new Locks(), {}, { workerFactory: () => new Worker(), initTimeoutMs: 30 })
-      const model = app.createElectricModel('todos')
+      const model = app.createElectricModel('todos', { primaryKey: 'id' })
       await assert.rejects(model.prepare(), triggerError ? /module not found/ : /timed out/)
       assert.equal(terminated, true)
       await assert.rejects(app.disposeElectricSync())
@@ -216,7 +279,7 @@ test('snapshots and reads recover after a database leader changes', async () =>
    const app = configure(shared, new Locks())
    const before = Stream.instances.length
    try {
-      const model = app.createElectricModel('todos')
+      const model = app.createElectricModel('todos', { primaryKey: 'id' })
       await model.prepare()
       await until(() => Stream.instances.length === before + 1)
       failSnapshot = true
@@ -252,3 +315,62 @@ test('an indeterminate foreground mutation is not replayed automatically', async
       assert.equal((await model.getStatus()).pending, 1)
    } finally { await db.close() }
 })
+
+test('network lifecycle preserves offline edits, transfers ownership and respects manual stop', async () => {
+   const db = new PGlite()
+   const locks = new Locks()
+   const events = new EventTarget()
+   const network = { onLine: false }
+   const calls = []
+   const service = { async create(id, data) { calls.push(id); return { ...data, id, version: '1' } } }
+   const first = configure(db, locks, service, { network, networkEvents: events })
+   const second = configure(db, locks, service, { network, networkEvents: events })
+   const before = Stream.instances.length
+   let subscription
+   try {
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
+      await owner.prepare(); await follower.prepare()
+      let rows = []
+      subscription = follower.getObservable().subscribe(value => { rows = value })
+      const created = await owner.create({ title: 'Created offline' })
+      await until(() => rows.length === 1)
+      assert.equal(Stream.instances.length, before)
+      assert.equal(calls.length, 0)
+      assert.equal((await owner.getStatus()).pending, 1)
+
+      network.onLine = true
+      events.dispatchEvent(new Event('online'))
+      await until(() => Stream.instances.length === before + 1 && calls.length === 1)
+      const stream = Stream.instances.at(-1)
+      stream.shape.emit({ rows: [{ ...created, version: '1', deleted: false }] })
+      await until(async () => (await follower.getStatus()).pending === 0)
+
+      network.onLine = false
+      events.dispatchEvent(new Event('offline'))
+      await until(() => stream.stopped === true)
+      await follower.update(created.id, { title: 'Updated offline' })
+      assert.equal((await owner.findMany())[0].title, 'Updated offline')
+      assert.equal((await follower.getStatus()).pending, 1)
+      assert.equal(Stream.instances.length, before + 1)
+
+      owner.stop()
+      network.onLine = true
+      events.dispatchEvent(new Event('online'))
+      await until(() => Stream.instances.length === before + 2)
+      follower.stop()
+      await new Promise(resolve => setTimeout(resolve, 20))
+      assert.equal(Stream.instances.length, before + 2, 'manually stopped owner must not take over')
+      await owner.start()
+      await until(() => Stream.instances.length === before + 3)
+      await first.disposeElectricSync()
+      await second.disposeElectricSync()
+      events.dispatchEvent(new Event('offline'))
+      events.dispatchEvent(new Event('online'))
+      await new Promise(resolve => setTimeout(resolve, 10))
+      assert.equal(Stream.instances.length, before + 3)
+   } finally {
+      subscription?.unsubscribe()
+      await first.disposeElectricSync(); await second.disposeElectricSync(); await db.close()
+   }
+})

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

@@ -2,6 +2,7 @@ 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'
+import { electricServerPlugin, prepareElectricSyncSchema } from '../src/electric-server-plugin.mjs'
 
 class Stream {
    subscribe() { return () => {} }
@@ -15,6 +16,70 @@ class Shape {
    subscribe(callback) { this.emit = callback; return () => {} }
 }
 
+test('edits survive a committed create whose response was lost', async () => {
+   const server = new PGlite()
+   const db = new PGlite()
+   let model
+   try {
+      await server.exec('CREATE TABLE todos (id UUID PRIMARY KEY, title TEXT NOT NULL)')
+      await prepareElectricSyncSchema(server, [{ name: 'todos', primaryKey: 'id', tombstoneData: { title: '' } }])
+      let service
+      const pool = {
+         query: server.query.bind(server),
+         async connect() { return { query: server.query.bind(server), release() {} } },
+      }
+      electricServerPlugin({ createService(_name, methods) { service = methods }, get() {} }, pool,
+         [{ name: 'todos', primaryKey: 'id', tombstoneData: { title: '' } }], { sync: true })
+      let loseResponse = true
+      const requests = []
+      const proxy = {
+         async create(...args) {
+            requests.push(args)
+            const result = await service.create(...args)
+            if (loseResponse) { loseResponse = false; throw new Error('response lost') }
+            return result
+         },
+      }
+      const app = { service: () => proxy }
+      electricClientPlugin(app, { ShapeStream: Stream, Shape })
+      model = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, retryMs: 60_000 })
+      await model.prepare()
+      const row = await model.create({ title: 'original' })
+      await model.flushQueue()
+      const original = (await server.query('SELECT * FROM todos')).rows[0]
+      await model.update(row.id, { title: 'edited' })
+      await model.flushQueue()
+      const edited = (await server.query('SELECT * FROM todos')).rows[0]
+      assert.equal(edited.title, 'edited')
+      assert.ok(BigInt(edited.version) > BigInt(original.version))
+
+      // Replaying either revision must preserve the edited row and its version.
+      await service.create(...requests[0])
+      await service.create(...requests[1])
+      assert.deepEqual((await server.query('SELECT * FROM todos')).rows, [edited])
+      model.start()
+      Shape.current.emit({ rows: [edited] })
+      await model.waitForIdle()
+      assert.equal((await model.findUnique({ id: row.id })).title, 'edited')
+      assert.equal((await model.getStatus()).pending, 0)
+
+      // Another client's colliding create still cannot overwrite the row.
+      await service.create(row.id, { title: 'collision' }, { clientId: crypto.randomUUID(), revision: '1' })
+      assert.deepEqual((await server.query('SELECT * FROM todos')).rows, [edited])
+
+      // A delayed edited create must not resurrect a tombstone.
+      const metadata = requests[1][2]
+      await service.delete(row.id, { ...metadata, revision: '100' })
+      const tombstone = await service.create(row.id, { title: 'delayed' }, { ...metadata, revision: '101' })
+      assert.equal(tombstone.deleted, true)
+   } finally {
+      model?.stop()
+      await model?.waitForIdle()
+      await db.close()
+      await server.close()
+   }
+})
+
 test('offline writes stay local until the acknowledged Electric version arrives', async () => {
    const db = new PGlite()
    const calls = []
@@ -30,7 +95,7 @@ test('offline writes stay local until the acknowledged Electric version arrives'
    }
    const app = { service: () => service }
    electricClientPlugin(app, { ShapeStream: Stream, Shape })
-   const model = app.createElectricModel('todos', { localDb: db, network: { onLine: false }, retryMs: 60_000 })
+   const model = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, network: { onLine: false }, retryMs: 60_000 })
    try {
       await model.prepare()
       const local = await model.create({ title: 'offline' })
@@ -40,7 +105,7 @@ test('offline writes stay local until the acknowledged Electric version arrives'
       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 })
+      const onlineModel = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, network: { onLine: true }, retryMs: 60_000 })
       await onlineModel.flushQueue()
       assert.equal(calls.length, 1)
       assert.equal(calls[0].metadata.revision, '1')

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

@@ -17,7 +17,7 @@ function fixture({ authorize = async () => true, fetch } = {}) {
       createService(name, methods) { services.set(name, methods) },
       get(path, handler) { routes.set(path, handler) },
    }
-   const registration = electricServerPlugin(app, db, ['todos'], { authorize, fetch: fetch ?? globalThis.fetch })
+   const registration = electricServerPlugin(app, db, [{ name: 'todos', primaryKey: 'id' }], { authorize, fetch: fetch ?? globalThis.fetch })
    return { app, db, services, routes, queries, registration }
 }
 
@@ -192,7 +192,7 @@ test('sync mode commits a versioned write and rejects replayed or stale revision
 
 test('sync schema prepares version and tombstone columns', async () => {
    const queries = []
-   await prepareElectricSyncSchema({ query: async sql => { queries.push(sql) } }, ['todos'])
+   await prepareElectricSyncSchema({ query: async sql => { queries.push(sql) } }, [{ name: 'todos', primaryKey: 'id' }])
    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/)
@@ -301,3 +301,10 @@ test('invalid tombstone factory results roll back before writing a tombstone', a
       assert.ok(!queries.some(sql => sql.includes('INSERT INTO "users"')))
    }
 })
+
+
+test('server models default to the uid primary key', () => {
+   const app = { createService() {}, get() {} }
+   const result = electricServerPlugin(app, { query() {} }, ['users'], { authorize: async () => true })
+   assert.equal(result.models[0].primaryKey, 'uid')
+})