@jcbuisson/express-x 3.0.4 → 3.1.0

package/CLAUDE.md

@@ -4,106 +4,102 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-**express-x** is a full-stack framework that unifies backend and frontend communication through WebSocket-based services. It's published as `@jcbuisson/express-x` on npm.
+**express-x** is a full-stack framework that unifies backend and frontend communication through WebSocket-based services.
+It's published as `@jcbuisson/express-x` on npm.
 
-Core concept: ExpressX is a thin wrapper around Express.js and Socket.io that provides a service-oriented, real-time RPC pattern. Clients call server-side service methods via WebSocket and receive results as promises. Services can publish events to channels, enabling pub/sub-style real-time updates.
+Core concept: ExpressX is a thin wrapper around Express.js and Socket.io that provides a service-oriented, real-time RPC pattern.
+Clients call server-side service methods via WebSocket and receive results as promises.
+Services can publish events to channels, enabling pub/sub-style real-time updates.
 
 **Repository**: https://github.com/jcbuisson/express-x  
 **Documentation**: https://expressx.jcbuisson.dev  
-**Version**: 3.0.3 (ES modules)
+**Version**: 3.1.0 (ES modules)
 
-## Architecture
+## Development Commands
 
-### Single Entry Point
-- `/src/server.mjs` (625 lines) is the complete framework implementation. This is the only source file.
-- Exports the main `expressX()` factory function and various utilities/plugins.
+```bash
+# Install dependencies
+npm install
 
-### Core Concepts
+# Run integration tests (round-trip + offline sync via real sockets/PGlite/Dexie)
+npm test
 
-1. **Services**: Named groups of callable methods. Created via `app.createService(name, methods)`. Each method receives a `context` object containing metadata about the call (transport, socket, service/method names, args).
+# Run unit tests for the sync algorithm only
+node --import tsx/esm --test test/sync.test.mjs
 
-2. **Context Object**: Contains execution metadata:
-   - `app`, `socket`, `serviceName`, `methodName`, `args`, `result`
-   - `caller` ('client' or 'server'), `transport` ('ws')
-   - Modified by hooks before/after method execution
+# Run both test files
+node --import tsx/esm --test --test-force-exit test/offline.test.mjs test/sync.test.mjs
 
-3. **Hooks**: Pre/post-execution functions that can modify context or validate requests. Attached to services via `service.hooks()`. Support method-specific and "all methods" variants:
-   ```js
-   service.hooks({
-     before: { methodName: [hook1, hook2], all: [globalHook] },
-     after: { methodName: [hook], all: [globalHook] }
-   })
-   ```
+# Run a single named test (partial match on test name)
+node --import tsx/esm --test --test-force-exit --test-name-pattern="service call" test/offline.test.mjs
+```
 
-4. **Channels & Pub/Sub**: Enable real-time broadcasting:
-   - Channels are Socket.io rooms with names
-   - Services attach a `publishFunction` via `service.publish()` that determines which channels receive events after method execution
-   - Clients join/subscribe to channels via `app.joinChannel(name, socket)`
-   - Events are published as `service-event` messages containing `{name, action, result}`
+No build step — the source is run directly as ES modules.
 
-5. **WebSocket Protocol**: Single `client-request` event from client → `client-response` event from server, with uid-based request/response correlation. Errors are serialized and sent back to client.
+## Architecture
 
-### Key Plugins
+### Source Files
+- `src/server.mjs` — complete server-side framework; all exports live here.
+- `src/client.mjs` — local mirror of the client-side library (`@jcbuisson/express-x-client`). Used for development and to track changes before publishing.
 
-- **reloadPlugin**: Manages connection recovery across page reloads/reconnects by caching socket data and rooms.
-- **offlinePlugin**: Implements offline-first CRUD operations with Prisma. Provides `sync.go()` service method that reconciles client cache with database using timestamps (created_at, updated_at, deleted_at).
+### Related Packages (also authored here, published separately)
+- **`@jcbuisson/express-x-client`** (`node_modules/@jcbuisson/express-x-client/src/client.mts`) — published client library: `createClient`, `offlinePlugin`, `Mutex`, `wherePredicate`. TypeScript source consumed directly via `tsx`. `src/client.mjs` is the local development counterpart.
+- **`@jcbuisson/express-x-drizzle`** (`node_modules/@jcbuisson/express-x-drizzle/src/drizzle-plugins.mjs`) — Drizzle ORM offline plugin. The installed version may lag behind local development; tests wire it via `serverApp.configure(drizzleOfflinePlugin, ...)`.
 
-### Common Hook Patterns (Exported Utilities)
-- `addTimestamp(field)`: Adds ISO timestamp to result
-- `hashPassword(field)`: Hashes password using bcryptjs
-- `protect(field)`: Removes sensitive fields from results
+### Core Concepts
 
-### Error Handling
-- `EXError(code, message)`: Custom error class with error codes. Method errors are caught, serialized, and sent to client as rejected promises.
+1. **Services**: Named groups of callable methods. Created via `app.createService(name, methods)`. Each method is wrapped to support hooks and pub/sub.
 
-## Development Commands
+2. **Context Object**: Passed to every hooked method — contains `app`, `socket`, `serviceName`, `methodName`, `args`, `result`, `caller` ('client'|'server'), `transport` ('ws').
 
-```bash
-# Install dependencies
-npm install
+3. **Hooks**: Pre/post-execution filters attached via `service.hooks({ before: { methodName: [...], all: [...] }, after: {...} })`. Hooks run: `before.all` → `before.method` → method → `after.method` → `after.all`.
 
-# Prisma (optional, if using database)
-npm run generate    # Generate Prisma client
-npm run migrate     # Run Prisma migrations
+4. **Channels & Pub/Sub**: Socket.io rooms. After a service method completes, `service.publishFunction(context)` returns channel names; the result is broadcast as `service-event` to all sockets in those rooms. Clients subscribe with `app.service(name).on(action, handler)`.
 
-# No dedicated test, build, or lint scripts
-# Manual testing via client-server examples in README
-```
+5. **WebSocket Protocol**: Client calls `socket.timeout(ms).emitWithAck('client-request', { name, action, args })` → server handler receives `({ name, action, args }, ack)` and responds via `ack({ result })` or `ack({ error })`. Correlation is handled by Socket.io's built-in acknowledgment mechanism — no custom uid tracking.
 
-## Key Dependencies
-- **express** (^4.18.2): HTTP server framework
-- **socket.io** (^4.6.0): WebSocket server
-- **bcryptjs** (^2.4.3): Password hashing
-- **config** (^3.3.9): Configuration management
-- Peer: Prisma for database CRUD services (optional)
+### Offline Sync Architecture
 
-## File Structure
-```
-express-x/
-  src/server.mjs          # Complete framework (625 lines)
-  package.json            # v3.0.3, ES module type
-  README.md               # Getting started + examples
-  .vscode/launch.json     # Debug config
-```
+The sync system reconciles a client Dexie cache with a server database. The protocol:
+
+1. Client calls `sync.go(modelName, where, cutoffDate, clientMetadataDict)` with its local metadata snapshot.
+2. Server computes diff using `computeSyncResult` (exported from `server.mjs`, pure function, no I/O).
+3. Server returns `{ addClient, updateClient, deleteClient, addDatabase, updateDatabase }`.
+4. Client applies each batch: puts addClient records into Dexie, deletes deleteClient, updates updateClient, then calls `createWithMeta`/`updateWithMeta` for addDatabase/updateDatabase.
 
-## Implementation Notes
+**Two offline plugin implementations:**
+- `offlinePlugin` in `server.mjs` — Prisma-based (legacy, uses `prisma.$transaction`).
+- `drizzleOfflinePlugin` from `@jcbuisson/express-x-drizzle` — Drizzle ORM-based, used in all tests.
 
-1. **Context Execution**: Service methods are wrapped with hook execution:
-   - All `before.all` hooks → method-specific `before` hooks → method execution → method-specific `after` hooks → all `after.all` hooks
-   - Hooks receive context and can throw errors (which propagate to client)
+**`computeSyncResult(databaseValuesDict, clientMetadataDict, databaseMetadataDict)`** is the pure sync algorithm exported from `server.mjs`. It uses `null` (not `new Date()`) as the fallback `created_at` for missing metadata, so a record without metadata is treated as older than any client record, preventing infinite `updateClient` loops.
 
-2. **Event Publishing**: After a service method completes, `publishFunction` is called with the context. It returns an array of channel names. The result is broadcast to all sockets in those channels as a `service-event`.
+### Key Plugins
+- **reloadPlugin**: Caches socket data/rooms on disconnect; restores them on reconnect via `cnx-transfer` socket event.
+- **offlinePlugin (Prisma)**: CRUD services + `sync.go` for offline-first with Prisma.
+- **drizzleOfflinePlugin**: Same pattern using Drizzle ORM + PGlite-compatible transactions.
 
-3. **Connection State**: Socket.io's built-in `socket.data` object stores per-connection state. Socket.io's connection recovery feature (2-minute default) restores socket.id, rooms, and data on network reconnects.
+### Exported Utilities
+- `Mutex` — simple async mutex used by sync and offline plugins.
+- `truncateString` — log truncation helper.
+- `addTimestamp(field)`, `hashPassword(field)`, `protect(field)` — common hook factories.
+- `EXError(code, message)` — custom error class; `code` is serialized and sent to the client.
+- `computeSyncResult` — pure sync diff algorithm.
 
-4. **Offline Sync**: The `offlinePlugin` uses transaction-safe Prisma operations and a mutex to ensure consistent synchronization. Clients track operation timestamps and the sync algorithm compares created_at/updated_at to determine add/update/delete operations.
+## Test Structure
 
-5. **Logging**: App-level logging via `app.log(severity, message)`. If no logger is configured, falls back to console.log.
+- `test/offline.test.mjs` — Integration tests. Spins up a real Express/Socket.io server on a random port, connects via `socket.io-client`, uses PGlite (in-memory Postgres) + Drizzle + Dexie (via `fake-indexeddb`). Tests cover the full client↔server sync protocol, pub/sub, rollbacks, and edge cases. Each test gets an isolated PGlite instance and unique model name.
+- `test/sync.test.mjs` — Unit tests for `computeSyncResult` only. Imports from `#root/src/drizzle-plugins.mjs` (the `#root/*` alias maps to the repo root via `package.json` imports).
+
+Each integration test uses `createTestContext(registerServices, opts)` which starts a server on a random port, connects a client, and returns a `cleanup()` function. Tests import from the published npm packages (`@jcbuisson/express-x`, `@jcbuisson/express-x-client`, `@jcbuisson/express-x-drizzle`), not from local `src/`.
 
 ## Configuration
 
-ExpressX accepts an optional config object (first parameter to `expressX(config)`):
-- `config.WS_PATH` (default: '/socket.io/'): Socket.io path
+`expressX(config)` accepts:
+- `config.WS_PATH` (default: `'/socket.io/'`): Socket.io path
 - `config.maxDisconnectionDuration` (default: 2 min): Connection recovery window
-- Any config is accessible server-side via `app.get('config')`
+- Accessible server-side as `app.get('config')`
 
+## Key Dependencies
+- **express** / **socket.io**: HTTP + WebSocket server
+- **bcryptjs**: Password hashing (hook utility)
+- Dev: **@electric-sql/pglite** (in-memory Postgres for tests), **drizzle-orm**, **fake-indexeddb** (Dexie in Node), **tsx** (runs `.mts` client source directly), **dexie**, **rxjs**, **uuid**, **@vueuse/core**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "",
   "type": "module",
   "main": "src/server.mjs",
@@ -18,7 +18,7 @@
     "#root/*": "./*"
   },
   "scripts": {
-    "test": "node --import tsx/esm --test --test-force-exit test/round-trip.test.mjs"
+    "test": "node --import tsx/esm --test --test-force-exit test/offline.test.mjs test/sync.test.mjs"
   },
   "keywords": [],
   "dependencies": {
@@ -30,7 +30,7 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.4.5",
     "@jcbuisson/express-x-client": "^3.0.5",
-    "@jcbuisson/express-x-drizzle": "^1.0.5",
+    "@jcbuisson/express-x-drizzle": "^1.0.7",
     "@vueuse/core": "^14.3.0",
     "dexie": "^4.4.2",
     "drizzle-orm": "^0.45.2",

package/src/server.mjs

@@ -6,10 +6,6 @@ import bcrypt from 'bcryptjs'
 
 
 
-// UTILISER L'ACKNOWLEDGEMENT : https://socket.io/docs/v4/#acknowledgements
-
-
-
 
 //////////////////////////       UTILITIES       //////////////////////////
 
@@ -185,11 +181,11 @@ export function expressX(config) {
 
       /*
       * Handle websocket client request
-      * Emit in return a 'client-response' message
+      * Respond via socket.io acknowledgment callback
       */
-      socket.on('client-request', async ({ uid, name, action, args }) => {
+      socket.on('client-request', async ({ name, action, args }, ack) => {
          const trimmedArgs = args ? JSON.stringify(args).slice(0, 300) : ''
-         app.log('verbose', `client-request ${uid} ${name} ${action} ${trimmedArgs}`)
+         app.log('verbose', `client-request ${name} ${action} ${trimmedArgs}`)
          if (name in services) {
             const service = services[name]
             try {
@@ -200,30 +196,21 @@ export function expressX(config) {
                      caller: 'client',
                      transport: 'ws',
                      socket,
-                     // connectionId,
                      serviceName: name,
                      methodName: action,
                      args,
                   }
 
                   try {
-                     // call method with context
-                     if (name === 'highlighted_part') {
-                        console.log('')
-                     }
                      const result = await serviceMethod(context, ...args)
 
                      const trimmedResult = result ? JSON.stringify(result).slice(0, 300) : ''
-                     app.log('verbose', `client-response ${uid} ${trimmedResult}`)
-                     socket.emit('client-response', {
-                        uid,
-                        result,
-                     })
+                     app.log('verbose', `client-response ${trimmedResult}`)
+                     ack({ result })
                   } catch(err) {
                      console.log('!!!!!!error', 'name', name, 'action', action, 'args', args, 'err.code', err.code, 'err.message', err.message)
                      app.log('verbose', err.stack)
-                     socket.emit('client-response', {
-                        uid,
+                     ack({
                         error: {
                            code: err.code || 'unknown-error',
                            message: err.message,
@@ -232,8 +219,7 @@ export function expressX(config) {
                      })
                   }
                } else {
-                  socket.emit('client-response', {
-                     uid,
+                  ack({
                      error: {
                         code: 'missing-method',
                         message: `there is no method named '${action}' for service '${name}'`,
@@ -243,18 +229,16 @@ export function expressX(config) {
             } catch(err) {
                console.log('err', err)
                app.log('verbose', err.stack)
-               socket.emit('client-response', {
-                  uid,
+               ack({
                   error: {
                      code: err.code || 'unknown-error',
                      message: err.message,
                      stack: err.stack,
-            }
+                  }
                })
             }
          } else {
-            socket.emit('client-response', {
-               uid,
+            ack({
                error: {
                   code: 'missing-service',
                   message: `there is no service named '${name}'`,

package/test/{round-trip.test.mjs → offline.test.mjs}

@@ -5,7 +5,7 @@ process.on('unhandledRejection', (reason, promise) => {
    console.error('UNHANDLED REJECTION:', reason)
 })
 
-import { test, describe } from 'node:test'
+import { test, describe, after } from 'node:test'
 import assert from 'node:assert/strict'
 import { io as ioc } from 'socket.io-client'
 import { PGlite } from '@electric-sql/pglite'
@@ -53,7 +53,7 @@ async function createTestDb(modelName) {
       uid: text('uid').primaryKey(),
       label: text('label').notNull(),
    })
-   return { db, metaTable, modelTable }
+   return { pglite, db, metaTable, modelTable }
 }
 
 // ─── Test context helper ──────────────────────────────────────────────────────
@@ -89,7 +89,7 @@ async function createTestContext(registerServices, { useOfflinePlugin = false }
 
 // ─────────────────────────────────────────────────────────────────────────────
 
-describe('Full client ↔ server protocol', () => {
+describe('Full offline-first client ↔ server protocol', () => {
 
    test('service call is routed through client-request / client-response', async () => {
       const { clientApp, cleanup } = await createTestContext(serverApp => {
@@ -128,7 +128,7 @@ describe('Full client ↔ server protocol', () => {
 
    test('sync.go through socket: server records pulled into real Dexie', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       await db.insert(modelTable).values({ uid: 'r1', label: 'Vacances' })
       await db.insert(metaTable).values({ uid: 'r1', created_at: T0 })
@@ -148,12 +148,13 @@ describe('Full client ↔ server protocol', () => {
          assert.equal(r1.label, 'Vacances')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
    test('sync.go through socket: local Dexie record pushed to server', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -172,12 +173,13 @@ describe('Full client ↔ server protocol', () => {
          assert.equal(rows[0].label, 'Formation')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
    test('record only on client, deleted → ignored on both sides', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -197,6 +199,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok(!d1, 'Dexie should no longer hold the deleted record')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -242,7 +245,7 @@ describe('Full client ↔ server protocol', () => {
 
    test('deleted record is fully removed from Dexie metadata after sync', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -266,12 +269,13 @@ describe('Full client ↔ server protocol', () => {
          assert.ok(!d1Meta, 'Dexie metadata should also be removed for deleted record')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
    test('record in both, DB newer → client cache is updated with server value', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       // Server has s1 at T2 (newer than client)
       await db.insert(modelTable).values({ uid: 's1', label: 'server-v2' })
@@ -300,6 +304,7 @@ describe('Full client ↔ server protocol', () => {
          assert.equal(s1Again.label, 'server-v2', 'second sync should not overwrite client value')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -346,7 +351,7 @@ describe('Full client ↔ server protocol', () => {
 
    test('record in both, client newer → server is updated via socket', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       await db.insert(modelTable).values({ uid: 'u1', label: 'old' })
       await db.insert(metaTable).values({ uid: 'u1', created_at: T0, updated_at: T1 })
@@ -369,12 +374,13 @@ describe('Full client ↔ server protocol', () => {
          assert.equal(clientValue.label, 'new', 'client Dexie should be unchanged')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
    test('record deleted on server while client was offline is re-created on reconnect', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       // r1 exists on server initially
       await db.insert(modelTable).values({ uid: 'r1', label: 'original' })
@@ -407,12 +413,13 @@ describe('Full client ↔ server protocol', () => {
          assert.ok(r1, 'client Dexie should still have r1 after sync')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
    test('offline changes are synced after server restart', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       // ─ Phase 1: start server, connect, register synchro scope ─
       const serverApp1 = expressX({})
@@ -479,6 +486,7 @@ describe('Full client ↔ server protocol', () => {
 
       socket.disconnect()
       await new Promise(resolve => serverApp2.io.close(resolve))
+      pglite.close()
    })
 
    test('updateWithMeta pub/sub handler tolerates undefined value (concurrent delete race)', async () => {
@@ -690,7 +698,7 @@ describe('Full client ↔ server protocol', () => {
       // other addClient records in the same batch.
       // Fix: use idbValues.put() (upsert) so a pre-existing uid is handled gracefully.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       await db.insert(modelTable).values({ uid: 'r1', label: 'server-r1' })
       await db.insert(metaTable).values({ uid: 'r1', created_at: T0 })
@@ -729,6 +737,7 @@ describe('Full client ↔ server protocol', () => {
          assert.equal(r2.label, 'server-r2')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -740,7 +749,7 @@ describe('Full client ↔ server protocol', () => {
       // Fix: use null instead of new Date() so the client's version "wins" once
       // (updateDatabase), the server gets metadata, and subsequent syncs see diff=0.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       // Server has s1 in model table but intentionally NO metadata row
       await db.insert(modelTable).values({ uid: 's1', label: 'server-label' })
@@ -774,6 +783,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok(s1Meta, 'server metadata must be created after the first sync (updateDatabase + upsert)')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -848,7 +858,7 @@ describe('Full client ↔ server protocol', () => {
       // TypeError that escapes to the outer try/catch, aborting the entire sync and
       // silently skipping every remaining addDatabase / updateDatabase entry.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -876,6 +886,7 @@ describe('Full client ↔ server protocol', () => {
             'a2 must be pushed to the server even though a1 has missing metadata')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -887,7 +898,7 @@ describe('Full client ↔ server protocol', () => {
       // That record enters clientMetadataDict, appears as addDatabase to the server,
       // and if score is NOT NULL the insert fails, rolling back the Dexie record.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -909,6 +920,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok( uids.includes('five-score'), 'score=5 must match { lte: 10 }')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -921,7 +933,7 @@ describe('Full client ↔ server protocol', () => {
       // the client includes the record in clientMetadataDict → addDatabase → if the
       // column is NOT NULL the insert fails → rollback deletes the record from Dexie.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -942,6 +954,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok( uids.includes('r2'), 'record with score=5 must match { gte: 1 }')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -988,6 +1001,7 @@ describe('Full client ↔ server protocol', () => {
          }
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -1045,6 +1059,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok(!uids.includes('hi'),  'score=15 is above range and must NOT be in Dexie')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -1096,6 +1111,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok( uids.includes('hi'), 'score=7 should be pulled (≥ 5)')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -1154,7 +1170,7 @@ describe('Full client ↔ server protocol', () => {
       // model table → throws → addDatabase catch deletes the record from Dexie.
       // Fix: model INSERT should use ON CONFLICT DO UPDATE just like the metadata INSERT.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       // Server already has r1 (createWithMeta_A already landed)
       await db.insert(modelTable).values({ uid: 'r1', label: 'original' })
@@ -1186,6 +1202,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok(r1, 'client Dexie should retain r1 after idempotent createWithMeta')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -1196,7 +1213,7 @@ describe('Full client ↔ server protocol', () => {
       // throws a ConstraintError (PK already taken by the orphan), aborting the
       // entire addClient transaction — the record never arrives in the client cache.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       await db.insert(modelTable).values({ uid: 'r1', label: 'from-server' })
       await db.insert(metaTable).values({ uid: 'r1', created_at: T0 })
@@ -1221,6 +1238,7 @@ describe('Full client ↔ server protocol', () => {
          assert.equal(r1.label, 'from-server')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -1229,7 +1247,7 @@ describe('Full client ↔ server protocol', () => {
       // nor the null branch nor the object branch — so boolean where-values are silently
       // ignored and every record passes, sending wrong records into clientMetadataDict.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -1249,6 +1267,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok(!uids.includes('r2'), 'active=false should NOT match { active: true }')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -1259,7 +1278,7 @@ describe('Full client ↔ server protocol', () => {
       // with user_uid === null.  In synchronize() this causes records with a non-null
       // user_uid to appear as addDatabase, hit a PK conflict, and get deleted.
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -1279,6 +1298,7 @@ describe('Full client ↔ server protocol', () => {
          assert.ok( uids.includes('r2'), 'record with user_uid=null should match { user_uid: null }')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
@@ -1289,7 +1309,7 @@ describe('Full client ↔ server protocol', () => {
       // and the sync pushes them to the server where they fail with PK conflicts,
       // then the rollback deletes them from Dexie (data loss).
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       const { clientApp, cleanup } = await createTestContext(
          serverApp => serverApp.configure(drizzleOfflinePlugin, db, metaTable, [modelTable]),
@@ -1312,12 +1332,13 @@ describe('Full client ↔ server protocol', () => {
          assert.ok( uids.includes('zero'), 'score=0  should match { lte: 0 }')
       } finally {
          await cleanup()
+         pglite.close()
       }
    })
 
    test('pub/sub createWithMeta event correctly updates a second client\'s Dexie', async () => {
       const modelName = `model${++dbCounter}`
-      const { db, metaTable, modelTable } = await createTestDb(modelName)
+      const { pglite, db, metaTable, modelTable } = await createTestDb(modelName)
 
       // Server with pub/sub: every client joins 'all' and createWithMeta broadcasts there
       const serverApp = expressX({})
@@ -1362,6 +1383,7 @@ describe('Full client ↔ server protocol', () => {
          socketA.disconnect()
          socketB.disconnect()
          await new Promise(resolve => serverApp.io.close(resolve))
+         pglite.close()
       }
    })
 

package/test/sync.test.mjs

@@ -1,7 +1,7 @@
 import { test, describe, mock } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { computeSyncResult } from '#root/src/drizzle-plugins.mjs'
+import { computeSyncResult } from '#root/src/server.mjs'
 
 const T0 = new Date('2026-01-01T00:00:00Z')
 const T1 = new Date('2026-01-02T00:00:00Z')

package/.claude/settings.local.json

@@ -1,11 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git -C /Users/chris/workspaces/NPM/express-x log --oneline --all)",
-      "Bash(git *)",
-      "Bash(npm scripts *)",
-      "Bash(npm test *)",
-      "Bash(npm install *)"
-    ]
-  }
-}