@nanolink/mirrors 1.0.1 → 1.0.2

package/README.md

@@ -1,30 +1,37 @@
 # @nanolink/mirrors
 
-GraphQL subscription client + mirror synchronization helper utilities.
+GraphQL subscription client + in‑memory mirror synchronization utilities. Optimized for incremental change streams that send START / UPDATED / DELETED / DONE / VERSION_ERROR frames.
 
 ## Features
-- Lightweight `SubscriptionClient` around `graphql-ws` with manual reconnect & lifecycle events.
-- `MirrorSync` keeps a local in‑memory mirror using START / UPDATED / DELETED / DONE / VERSION_ERROR messages.
-- Deferred `loaded` promise resolves after first full sync DONE.
-- Automatic resubscribe after reconnect (from last version) without duplicating items.
-- Read‑only delegated map interface for safe consumer access.
-- `Connection` helper to manage multiple named mirrors and re‑emit namespaced events (`mirror:start`, `mirror:updated`, ...).
-- Optional global proxy support via `global-agent` (enable before creating the client).
+* Lightweight `SubscriptionClient` around `graphql-ws` with explicit connect, controlled reconnect, and small event surface.
+* Dual version support in `MirrorSync` (`version` numeric + `opVersion` string) for hybrid sequence + causality ordering (either dimension can drive resync logic).
+* Stale delete & update guards: ignores events older in either version dimension to prevent resurrecting removed or outdated entities.
+* Efficient updates: UPDATED replaces item wholesale only when newer; no deep merge overhead.
+* Full sync cycle handling via START/DONE gates; `loaded` promise resolves after first DONE and re-arms on VERSION_ERROR.
+* Automatic resubscribe after reconnect using last known versions (no duplicate inserts).
+* Read‑only delegated map interface for consumers (prevents accidental mutation of internal state).
+* `Connection` helper manages multiple mirrors, re‑emitting namespaced events (`mirror:start`, `mirror:updated`, ...).
+* Proxy-aware WebSocket resolution: if proxy env vars are present (ALL_PROXY / HTTPS_PROXY / HTTP_PROXY / GLOBAL_AGENT_HTTP_PROXY) the client prefers the Node `ws` implementation; otherwise uses existing global WebSocket (browser / Node >=18) or falls back to `ws`.
+* Minimal dependencies; event system via `eventemitter3`.
 
 ## Install
-```
+```bash
 npm install @nanolink/mirrors
 ```
 
-If you need a proxy:
+Optional (proxy via global-agent for generic HTTP(S) requests—WebSocket selection is still handled automatically as described):
 ```js
-// enableGlobalProxy.js
+// enableProxy.js
 import 'global-agent/bootstrap';
 process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://proxy:3128';
 ```
-Run node with: `node -r global-agent/bootstrap yourApp.js`
+Run with:
+```bash
+node -r global-agent/bootstrap app.js
+```
 
 ## Usage
+### Quick (multi‑mirror connection)
 ```ts
 import { Connection } from '@nanolink/mirrors';
 
@@ -32,42 +39,89 @@ const conn = new Connection('https://api.example.com', 'TOKEN');
 conn.connect();
 
 conn.on('connected', () => console.log('socket up'));
-conn.on('mirror:updated', e => console.log('item updated', e.mirrorName, e.item.id));
+conn.on('mirror:updated', e => console.log('updated', e.mirrorName, e.item.id));
 
-async function start() {
+async function main() {
   const users = await conn.getMirror('users', /* GraphQL subscription */ `
-    subscription Users($version: Long!) {
-      users(version: $version) { type total deleteId deleteVersion data { id version name } }
+    subscription Users($version: Long, $opVersion: String) {
+      users(version: $version, opVersion: $opVersion) {
+        type
+        total
+        deleteId
+        deleteVersion
+        deleteOpVersion
+        data { id version opVersion name }
+      }
     }
   `, {});
 
-  // Waits until first DONE; then you can read:
   console.log('Initial size', users.size);
-  for (const [id, user] of users) console.log(user);
+  for (const user of users.values()) {
+    console.log(user);
+  }
 }
-start();
+main();
+```
+
+### Direct low‑level client
+```ts
+import { SubscriptionClient } from '@nanolink/mirrors';
+
+const sc = new SubscriptionClient({ url: 'https://api.example.com', maxReconnectAttempts: 10 });
+sc.connect();
+sc.on('connected', () => {
+  const dispose = sc.subscribe({
+    query: 'subscription Ping { ping }'
+  }, {
+    next: (msg) => console.log(msg),
+    error: (e) => console.error('err', e),
+    complete: () => console.log('done')
+  });
+});
 ```
 
 ## Events
 `SubscriptionClient` emits:
-- connecting, connected, reconnected, disconnected, retry, error
+* connecting
+* connected (first successful connect)
+* reconnected (subsequent successful connect after a disconnect)
+* disconnected ({ code, reason, wasClean })
+* retry ({ attempt }) before a reconnect attempt delay
+* error (network/protocol)
 
 `Connection` re‑emits mirror events as `mirror:<event>` with payload `{ mirrorName, ... }`:
-- start, updated, deleted, done, versionError, resubscribe, error, removed, cleared
+* start
+* updated (only when a newer item actually replaced stored data)
+* deleted
+* done (end of full sync batch)
+* versionError (triggered resync)
+* resubscribe (automatic after reconnect)
+* error
+* removed (mirror explicitly removed)
+* cleared (mirror internal state cleared)
 
 ## API Surface
-- `SubscriptionClient` - low level client (call `connect()` then `subscribe()`)
-- `MirrorSync` - single mirror controller (normally use via `Connection.getMirror()`)
-- `Connection` - multi‑mirror manager extending `SubscriptionClient`
-- `ReadonlyMapView` - interface returned by `getMirror()` / `MirrorSync.load()`
+* `SubscriptionClient` – low level websocket subscription wrapper.
+* `MirrorSync` – single mirror controller (dual version tracking).
+* `Connection` – manages multiple mirrors + namespaced events.
+* `ReadonlyMapView` – immutable view returned by `getMirror()` / `MirrorSync.load()`.
 
 ## Notes
-- Always call `connect()` explicitly; there is no implicit lazy connect.
-- A VERSION_ERROR triggers an automatic full resync (resetting the loaded promise).
-- The first (and only the first) field in the GraphQL payload is used as the sync message wrapper.
+* Always call `connect()` explicitly; no implicit lazy connect.
+* VERSION_ERROR triggers automatic full resync (re-arms `loaded`).
+* First top-level field in GraphQL subscription payload is treated as the sync envelope.
+* Provide `webSocketImpl` manually if bundling for environments without a global WebSocket and you do NOT want `ws` as fallback.
+* When proxy env vars are set in Node, `SubscriptionClient` prefers `ws` (allowing external agent configuration); browsers ignore these env vars.
 
-## Build
-TypeScript compiles to `dist/`. Published package exposes `dist/index.js` and types.
+## Build & Publish
+TypeScript sources compile to `dist/`.
+
+Scripts:
+```bash
+npm run build       # compile
+npm run publish:dry # preview publish contents
+npm run release     # build + publish (public)
+```
 
 ## License
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanolink/mirrors",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "GraphQL subscription client + mirror synchronization utilities.",
   "license": "MIT",
   "author": "Nanolink ApS, Mogens Bak Nielsen",