@jcbuisson/express-x-plugins 3.0.0

package/README.md

@@ -0,0 +1,105 @@
+# express-x-electric
+
+The smallest useful ElectricSQL integration for Express-X. Express-X handles
+authorized PostgreSQL mutations; Electric's Shape API streams those changes to
+clients. It is analogous to `express-x-drizzle`, but deliberately has no
+metadata table and no custom `sync.go`: Electric is the sync engine.
+
+## Install
+
+```sh
+npm install @jcbuisson/express-x-electric pg
+```
+
+This server-only installation does not install the browser Electric client or
+RxJS.
+
+## Server
+
+```js
+import { Pool } from 'pg'
+import { expressX } from '@jcbuisson/express-x'
+import { electricOfflinePlugin } from '@jcbuisson/express-x-electric'
+
+const app = expressX()
+const db = new Pool({ connectionString: process.env.DATABASE_URL })
+
+app.configure(electricOfflinePlugin, db, [
+  'todos',
+  { name: 'projects', table: 'projects', primaryKey: 'uid' },
+], {
+  electricUrl: process.env.ELECTRIC_URL, // ElectricSQL sync service, e.g. http://localhost:3000/v1/shape
+  sourceId: process.env.ELECTRIC_SOURCE_ID,
+  sourceSecret: process.env.ELECTRIC_SOURCE_SECRET,
+  authorize: async (context, { modelName, action }) => {
+    // `context.transport` is "http" for Shapes and "ws" for Express-X calls.
+    return Boolean(context.request?.user || context.socket?.data?.user)
+  },
+})
+```
+
+This registers one Express-X service per model with the familiar API:
+
+- `createWithMeta(uid, data, createdAt)`
+- `updateWithMeta(uid, data, updatedAt)`
+- `deleteWithMeta(uid, deletedAt)`
+
+Synchronized reads are provided client-side by `getObservable(where)` below;
+one-shot server reads would bypass Electric and are intentionally omitted.
+
+Mutation results remain `[value, meta]` tuples for compatibility. `meta.txid`
+contains `pg_current_xact_id()` and can be passed to an Electric-aware client to
+wait for the matching transaction in its Shape stream.
+
+## Client Shape
+
+Install the optional client dependencies in the browser application:
+
+```sh
+npm install @jcbuisson/express-x-electric @electric-sql/client rxjs
+```
+
+Configure the client plugin and use the same `getObservable(where)` style as
+`express-x-client`'s offline model:
+
+```js
+import { electricClientPlugin } from '@jcbuisson/express-x-electric/client'
+
+app.configure(electricClientPlugin, {
+  shapePath: '/electric/v1/shape',
+})
+
+const todo = app.createElectricModel('todos')
+const subscription = todo.getObservable({ completed: false }).subscribe(rows => {
+  console.log(rows)
+})
+
+// Mutations use the matching Express-X service and are reflected by Electric.
+await todo.create({ title: 'Learn Shapes', completed: false })
+await todo.update(uid, { completed: true })
+await todo.remove(uid)
+
+subscription.unsubscribe()
+```
+
+Object filters use parameterized Electric Shape predicates. Exact values,
+`null`, and `gt`/`gte`/`lt`/`lte` ranges are supported.
+
+All Electric cursor parameters are forwarded. The client cannot override the
+configured table, and Electric source credentials stay server-side.
+
+## Model configuration
+
+Models may be strings (table, service name, and default `uid` key) or objects:
+
+```js
+{ name: 'todo', table: 'todos', primaryKey: 'id' }
+```
+
+Names are restricted to simple PostgreSQL identifiers. Values are always sent
+as query parameters; range filters support `gt`, `gte`, `lt`, and `lte`.
+
+Requires Node 18+ for the built-in Fetch API. The PostgreSQL client only needs a
+`query(sql, values)` method; a `pg.Pool` is recommended so each mutation and its
+transaction ID are captured in the same transaction.
+# express-x-electric

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@jcbuisson/express-x-plugins",
+  "version": "3.0.0",
+  "description": "Plugins for express-x",
+  "type": "module",
+  "main": "./src/electric-server-plugin.mjs",
+  "exports": {
+    "./server/electric": "./src/electric-server-plugin.mjs",
+    "./client/electric": "./src/electric-client-plugin.mjs",
+    "./server/reload": "./src/reload-server-plugin.mjs",
+    "./client/reload": "./src/reload-client-plugin.mjs"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/jcbuisson/express-x-plugins.git"
+  },
+  "author": "Jean-Christophe Buisson <buisson@enseeiht.fr> (jcbuisson.dev)",
+  "license": "MIT",
+  "keywords": [
+    "express-x",
+    "electric-sql",
+    "sync",
+    "local-first"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "@electric-sql/client": "^1.5.24",
+    "rxjs": "^7.8.2"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/client": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@electric-sql/client": "^1.5.24",
+    "rxjs": "^7.8.2"
+  }
+}

package/src/electric-client-plugin.mjs

@@ -0,0 +1,141 @@
+import { Shape, ShapeStream } from '@electric-sql/client'
+import { Observable } from 'rxjs'
+
+
+/**
+ * Add Electric-backed reactive models to an Express-X client.
+ *
+ * Usage:
+ *   electricClientPlugin(app)
+ *   const todo = app.createElectricModel('todos')
+ *   todo.getObservable({ completed: false }).subscribe(...)
+ */
+export function electricClientPlugin(app, options = {}) {
+   const shapePath = options.shapePath ?? '/electric/v1/shape'
+   const ShapeStreamClass = options.ShapeStream ?? ShapeStream
+   const ShapeClass = options.Shape ?? Shape
+   const ObservableClass = options.Observable ?? Observable
+
+   function createElectricModel(modelName, modelOptions = {}) {
+      quoteIdentifier(modelName)
+      const service = app.service(modelName)
+      const url = modelOptions.url ?? modelPath(shapePath, modelName)
+      const streamOptions = modelOptions.streamOptions ?? {}
+
+      function getObservable(where = {}) {
+         // Validate eagerly, as getObservable in express-x-client does.
+         const filterParams = whereToElectricParams(where)
+         return new ObservableClass(subscriber => {
+            const stream = new ShapeStreamClass({
+               ...streamOptions,
+               url,
+               params: { ...streamOptions.params, ...filterParams },
+            })
+            const shape = new ShapeClass(stream)
+            let previous
+            const unsubscribe = shape.subscribe(({ rows }) => {
+               const current = [...rows]
+               const serialized = JSON.stringify(current)
+               if (serialized === previous) return
+               previous = serialized
+               subscriber.next(current)
+            })
+            // Shape exposes errors as state. ShapeStream retries transient failures;
+            // callers keep one observable subscription across reconnects.
+            return () => unsubscribe()
+         })
+      }
+
+      async function create(data) {
+         assertPlainObject(data, 'mutation data')
+         const uid = globalThis.crypto?.randomUUID?.()
+         if (!uid) throw new Error('crypto.randomUUID() is required')
+         const now = new Date().toISOString()
+         const [value] = await service.createWithMeta(uid, data, now)
+         return value
+      }
+
+      async function update(uid, data) {
+         const [value] = await service.updateWithMeta(uid, data, new Date().toISOString())
+         return value
+      }
+
+      async function remove(uid) {
+         const [value] = await service.deleteWithMeta(uid, new Date().toISOString())
+         return value
+      }
+
+      return { getObservable, create, update, remove }
+   }
+
+   return Object.assign(app, { createElectricModel })
+}
+
+
+//////////////////////                   UTILITIES                   //////////////////////
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+const RANGE_OPERATORS = { gt: '>', gte: '>=', lt: '<', lte: '<=' }
+
+function quoteIdentifier(value) {
+   if (typeof value !== 'string' || !IDENTIFIER.test(value)) {
+      throw new TypeError(`'${value}' must be a simple SQL identifier`)
+   }
+   return `"${value}"`
+}
+
+function assertPlainObject(value, label) {
+   if (!value || typeof value !== 'object' || Array.isArray(value) || Object.prototype.toString.call(value) !== '[object Object]') {
+      throw new TypeError(`${label} must be a plain object`)
+   }
+}
+
+function serializeValue(value, path) {
+   if (value instanceof Date) {
+      if (Number.isNaN(value.getTime())) throw new TypeError(`${path} contains an invalid Date`)
+      return value.toISOString()
+   }
+   if (['string', 'number', 'boolean'].includes(typeof value) && value !== undefined) {
+      if (typeof value === 'number' && !Number.isFinite(value)) {
+         throw new TypeError(`${path} contains a non-finite number`)
+      }
+      return String(value)
+   }
+   throw new TypeError(`${path} contains an unsupported value`)
+}
+
+/** Convert the Express-X object filter into Electric's parameterized SQL filter. */
+function whereToElectricParams(where = {}) {
+   assertPlainObject(where, 'where')
+   const clauses = []
+   const params = []
+
+   for (const [column, constraint] of Object.entries(where)) {
+      const quotedColumn = quoteIdentifier(column)
+      if (constraint === undefined) continue
+      if (constraint === null) {
+         clauses.push(`${quotedColumn} IS NULL`)
+         continue
+      }
+      if (constraint && typeof constraint === 'object' && !Array.isArray(constraint) && !(constraint instanceof Date)) {
+         const entries = Object.entries(constraint)
+         if (entries.length === 0 || entries.some(([operator]) => !RANGE_OPERATORS[operator])) {
+            throw new TypeError(`unsupported where constraint for '${column}'`)
+         }
+         for (const [operator, value] of entries) {
+            params.push(serializeValue(value, `where.${column}.${operator}`))
+            clauses.push(`${quotedColumn} ${RANGE_OPERATORS[operator]} $${params.length}`)
+         }
+         continue
+      }
+      params.push(serializeValue(constraint, `where.${column}`))
+      clauses.push(`${quotedColumn} = $${params.length}`)
+   }
+
+   return clauses.length ? { where: clauses.join(' AND '), params } : {}
+}
+
+function modelPath(shapePath, modelName) {
+   const base = shapePath.replace(/\/$/, '')
+   return `${base}/${encodeURIComponent(modelName)}`
+}

package/src/electric-server-plugin.mjs

@@ -0,0 +1,250 @@
+/**
+ * Register Express-X mutation services and an Electric Shape proxy.
+ *
+ * @param {object} app Express-X/Express application
+ * @param {object} db pg-compatible Pool or Client exposing query()
+ * @param {(string|{name:string,table?:string,primaryKey?:string})[]} models
+ * @param {object} options
+ */
+export function electricOfflinePlugin(app, db, models, options = {}) {
+   if (!db || typeof db.query !== 'function') throw new TypeError('db must expose query(sql, values)')
+   if (typeof options.authorize !== 'function') {
+      throw new TypeError('electricOfflinePlugin requires an authorize(context, operation) policy')
+   }
+   const configuredModels = normalizeModels(models)
+   const electricUrl = new URL(options.electricUrl ?? process.env.ELECTRIC_URL ?? 'http://localhost:3000/v1/shape')
+   const shapePath = options.shapePath ?? '/electric/v1/shape/:model'
+   const fetchImpl = options.fetch ?? globalThis.fetch
+   if (typeof fetchImpl !== 'function') throw new TypeError('a fetch implementation is required')
+
+   async function authorize(context, modelName, action, args) {
+      const allowed = await options.authorize(context, { modelName, action, args })
+      if (!allowed) {
+         const error = new Error(`not authorized to ${action} '${modelName}'`)
+         error.code = 'forbidden'
+         throw error
+      }
+   }
+
+   for (const model of configuredModels) {
+      app.createService(model.name, {
+         // findUnique: async function(where) {
+         //    await authorize(this, model.name, 'findUnique', [where])
+         //    const filter = buildWhere(where)
+         //    const result = await db.query(`SELECT * FROM ${model.quotedTable} WHERE ${filter.sql} LIMIT 1`, filter.values)
+         //    return result.rows[0] ?? null
+         // },
+
+         // findMany: async function(where, queryOptions = {}) {
+         //    await authorize(this, model.name, 'findMany', [where, queryOptions])
+         //    const filter = buildWhere(where)
+         //    let sql = `SELECT * FROM ${model.quotedTable} WHERE ${filter.sql}`
+         //    const values = [...filter.values]
+         //    if (queryOptions.limit != null) {
+         //       if (!Number.isInteger(queryOptions.limit) || queryOptions.limit < 1) {
+         //          throw new TypeError('limit must be a positive integer')
+         //       }
+         //       values.push(queryOptions.limit)
+         //       sql += ` LIMIT $${values.length}`
+         //    }
+         //    return (await db.query(sql, values)).rows
+         // },
+
+         createWithMeta: async function(uid, data, createdAt = new Date()) {
+            await authorize(this, model.name, 'createWithMeta', [uid, data, createdAt])
+            assertPlainObject(data, 'mutation data')
+            const timestamp = normalizeTimestamp(createdAt, 'created_at')
+            const safeData = { ...data, [model.primaryKey]: uid }
+            const entries = Object.entries(safeData).filter(([, value]) => value !== undefined)
+            const columns = entries.map(([column]) => quoteIdentifier(column, 'data column'))
+            const values = entries.map(([, value]) => value)
+            const parameters = values.map((_, index) => `$${index + 1}`)
+            const updateEntries = entries.filter(([column]) => column !== model.primaryKey)
+            const conflictAction = updateEntries.length
+               ? 'DO UPDATE SET ' + updateEntries
+                  .map(([column]) => `${quoteIdentifier(column, 'data column')} = EXCLUDED.${quoteIdentifier(column, 'data column')}`).join(', ')
+               : 'DO UPDATE SET ' + `${model.quotedPrimaryKey} = EXCLUDED.${model.quotedPrimaryKey}`
+            return withTransaction(db, async client => {
+               const result = await client.query(
+                  `INSERT INTO ${model.quotedTable} (${columns.join(', ')}) VALUES (${parameters.join(', ')}) `
+                  + `ON CONFLICT (${model.quotedPrimaryKey}) ${conflictAction}`
+                  + ' RETURNING *',
+                  values,
+               )
+               const txid = await transactionId(client)
+               return [result.rows[0], mutationMeta(uid, 'created_at', timestamp, txid)]
+            })
+         },
+
+         updateWithMeta: async function(uid, data, updatedAt = new Date()) {
+            await authorize(this, model.name, 'updateWithMeta', [uid, data, updatedAt])
+            const timestamp = normalizeTimestamp(updatedAt, 'updated_at')
+            const set = buildSet(data)
+            return withTransaction(db, async client => {
+               const result = await client.query(
+                  `UPDATE ${model.quotedTable} SET ${set.sql} WHERE ${model.quotedPrimaryKey} = $${set.values.length + 1} RETURNING *`,
+                  [...set.values, uid],
+               )
+               const txid = await transactionId(client)
+               return [result.rows[0], mutationMeta(uid, 'updated_at', timestamp, txid)]
+            })
+         },
+
+         deleteWithMeta: async function(uid, deletedAt = new Date()) {
+            await authorize(this, model.name, 'deleteWithMeta', [uid, deletedAt])
+            const timestamp = normalizeTimestamp(deletedAt, 'deleted_at')
+            return withTransaction(db, async client => {
+               const result = await client.query(
+                  `DELETE FROM ${model.quotedTable} WHERE ${model.quotedPrimaryKey} = $1 RETURNING *`, [uid],
+               )
+               const txid = await transactionId(client)
+               return [result.rows[0], mutationMeta(uid, 'deleted_at', timestamp, txid)]
+            })
+         },
+      })
+   }
+
+   // uses long-polling request waiting for changes
+   app.get(shapePath, async (request, response, next) => {
+      try {
+         const model = configuredModels.find(candidate => candidate.name === request.params.model)
+         if (!model) return response.status(404).json({ error: 'unknown model' })
+         await authorize({ app, request, response, transport: 'http' }, model.name, 'shape', [request.query])
+         const target = new URL(electricUrl)
+         for (const [key, value] of Object.entries(request.query)) {
+            if (key === 'table') continue
+            if (Array.isArray(value)) value.forEach(entry => target.searchParams.append(key, entry))
+            else if (value != null) target.searchParams.set(key, value)
+         }
+         target.searchParams.set('table', model.table)
+         if (options.sourceId) target.searchParams.set('source_id', options.sourceId)
+         if (options.sourceSecret) target.searchParams.set('secret', options.sourceSecret)
+         const upstream = await fetchImpl(target, { headers: { accept: request.get('accept') ?? '*/*' } })
+         response.status(upstream.status)
+         copyResponseHeaders(upstream, response)
+         response.send(Buffer.from(await upstream.arrayBuffer()))
+      } catch (error) {
+         next(error)
+      }
+   })
+
+   return { shapePath, models: configuredModels.map(({ name, table, primaryKey }) => ({ name, table, primaryKey })) }
+}
+
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+const RANGE_OPERATORS = { gt: '>', gte: '>=', lt: '<', lte: '<=' }
+
+function quoteIdentifier(value, label) {
+   if (typeof value !== 'string' || !IDENTIFIER.test(value)) {
+      throw new TypeError(`${label} must be a simple SQL identifier`)
+   }
+   return `"${value}"`
+}
+
+function normalizeModels(models) {
+   if (!Array.isArray(models) || models.length === 0) {
+      throw new TypeError('models must be a non-empty array')
+   }
+   return models.map(model => {
+      const config = typeof model === 'string' ? { name: model } : model
+      if (!config || typeof config !== 'object' || Array.isArray(config)) {
+         throw new TypeError('each model must be a name or configuration object')
+      }
+      const name = config.name
+      const table = config.table ?? name
+      const primaryKey = config.primaryKey ?? 'uid'
+      quoteIdentifier(name, 'model name')
+      return {
+         name,
+         table,
+         primaryKey,
+         quotedTable: quoteIdentifier(table, `table for '${name}'`),
+         quotedPrimaryKey: quoteIdentifier(primaryKey, `primary key for '${name}'`),
+      }
+   })
+}
+
+function assertPlainObject(value, label) {
+   if (!value || typeof value !== 'object' || Array.isArray(value)
+      || Object.prototype.toString.call(value) !== '[object Object]') {
+      throw new TypeError(`${label} must be a plain object`)
+   }
+}
+
+function buildWhere(where, startIndex = 1) {
+   assertPlainObject(where, 'where')
+   const clauses = []
+   const values = []
+   for (const [column, constraint] of Object.entries(where)) {
+      const quotedColumn = quoteIdentifier(column, 'where column')
+      if (constraint === undefined) continue
+      if (constraint === null) {
+         clauses.push(`${quotedColumn} IS NULL`)
+         continue
+      }
+      if (constraint && typeof constraint === 'object' && !Array.isArray(constraint)) {
+         const entries = Object.entries(constraint)
+         if (entries.length === 0 || entries.some(([operator]) => !RANGE_OPERATORS[operator])) {
+            throw new TypeError(`unsupported where constraint for '${column}'`)
+         }
+         for (const [operator, value] of entries) {
+            values.push(value)
+            clauses.push(`${quotedColumn} ${RANGE_OPERATORS[operator]} $${startIndex + values.length - 1}`)
+         }
+         continue
+      }
+      values.push(constraint)
+      clauses.push(`${quotedColumn} = $${startIndex + values.length - 1}`)
+   }
+   return { sql: clauses.length ? clauses.join(' AND ') : 'TRUE', values }
+}
+
+function buildSet(data, startIndex = 1) {
+   assertPlainObject(data, 'mutation data')
+   const entries = Object.entries(data).filter(([key, value]) => key !== 'uid' && value !== undefined)
+   if (entries.length === 0) throw new TypeError('mutation data must contain at least one field')
+   return {
+      sql: entries.map(([column], index) => `${quoteIdentifier(column, 'data column')} = $${startIndex + index}`).join(', '),
+      values: entries.map(([, value]) => value),
+   }
+}
+
+async function withTransaction(db, operation) {
+   if (typeof db?.connect !== 'function') return operation(db)
+   const client = await db.connect()
+   try {
+      await client.query('BEGIN')
+      const result = await operation(client)
+      await client.query('COMMIT')
+      return result
+   } catch (error) {
+      await client.query('ROLLBACK')
+      throw error
+   } finally {
+      client.release()
+   }
+}
+
+async function transactionId(client) {
+   const result = await client.query('SELECT pg_current_xact_id()::text AS txid')
+   return result.rows[0]?.txid
+}
+
+function mutationMeta(uid, field, timestamp, txid) {
+   return { uid, created_at: null, updated_at: null, deleted_at: null, [field]: timestamp, txid }
+}
+
+function normalizeTimestamp(value, field) {
+   const timestamp = new Date(value)
+   if (Number.isNaN(timestamp.getTime())) throw new TypeError(`${field} must be a valid timestamp`)
+   return timestamp.toISOString()
+}
+
+function copyResponseHeaders(source, target) {
+   source.headers.forEach((value, key) => {
+      if (!['content-encoding', 'content-length', 'transfer-encoding'].includes(key.toLowerCase())) {
+         target.setHeader(key, value)
+      }
+   })
+}

package/src/reload-client-plugin.mjs

@@ -0,0 +1,45 @@
+/**
+ * Enrich `app` with listeners handling socket data transfer on page reload
+ *
+ * Usage:
+ *   reloadPlugin(app)
+ */
+export async function reloadPlugin(app) {
+
+   const cnxid = useSessionStorage('cnxid', '')
+   const cnxtoken = useSessionStorage('cnxtoken', '')
+   const handleTransferToken = token => {
+      if (typeof token === 'string') cnxtoken.value = token
+   }
+
+   app.addConnectListener(async (socket) => {
+      const socketId = socket.id
+      console.log('connect', socketId)
+      const prevSocketId = cnxid.value
+      const prevTransferToken = cnxtoken.value
+      socket.off('cnx-transfer-token', handleTransferToken)
+      socket.on('cnx-transfer-token', handleTransferToken)
+      cnxid.value = socketId
+      if (prevSocketId && prevTransferToken) {
+         console.log('cnx-transfer', prevSocketId, 'to', socketId)
+         let timeout
+         const cleanup = () => {
+            clearTimeout(timeout)
+            socket.off('cnx-transfer-ack', handleAck)
+            socket.off('cnx-transfer-error', handleError)
+         }
+         const handleAck = (fromSocketId, toSocketId) => {
+            console.log('ACK ACK!!!', fromSocketId, toSocketId)
+            cleanup()
+         }
+         const handleError = (fromSocketId, toSocketId) => {
+            console.log('ERR ERR!!!', fromSocketId, toSocketId)
+            cleanup()
+         }
+         socket.once('cnx-transfer-ack', handleAck)
+         socket.once('cnx-transfer-error', handleError)
+         timeout = setTimeout(cleanup, 5000)
+         socket.emit('cnx-transfer', prevSocketId, socketId, prevTransferToken)
+      }
+   })
+}

package/src/reload-server-plugin.mjs

@@ -0,0 +1,95 @@
+/**
+ * Register Express-X reload plugin
+ *
+ * @param {object} app Express-X/Express application
+ * @param {object} options
+ */
+
+export const roomCache = new WeakMap()
+export const dataCache = new WeakMap()
+
+
+export async function reloadPlugin(app, options = {}) {
+
+   const io = app.get('io')
+   const transferTtlMs = app.get('config')?.reloadTransferTtlMs ?? 2 * 60 * 1000
+   const rooms = Object.create(null)
+   const data = Object.create(null)
+   const transferTokens = Object.create(null)
+   const transferExpiryTimers = Object.create(null)
+   roomCache.set(app, rooms)
+   dataCache.set(app, data)
+
+   app.addDisconnectingListener((socket, reason) => {
+      console.log('onSocketDisconnecting', socket.id, reason)
+      // save socket data & rooms in caches
+      const alreadySavedData = data[socket.id]
+      const alreadySavedRooms = rooms[socket.id]
+
+      // Current socket.data takes precedence over stale cached data so that any
+      // updates made between disconnections are not overwritten.
+      data[socket.id] = Object.assign({}, alreadySavedData, socket.data)
+      rooms[socket.id] = new Set(socket.rooms)
+      if (alreadySavedRooms) for (const room of alreadySavedRooms) rooms[socket.id].add(room)
+      transferTokens[socket.id] = socket.data.__cnxTransferToken
+      clearTimeout(transferExpiryTimers[socket.id])
+      transferExpiryTimers[socket.id] = setTimeout(() => {
+         delete rooms[socket.id]
+         delete data[socket.id]
+         delete transferTokens[socket.id]
+         delete transferExpiryTimers[socket.id]
+      }, transferTtlMs)
+      transferExpiryTimers[socket.id].unref?.()
+   })
+
+   app.addConnectListener((socket) => {
+      console.log('onSocketConnect', socket.id)
+      const transferToken = randomUUID()
+      socket.data.__cnxTransferToken = transferToken
+      socket.emit('cnx-transfer-token', transferToken)
+   
+      // when client ask for transfer from fromSocketId to toSocketId
+      socket.on('cnx-transfer', async (fromSocketId, toSocketId, claimedToken) => {
+         app.log('verbose', `cnx-transfer from ${fromSocketId} to ${toSocketId}`)
+         // A socket may only claim its own ID as the destination — prevent session hijacking
+         if (toSocketId !== socket.id || typeof claimedToken !== 'string'
+            || transferTokens[fromSocketId] !== claimedToken) {
+            app.log('verbose', `cnx-transfer rejected: toSocketId ${toSocketId} !== socket.id ${socket.id}`)
+            socket.emit('cnx-transfer-error', fromSocketId, toSocketId)
+            return
+         }
+         // copy connection room & data from 'fromSocketId' to 'toSocketId'
+         const toSocket = io.sockets.sockets.get(toSocketId)
+         // data & rooms of fromSocketId are taken from dataCache and roomCache, since socket no longer exists
+         const fromSocketRooms = rooms[fromSocketId]
+         if (toSocket && fromSocketRooms) {
+            // copy rooms
+            for (const room of fromSocketRooms) {
+               if (room === fromSocketId) continue // do not include room associated to socket#id
+               const allowed = typeof options.authorizeRoomRestore === 'function'
+                  && await options.authorizeRoomRestore({ app, socket: toSocket, room })
+               if (allowed) toSocket.join(room)
+            }
+            // copy data
+            toSocket.data = {
+               ...data[fromSocketId],
+               ...toSocket.data,
+               __cnxTransferToken: transferToken,
+            }
+            // console.log('cnx-transfer data', toSocket.data)
+            // console.log('cnx-transfer rooms', toSocket.rooms)
+            // remove 'from' cache data
+            delete rooms[fromSocketId]
+            delete data[fromSocketId]
+            delete transferTokens[fromSocketId]
+            clearTimeout(transferExpiryTimers[fromSocketId])
+            delete transferExpiryTimers[fromSocketId]
+            // send acknowlegment to toSocket
+            toSocket.emit('cnx-transfer-ack', fromSocketId, toSocketId)
+         } else {
+            console.log(`*** CNX TRANSFER ERROR, ${fromSocketId} -> ${toSocketId}`)
+            if (toSocket) toSocket.emit('cnx-transfer-error', fromSocketId, toSocketId)
+         }
+      })
+   })
+}

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

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { electricClientPlugin, whereToElectricParams } from '../src/electric-client-plugin.mjs'
+
+class FakeStream {
+   static instances = []
+   constructor(options) {
+      this.options = options
+      FakeStream.instances.push(this)
+   }
+}
+
+class FakeShape {
+   constructor(stream) { this.stream = stream }
+   subscribe(callback) {
+      callback({ rows: [{ uid: 'one', completed: false }] })
+      return () => { this.unsubscribed = true }
+   }
+}
+
+test('translates where objects into parameterized Electric filters', () => {
+   assert.deepEqual(whereToElectricParams({ completed: false, priority: { gte: 2, lt: 5 }, owner: null }), {
+      where: '"completed" = $1 AND "priority" >= $2 AND "priority" < $3 AND "owner" IS NULL',
+      params: ['false', '2', '5'],
+   })
+   assert.deepEqual(whereToElectricParams({}), {})
+   assert.throws(() => whereToElectricParams({ 'bad;drop': 1 }), /simple SQL identifier/)
+})
+
+test('getObservable emits Shape rows and cleans up its subscription', () => {
+   const app = { service: () => ({}) }
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })
+   const todo = app.createElectricModel('todos')
+   let rows
+   const subscription = todo.getObservable({ completed: false }).subscribe(value => { rows = value })
+
+   assert.deepEqual(rows, [{ uid: 'one', completed: false }])
+   assert.equal(FakeStream.instances.at(-1).options.url, '/electric/v1/shape/todos')
+   assert.deepEqual(FakeStream.instances.at(-1).options.params, {
+      where: '"completed" = $1', params: ['false'],
+   })
+   subscription.unsubscribe()
+})
+
+test('model mutations retain the simple Express-X API', async () => {
+   const calls = []
+   const service = {
+      async createWithMeta(...args) { calls.push(['create', ...args]); return [{ uid: args[0], ...args[1] }, {}] },
+      async updateWithMeta(...args) { calls.push(['update', ...args]); return [{ uid: args[0], ...args[1] }, {}] },
+      async deleteWithMeta(...args) { calls.push(['remove', ...args]); return [{ uid: args[0] }, {}] },
+   }
+   const app = { service: () => service }
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })
+   const todo = app.createElectricModel('todos')
+
+   const created = await todo.create({ title: 'Test' })
+   await todo.update(created.uid, { completed: true })
+   await todo.remove(created.uid)
+   assert.deepEqual(calls.map(call => call[0]), ['create', 'update', 'remove'])
+})

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

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { electricOfflinePlugin } from '../src/electric-server-plugin.mjs'
+
+function fixture({ authorize = async () => true, fetch } = {}) {
+   const services = new Map()
+   const routes = new Map()
+   const queries = []
+   const db = {
+      async query(sql, values = []) {
+         queries.push({ sql, values })
+         if (sql.startsWith('SELECT pg_current')) return { rows: [{ txid: '42' }] }
+         return { rows: [{ uid: values.at(-1) ?? 'one', label: 'row' }] }
+      },
+   }
+   const app = {
+      createService(name, methods) { services.set(name, methods) },
+      get(path, handler) { routes.set(path, handler) },
+   }
+   const registration = electricOfflinePlugin(app, db, ['todos'], { authorize, fetch: fetch ?? globalThis.fetch })
+   return { app, db, services, routes, queries, registration }
+}
+
+test('registers the familiar mutation API', async () => {
+   const { services, queries } = fixture()
+   const service = services.get('todos')
+   assert.deepEqual(Object.keys(service), [
+      'createWithMeta', 'updateWithMeta', 'deleteWithMeta',
+   ])
+
+   const [, meta] = await service.createWithMeta.call({}, 'one', { label: 'new' }, '2026-01-01T00:00:00Z')
+   assert.equal(meta.uid, 'one')
+   assert.equal(meta.txid, '42')
+   assert.equal(meta.created_at, '2026-01-01T00:00:00.000Z')
+
+   await service.createWithMeta.call({}, 'only-id', {}, '2026-01-01T00:00:00Z')
+   assert.match(queries[2].sql, /DO UPDATE SET "uid" = EXCLUDED\."uid"/)
+   await assert.rejects(service.createWithMeta.call({}, 'bad', [], new Date()), /plain object/)
+})
+
+test('requires authorization and reports forbidden calls', async () => {
+   const { services } = fixture({ authorize: async () => false })
+   await assert.rejects(
+      services.get('todos').createWithMeta.call({}, 'one', { label: 'no' }, new Date()),
+      error => error.code === 'forbidden',
+   )
+})
+
+test('shape proxy pins the configured table and keeps credentials server-side', async () => {
+   let fetched
+   const fetch = async (url) => {
+      fetched = new URL(url)
+      return new Response('[{"value":{"uid":"one"}}]', {
+         status: 200,
+         headers: { 'content-type': 'application/json', 'electric-handle': 'abc' },
+      })
+   }
+   const services = new Map()
+   const routes = new Map()
+   const db = { query: async () => ({ rows: [] }) }
+   const app = {
+      createService(name, methods) { services.set(name, methods) },
+      get(path, handler) { routes.set(path, handler) },
+   }
+   electricOfflinePlugin(app, db, [{ name: 'todo', table: 'todos' }], {
+      authorize: async () => true,
+      electricUrl: 'https://electric.example/v1/shape',
+      sourceId: 'source',
+      sourceSecret: 'secret',
+      fetch,
+   })
+   const response = {
+      headers: {},
+      status(value) { this.statusCode = value; return this },
+      setHeader(key, value) { this.headers[key] = value },
+      send(value) { this.body = value },
+      json(value) { this.body = value },
+   }
+   await routes.get('/electric/v1/shape/:model')({
+      params: { model: 'todo' },
+      query: { table: 'secrets', offset: '10' },
+      get: () => 'application/json',
+   }, response, error => { throw error })
+
+   assert.equal(fetched.searchParams.get('table'), 'todos')
+   assert.equal(fetched.searchParams.get('offset'), '10')
+   assert.equal(fetched.searchParams.get('source_id'), 'source')
+   assert.equal(fetched.searchParams.get('secret'), 'secret')
+   assert.equal(response.statusCode, 200)
+   assert.equal(response.headers['electric-handle'], 'abc')
+})
+
+test('rejects unsafe SQL identifiers', () => {
+   assert.throws(
+      () => electricOfflinePlugin(
+         { createService() {}, get() {} },
+         { query() {} },
+         ['todos; DROP TABLE users'],
+         { authorize: async () => true, fetch: async () => {} },
+      ),
+      /simple SQL identifier/,
+   )
+})