@jcbuisson/express-x-plugins 4.0.5 → 4.0.7

package/README.md

@@ -1,5 +1,10 @@
+
 # express-x-plugins
 
+
+IMPORTANT: set lc_messages=C for the PostgreSQL chris role so Electric receives recognizable English errors.
+
+
 Currently includes:
 
 - a plugin which preserves room membership and socket data across page reloads
@@ -58,16 +63,15 @@ 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(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.
 
-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
 
@@ -84,8 +88,14 @@ 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 })
 
@@ -98,6 +108,9 @@ 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()
 ```
 
@@ -115,7 +128,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' }
@@ -124,6 +137,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.

package/package.json

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

package/src/electric-client-plugin.mjs

@@ -23,6 +23,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,21 +66,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')
-         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
+      async function update(id, data) {
+         return service.update(id, data)
       }
 
-      async function remove(uid) {
-         const [value] = await service.deleteWithMeta(uid, new Date().toISOString())
-         return value
+      async function remove(id) {
+         return service.delete(id)
       }
 
       return { getObservable, findMany, create, update, remove }

package/src/electric-server-plugin.mjs

@@ -28,77 +28,83 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
 
    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 }
+         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) (primary key is server-generated) or create(uid, data) (uid is the primary key, client-generated)
+         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,
                )
-               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(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],
                )
-               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(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],
                )
-               const txid = await transactionId(client)
-               return [result.rows[0], mutationMeta(uid, 'deleted_at', timestamp, txid)]
+               return result.rows[0]
             })
          },
       })
@@ -166,8 +172,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`)
    }
 }
@@ -226,21 +231,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 })
@@ -143,3 +143,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

@@ -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,37 @@ 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('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(
-      services.get('todos').createWithMeta.call({}, 'one', { label: 'no' }, new Date()),
+      services.get('todos').create.call({}, 'one', { label: 'no' }),
       error => error.code === 'forbidden',
    )
 })