@jcbuisson/express-x-plugins 4.0.7 → 4.0.9

package/README.md

@@ -2,7 +2,21 @@
 # express-x-plugins
 
 
-IMPORTANT: set lc_messages=C for the PostgreSQL chris role so Electric receives recognizable English errors.
+IMPORTANT FOR ELECTRIC
+
+# set lc_messages=C for the PostgreSQL role so Electric receives recognizable English errors
+ALTER ROLE chris SET lc_messages = 'C';
+
+# ALLOW POSTGRES LOGICAL REPLICATION
+ALTER SYSTEM SET wal_level = 'logical';
+ALTER SYSTEM SET max_replication_slots = 10;
+ALTER SYSTEM SET max_wal_senders = 10;
+ALTER ROLE chris WITH REPLICATION;
+
+(restart postgres: `sudo systemctl restart postgresql`)
+
+## Use HTTP2
+nginx: `listen 443 ssl http2;`
 
 
 Currently includes:
@@ -63,13 +77,16 @@ app.configure(electricOfflinePlugin, db, [
 
 This registers one Express-X service per model with the familiar API:
 
+- `findUnique(where)`
+- `findMany(where, queryOptions)`
 - `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.
+The client model provides synchronized reads through `findMany(where)` and
+`getObservable(where)`. The service also exposes direct one-shot server reads
+when synchronization is not required.
 
 Mutation methods return the created, updated, or deleted row directly.
 
@@ -97,7 +114,6 @@ const numberedTodo = app.createElectricModel('numberedTodos', {
 })
 
 const incompleteTodos = await todo.findMany({ completed: false })
-const selectedTodo = await todo.findUnique({ uid })
 
 const subscription = todo.getObservable({ completed: false }).subscribe(rows => {
   console.log(rows)
@@ -116,9 +132,8 @@ 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.
+It unsubscribes after the first emission; if called within a Vue scope, it also
+unsubscribes 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.
@@ -156,8 +171,16 @@ services:
     environment:
       DATABASE_URL: postgresql://user:password@host.docker.internal:5432/mydb
       ELECTRIC_INSECURE: "true"
+      ELECTRIC_STORAGE: FAST_FILE
+      ELECTRIC_PERSISTENT_STATE: FILE
+      ELECTRIC_STORAGE_DIR: /var/lib/electric
     ports:
       - "3001:3000"
+    volumes:
+      - electric_mydb_data:/var/lib/electric
+
+volumes:
+  electric_mydb_data:
 ```
 
 ```

package/package.json

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

package/src/electric-client-plugin.mjs

@@ -2,20 +2,20 @@ import { Shape, ShapeStream } from '@electric-sql/client'
 import { firstValueFrom, Observable, Subject, takeUntil } from 'rxjs'
 import { getCurrentScope, onScopeDispose, ref } from 'vue'
 
-
 /**
  * Add Electric-backed reactive models to an Express-X client.
  *
  * Usage:
  *   electricClientPlugin(app)
- *   const todo = app.createElectricModel('todos')
+ *   const todo = app.createElectricModel('todos') // primary key is provided by client
+ *   const todo = app.createElectricModel('todos', { idGeneration: 'server' }) // primary key is server-generated
  *   todo.getObservable({ completed: false }).subscribe(...)
  *   const completedTodos = await todo.findMany({ completed: false })
  */
 export function electricClientPlugin(app, options = {}) {
    const shapePath = options.shapePath ?? '/electric/v1/shape'
    const ShapeStreamClass = options.ShapeStream ?? ShapeStream
-   const ShapeClass = options.Shape ?? Shape
+   const ShapeClass = options.Shape ?? DisposableShape
    const ObservableClass = options.Observable ?? Observable
 
    function createElectricModel(modelName, modelOptions = {}) {
@@ -89,6 +89,16 @@ export function electricClientPlugin(app, options = {}) {
 
 //////////////////////                   UTILITIES                   //////////////////////
 
+export class DisposableShape extends Shape {
+   subscribe(callback) {
+      const unsubscribe = super.subscribe(callback)
+      return () => {
+         unsubscribe()
+         if (this.numSubscribers === 0) this.stream.unsubscribeAll()
+      }
+   }
+}
+
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
 const RANGE_OPERATORS = { gt: '>', gte: '>=', lt: '<', lte: '<=' }
 

package/src/electric-server-plugin.mjs

@@ -26,8 +26,10 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
       }
    }
 
+   // for each model 'name', there is a service 'name' with methods 'findUnique', 'findMany', 'create', 'update', 'delete'
    for (const model of configuredModels) {
       app.createService(model.name, {
+
          findUnique: async function(where) {
             await authorize(this, model.name, 'findUnique', [where])
             const filter = buildWhere(where)
@@ -50,7 +52,8 @@ export function electricOfflinePlugin(app, db, models, options = {}) {
             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(data): the primary key is server-generated
+         // create(uid, data): uid (the primary key) is provided by the client
          create: async function(idOrData, data) {
             const hasClientId = data !== undefined
             const mutationData = hasClientId ? data : idOrData

package/src/reload-client-plugin.mjs

@@ -1,3 +1,5 @@
+import { useSessionStorage } from '@vueuse/core'
+
 /**
  * Enrich `app` with listeners handling socket data transfer on page reload
  *

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

@@ -2,7 +2,11 @@ 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'
+import {
+   DisposableShape,
+   electricClientPlugin,
+   whereToElectricParams,
+} from '../src/electric-client-plugin.mjs'
 
 class FakeStream {
    static instances = []
@@ -36,6 +40,19 @@ class EmptyShape {
    }
 }
 
+test('DisposableShape tears down its stream with its last subscriber', () => {
+   const stream = {
+      subscribe() { return () => {} },
+      unsubscribeAll() { this.unsubscribed = true },
+   }
+   const shape = new DisposableShape(stream)
+   const unsubscribe = shape.subscribe(() => {})
+
+   unsubscribe()
+
+   assert.equal(stream.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',