@jcbuisson/express-x-plugins 4.0.1 → 4.0.3

package/README.md

@@ -2,8 +2,7 @@
 
 The smallest useful ElectricSQL integration for Express-X. Express-X handles
 authorized PostgreSQL mutations; Electric's Shape API streams those changes to
-clients. It is analogous to `express-x-drizzle`, but deliberately has no
-metadata table and no custom `sync.go`: Electric is the sync engine.
+clients: Electric is the sync engine.
 
 ## Install
 
@@ -11,8 +10,7 @@ metadata table and no custom `sync.go`: Electric is the sync engine.
 npm install @jcbuisson/express-x-electric pg
 ```
 
-This server-only installation does not install the browser Electric client or
-RxJS.
+This server-only installation does not install the browser Electric client or RxJS.
 
 ## Server
 
@@ -102,4 +100,23 @@ as query parameters; range filters support `gt`, `gte`, `lt`, and `lte`.
 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.
-# express-x-electric
+
+## 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.
+
+```
+services:
+  electric:
+    image: electricsql/electric:latest
+    environment:
+      DATABASE_URL: postgresql://user:password@host.docker.internal:5432/mydb
+      ELECTRIC_INSECURE: "true"
+    ports:
+      - "3001:3000"
+```
+
+```
+docker compose pull electric
+docker compose up electric
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x-plugins",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Plugins for express-x",
   "type": "module",
   "main": "./src/electric-server-plugin.mjs",
@@ -35,7 +35,8 @@
   },
   "peerDependencies": {
     "@electric-sql/client": "^1.5.24",
-    "rxjs": "^7.8.2"
+    "rxjs": "^7.8.2",
+    "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
     "@electric-sql/client": {
@@ -43,10 +44,14 @@
     },
     "rxjs": {
       "optional": true
+    },
+    "vue": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@electric-sql/client": "^1.5.24",
-    "rxjs": "^7.8.2"
+    "rxjs": "^7.8.2",
+    "vue": "^3.5.0"
   }
 }

package/src/electric-client-plugin.mjs

@@ -1,5 +1,6 @@
 import { Shape, ShapeStream } from '@electric-sql/client'
-import { Observable } from 'rxjs'
+import { firstValueFrom, Observable } from 'rxjs'
+import { getCurrentScope, onScopeDispose, ref } from 'vue'
 
 
 /**
@@ -46,6 +47,17 @@ export function electricClientPlugin(app, options = {}) {
          })
       }
 
+      function getVueRef(where = {}) {
+         const value = ref([])
+         const subscription = getObservable(where).subscribe(rows => { value.value = rows })
+         if (getCurrentScope()) onScopeDispose(() => subscription.unsubscribe())
+         return value
+      }
+
+      function firstResult(where = {}) {
+         return firstValueFrom(getObservable(where))
+      }
+
       async function create(data) {
          assertPlainObject(data, 'mutation data')
          const uid = globalThis.crypto?.randomUUID?.()
@@ -65,7 +77,7 @@ export function electricClientPlugin(app, options = {}) {
          return value
       }
 
-      return { getObservable, create, update, remove }
+      return { getObservable, getVueRef, firstResult, create, update, remove }
    }
 
    return Object.assign(app, { createElectricModel })
@@ -105,7 +117,7 @@ function serializeValue(value, path) {
 }
 
 /** Convert the Express-X object filter into Electric's parameterized SQL filter. */
-function whereToElectricParams(where = {}) {
+export function whereToElectricParams(where = {}) {
    assertPlainObject(where, 'where')
    const clauses = []
    const params = []
@@ -139,3 +151,5 @@ function modelPath(shapePath, modelName) {
    const base = shapePath.replace(/\/$/, '')
    return `${base}/${encodeURIComponent(modelName)}`
 }
+
+export default electricClientPlugin

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

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
+import { effectScope, isRef } from 'vue'
 
 import { electricClientPlugin, whereToElectricParams } from '../src/electric-client-plugin.mjs'
 
@@ -12,7 +13,7 @@ class FakeStream {
 }
 
 class FakeShape {
-   constructor(stream) { this.stream = stream }
+   constructor(stream) { this.stream = stream; stream.shape = this }
    subscribe(callback) {
       callback({ rows: [{ uid: 'one', completed: false }] })
       return () => { this.unsubscribed = true }
@@ -43,6 +44,38 @@ test('getObservable emits Shape rows and cleans up its subscription', () => {
    subscription.unsubscribe()
 })
 
+test('getVueRef returns Shape rows in a Vue ref and cleans up with its scope', () => {
+   const app = { service: () => ({}) }
+   electricClientPlugin(app, { ShapeStream: FakeStream, Shape: FakeShape })
+   const todo = app.createElectricModel('todos')
+   const scope = effectScope()
+   let rows
+
+   scope.run(() => { rows = todo.getVueRef({ completed: false }) })
+
+   assert.equal(isRef(rows), true)
+   assert.deepEqual(rows.value, [{ uid: 'one', completed: false }])
+   const shape = FakeStream.instances.at(-1).shape
+   assert.equal(shape.unsubscribed, undefined)
+   scope.stop()
+   assert.equal(shape.unsubscribed, true)
+})
+
+test('firstResult 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 })
+
+   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('model mutations retain the simple Express-X API', async () => {
    const calls = []
    const service = {