@jcbuisson/express-x-plugins 5.0.6 → 5.0.7

package/README.md

@@ -150,11 +150,12 @@ app.configure(electricClientPlugin, {
   shapePath: '/electric/v1/shape',
 })
 
-// Client-generated UUID stored in the default `id` primary key:
+// 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', {
+  primaryKey: 'id',
   idGeneration: 'server',
 })
 
@@ -192,7 +193,7 @@ app.configure(electricClientPlugin, {
   onError: (error, { modelName }) => console.error(modelName, error),
 })
 
-const ranges = app.createElectricModel('range', { primaryKey: 'uid' })
+const ranges = app.createElectricModel('range')
 const subscription = ranges.getObservable().subscribe(rows => console.log(rows))
 await ranges.create({ label: 'Works offline' })
 await ranges.update(uid, { label: 'Edited offline' })
@@ -365,3 +366,12 @@ Disposing a model removes its network listeners. Browser connectivity is a hint;
 requests can still fail while reported online and retain the usual retry behavior.
 For custom runtimes/tests, plugin options `network` and `networkEvents` can supply
 the connectivity state and an EventTarget respectively.
+
+
+Models default to `primaryKey: 'uid'` on both client and server. Set
+`primaryKey: 'id'` explicitly for tables that use `id`.
+
+With `sync: true`, the sync owner's Electric stream stays active when its tab is
+hidden because it serves other tabs too. To customize this behavior, pass
+`streamOptions.runtimeVisibility` to `createElectricModel`. Other stream options
+are preserved. Independent streams retain Electric's normal visibility behavior.

package/package.json

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

package/src/electric-client-plugin.mjs

@@ -9,7 +9,7 @@ import { createManagedSync } from './electric-managed-sync.mjs'
  *
  * Usage:
  *   electricClientPlugin(app)
- *   const todoModel = app.createElectricModel('todos') // primary key is automatically provided by server (auto-increment)
+ *   const todoModel = app.createElectricModel('todos') // client-generated UUID in the default uid primary key
  *   const todoMilk = await todoModel.create({ label: "Buy milk" })
  *   todoMilk.update({ completed: true })
  *   todoModel.getObservable({ completed: false }).subscribe(...) // subscribe to an observable for todos with completed===false
@@ -26,7 +26,7 @@ export function electricClientPlugin(app, options = {}) {
 
    function createElectricModel(modelName, modelOptions = {}) {
       quoteIdentifier(modelName)
-      quoteIdentifier(modelOptions.primaryKey ?? 'id')
+      quoteIdentifier(modelOptions.primaryKey ?? 'uid')
       if (managed) {
          if (modelOptions.idGeneration === 'server') throw new TypeError('sync models require client-generated UUIDs')
          return managed.model(modelName, modelOptions)
@@ -39,7 +39,7 @@ export function electricClientPlugin(app, options = {}) {
       const url = modelOptions.url ?? modelPath(shapePath, modelName)
       if (modelOptions.localDb) return createOfflineElectricModel({
          db: modelOptions.localDb, service, modelName, url,
-         primaryKey: modelOptions.primaryKey ?? 'id',
+         primaryKey: modelOptions.primaryKey ?? 'uid',
          ShapeStreamClass, ShapeClass,
          ownsSync: modelOptions.ownsSync ?? true,
          channel: modelOptions.channel,
@@ -50,7 +50,7 @@ export function electricClientPlugin(app, options = {}) {
       })
       const streamOptions = modelOptions.streamOptions ?? {}
       const idGeneration = modelOptions.idGeneration ?? 'client'
-      const primaryKey = modelOptions.primaryKey ?? 'id'
+      const primaryKey = modelOptions.primaryKey ?? 'uid'
       quoteIdentifier(primaryKey)
       if (!['client', 'server'].includes(idGeneration)) {
          throw new TypeError("idGeneration must be 'client' or 'server'")

package/src/electric-managed-sync.mjs

@@ -47,7 +47,7 @@ export function createManagedSync(options, createModel) {
       if (closed) throw new Error('Electric sync has been disposed')
       const existing = models.get(name)
       if (existing) {
-         if (existing.primaryKey !== (modelOptions.primaryKey ?? 'id')) throw new TypeError('A cached sync model cannot change primaryKey')
+         if (existing.primaryKey !== (modelOptions.primaryKey ?? 'uid')) throw new TypeError('A cached sync model cannot change primaryKey')
          return existing.api
       }
       let active = true
@@ -66,7 +66,15 @@ export function createManagedSync(options, createModel) {
       }
       const ready = getDatabase().then(async db => {
          channel = new Channel(`express-x:${databaseName}:${name}`)
-         offline = createModel(name, { ...modelOptions, network, localDb: db, channel, ownsSync: false, onError: report })
+         // The sync owner serves every tab, even while its own tab is hidden.
+         const streamOptions = {
+            ...modelOptions.streamOptions,
+            runtimeVisibility: modelOptions.streamOptions?.runtimeVisibility ?? {
+               getCurrentState: () => 'visible',
+               subscribe: () => () => {},
+            },
+         }
+         offline = createModel(name, { ...modelOptions, streamOptions, network, localDb: db, channel, ownsSync: false, onError: report })
          const prepared = preparation.then(() => offline.prepare())
          preparation = prepared.catch(() => {})
          await prepared
@@ -153,7 +161,7 @@ export function createManagedSync(options, createModel) {
          flushQueue: () => invoke('flushQueue'),
          getStatus: async () => ({ ...await invoke('getStatus'), error: error?.message ?? null }),
       }
-      models.set(name, { api, primaryKey: modelOptions.primaryKey ?? 'id' })
+      models.set(name, { api, primaryKey: modelOptions.primaryKey ?? 'uid' })
       return api
    }
    async function dispose() {

package/src/electric-server-plugin.mjs

@@ -253,7 +253,7 @@ function normalizeModels(models) {
       }
       const name = config.name
       const table = config.table ?? name
-      const primaryKey = config.primaryKey ?? 'id'
+      const primaryKey = config.primaryKey ?? 'uid'
       quoteIdentifier(name, 'model name')
       const tombstoneData = config.tombstoneData ?? {}
       if (typeof tombstoneData !== 'function') validateTombstoneData(tombstoneData, primaryKey)

package/test/electric-managed-sync.test.mjs

@@ -76,13 +76,26 @@ test('managed models initialize automatically, share one database, and cache mod
       assert.equal(dataDir, 'idb://test-db'); created++; return db
    } })
    try {
-      const users = app.createElectricModel('users', { primaryKey: 'uid' })
-      const ranges = app.createElectricModel('ranges', { primaryKey: 'uid' })
+      const users = app.createElectricModel('users')
+      const customVisibility = { getCurrentState: () => 'hidden', subscribe: () => () => {} }
+      const ranges = app.createElectricModel('ranges', { streamOptions: { runtimeVisibility: customVisibility, params: { test: 'preserved' } } })
       assert.equal(app.createElectricModel('users', { primaryKey: 'uid' }), users)
-      assert.throws(() => app.createElectricModel('users'), /primaryKey/)
+      assert.equal(app.createElectricModel('users'), users)
+      assert.throws(() => app.createElectricModel('users', { primaryKey: 'id' }), /primaryKey/)
       const row = await users.create({ name: 'Works before prepare' })
       await ranges.prepare()
       assert.equal(created, 1)
+      await until(() => Stream.instances.some(stream => stream.options.url.endsWith('/users')))
+      const visibility = Stream.instances.findLast(stream => stream.options.url.endsWith('/users')).options.runtimeVisibility
+      assert.equal(visibility.getCurrentState(), 'visible')
+      let notified = false
+      const cleanup = visibility.subscribe(() => { notified = true })
+      cleanup()
+      assert.equal(notified, false)
+      await until(() => Stream.instances.some(stream => stream.options.url.endsWith('/ranges')))
+      const rangeOptions = Stream.instances.findLast(stream => stream.options.url.endsWith('/ranges')).options
+      assert.equal(rangeOptions.runtimeVisibility, customVisibility)
+      assert.deepEqual(rangeOptions.params, { test: 'preserved' })
       assert.equal((await users.findUnique({ uid: row.uid })).name, row.name)
    } finally {
       await app.disposeElectricSync()
@@ -100,8 +113,8 @@ test('only one tab streams and flushes; follower edits broadcast and ownership t
    const before = Stream.instances.length
    let subscription
    try {
-      const owner = first.createElectricModel('todos')
-      const follower = second.createElectricModel('todos')
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
       await owner.prepare()
       await follower.prepare()
       await until(() => Stream.instances.length === before + 1)
@@ -137,8 +150,8 @@ test('stopping a waiting follower cancels takeover; restart can acquire ownershi
    const second = configure(db, locks)
    const before = Stream.instances.length
    try {
-      const owner = first.createElectricModel('todos')
-      const follower = second.createElectricModel('todos')
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
       await owner.prepare(); await follower.prepare()
       await until(() => Stream.instances.length === before + 1)
       follower.stop()
@@ -169,8 +182,8 @@ test('a returning sync owner preserves shared rows until its new snapshot arrive
    const changed = { ...original, title: 'updated by next owner', version: '2' }
    const added = { id: crypto.randomUUID(), title: 'added by next owner', version: '2', deleted: false }
    try {
-      const owner = first.createElectricModel('todos')
-      const follower = second.createElectricModel('todos')
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
       await owner.prepare(); await follower.prepare()
       await until(() => Stream.instances.length === before + 1)
       Stream.instances.at(-1).shape.emit({ rows: [original] })
@@ -209,7 +222,7 @@ test('initialization errors reject writes and observable reads and call onError'
       createDatabase: async () => { throw error },
       onError: cause => reported.push(cause),
    })
-   const model = app.createElectricModel('todos')
+   const model = app.createElectricModel('todos', { primaryKey: 'id' })
    await assert.rejects(model.create({ title: 'No silent failure' }), /load assets/)
    await new Promise(resolve => model.getObservable().subscribe({ error: cause => {
       assert.equal(cause, error); resolve()
@@ -239,7 +252,7 @@ test('default worker errors and timeouts reject preparation instead of hanging',
          terminate() { terminated = true }
       }
       const app = configure(undefined, new Locks(), {}, { workerFactory: () => new Worker(), initTimeoutMs: 30 })
-      const model = app.createElectricModel('todos')
+      const model = app.createElectricModel('todos', { primaryKey: 'id' })
       await assert.rejects(model.prepare(), triggerError ? /module not found/ : /timed out/)
       assert.equal(terminated, true)
       await assert.rejects(app.disposeElectricSync())
@@ -266,7 +279,7 @@ test('snapshots and reads recover after a database leader changes', async () =>
    const app = configure(shared, new Locks())
    const before = Stream.instances.length
    try {
-      const model = app.createElectricModel('todos')
+      const model = app.createElectricModel('todos', { primaryKey: 'id' })
       await model.prepare()
       await until(() => Stream.instances.length === before + 1)
       failSnapshot = true
@@ -315,8 +328,8 @@ test('network lifecycle preserves offline edits, transfers ownership and respect
    const before = Stream.instances.length
    let subscription
    try {
-      const owner = first.createElectricModel('todos')
-      const follower = second.createElectricModel('todos')
+      const owner = first.createElectricModel('todos', { primaryKey: 'id' })
+      const follower = second.createElectricModel('todos', { primaryKey: 'id' })
       await owner.prepare(); await follower.prepare()
       let rows = []
       subscription = follower.getObservable().subscribe(value => { rows = value })

package/test/electric-offline-model.test.mjs

@@ -22,14 +22,14 @@ test('edits survive a committed create whose response was lost', async () => {
    let model
    try {
       await server.exec('CREATE TABLE todos (id UUID PRIMARY KEY, title TEXT NOT NULL)')
-      await prepareElectricSyncSchema(server, [{ name: 'todos', tombstoneData: { title: '' } }])
+      await prepareElectricSyncSchema(server, [{ name: 'todos', primaryKey: 'id', tombstoneData: { title: '' } }])
       let service
       const pool = {
          query: server.query.bind(server),
          async connect() { return { query: server.query.bind(server), release() {} } },
       }
       electricServerPlugin({ createService(_name, methods) { service = methods }, get() {} }, pool,
-         [{ name: 'todos', tombstoneData: { title: '' } }], { sync: true })
+         [{ name: 'todos', primaryKey: 'id', tombstoneData: { title: '' } }], { sync: true })
       let loseResponse = true
       const requests = []
       const proxy = {
@@ -42,7 +42,7 @@ test('edits survive a committed create whose response was lost', async () => {
       }
       const app = { service: () => proxy }
       electricClientPlugin(app, { ShapeStream: Stream, Shape })
-      model = app.createElectricModel('todos', { localDb: db, retryMs: 60_000 })
+      model = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, retryMs: 60_000 })
       await model.prepare()
       const row = await model.create({ title: 'original' })
       await model.flushQueue()
@@ -95,7 +95,7 @@ test('offline writes stay local until the acknowledged Electric version arrives'
    }
    const app = { service: () => service }
    electricClientPlugin(app, { ShapeStream: Stream, Shape })
-   const model = app.createElectricModel('todos', { localDb: db, network: { onLine: false }, retryMs: 60_000 })
+   const model = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, network: { onLine: false }, retryMs: 60_000 })
    try {
       await model.prepare()
       const local = await model.create({ title: 'offline' })
@@ -105,7 +105,7 @@ test('offline writes stay local until the acknowledged Electric version arrives'
       assert.equal(calls.length, 0)
 
       // Simulate reconnect, then an old Shape snapshot followed by confirmation.
-      const onlineModel = app.createElectricModel('todos', { localDb: db, network: { onLine: true }, retryMs: 60_000 })
+      const onlineModel = app.createElectricModel('todos', { primaryKey: 'id', localDb: db, network: { onLine: true }, retryMs: 60_000 })
       await onlineModel.flushQueue()
       assert.equal(calls.length, 1)
       assert.equal(calls[0].metadata.revision, '1')

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

@@ -17,7 +17,7 @@ function fixture({ authorize = async () => true, fetch } = {}) {
       createService(name, methods) { services.set(name, methods) },
       get(path, handler) { routes.set(path, handler) },
    }
-   const registration = electricServerPlugin(app, db, ['todos'], { authorize, fetch: fetch ?? globalThis.fetch })
+   const registration = electricServerPlugin(app, db, [{ name: 'todos', primaryKey: 'id' }], { authorize, fetch: fetch ?? globalThis.fetch })
    return { app, db, services, routes, queries, registration }
 }
 
@@ -192,7 +192,7 @@ test('sync mode commits a versioned write and rejects replayed or stale revision
 
 test('sync schema prepares version and tombstone columns', async () => {
    const queries = []
-   await prepareElectricSyncSchema({ query: async sql => { queries.push(sql) } }, ['todos'])
+   await prepareElectricSyncSchema({ query: async sql => { queries.push(sql) } }, [{ name: 'todos', primaryKey: 'id' }])
    assert.equal(queries.length, 4)
    assert.match(queries[2], /ADD COLUMN IF NOT EXISTS version BIGINT/)
    assert.match(queries[3], /ADD COLUMN IF NOT EXISTS deleted BOOLEAN/)
@@ -301,3 +301,10 @@ test('invalid tombstone factory results roll back before writing a tombstone', a
       assert.ok(!queries.some(sql => sql.includes('INSERT INTO "users"')))
    }
 })
+
+
+test('server models default to the uid primary key', () => {
+   const app = { createService() {}, get() {} }
+   const result = electricServerPlugin(app, { query() {} }, ['users'], { authorize: async () => true })
+   assert.equal(result.models[0].primaryKey, 'uid')
+})