@jcbuisson/express-x-plugins 4.0.6 → 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,9 +63,10 @@ app.configure(electricOfflinePlugin, db, [
 
 This registers one Express-X service per model with the familiar API:
 
-- `create(uid, data)`
-- `update(uid, data)`
-- `delete(uid)`
+- `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.
@@ -82,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 })
 
@@ -96,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()
 ```
 
@@ -113,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' }
@@ -122,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.6",
+  "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,17 +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')
          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

@@ -28,69 +28,81 @@ 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
-         // },
-
-         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) (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,
                )
                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 +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`)
    }
 }

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

@@ -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

@@ -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(