@jcbuisson/express-x-plugins 4.0.4 → 4.0.6

package/README.md

@@ -1,23 +1,43 @@
-# express-x-electric
+# express-x-plugins
+
+Currently includes:
+
+- a plugin which preserves room membership and socket data across page reloads
+- a plugin integrating ElectricSQL sync engine into express-x, which greatly simplifies relational database
+access and provides powerful local-first features
 
-The smallest useful ElectricSQL integration for Express-X. Express-X handles
-authorized PostgreSQL mutations; Electric's Shape API streams those changes to
-clients: Electric is the sync engine.
 
 ## Install
 
 ```sh
-npm install @jcbuisson/express-x-electric pg
+npm install @jcbuisson/express-x-plugins
 ```
 
-This server-only installation does not install the browser Electric client or RxJS.
 
-## Server
+## Reload plugin
+
+### Server
+
+```js
+import { reloadPlugin } from '@jcbuisson/express-x-plugins/reload-server'
+```
+
+
+## Local-first Postgres plugin
+
+The smallest useful ElectricSQL integration for Express-X. Express-X handles authorized PostgreSQL mutations;
+Electric's Shape API streams those changes to clients: Electric is the sync engine.
+
+### Server
+
+```sh
+npm install pg
+```
 
 ```js
 import { Pool } from 'pg'
-import { expressX } from '@jcbuisson/express-x'
-import { electricOfflinePlugin } from '@jcbuisson/express-x-electric'
+import { expressX } from '@jcbuisson/express-x/server'
+import { electricOfflinePlugin } from '@jcbuisson/express-x-plugins/electric-server'
 
 const app = expressX()
 const db = new Pool({ connectionString: process.env.DATABASE_URL })
@@ -38,27 +58,25 @@ app.configure(electricOfflinePlugin, db, [
 
 This registers one Express-X service per model with the familiar API:
 
-- `createWithMeta(uid, data, createdAt)`
-- `updateWithMeta(uid, data, updatedAt)`
-- `deleteWithMeta(uid, deletedAt)`
+- `create(uid, data)`
+- `update(uid, data)`
+- `delete(uid)`
 
 Synchronized reads are provided client-side by `findMany(where)`, `findUnique(where)`, and `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.
+Mutation methods return the created, updated, or deleted row directly.
 
-## Client Shape
+### Client
 
 Install the optional client dependencies in the browser application:
 
 ```sh
-npm install @jcbuisson/express-x-electric @electric-sql/client rxjs vue
+npm install @electric-sql/client rxjs
 ```
 
 ```js
-import { electricClientPlugin } from '@jcbuisson/express-x-electric/client'
+import { electricClientPlugin } from '@jcbuisson/express-x-plugins/electric-client'
 
 app.configure(electricClientPlugin, {
   shapePath: '/electric/v1/shape',
@@ -93,7 +111,7 @@ Object filters use parameterized Electric Shape predicates. Exact values,
 All Electric cursor parameters are forwarded. The client cannot override the
 configured table, and Electric source credentials stay server-side.
 
-## Model configuration
+### Model configuration
 
 Models may be strings (table, service name, and default `uid` key) or objects:
 
@@ -108,7 +126,7 @@ 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.
 
-## Run Electric from Docker
+### Run Electric from Docker
 
 A local install of the Electric sync engine requires Elixir and Erlang; it is simpler to use a pre-built Docker image.
 

package/package.json

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

package/src/electric-client-plugin.mjs

@@ -10,6 +10,7 @@ import { getCurrentScope, onScopeDispose, ref } from 'vue'
  *   electricClientPlugin(app)
  *   const todo = app.createElectricModel('todos')
  *   todo.getObservable({ completed: false }).subscribe(...)
+ *   const completedTodos = await todo.findMany({ completed: false })
  */
 export function electricClientPlugin(app, options = {}) {
    const shapePath = options.shapePath ?? '/electric/v1/shape'
@@ -47,13 +48,6 @@ export function electricClientPlugin(app, options = {}) {
          })
       }
 
-      function getVueRef(where = {}) {
-         const value = ref([])
-         const subscription = getObservable(where).subscribe(rows => { value.value = rows })
-         if (getCurrentScope()) onScopeDispose(() => subscription.unsubscribe())
-         return value
-      }
-
       function findMany(where = {}) {
          const observable = getObservable(where)
          if (!getCurrentScope()) return firstValueFrom(observable)
@@ -66,30 +60,22 @@ export function electricClientPlugin(app, options = {}) {
          return firstValueFrom(observable.pipe(takeUntil(scopeDisposed)))
       }
 
-      function findUnique(where = {}) {
-         return findMany(where).then(rows => rows[0] ?? null)
-      }
-
       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
+         return service.create(uid, data)
       }
 
       async function update(uid, data) {
-         const [value] = await service.updateWithMeta(uid, data, new Date().toISOString())
-         return value
+         return service.update(uid, data)
       }
 
       async function remove(uid) {
-         const [value] = await service.deleteWithMeta(uid, new Date().toISOString())
-         return value
+         return service.delete(uid)
       }
 
-      return { getObservable, getVueRef, findMany, findUnique, create, update, remove }
+      return { getObservable, findMany, create, update, remove }
    }
 
    return Object.assign(app, { createElectricModel })

package/src/electric-server-plugin.mjs

@@ -50,10 +50,9 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
          //    return (await db.query(sql, values)).rows
          // },
 
-         createWithMeta: async function(uid, data, createdAt = new Date()) {
-            await authorize(this, model.name, 'createWithMeta', [uid, data, createdAt])
+         create: async function(uid, data) {
+            await authorize(this, model.name, 'create', [uid, data])
             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'))
@@ -71,34 +70,29 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
                   + ' RETURNING *',
                   values,
                )
-               const txid = await transactionId(client)
-               return [result.rows[0], mutationMeta(uid, 'created_at', timestamp, txid)]
+               return result.rows[0]
             })
          },
 
-         updateWithMeta: async function(uid, data, updatedAt = new Date()) {
-            await authorize(this, model.name, 'updateWithMeta', [uid, data, updatedAt])
-            const timestamp = normalizeTimestamp(updatedAt, 'updated_at')
+         update: async function(uid, data) {
+            await authorize(this, model.name, 'update', [uid, data])
             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)]
+               return result.rows[0]
             })
          },
 
-         deleteWithMeta: async function(uid, deletedAt = new Date()) {
-            await authorize(this, model.name, 'deleteWithMeta', [uid, deletedAt])
-            const timestamp = normalizeTimestamp(deletedAt, 'deleted_at')
+         delete: async function(uid) {
+            await authorize(this, model.name, 'delete', [uid])
             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)]
+               return result.rows[0]
             })
          },
       })
@@ -226,21 +220,6 @@ async function withTransaction(db, operation) {
    }
 }
 
-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())) {

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

@@ -130,9 +130,9 @@ test('findUnique resolves with the first matching row or null', async () => {
 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] }, {}] },
+      async create(...args) { calls.push(['create', ...args]); return { uid: args[0], ...args[1] } },
+      async update(...args) { calls.push(['update', ...args]); return { uid: args[0], ...args[1] } },
+      async delete(...args) { calls.push(['remove', ...args]); return { uid: args[0] } },
    }
    const app = { service: () => service }
    electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })

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

@@ -10,7 +10,6 @@ function fixture({ authorize = async () => true, fetch } = {}) {
    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' }] }
       },
    }
@@ -22,27 +21,25 @@ function fixture({ authorize = async () => true, fetch } = {}) {
    return { app, db, services, routes, queries, registration }
 }
 
-test('registers the familiar mutation API', async () => {
+test('registers the mutation API', async () => {
    const { services, queries } = fixture()
    const service = services.get('todos')
    assert.deepEqual(Object.keys(service), [
-      'createWithMeta', 'updateWithMeta', 'deleteWithMeta',
+      'create', 'update', 'delete',
    ])
 
-   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')
+   const value = await service.create.call({}, 'one', { label: 'new' })
+   assert.equal(value.uid, 'one')
 
-   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/)
+   await service.create.call({}, 'only-id', {})
+   assert.match(queries[1].sql, /DO UPDATE SET "uid" = EXCLUDED\."uid"/)
+   await assert.rejects(service.create.call({}, 'bad', []), /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()),
+      services.get('todos').create.call({}, 'one', { label: 'no' }),
       error => error.code === 'forbidden',
    )
 })