@jcbuisson/express-x-plugins 4.0.2 → 4.0.4

package/README.md

@@ -42,7 +42,7 @@ 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`
@@ -54,12 +54,9 @@ wait for the matching transaction in its Shape stream.
 Install the optional client dependencies in the browser application:
 
 ```sh
-npm install @jcbuisson/express-x-electric @electric-sql/client rxjs
+npm install @jcbuisson/express-x-electric @electric-sql/client rxjs vue
 ```
 
-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'
 
@@ -68,6 +65,10 @@ app.configure(electricClientPlugin, {
 })
 
 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,6 +81,12 @@ 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x-plugins",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "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 { Observable } from 'rxjs'
+import { firstValueFrom, Observable, Subject, takeUntil } from 'rxjs'
 import { getCurrentScope, onScopeDispose, ref } from 'vue'
 
 
@@ -24,7 +24,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,7 +42,7 @@ 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()
          })
       }
@@ -54,6 +54,22 @@ export function electricClientPlugin(app, options = {}) {
          return value
       }
 
+      function findMany(where = {}) {
+         const observable = getObservable(where)
+         if (!getCurrentScope()) return firstValueFrom(observable)
+
+         const scopeDisposed = new Subject()
+         onScopeDispose(() => {
+            scopeDisposed.next()
+            scopeDisposed.complete()
+         })
+         return firstValueFrom(observable.pipe(takeUntil(scopeDisposed)))
+      }
+
+      function findUnique(where = {}) {
+         return findMany(where).then(rows => rows[0] ?? null)
+      }
+
       async function create(data) {
          assertPlainObject(data, 'mutation data')
          const uid = globalThis.crypto?.randomUUID?.()
@@ -73,7 +89,7 @@ export function electricClientPlugin(app, options = {}) {
          return value
       }
 
-      return { getObservable, getVueRef, create, update, remove }
+      return { getObservable, getVueRef, findMany, findUnique, 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,6 +77,56 @@ test('getVueRef returns Shape rows in a Vue ref and cleans up with its scope', (
    assert.equal(shape.unsubscribed, true)
 })
 
+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.findMany({ completed: false })
+
+   assert.deepEqual(rows, [{ uid: 'one', completed: false }])
+   const stream = FakeStream.instances.at(-1)
+   assert.deepEqual(stream.options.params, {
+      where: '"completed" = $1', params: ['false'],
+   })
+   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 = {