@jcbuisson/express-x 3.1.6 → 3.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x",
-  "version": "3.1.6",
+  "version": "3.1.11",
   "description": "",
   "type": "module",
   "main": "src/server.mjs",
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.4.5",
-    "@jcbuisson/express-x-client": "^3.1.6",
+    "@jcbuisson/express-x-client": "^3.1.11",
     "@jcbuisson/express-x-drizzle": "^3.1.6",
     "@vueuse/core": "^14.3.0",
     "dexie": "^4.4.2",

package/src/server.mjs

@@ -46,6 +46,17 @@ export class Mutex {
 
 //////////////////////////       SYNC ALGORITHM (common to all offline plugins)       //////////////////////////
 
+// This sync algorithm uses the metadata table as its only source of truth for existence and recency. Manual SQL changes
+// create a split reality — the data table and the metadata table diverge — and the algorithm's set-intersection logic
+// misidentifies the divergence as intentional client-side changes that must be propagated.
+// If you need to seed or manipulate data outside the framework, you must also write the corresponding rows into the
+// metadata table with valid created_at/updated_at/deleted_at values.
+
+// The metadata table is a tombstone log that grows monotonically. Every record ever created leaves a permanent entry. For
+// long-lived applications with high churn this is worth planning for: you can only safely purge a tombstone once you're certain no
+// client still holds a copy of that record (i.e., every client has synced at least once after the deletion). There's currently no
+// pruning mechanism in the framework.
+
 export function computeSyncResult(databaseValuesDict, clientMetadataDict, databaseMetadataDict) {
    const onlyDatabaseIds = new Set()
    const onlyClientIds = new Set()
@@ -79,11 +90,18 @@ export function computeSyncResult(databaseValuesDict, clientMetadataDict, databa
 
    for (const uid of databaseAndClientIds) {
       const clientMetaData = clientMetadataDict[uid]
+      const databaseMetaData = databaseMetadataDict[uid] || { uid, created_at: null }
       if (clientMetaData.deleted_at) {
-         deleteDatabase.push(uid)
-         deleteClient.push([uid, clientMetaData.deleted_at])
+         const clientDeletedAt = new Date(clientMetaData.deleted_at)
+         const databaseUpdatedAt = new Date(databaseMetaData.updated_at || databaseMetaData.created_at)
+         const diff = clientDeletedAt - databaseUpdatedAt
+         if (diff >= 0) {
+            deleteDatabase.push(uid)
+            deleteClient.push([uid, clientMetaData.deleted_at])
+         } else {
+            updateClient.push([databaseValuesDict[uid], databaseMetaData])
+         }
       } else {
-         const databaseMetaData = databaseMetadataDict[uid] || { uid, created_at: null }
          const clientUpdatedAt = new Date(clientMetaData.updated_at || clientMetaData.created_at)
          const databaseUpdatedAt = new Date(databaseMetaData.updated_at || databaseMetaData.created_at)
          const diff = clientUpdatedAt - databaseUpdatedAt

package/test/offline.test.mjs

@@ -308,6 +308,41 @@ describe('Full offline-first client ↔ server protocol', () => {
       }
    })
 
+   test('record in both, DB created_at newer → client metadata is fully replaced', async () => {
+      const modelName = `model${++dbCounter}`
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
+
+      // Server is newer by created_at only; updated_at is null.
+      await db.insert(modelTable).values({ uid: 's1', label: 'server-created-later' })
+      await db.insert(metaTable).values({ uid: 's1', created_at: T2 })
+
+      const { clientApp, cleanup } = await createTestContext(
+         serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
+         { useOfflinePlugin: true },
+      )
+
+      try {
+         const model = clientApp.createOfflineModel(modelName, ['label'])
+         await model.db.values.add({ uid: 's1', label: 'client-created-earlier' })
+         await model.db.metadata.add({ uid: 's1', created_at: T1 })
+         await model.addSynchroWhere({})
+
+         await model.synchronizeAll()
+
+         const s1 = await model.db.values.get('s1')
+         const meta = await model.db.metadata.get('s1')
+         assert.equal(s1.label, 'server-created-later')
+         assert.equal(new Date(meta.created_at).getTime(), T2.getTime())
+
+         await model.synchronizeAll()
+         const s1Again = await model.db.values.get('s1')
+         assert.equal(s1Again.label, 'server-created-later')
+      } finally {
+         await cleanup()
+         pglite.close()
+      }
+   })
+
    test('one failed updateWithMeta does not abort remaining updateDatabase entries', async () => {
       const modelName = `model${++dbCounter}`
       const serverUpdated = {}
@@ -489,6 +524,102 @@ describe('Full offline-first client ↔ server protocol', () => {
       pglite.close()
    })
 
+   test('reconnect keeps disconnectedDate until automatic sync completes', async () => {
+      const modelName = `model${++dbCounter}`
+      const serverRows = []
+      let resolveSyncStarted
+      let releaseSync
+      let resolveCreate
+      const syncStarted = new Promise(resolve => { resolveSyncStarted = resolve })
+      const syncRelease = new Promise(resolve => { releaseSync = resolve })
+      const createDone = new Promise(resolve => { resolveCreate = resolve })
+
+      function registerServices(app, { slowSync = false } = {}) {
+         app.createService(modelName, {
+            createWithMeta: async (uid, data, created_at) => {
+               serverRows.push({ uid, ...data })
+               resolveCreate()
+               return [{ uid, ...data }, { uid, created_at, updated_at: null, deleted_at: null }]
+            },
+            updateWithMeta: async () => {},
+            deleteWithMeta: async () => {},
+            findMany: async () => [],
+         })
+         app.createService('sync', {
+            go: async (_modelName, _where, _cutoffDate, clientMetadataDict) => {
+               if (slowSync) {
+                  resolveSyncStarted()
+                  await syncRelease
+               }
+               return {
+                  addClient: [],
+                  updateClient: [],
+                  deleteClient: [],
+                  addDatabase: Object.values(clientMetadataDict),
+                  updateDatabase: [],
+               }
+            },
+         })
+      }
+
+      const serverApp1 = expressX({})
+      registerServices(serverApp1)
+      await new Promise(resolve => serverApp1.httpServer.listen(0, resolve))
+      const port = serverApp1.httpServer.address().port
+
+      const socket = ioc(`http://localhost:${port}`, {
+         transports: ['websocket'],
+         autoConnect: false,
+      })
+      const clientApp = createClient(socket, { debug: false })
+      offlinePlugin(clientApp)
+      socket.connect()
+      await new Promise((resolve, reject) => {
+         socket.on('connect', resolve)
+         socket.on('connect_error', reject)
+      })
+
+      const model = clientApp.createOfflineModel(modelName, ['label'])
+      await model.addSynchroWhere({})
+      await model.synchronizeAll()
+
+      const disconnected = new Promise(resolve => socket.once('disconnect', resolve))
+      serverApp1.io.disconnectSockets(true)
+      await new Promise(resolve => serverApp1.io.close(resolve))
+      await disconnected
+
+      await model.db.values.add({ uid: 'reconnect-1', label: 'from reconnect' })
+      await model.db.metadata.add({ uid: 'reconnect-1', created_at: T1 })
+
+      const serverApp2 = expressX({})
+      registerServices(serverApp2, { slowSync: true })
+      await new Promise(resolve => serverApp2.httpServer.listen(port, resolve))
+
+      const reconnected = new Promise((resolve, reject) => {
+         const timer = setTimeout(() => reject(new Error('reconnect timeout')), 5000)
+         socket.once('connect', () => { clearTimeout(timer); resolve() })
+      })
+      socket.connect()
+      await reconnected
+      await syncStarted
+
+      assert.ok(clientApp.disconnectedDate, 'disconnect cutoff should remain while reconnect sync is running')
+      assert.equal(serverRows.length, 0, 'offline row should not be pushed before sync is released')
+
+      releaseSync()
+      await createDone
+
+      for (let i = 0; i < 50 && clientApp.disconnectedDate; i++) {
+         await new Promise(resolve => setTimeout(resolve, 10))
+      }
+
+      assert.equal(clientApp.disconnectedDate, null, 'disconnect cutoff should clear after reconnect sync completes')
+      assert.deepEqual(serverRows, [{ uid: 'reconnect-1', label: 'from reconnect' }])
+
+      socket.disconnect()
+      await new Promise(resolve => serverApp2.io.close(resolve))
+   })
+
    test('updateWithMeta pub/sub handler tolerates undefined value (concurrent delete race)', async () => {
       // updateWithMeta does `const [value] = UPDATE ... RETURNING`.  If the model row
       // was deleted by a concurrent operation between the sync's findMany snapshot and

package/test/sync.test.mjs

@@ -99,6 +99,26 @@ describe('computeSyncResult', () => {
       assert.deepEqual(result.deleteClient, [['g', T1]])
    })
 
+   test('record in both, client delete newer than DB update → delete on DB and notify client', () => {
+      const value      = { uid: 'h', label: 'server-old' }
+      const dbMeta     = { uid: 'h', created_at: T0, updated_at: T1 }
+      const clientMeta = { uid: 'h', created_at: T0, deleted_at: T2 }
+      const result = computeSyncResult({ h: value }, { h: clientMeta }, { h: dbMeta })
+      assert.deepEqual(result.deleteDatabase, ['h'])
+      assert.deepEqual(result.deleteClient, [['h', T2]])
+      assert.deepEqual(result.updateClient, [])
+   })
+
+   test('record in both, DB update newer than client delete → restore client from DB', () => {
+      const value      = { uid: 'i', label: 'server-new' }
+      const dbMeta     = { uid: 'i', created_at: T0, updated_at: T2 }
+      const clientMeta = { uid: 'i', created_at: T0, deleted_at: T1 }
+      const result = computeSyncResult({ i: value }, { i: clientMeta }, { i: dbMeta })
+      assert.deepEqual(result.updateClient, [[value, dbMeta]])
+      assert.deepEqual(result.deleteDatabase, [])
+      assert.deepEqual(result.deleteClient, [])
+   })
+
    test('mixed scenario: one of each case', () => {
       const dbOnly      = { uid: 'db', label: 'db-only' }
       const dbOnlyMeta  = { uid: 'db', created_at: T0 }