@jcbuisson/express-x-plugins 5.0.4 → 5.0.6

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
 
@@ -343,3 +345,23 @@ 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.

package/package.json

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

package/src/electric-managed-sync.mjs

@@ -58,13 +58,15 @@ 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 })
+         offline = createModel(name, { ...modelOptions, network, localDb: db, channel, ownsSync: false, onError: report })
          const prepared = preparation.then(() => offline.prepare())
          preparation = prepared.catch(() => {})
          await prepared
@@ -78,10 +80,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 +94,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 +128,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) }
          },

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])

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

@@ -152,6 +152,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')
+      const follower = second.createElectricModel('todos')
+      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 = []
@@ -252,3 +302,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')
+      const follower = second.createElectricModel('todos')
+      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', 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', 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', { 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 = []