@jcbuisson/express-x-plugins 4.0.6 → 4.0.8

package/README.md

@@ -1,5 +1,23 @@
+
 # express-x-plugins
 
+
+IMPORTANT
+
+# set lc_messages=C for the PostgreSQL role so Electric receives recognizable English errors
+ALTER ROLE chris SET lc_messages = 'C';
+
+# ALLOW POSTGRES LOGICAL REPLICATION
+ALTER SYSTEM SET wal_level = 'logical';
+ALTER SYSTEM SET max_replication_slots = 10;
+ALTER SYSTEM SET max_wal_senders = 10;
+ALTER ROLE chris WITH REPLICATION;
+
+## restart postgres
+sudo systemctl restart postgresql
+
+
+
 Currently includes:
 
 - a plugin which preserves room membership and socket data across page reloads
@@ -58,12 +76,16 @@ app.configure(electricOfflinePlugin, db, [
 
 This registers one Express-X service per model with the familiar API:
 
-- `create(uid, data)`
-- `update(uid, data)`
-- `delete(uid)`
+- `findUnique(where)`
+- `findMany(where, queryOptions)`
+- `create(id, data)` for a client-generated primary key
+- `create(data)` for a database-generated primary key
+- `update(id, data)`
+- `delete(id)`
 
-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.
+The client model provides synchronized reads through `findMany(where)` and
+`getObservable(where)`. The service also exposes direct one-shot server reads
+when synchronization is not required.
 
 Mutation methods return the created, updated, or deleted row directly.
 
@@ -82,10 +104,15 @@ app.configure(electricClientPlugin, {
   shapePath: '/electric/v1/shape',
 })
 
+// Client-generated UUID stored in the default `uid` primary key:
 const todo = app.createElectricModel('todos')
 
+// Or, for a database-generated primary key such as SERIAL/IDENTITY:
+const numberedTodo = app.createElectricModel('numberedTodos', {
+  idGeneration: 'server',
+})
+
 const incompleteTodos = await todo.findMany({ completed: false })
-const selectedTodo = await todo.findUnique({ uid })
 
 const subscription = todo.getObservable({ completed: false }).subscribe(rows => {
   console.log(rows)
@@ -96,14 +123,16 @@ await todo.create({ title: 'Learn Shapes', completed: false })
 await todo.update(uid, { completed: true })
 await todo.remove(uid)
 
+const created = await numberedTodo.create({ title: 'Assigned by PostgreSQL' })
+console.log(created.id)
+
 subscription.unsubscribe()
 ```
 
 `findMany(where)` resolves with all matching rows from the first synchronized Shape emission.
 
-`findUnique(where)` resolves with the first matching row, or `null` when there is no match.
-Both unsubscribe after their first emission; if called within a Vue scope, they also unsubscribe
-if that scope is disposed before a result arrives.
+It unsubscribes after the first emission; if called within a Vue scope, it also
+unsubscribes if that scope is disposed before a result arrives.
 
 Object filters use parameterized Electric Shape predicates. Exact values,
 `null`, and `gt`/`gte`/`lt`/`lte` ranges are supported.
@@ -113,7 +142,7 @@ configured table, and Electric source credentials stay server-side.
 
 ### Model configuration
 
-Models may be strings (table, service name, and default `uid` key) or objects:
+Server models may be strings (table, service name, and default `uid` key) or objects:
 
 ```js
 { name: 'todo', table: 'todos', primaryKey: 'id' }
@@ -122,6 +151,10 @@ Models may be strings (table, service name, and default `uid` key) or objects:
 Names are restricted to simple PostgreSQL identifiers. Values are always sent
 as query parameters; range filters support `gt`, `gte`, `lt`, and `lte`.
 
+Client models default to `idGeneration: 'client'`, which generates a UUID and calls
+`create(id, data)`. Set `idGeneration: 'server'` to call `create(data)` and let a
+PostgreSQL default, sequence, or identity column generate the primary key.
+
 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.
@@ -137,8 +170,16 @@ services:
     environment:
       DATABASE_URL: postgresql://user:password@host.docker.internal:5432/mydb
       ELECTRIC_INSECURE: "true"
+      ELECTRIC_STORAGE: FAST_FILE
+      ELECTRIC_PERSISTENT_STATE: FILE
+      ELECTRIC_STORAGE_DIR: /var/lib/electric
     ports:
       - "3001:3000"
+    volumes:
+      - electric_mydb_data:/var/lib/electric
+
+volumes:
+  electric_mydb_data:
 ```
 
 ```

package/package.json

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

package/src/electric-client-plugin.mjs

@@ -2,20 +2,31 @@ import { Shape, ShapeStream } from '@electric-sql/client'
 import { firstValueFrom, Observable, Subject, takeUntil } from 'rxjs'
 import { getCurrentScope, onScopeDispose, ref } from 'vue'
 
+export class DisposableShape extends Shape {
+   subscribe(callback) {
+      const unsubscribe = super.subscribe(callback)
+      return () => {
+         unsubscribe()
+         if (this.numSubscribers === 0) this.stream.unsubscribeAll()
+      }
+   }
+}
+
 
 /**
  * Add Electric-backed reactive models to an Express-X client.
  *
  * Usage:
  *   electricClientPlugin(app)
- *   const todo = app.createElectricModel('todos')
+ *   const todo = app.createElectricModel('todos') // primary key is provided by client
+ *   const todo = app.createElectricModel('todos', { idGeneration: 'server' }) // primary key is server-generated
  *   todo.getObservable({ completed: false }).subscribe(...)
  *   const completedTodos = await todo.findMany({ completed: false })
  */
 export function electricClientPlugin(app, options = {}) {
    const shapePath = options.shapePath ?? '/electric/v1/shape'
    const ShapeStreamClass = options.ShapeStream ?? ShapeStream
-   const ShapeClass = options.Shape ?? Shape
+   const ShapeClass = options.Shape ?? DisposableShape
    const ObservableClass = options.Observable ?? Observable
 
    function createElectricModel(modelName, modelOptions = {}) {
@@ -23,6 +34,10 @@ export function electricClientPlugin(app, options = {}) {
       const service = app.service(modelName)
       const url = modelOptions.url ?? modelPath(shapePath, modelName)
       const streamOptions = modelOptions.streamOptions ?? {}
+      const idGeneration = modelOptions.idGeneration ?? 'client'
+      if (!['client', 'server'].includes(idGeneration)) {
+         throw new TypeError("idGeneration must be 'client' or 'server'")
+      }
 
       function getObservable(where = {}) {
          // Validate eagerly
@@ -62,17 +77,18 @@ export function electricClientPlugin(app, options = {}) {
 
       async function create(data) {
          assertPlainObject(data, 'mutation data')
+         if (idGeneration === 'server') return service.create(data)
          const uid = globalThis.crypto?.randomUUID?.()
          if (!uid) throw new Error('crypto.randomUUID() is required')
          return service.create(uid, data)
       }
 
-      async function update(uid, data) {
-         return service.update(uid, data)
+      async function update(id, data) {
+         return service.update(id, data)
       }
 
-      async function remove(uid) {
-         return service.delete(uid)
+      async function remove(id) {
+         return service.delete(id)
       }
 
       return { getObservable, findMany, create, update, remove }

package/src/electric-server-plugin.mjs

@@ -26,71 +26,86 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
       }
    }
 
+   // for each model 'name', there is a service 'name' with methods 'findUnique', 'findMany', 'create', 'update', 'delete'
    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
-         // },
-
-         create: async function(uid, data) {
-            await authorize(this, model.name, 'create', [uid, data])
-            assertPlainObject(data, 'mutation data')
-            const safeData = { ...data, [model.primaryKey]: uid }
+
+         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
+         },
+
+         // create(data): the primary key is server-generated
+         // create(uid, data): uid (the primary key) is provided by the client
+         create: async function(idOrData, data) {
+            const hasClientId = data !== undefined
+            const mutationData = hasClientId ? data : idOrData
+            await authorize(this, model.name, 'create', hasClientId ? [idOrData, mutationData] : [mutationData])
+            assertPlainObject(mutationData, 'mutation data')
+            const safeData = hasClientId
+               ? { ...mutationData, [model.primaryKey]: idOrData }
+               : { ...mutationData }
             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 => {
+               if (entries.length === 0) {
+                  const result = await client.query(`INSERT INTO ${model.quotedTable} DEFAULT VALUES RETURNING *`)
+                  return result.rows[0]
+               }
+               const conflictAction = hasClientId
+                  ? ' ON CONFLICT (' + model.quotedPrimaryKey + ') DO UPDATE SET '
+                     + (entries.some(([column]) => column !== model.primaryKey)
+                        ? entries
+                           .filter(([column]) => column !== model.primaryKey)
+                           .map(([column]) => `${quoteIdentifier(column, 'data column')} = EXCLUDED.${quoteIdentifier(column, 'data column')}`)
+                           .join(', ')
+                        : `${model.quotedPrimaryKey} = EXCLUDED.${model.quotedPrimaryKey}`)
+                  : ''
                const result = await client.query(
-                  `INSERT INTO ${model.quotedTable} (${columns.join(', ')}) VALUES (${parameters.join(', ')}) `
-                  + `ON CONFLICT (${model.quotedPrimaryKey}) ${conflictAction}`
-                  + ' RETURNING *',
+                  `INSERT INTO ${model.quotedTable} (${columns.join(', ')}) VALUES (${parameters.join(', ')})`
+                  + conflictAction + ' RETURNING *',
                   values,
                )
                return result.rows[0]
             })
          },
 
-         update: async function(uid, data) {
-            await authorize(this, model.name, 'update', [uid, data])
+         update: async function(id, data) {
+            await authorize(this, model.name, 'update', [id, 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],
+                  [...set.values, id],
                )
                return result.rows[0]
             })
          },
 
-         delete: async function(uid) {
-            await authorize(this, model.name, 'delete', [uid])
+         delete: async function(id) {
+            await authorize(this, model.name, 'delete', [id])
             return withTransaction(db, async client => {
                const result = await client.query(
-                  `DELETE FROM ${model.quotedTable} WHERE ${model.quotedPrimaryKey} = $1 RETURNING *`, [uid],
+                  `DELETE FROM ${model.quotedTable} WHERE ${model.quotedPrimaryKey} = $1 RETURNING *`, [id],
                )
                return result.rows[0]
             })
@@ -160,8 +175,7 @@ function normalizeModels(models) {
 }
 
 function assertPlainObject(value, label) {
-   if (!value || typeof value !== 'object' || Array.isArray(value)
-      || Object.prototype.toString.call(value) !== '[object Object]') {
+   if (!value || typeof value !== 'object' || Array.isArray(value) || Object.prototype.toString.call(value) !== '[object Object]') {
       throw new TypeError(`${label} must be a plain object`)
    }
 }

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

@@ -2,7 +2,11 @@ import assert from 'node:assert/strict'
 import test from 'node:test'
 import { effectScope, isRef } from 'vue'
 
-import { electricClientPlugin, whereToElectricParams } from '../src/electric-client-plugin.mjs'
+import {
+   DisposableShape,
+   electricClientPlugin,
+   whereToElectricParams,
+} from '../src/electric-client-plugin.mjs'
 
 class FakeStream {
    static instances = []
@@ -36,6 +40,19 @@ class EmptyShape {
    }
 }
 
+test('DisposableShape tears down its stream with its last subscriber', () => {
+   const stream = {
+      subscribe() { return () => {} },
+      unsubscribeAll() { this.unsubscribed = true },
+   }
+   const shape = new DisposableShape(stream)
+   const unsubscribe = shape.subscribe(() => {})
+
+   unsubscribe()
+
+   assert.equal(stream.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',
@@ -143,3 +160,25 @@ test('model mutations retain the simple Express-X API', async () => {
    await todo.remove(created.uid)
    assert.deepEqual(calls.map(call => call[0]), ['create', 'update', 'remove'])
 })
+
+test('model creation supports server-generated IDs', async () => {
+   const calls = []
+   const service = {
+      async create(...args) { calls.push(args); return { id: 42, ...args[0] } },
+   }
+   const app = { service: () => service }
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })
+   const todo = app.createElectricModel('todos', { idGeneration: 'server' })
+
+   assert.deepEqual(await todo.create({ title: 'Test' }), { id: 42, title: 'Test' })
+   assert.deepEqual(calls, [[{ title: 'Test' }]])
+})
+
+test('rejects an unsupported ID generation strategy', () => {
+   const app = { service: () => ({}) }
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })
+   assert.throws(
+      () => app.createElectricModel('todos', { idGeneration: 'database-ish' }),
+      /idGeneration/,
+   )
+})

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

@@ -36,6 +36,18 @@ test('registers the mutation API', async () => {
    await assert.rejects(service.create.call({}, 'bad', []), /plain object/)
 })
 
+test('allows the database to generate a primary key', async () => {
+   const { services, queries } = fixture()
+   const service = services.get('todos')
+
+   await service.create.call({}, { label: 'generated id' })
+   assert.match(queries[0].sql, /^INSERT INTO "todos" \("label"\) VALUES \(\$1\) RETURNING \*$/)
+   assert.doesNotMatch(queries[0].sql, /ON CONFLICT/)
+
+   await service.create.call({}, {})
+   assert.equal(queries[1].sql, 'INSERT INTO "todos" DEFAULT VALUES RETURNING *')
+})
+
 test('requires authorization and reports forbidden calls', async () => {
    const { services } = fixture({ authorize: async () => false })
    await assert.rejects(