@jcbuisson/express-x-plugins 4.0.3 → 4.0.5

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 })
@@ -42,32 +62,33 @@ This registers one Express-X service per model with the familiar API:
 - `updateWithMeta(uid, data, updatedAt)`
 - `deleteWithMeta(uid, deletedAt)`
 
-Synchronized reads are provided client-side by `getObservable(where)` below;
+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.
 
-## Client Shape
+### Client
 
 Install the optional client dependencies in the browser application:
 
 ```sh
-npm install @jcbuisson/express-x-electric @electric-sql/client rxjs
+npm install @electric-sql/client rxjs
 ```
 
-Configure the client plugin and use the same `getObservable(where)` style as
-`express-x-client`'s offline model:
-
 ```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',
 })
 
 const todo = app.createElectricModel('todos')
+
+const incompleteTodos = await todo.findMany({ completed: false })
+const selectedTodo = await todo.findUnique({ uid })
+
 const subscription = todo.getObservable({ completed: false }).subscribe(rows => {
   console.log(rows)
 })
@@ -80,13 +101,19 @@ await todo.remove(uid)
 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.
+
 Object filters use parameterized Electric Shape predicates. Exact values,
 `null`, and `gt`/`gte`/`lt`/`lte` ranges are supported.
 
 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:
 
@@ -101,7 +128,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.3",
+  "version": "4.0.5",
   "description": "Plugins for express-x",
   "type": "module",
   "main": "./src/electric-server-plugin.mjs",

package/src/electric-client-plugin.mjs

@@ -1,5 +1,5 @@
 import { Shape, ShapeStream } from '@electric-sql/client'
-import { firstValueFrom, Observable } from 'rxjs'
+import { firstValueFrom, Observable, Subject, takeUntil } from 'rxjs'
 import { getCurrentScope, onScopeDispose, ref } from 'vue'
 
 
@@ -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'
@@ -24,7 +25,7 @@ export function electricClientPlugin(app, options = {}) {
       const streamOptions = modelOptions.streamOptions ?? {}
 
       function getObservable(where = {}) {
-         // Validate eagerly, as getObservable in express-x-client does.
+         // Validate eagerly
          const filterParams = whereToElectricParams(where)
          return new ObservableClass(subscriber => {
             const stream = new ShapeStreamClass({
@@ -42,20 +43,21 @@ export function electricClientPlugin(app, options = {}) {
                subscriber.next(current)
             })
             // Shape exposes errors as state. ShapeStream retries transient failures;
-            // callers keep one observable subscription across reconnects.
+            // callers keep one observable subscription across reconnects
             return () => unsubscribe()
          })
       }
 
-      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)
 
-      function firstResult(where = {}) {
-         return firstValueFrom(getObservable(where))
+         const scopeDisposed = new Subject()
+         onScopeDispose(() => {
+            scopeDisposed.next()
+            scopeDisposed.complete()
+         })
+         return firstValueFrom(observable.pipe(takeUntil(scopeDisposed)))
       }
 
       async function create(data) {
@@ -77,7 +79,7 @@ export function electricClientPlugin(app, options = {}) {
          return value
       }
 
-      return { getObservable, getVueRef, firstResult, create, update, remove }
+      return { getObservable, findMany, create, update, remove }
    }
 
    return Object.assign(app, { createElectricModel })

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

@@ -20,6 +20,22 @@ class FakeShape {
    }
 }
 
+class DeferredShape {
+   constructor(stream) { this.stream = stream; stream.shape = this }
+   subscribe(callback) {
+      this.callback = callback
+      return () => { this.unsubscribed = true }
+   }
+}
+
+class EmptyShape {
+   constructor(stream) { this.stream = stream; stream.shape = this }
+   subscribe(callback) {
+      callback({ rows: [] })
+      return () => { this.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',
@@ -61,12 +77,12 @@ test('getVueRef returns Shape rows in a Vue ref and cleans up with its scope', (
    assert.equal(shape.unsubscribed, true)
 })
 
-test('firstResult resolves with the first Shape rows and cleans up its subscription', async () => {
+test('findMany resolves with the first Shape rows and cleans up its subscription', async () => {
    const app = { service: () => ({}) }
    electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })
    const todo = app.createElectricModel('todos')
 
-   const rows = await todo.firstResult({ completed: false })
+   const rows = await todo.findMany({ completed: false })
 
    assert.deepEqual(rows, [{ uid: 'one', completed: false }])
    const stream = FakeStream.instances.at(-1)
@@ -76,6 +92,41 @@ test('firstResult resolves with the first Shape rows and cleans up its subscript
    assert.equal(stream.shape.unsubscribed, true)
 })
 
+test('findMany unsubscribes when its Vue scope is disposed before a result', async () => {
+   const app = { service: () => ({}) }
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: DeferredShape })
+   const todo = app.createElectricModel('todos')
+   const scope = effectScope()
+   let result
+
+   scope.run(() => { result = todo.findMany({ completed: false }) })
+   const rejection = assert.rejects(result, error => error.name === 'EmptyError')
+   const shape = FakeStream.instances.at(-1).shape
+   assert.equal(shape.unsubscribed, undefined)
+
+   scope.stop()
+
+   await rejection
+   assert.equal(shape.unsubscribed, true)
+})
+
+test('findUnique resolves with the first matching row or null', async () => {
+   const app = { service: () => ({}) }
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })
+   const todo = app.createElectricModel('todos')
+
+   assert.deepEqual(
+      await todo.findUnique({ uid: 'one' }),
+      { uid: 'one', completed: false },
+   )
+   assert.equal(FakeStream.instances.at(-1).shape.unsubscribed, true)
+
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: EmptyShape })
+   const emptyTodo = app.createElectricModel('todos')
+   assert.equal(await emptyTodo.findUnique({ uid: 'missing' }), null)
+   assert.equal(FakeStream.instances.at(-1).shape.unsubscribed, true)
+})
+
 test('model mutations retain the simple Express-X API', async () => {
    const calls = []
    const service = {