@jcbuisson/express-x-plugins 5.0.8 → 5.1.0

package/README.md

@@ -489,3 +489,68 @@ Restored from the last committed custom implementations, dated July 8, 2026:
 **944c398** (client), and `express-x-drizzle` **ddf6804** (server). The algorithm
 was removed from Express-X in **47c2293** on July 19. Only module imports and
 plugin export aliases were adapted; the synchronization logic is preserved.
+
+## Minimal SQL-oriented Electric plugin
+
+A separate plugin provides two client methods: `sql.watch` for live table rows
+and `sql.query` for named, parameterized PostgreSQL statements. It needs no models,
+ORM, local database, Vue, RxJS, schema changes, or sync metadata.
+
+```js
+// Server (pg Pool or Client)
+import { electricSqlServerPlugin } from '@jcbuisson/express-x-plugins/electric-sql-server'
+
+app.configure(electricSqlServerPlugin, pool, {
+  tables: ['todos'],
+  statements: {
+    add: 'INSERT INTO todos (label) VALUES ($1) RETURNING *',
+    complete: 'UPDATE todos SET done = $1 WHERE id = $2 RETURNING *',
+    remove: 'DELETE FROM todos WHERE id = $1 RETURNING *',
+  },
+  electricUrl: 'http://localhost:3000/v1/shape',
+  authorize(context, operation) {
+    // Supply your application's authorization policy. Check statement name and
+    // params for query calls; table and SQL filter params for shape calls.
+    return Boolean(context.request?.user)
+  },
+})
+```
+
+```js
+// Browser (install @electric-sql/client)
+import { electricSqlClientPlugin } from '@jcbuisson/express-x-plugins/electric-sql-client'
+
+app.configure(electricSqlClientPlugin)
+const stop = app.sql.watch('todos', {
+  where: 'done = $1',
+  params: [false],
+}, rows => console.log(rows))
+
+const [todo] = await app.sql.query('add', ['Buy milk'])
+await app.sql.query('complete', [true, todo.id])
+await app.sql.query('remove', [todo.id])
+stop() // unsubscribe and abort this stream
+app.sql.dispose() // stop every active watch
+```
+
+`watch(table, callback)` watches the whole table. Filters use Electric-supported
+PostgreSQL WHERE expressions with `$1`, `$2`, etc.; null comparisons use `IS NULL`.
+Callbacks receive the initial synchronized rows and later committed changes.
+Electric Shapes are table subscriptions, not arbitrary SELECTs or joins. Named
+statements can use full PostgreSQL SQL, including joins and `RETURNING`; `query`
+returns their rows. SQL text stays on the server, and values are bound through pg.
+
+Authorization is required for both statements and Shapes. A table allowlist alone
+is not row authorization: enforce tenant restrictions in server SQL and validate
+Shape filters in your policy. The proxy ignores client-supplied source credentials.
+Server options include `sourceId`, `sourceSecret`, `serviceName` (default `sql`),
+and `shapePath` (default `/electric-sql/v1/shape/:table`). Match a custom service
+name and Shape base path on the client. Client `headers` and `onError` are passed
+to Electric for authentication and stream error handling.
+
+This plugin performs online writes with server-generated keys and physical deletes.
+A successful write resolves before its Electric echo necessarily arrives. It does
+not queue offline writes or apply optimistic updates. Electric reconnects and
+resumes live reads; the existing managed Electric plugin remains available for
+persistent offline storage and writes. Use separate service names and paths when
+installing both plugins in one application.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x-plugins",
-  "version": "5.0.8",
+  "version": "5.1.0",
   "description": "Plugins for express-x",
   "type": "module",
   "main": "./src/electric-server-plugin.mjs",
@@ -12,7 +12,9 @@
     "./electric-worker": "./src/electric-pglite-worker.mjs",
     "./sync-client": "./src/sync-client-plugin.mjs",
     "./sync-server": "./src/sync-server-plugin.mjs",
-    "./sync-algorithm": "./src/sync-algorithm.mjs"
+    "./sync-algorithm": "./src/sync-algorithm.mjs",
+    "./electric-sql-server": "./src/electric-sql-server-plugin.mjs",
+    "./electric-sql-client": "./src/electric-sql-client-plugin.mjs"
   },
   "private": false,
   "publishConfig": {

package/src/electric-sql-client-plugin.mjs

@@ -0,0 +1,52 @@
+import { Shape, ShapeStream } from '@electric-sql/client'
+
+/** Install app.sql.query(name, params) and app.sql.watch(table, filter, callback). */
+export function electricSqlClientPlugin(app, options = {}) {
+   const service = app.service(options.serviceName ?? 'sql')
+   const Stream = options.ShapeStream ?? ShapeStream
+   const LiveShape = options.Shape ?? Shape
+   const active = new Set()
+   function watch(table, filter, callback) {
+      if (typeof filter === 'function') { callback = filter; filter = {} }
+      const { where, params = [] } = filter ?? {}
+      if (typeof table !== 'string' || !table) throw new TypeError('table is required')
+      if (typeof callback !== 'function') throw new TypeError('callback is required')
+      if (where !== undefined && typeof where !== 'string') throw new TypeError('where must be SQL text')
+      if (!Array.isArray(params)) throw new TypeError('params must be an array')
+      const values = params.map(value => {
+         if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString()
+         if (typeof value === 'string' || typeof value === 'boolean' || typeof value === 'bigint'
+            || (typeof value === 'number' && Number.isFinite(value))) return String(value)
+         throw new TypeError('shape params must be strings, booleans, finite numbers, bigints or Dates; use IS NULL for null')
+      })
+      const controller = new AbortController()
+      const stream = new Stream({
+         url: `${(options.shapePath ?? '/electric-sql/v1/shape').replace(/\/$/, '')}/${encodeURIComponent(table)}`,
+         headers: options.headers,
+         onError: options.onError,
+         signal: controller.signal,
+         params: { ...(where === undefined ? {} : { where }), params: values },
+      })
+      const shape = new LiveShape(stream)
+      const unsubscribe = shape.subscribe(({ rows }) => callback([...rows]))
+      let stopped = false
+      function stop() {
+         if (stopped) return
+         stopped = true
+         unsubscribe()
+         stream.unsubscribeAll()
+         controller.abort()
+         active.delete(stop)
+      }
+      active.add(stop)
+      return stop
+   }
+   app.sql = {
+      query: (name, params = []) => service.query(name, params),
+      watch,
+      dispose() { for (const stop of active) stop() },
+   }
+   return app
+}
+
+export default electricSqlClientPlugin

package/src/electric-sql-server-plugin.mjs

@@ -0,0 +1,69 @@
+/** SQL statements execute on PostgreSQL; Electric supplies live table reads. */
+export function electricSqlServerPlugin(app, db, options = {}) {
+   const { tables, statements = {}, authorize } = options
+   if (!db || typeof db.query !== 'function') throw new TypeError('db must expose query(sql, params)')
+   if (!Array.isArray(tables) || !tables.length || tables.some(table => typeof table !== 'string' || !table)) {
+      throw new TypeError('tables must be a non-empty array of table names')
+   }
+   if (typeof authorize !== 'function') throw new TypeError('authorize(context, operation) is required')
+   const sql = new Map(Object.entries(statements))
+   for (const statement of sql.values()) {
+      if (typeof statement !== 'string' || !statement.trim()) throw new TypeError('statements must contain SQL strings')
+   }
+   const fetchImpl = options.fetch ?? globalThis.fetch
+   const upstreamUrl = new URL(options.electricUrl ?? process.env.ELECTRIC_URL ?? 'http://localhost:3000/v1/shape')
+   const shapePath = options.shapePath ?? '/electric-sql/v1/shape/:table'
+   async function check(context, operation) {
+      if (!await authorize(context, operation)) {
+         const error = new Error('forbidden')
+         error.code = 'forbidden'
+         throw error
+      }
+   }
+   app.createService(options.serviceName ?? 'sql', {
+      async query(name, params = []) {
+         if (!sql.has(name)) throw new TypeError('unknown SQL statement')
+         if (!Array.isArray(params)) throw new TypeError('params must be an array')
+         await check(this, { action: 'query', name, params })
+         return (await db.query(sql.get(name), params)).rows
+      },
+   })
+   app.get(shapePath, async (request, response, next) => {
+      try {
+         const table = request.params.table
+         if (!tables.includes(table)) return response.status(404).json({ error: 'unknown table' })
+         const target = new URL(upstreamUrl)
+         // Only Electric protocol and SQL filter parameters cross the proxy.
+         for (const [key, value] of Object.entries(request.query)) {
+            if (!['offset', 'handle', 'live', 'cursor', 'where', 'columns', 'replica'].includes(key)
+               && !/^params\[[1-9][0-9]*\]$/.test(key)) continue
+            if (typeof value !== 'string') throw new TypeError('shape parameters must be strings')
+            target.searchParams.set(key, value)
+         }
+         target.searchParams.set('table', table)
+         await check({ app, request, response, transport: 'http' }, {
+            action: 'shape', table, params: Object.fromEntries(target.searchParams),
+         })
+         if (options.sourceId) target.searchParams.set('source_id', options.sourceId)
+         if (options.sourceSecret) target.searchParams.set('secret', options.sourceSecret)
+         const controller = new AbortController()
+         const abort = () => controller.abort()
+         response.on?.('close', abort)
+         try {
+            const upstream = await fetchImpl(target, { signal: controller.signal })
+            response.status(upstream.status)
+            upstream.headers.forEach((value, key) => {
+               if (!['content-encoding', 'content-length', 'transfer-encoding', 'connection', 'set-cookie'].includes(key.toLowerCase())) {
+                  response.setHeader(key, value)
+               }
+            })
+            response.send(Buffer.from(await upstream.arrayBuffer()))
+         } finally {
+            response.off?.('close', abort)
+         }
+      } catch (error) { next(error) }
+   })
+   return { shapePath }
+}
+
+export default electricSqlServerPlugin

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

@@ -0,0 +1,74 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { electricSqlServerPlugin } from '../src/electric-sql-server-plugin.mjs'
+import { electricSqlClientPlugin } from '../src/electric-sql-client-plugin.mjs'
+
+function server(authorize = () => true) {
+   const state = { queries: [] }
+   const app = {
+      createService(name, methods) { state.service = methods },
+      get(path, handler) { state.route = handler },
+   }
+   electricSqlServerPlugin(app, { async query(...args) { state.queries.push(args); return { rows: [{ id: 1 }] } } }, {
+      tables: ['todos'], statements: { add: 'INSERT INTO todos (label) VALUES ($1) RETURNING *' },
+      authorize, sourceSecret: 'server-secret',
+      async fetch(url) { state.target = url; return new Response('[]', { headers: { 'electric-handle': 'abc' } }) },
+   })
+   return state
+}
+
+test('executes only registered SQL with bound values and caller context', async () => {
+   const context = { user: 1 }
+   const state = server((caller, operation) => caller === context && operation.name === 'add')
+   const value = "'); DROP TABLE todos; --"
+   assert.deepEqual(await state.service.query.call(context, 'add', [value]), [{ id: 1 }])
+   assert.deepEqual(state.queries[0], ['INSERT INTO todos (label) VALUES ($1) RETURNING *', [value]])
+   await assert.rejects(state.service.query.call(context, 'toString'), /unknown/)
+   await assert.rejects(state.service.query.call({}, 'add', ['blocked']), { code: 'forbidden' })
+   assert.equal(state.queries.length, 1)
+})
+
+test('shape proxy pins table and credentials and preserves SQL parameters', async () => {
+   const state = server()
+   const response = { status() { return this }, setHeader() {}, send(body) { this.body = body } }
+   await state.route({ params: { table: 'todos' }, query: {
+      table: 'private', secret: 'attacker', source_id: 'attacker', offset: '-1', where: 'id = $1', 'params[1]': '123',
+   } }, response, error => { throw error })
+   assert.equal(state.target.searchParams.get('table'), 'todos')
+   assert.equal(state.target.searchParams.get('secret'), 'server-secret')
+   assert.equal(state.target.searchParams.get('source_id'), null)
+   assert.equal(state.target.searchParams.get('params[1]'), '123')
+   assert.equal(response.body.toString(), '[]')
+   const denied = server(() => false)
+   let failure
+   await denied.route({ params: { table: 'todos' }, query: {} }, response, error => { failure = error })
+   assert.equal(failure.code, 'forbidden')
+   assert.equal(denied.target, undefined)
+})
+
+test('client binds SQL filters and stops network work on unsubscribe or disposal', async () => {
+   const streams = []
+   class Stream {
+      constructor(options) { this.options = options; streams.push(this) }
+      unsubscribeAll() { this.stopped = true }
+   }
+   class Shape {
+      constructor(stream) { this.stream = stream }
+      subscribe(callback) { this.stream.emit = callback; return () => { this.stream.unsubscribed = true } }
+   }
+   const app = { service: () => ({ query: async (...args) => args }) }
+   electricSqlClientPlugin(app, { ShapeStream: Stream, Shape })
+   assert.deepEqual(await app.sql.query('add', ['hello']), ['add', ['hello']])
+   let rows
+   const stop = app.sql.watch('todos', { where: 'done = $1', params: [false] }, value => { rows = value })
+   assert.deepEqual(streams[0].options.params, { where: 'done = $1', params: ['false'] })
+   streams[0].emit({ rows: [{ id: 1 }] })
+   assert.deepEqual(rows, [{ id: 1 }])
+   stop()
+   stop()
+   assert.ok(streams[0].stopped && streams[0].unsubscribed && streams[0].options.signal.aborted)
+   app.sql.watch('todos', () => {})
+   app.sql.dispose()
+   assert.ok(streams[1].options.signal.aborted)
+   assert.throws(() => app.sql.watch('todos', { params: [null] }, () => {}), /IS NULL/)
+})