@jcbuisson/express-x-plugins 5.0.7 → 5.1.0

package/README.md

@@ -4,6 +4,7 @@
 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
 
@@ -17,7 +18,10 @@ npm install @jcbuisson/express-x-plugins
 
 ## Electric plugin: local-first Postgres
 
-Express-X handles authorized PostgreSQL mutations; Electric streams committed rows to clients.
+Without managed sync (sync: false) or a supplied localDb, the client streams Shapes directly and sends CRUD calls directly;
+it has no persistent local mutation queue or owner election.
+
+Wth managed sync (sync: true) Express-X handles authorized PostgreSQL mutations; Electric streams committed rows to clients.
 
 The electric plugin has two separate elections:
 
@@ -28,6 +32,11 @@ Each PGlite instance has its own in-memory state: caches, transaction state, and
 They prevent duplicate database engines and duplicate synchronization across tabs. The database leader and sync owner can be different tabs.
 
 
+Electric’s does incremental replication: after the initial snapshot, it streams database changes instead of repeatedly comparing client/server metadata.
+Its Shapes can represent filtered subsets of tables
+
+
+
 ### Settings
 ```bash
 # set lc_messages=C for the PostgreSQL role so Electric receives recognizable English errors
@@ -130,6 +139,48 @@ Import `prepareElectricSyncSchema` alongside `electricServerPlugin`. It adds
 table. The primary key must be UUID in sync mode. All writes to synced tables must
 advance `version`; hard deletes bypass tombstone confirmation.
 
+#### Relationships and offline deletes
+
+In sync mode, the server discovers PostgreSQL `ON DELETE CASCADE` foreign keys
+between configured models. Deleting a parent writes tombstones for its current
+children and descendants in the same transaction, including rows the deleting
+offline client never saw. A delayed create or update referencing a deleted parent
+is resolved as a child tombstone, so deletion wins in either arrival order.
+The result includes `syncRejection: { code: 'sync-parent-deleted', message }`.
+Retries replay that result through the normal mutation cursor.
+
+The browser removes a rejected optimistic row immediately, acknowledges its
+tombstone version, and reports an error through `onError` with `code` and `rowId`.
+It does not resend the rejected mutation. Electric's tombstone snapshot completes
+queue cleanup. An edit to an already deleted row is handled the same way, with
+`code: 'sync-row-deleted'`. If the parent is missing rather than deleted, the
+write remains retriable: its parent's offline create may still be queued.
+
+Pass the same complete model list, including `tombstoneData`, to
+`prepareElectricSyncSchema` and `electricServerPlugin`. Startup preparation also
+repairs existing active children of soft-deleted parents and their descendants.
+Clients only need to queue the parent deletion; explicit child deletions remain
+compatible. Cascades are part of the authorized parent deletion and do not invoke
+separate child authorization callbacks.
+
+These rules apply to single-column `ON DELETE CASCADE` foreign keys referencing
+the configured parent's primary key. Other foreign-key delete policies retain
+their existing behavior. Unsupported CASCADE keys between configured models
+fail discovery rather than silently losing integrity. Configure every model in
+the relationship graph. Restart the plugin after changing foreign keys: discovery
+is cached after the first sync mutation.
+
+Transactions affecting these relationships acquire one shared PostgreSQL advisory
+lock before cursor or row locks. This deliberately serializes relational writes
+across plugin instances, including cyclic graphs; models without discovered
+relationships remain parallel. All participating instances must use these rules.
+Direct SQL writes and non-sync services bypass this coordination.
+
+Regression tests run with `npm test`. To also exercise actual concurrent PostgreSQL
+transactions, set `ELECTRIC_TEST_DATABASE_URL` to a test database and run `npm test`.
+The PostgreSQL test creates and removes its own isolated schema and requires
+permission to create schemas; it does not use application tables.
+
 Without `sync: true`, the existing direct service methods remain available and
 return created, updated, or deleted rows directly.
 
@@ -375,3 +426,131 @@ 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.
+
+## Custom metadata sync plugin
+
+The original timestamp/metadata synchronization engine is available separately
+from Electric:
+
+```sh
+npm install dexie uuid @vueuse/core rxjs vue drizzle-orm
+```
+
+On the server, register Drizzle tables with a `uid` primary key and a shared
+metadata table (`uid` primary key, `created_at`, `updated_at`, `deleted_at`
+timestamps):
+
+```js
+import { syncServerPlugin } from '@jcbuisson/express-x-plugins/sync-server'
+
+app.configure(syncServerPlugin, db, metadata, [todos], {
+  authorize: async (context, { modelName, action, args }) => {
+    return Boolean(context.socket?.data?.user)
+  },
+})
+```
+
+The plugin registers each model's `findUnique`, `findMany`, `createWithMeta`,
+`updateWithMeta`, and `deleteWithMeta` methods, plus `sync.go`. Configure each
+model service's Express-X publishing policy to send mutation events to its
+authorized subscribers. Authorization is required; `maxSyncRecords` defaults
+to 10,000. Use separate applications for Electric and custom sync services
+when their model names overlap.
+
+On the client:
+
+```js
+import { syncClientPlugin } from '@jcbuisson/express-x-plugins/sync-client'
+
+app.configure(syncClientPlugin, { cacheNamespace: 'my-app:current-user' })
+const todo = app.createOfflineModel('todos', ['label'])
+const subscription = todo.getObservable({}).subscribe(rows => console.log(rows))
+await todo.create({ label: 'Available offline' })
+await todo.update(uid, { label: 'Edited offline' })
+await todo.remove(uid)
+subscription.unsubscribe()
+```
+
+The client persists rows and dirty mutations in Dexie/IndexedDB and reconciles
+subscribed filters on reconnect. `cacheNamespace` must be non-empty and should
+isolate each backend/user. Models support `findByUID`, `reset`, and
+`synchronizeAll` alongside observable reads and mutations. Vue scope disposal
+cleans up model listeners and filter subscriptions.
+
+The original names `offlinePlugin` and `drizzleOfflinePlugin` remain exported.
+The pure algorithm is exported as `computeSyncResult` from `/sync-algorithm`
+and `/sync-server`. It compares metadata timestamps and returns additions,
+updates, and deletions for each side. Writes outside the plugin must maintain
+the metadata table too. Tombstones persist; safe pruning requires knowing all
+clients have observed a deletion.
+
+Restored from the last committed custom implementations, dated July 8, 2026:
+`express-x` **edb1db3** (algorithm and regression tests), `express-x-client`
+**944c398** (client), and `express-x-drizzle` **ddf6804** (server). The algorithm
+was removed from Express-X in **47c2293** on July 19. Only module imports and
+plugin export aliases were adapted; the synchronization logic is preserved.
+
+## Minimal SQL-oriented Electric plugin
+
+A separate plugin provides two client methods: `sql.watch` for live table rows
+and `sql.query` for named, parameterized PostgreSQL statements. It needs no models,
+ORM, local database, Vue, RxJS, schema changes, or sync metadata.
+
+```js
+// Server (pg Pool or Client)
+import { electricSqlServerPlugin } from '@jcbuisson/express-x-plugins/electric-sql-server'
+
+app.configure(electricSqlServerPlugin, pool, {
+  tables: ['todos'],
+  statements: {
+    add: 'INSERT INTO todos (label) VALUES ($1) RETURNING *',
+    complete: 'UPDATE todos SET done = $1 WHERE id = $2 RETURNING *',
+    remove: 'DELETE FROM todos WHERE id = $1 RETURNING *',
+  },
+  electricUrl: 'http://localhost:3000/v1/shape',
+  authorize(context, operation) {
+    // Supply your application's authorization policy. Check statement name and
+    // params for query calls; table and SQL filter params for shape calls.
+    return Boolean(context.request?.user)
+  },
+})
+```
+
+```js
+// Browser (install @electric-sql/client)
+import { electricSqlClientPlugin } from '@jcbuisson/express-x-plugins/electric-sql-client'
+
+app.configure(electricSqlClientPlugin)
+const stop = app.sql.watch('todos', {
+  where: 'done = $1',
+  params: [false],
+}, rows => console.log(rows))
+
+const [todo] = await app.sql.query('add', ['Buy milk'])
+await app.sql.query('complete', [true, todo.id])
+await app.sql.query('remove', [todo.id])
+stop() // unsubscribe and abort this stream
+app.sql.dispose() // stop every active watch
+```
+
+`watch(table, callback)` watches the whole table. Filters use Electric-supported
+PostgreSQL WHERE expressions with `$1`, `$2`, etc.; null comparisons use `IS NULL`.
+Callbacks receive the initial synchronized rows and later committed changes.
+Electric Shapes are table subscriptions, not arbitrary SELECTs or joins. Named
+statements can use full PostgreSQL SQL, including joins and `RETURNING`; `query`
+returns their rows. SQL text stays on the server, and values are bound through pg.
+
+Authorization is required for both statements and Shapes. A table allowlist alone
+is not row authorization: enforce tenant restrictions in server SQL and validate
+Shape filters in your policy. The proxy ignores client-supplied source credentials.
+Server options include `sourceId`, `sourceSecret`, `serviceName` (default `sql`),
+and `shapePath` (default `/electric-sql/v1/shape/:table`). Match a custom service
+name and Shape base path on the client. Client `headers` and `onError` are passed
+to Electric for authentication and stream error handling.
+
+This plugin performs online writes with server-generated keys and physical deletes.
+A successful write resolves before its Electric echo necessarily arrives. It does
+not queue offline writes or apply optimistic updates. Electric reconnects and
+resumes live reads; the existing managed Electric plugin remains available for
+persistent offline storage and writes. Use separate service names and paths when
+installing both plugins in one application.

package/docs/electric-fsm.md

@@ -0,0 +1,244 @@
+# Electric sync state machines
+
+These diagrams model `electric-managed-sync.mjs`, `electric-offline-model.mjs`,
+and `electric-server-plugin.mjs`. They describe the plugin's own control flow,
+not Electric's internal replication protocol. State names are analytical labels
+unless explicitly identified as persisted fields. Timestamps, revisions, rows,
+and versions are data guards, so the precise model is an extended FSM.
+
+The main diagrams assume `sync: true` on both client and server. Without managed
+sync or a supplied `localDb`, the client streams Shapes directly and sends CRUD
+calls directly; it has no persistent local mutation queue or owner election.
+
+## One managed model in one tab
+
+```mermaid
+stateDiagram-v2
+    [*] --> preparing
+    preparing --> active: database and schema ready
+    preparing --> initFailed: initialization rejected
+    preparing --> stopped: stop before preparation completes
+    state active {
+        [*] --> networkCheck
+        state networkCheck <<choice>>
+        networkCheck --> offline: browser reports offline
+        networkCheck --> waiting: browser permits network
+        offline --> waiting: online event
+        waiting --> owner: Web Lock acquired
+        waiting --> offline: offline event cancels request
+        owner --> offline: offline event releases ownership
+    }
+    active --> stopped: stop
+    stopped --> active: start after readiness
+    stopped --> initFailed: outstanding preparation rejects
+    preparing --> disposed: dispose
+    active --> disposed: dispose
+    stopped --> disposed: dispose
+    initFailed --> disposed: dispose cleanup
+    disposed --> [*]
+```
+
+- `preparing` creates or obtains the PGlite database, prepares local tables, and
+  installs the BroadcastChannel. Preparation is serialized across this plugin
+  instance's models. Reads and writes wait for readiness; failure rejects them.
+- `waiting` is a follower with a pending Web Lock request. It can read and write
+  shared local rows and enqueue mutations; only the owner streams and flushes.
+- The lock key is database/model-specific. One tab can own one model and follow
+  another. PGlite's database leader is a separate role and need not be the sync
+  owner. Closing an owner lets another waiting tab acquire the lock.
+- `offline` means the browser reports offline, so ownership is released. This
+  differs from a stream error while the browser still reports online: a stream
+  error does not by itself release ownership.
+- Release invalidates old stream callbacks, cancels the pending lock request,
+  and stops owner work. The lock callback drains background work before exiting.
+  Snapshot reset is ordered after previously queued snapshot tasks.
+- `stop()` retains local rows and the mutation queue. Reads and local mutations
+  remain available. `start()` requests ownership; its promise does not wait for
+  ownership, a snapshot, or complete synchronization.
+- `dispose()` removes network listeners, stops the model, waits for outstanding
+  work, closes its channel, and removes it from the model cache. The old API
+  cannot restart; a new `createElectricModel` call can create a fresh instance
+  while the plugin itself remains open. Disposing the plugin closes its owned
+  database after disposing all models; a supplied `localDb` is caller-owned.
+- `initFailed` has no built-in initialization retry for that model instance.
+  Disposal still performs cleanup, although its promise can reject when
+  readiness failed. A non-abort Web Lock request failure is reported and does
+  not automatically enqueue a replacement request.
+
+## The owner's stream connection
+
+```mermaid
+stateDiagram-v2
+    [*] --> connecting
+    connecting --> connected: Shape rows or connected stream message
+    connecting --> disconnected: stream error or disconnected message
+    connected --> disconnected: stream error or disconnected message
+    disconnected --> connected: later connected message or Shape rows
+    connected --> connected: apply Shape snapshot
+    connected --> connected: must-refetch invalidates cached snapshot
+    disconnected --> disconnected: must-refetch invalidates cached snapshot
+    connecting --> closed: ownership released or model stopped
+    connected --> closed: ownership released or model stopped
+    disconnected --> closed: ownership released or model stopped
+    closed --> [*]
+```
+
+Actual reconnection/retry mechanics belong to `ShapeStream`. This wrapper marks
+its connection false on a stream error and reports the error; it does not create
+a fresh stream solely because an error occurred. Generation guards ignore late
+callbacks from stopped streams. A `must-refetch` message resets the cached
+snapshot; the connection flag is still independently taken from the stream.
+
+Queue uploads are gated by ownership and browser network state, **not** by the
+stream's `connected` flag. Writes can reach the server while the Shape stream
+is disconnected. Followers receive the owner's connection status through
+BroadcastChannel, so `online` is an observation, not a convergence guarantee.
+
+## One local mutation queue entry
+
+There is at most one entry per `(model_name, row_id)`. Local CRUD and queue
+updates commit together in a PGlite transaction. A later local edit replaces
+the entry's payload and allocates a new monotonically increasing revision.
+
+```mermaid
+stateDiagram-v2
+    [*] --> unqueued
+    unqueued --> pending: local create, update, or remove
+    pending --> sending: owner selects next revision
+    sending --> pending: transient error
+    sending --> failed: permanent error for current revision
+    sending --> awaitingEcho: response version recorded for current revision
+    sending --> pending: newer local revision supersedes request
+    awaitingEcho --> unqueued: snapshot version reaches acknowledged version
+    pending --> pending: local edit replaces revision
+    awaitingEcho --> pending: local edit resets acknowledgement
+    failed --> pending: local edit resets failure
+    failed --> failed: ordinary flush skips failed entry
+```
+
+| Diagram state | Persisted queue representation |
+| --- | --- |
+| Unqueued | No queue entry |
+| Pending | `status = 'pending'`, `acknowledged_version IS NULL` |
+| Sending | Same persisted state as Pending; selected request is in flight |
+| Awaiting echo | `status = 'pending'`, `acknowledged_version` is set |
+| Failed | `status = 'failed'`, with `failure_reason` |
+
+The critical acknowledgement condition is:
+
+```text
+incoming row ID = queued row ID
+AND incoming.version >= queued.acknowledged_version
+```
+
+The snapshot transaction removes acknowledged queue entries first, then adopts
+unprotected live rows and removes unprotected rows missing from the live
+snapshot. Tombstones carry versions too, allowing deletes to be acknowledged.
+A mutation response alone does not clear the queue; if a sufficient snapshot
+was already cached, reconciliation can clear it immediately after the response.
+
+Additional transition guards and actions:
+
+- Only the owner flushes, with one flush loop at a time per local model instance.
+  It selects unacknowledged Pending entries in revision order. A timer, local
+  write, owner startup, online event, owner BroadcastChannel notification, or
+  explicit `flushQueue()` can trigger a flush.
+- A transient failure leaves the entry Pending and ends the current flush loop.
+  A later trigger retries it. A permanent failure marks the matching revision
+  Failed and permits the loop to continue with other entries.
+- Permanent means `forbidden`, a `TypeError`, or HTTP 4xx except 408, 425, and
+  429. A response without a version is an error and remains retryable.
+- Responses and failure writes are revision-guarded. An old response must not
+  acknowledge a newer local edit. If a create was edited while its request was
+  in flight, its successful response converts the queued create into an update
+  with another revision. If the old request failed, the newer create stays
+  queued and the server handles its newer revision idempotently.
+- Any queue entry, including Failed and Awaiting echo, protects the optimistic
+  local row from snapshot replacement. Failed entries are not automatically
+  retried or rolled back. A subsequent local operation resets their status.
+- Local remove hides the row immediately and queues delete. Update requires a
+  local row. Updates to an unacknowledged queued create retain action `create`;
+  updates after its acknowledgement use action `update`.
+
+## One server mutation request
+
+```mermaid
+stateDiagram-v2
+    [*] --> validating
+    validating --> rejected: forbidden or invalid mutation
+    validating --> transaction: authorized and valid
+    state transaction {
+        [*] --> cursorLocked
+        state revisionCheck <<choice>>
+        cursorLocked --> revisionCheck: cursor row locked
+        revisionCheck --> replayed: revision at or below stored cursor
+        revisionCheck --> applied: revision above stored cursor
+        applied --> recorded: save revision and result
+        replayed --> [*]
+        recorded --> [*]
+    }
+    transaction --> committed: commit and return result
+    transaction --> rolledBack: transactional failure
+    rejected --> [*]
+    committed --> [*]
+    rolledBack --> [*]
+```
+
+The cursor key is `(table_name, client_id, row_id)`. Equal or older revisions
+return that cursor's stored result without applying another mutation. A newer
+revision applies its operation and saves its result atomically with the row
+change. Losing the response after commit is therefore safe to retry. An older
+revision returns the latest stored cursor result, not necessarily its own
+original result.
+
+The cursor serializes requests for the same client/row. It does not impose a
+revision ordering across different clients; PostgreSQL row conflicts and
+transaction execution determine their resulting writes. Server versions come
+from `electric_sync_version_seq`, not client timestamps.
+
+## One server record in sync mode
+
+```mermaid
+stateDiagram-v2
+    [*] --> absent
+    absent --> live: first create inserts row
+    absent --> tombstone: update or delete
+    live --> live: accepted update or edited create advances version
+    live --> live: initial create conflicts and preserves row
+    live --> tombstone: accepted delete advances version
+    tombstone --> tombstone: update or delete advances tombstone version
+    tombstone --> tombstone: create preserves tombstone
+```
+
+These transitions describe accepted newer cursor revisions. Replayed revisions
+do not change the record. An initial create conflicts by preserving the existing
+row. A later create from a cursor that already has an accepted revision is
+treated as an update when it contains non-key data. Updates affect only live
+rows; updating an absent or deleted row writes a tombstone instead. This sync
+API has no tombstone-to-live transition or automatic tombstone pruning.
+
+| State | PostgreSQL representation | Local snapshot result without a queued mutation |
+| --- | --- | --- |
+| Absent | No row | No local row |
+| Live | Row with `deleted = false` and `version` | Local row mirrors snapshot |
+| Tombstone | Row with `deleted = true` and `version` | Local row removed |
+
+`tombstoneData` supplies values needed to insert a missing-row tombstone and
+can clear selected fields on an existing row. It does not necessarily erase
+every other stored column.
+
+## What status means
+
+`getStatus()` is a combination of independent observations, not a single FSM
+state:
+
+- `pending` counts both unsent mutations and acknowledged mutations awaiting
+  their Electric echo.
+- `failed` counts permanently failed queue entries.
+- `online` combines the browser network flag and observed stream connection.
+- Managed `error` is the latest reported error message. It is not explicitly
+  cleared on recovery, so its presence alone does not establish current failure.
+
+`pending = 0` does not establish initial snapshot readiness, and the plugin
+exposes no explicit fully-caught-up state. The main completion boundary for a
+local mutation is its queue entry being removed after version reconciliation.

package/docs/sync-fsm.md

@@ -0,0 +1,117 @@
+# Drizzle sync state machines
+
+This models the restored implementation in `src/sync-server-plugin.mjs` and
+`src/sync-algorithm.mjs`. The state names are analytical labels, not persisted
+plugin fields. Because timestamps, UIDs, filters, and rows are unbounded data,
+the precise model is an extended FSM: finite control states plus data guards.
+
+## One server sync request
+
+Each `sync.go(modelName, where, clientMetadataDict)` invocation has its own
+machine. There is no single global synchronization state.
+
+```mermaid
+stateDiagram-v2
+    [*] --> validating
+    validating --> waiting: configured, authorized, valid envelope
+    validating --> rejected: validation or authorization error
+    waiting --> locked: scope lock granted
+    waiting --> rejected: lock acquisition error
+    state locked {
+        [*] --> reading
+        reading --> scoping: bounded rows loaded
+        scoping --> metadata: exclude existing rows outside filter
+        metadata --> planning: load metadata and repair eligible gaps
+        planning --> deleting: computeSyncResult
+        deleting --> ready: server deletions completed
+        ready --> [*]
+    }
+    locked --> succeeded: release lock and return plan
+    locked --> failed: exception and release lock
+    rejected --> [*]
+    failed --> [*]
+    succeeded --> [*]
+```
+
+- `validating` checks model configuration, authorization, metadata envelope,
+  and client record limit. Detailed metadata timestamp validation happens in
+  `planning` with the default algorithm; filter validation happens during reads.
+- The lock queues overlapping filters for the same model. Independent scopes
+  can proceed concurrently. This lock is local to the plugin instance.
+- `metadata` considers server row UIDs and effective client UIDs, so deleted
+  server records can still be found through their metadata tombstones.
+- `deleting` calls authorized `deleteWithMeta` operations. Each mutation has its
+  own transaction and metadata row lock. The entire sync request is **not one
+  transaction**: failure can leave earlier repairs or deletions committed.
+- Success returns a reconciliation plan. It does **not** mean the client has
+  applied the plan or uploaded its mutations. Retry is a new request initiated
+  by the client, not an automatic transition inside the server request.
+
+## One server record
+
+For a fixed `(modelName, uid)`, the normal persistent states are:
+
+| State | Model row | Metadata |
+| --- | --- | --- |
+| Absent | Missing | Missing |
+| Live | Present | No deletion timestamp |
+| Tombstone | Missing | Deletion timestamp retained |
+
+`t` is the incoming operation timestamp. `v` is the stored version selected
+by the handler: `deleted_at`, otherwise `updated_at`, otherwise `created_at`.
+The transitions below assume valid timestamps, authorization, successful
+transactions, and normal metadata integrity.
+
+```mermaid
+stateDiagram-v2
+    [*] --> absent
+    absent --> live: create or timestamped update
+    absent --> tombstone: delete
+    live --> live: create or update with t greater than v
+    live --> live: stale create or update ignored
+    live --> live: delete with t less than v ignored
+    live --> tombstone: delete with t greater than or equal to v
+    tombstone --> live: create or update with t greater than v
+    tombstone --> tombstone: create or update with t less than or equal to v
+    tombstone --> tombstone: delete retains or advances tombstone
+```
+
+A deletion wins a tie with a live version. Equal live timestamps produce no
+reconciliation action; the algorithm does not compare row contents. Newer
+creates or updates can resurrect a tombstone. No automatic tombstone pruning
+or transition back to Absent exists.
+
+Integrity gaps add exceptional states: a row without metadata, metadata without
+a row, or a row coexisting with a tombstone. The implementation repairs selected
+gaps during sync and mutation handling. These repairs depend on the incoming
+metadata and timestamps; they are not unconditional background transitions.
+`updateWithMeta` also permits a missing timestamp, which can create
+timestamp-free metadata when no stored version blocks it; the normal-state
+diagram intentionally assumes timestamped operations.
+
+## Reconciliation outputs
+
+The pure algorithm is a guarded decision function over a snapshot. Its six
+outputs are actions, not persistent record states.
+
+| Output | Meaning | Executor |
+| --- | --- | --- |
+| `addClient` | Copy server row and metadata into local cache | Client |
+| `updateClient` | Replace local copy with server version | Client |
+| `deleteClient` | Remove local copy using the deletion version | Client |
+| `addDatabase` | Upload a locally held row | Client calls `createWithMeta` |
+| `updateDatabase` | Upload the newer local version | Client calls `updateWithMeta` |
+| `deleteDatabase` | Delete a server row and retain metadata | Server during `sync.go` |
+
+For live versions on both sides, the newer timestamp wins. A deletion wins
+against an equal or older live version. When the server row is absent, retained
+server metadata still participates: a sufficiently new server version can
+remove the client copy, while a newer live client version can recreate the row.
+Server records outside `where` are excluded before these comparisons.
+
+The client applies downloads before uploads. Failed sync uploads preserve local
+dirty mutations for a later reconnect or explicit `synchronizeAll()`. Individual
+upload failures can be caught while the rest of the synchronization continues,
+so a resolved synchronization call does not prove every dirty row was accepted.
+Timestamp guards on acknowledgements prevent an older response from clearing
+a newer local mutation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcbuisson/express-x-plugins",
-  "version": "5.0.7",
+  "version": "5.1.0",
   "description": "Plugins for express-x",
   "type": "module",
   "main": "./src/electric-server-plugin.mjs",
@@ -9,7 +9,12 @@
     "./electric-client": "./src/electric-client-plugin.mjs",
     "./reload-server": "./src/reload-server-plugin.mjs",
     "./reload-client": "./src/reload-client-plugin.mjs",
-    "./electric-worker": "./src/electric-pglite-worker.mjs"
+    "./electric-worker": "./src/electric-pglite-worker.mjs",
+    "./sync-client": "./src/sync-client-plugin.mjs",
+    "./sync-server": "./src/sync-server-plugin.mjs",
+    "./sync-algorithm": "./src/sync-algorithm.mjs",
+    "./electric-sql-server": "./src/electric-sql-server-plugin.mjs",
+    "./electric-sql-client": "./src/electric-sql-client-plugin.mjs"
   },
   "private": false,
   "publishConfig": {
@@ -37,7 +42,11 @@
   "peerDependencies": {
     "@electric-sql/client": "^1.5.24",
     "@electric-sql/pglite": "^0.5.8",
+    "@vueuse/core": "^14.3.0",
+    "dexie": "^4.4.4",
+    "drizzle-orm": "^0.45.2",
     "rxjs": "^7.8.2",
+    "uuid": "^14.0.1",
     "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
@@ -52,12 +61,35 @@
     },
     "vue": {
       "optional": true
+    },
+    "dexie": {
+      "optional": true
+    },
+    "uuid": {
+      "optional": true
+    },
+    "@vueuse/core": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@electric-sql/client": "^1.5.24",
     "@electric-sql/pglite": "^0.5.8",
+    "@jcbuisson/express-x": "^4.0.5",
+    "@vueuse/core": "^14.3.0",
+    "bcryptjs": "^2.4.3",
+    "dexie": "^4.4.4",
+    "drizzle-orm": "^0.45.2",
+    "express": "^5.3.0",
+    "fake-indexeddb": "^6.2.4",
+    "pg": "^8.19.0",
     "rxjs": "^7.8.2",
+    "socket.io": "^4.8.4",
+    "socket.io-client": "^4.8.3",
+    "uuid": "^14.0.1",
     "vue": "^3.5.0"
   }
 }