@nanolink/mirrors 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @nanolink/mirrors
+
+GraphQL subscription client + mirror synchronization helper utilities.
+
+## 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).
+
+## Install
+```
+npm install @nanolink/mirrors
+```
+
+If you need a proxy:
+```js
+// enableGlobalProxy.js
+import 'global-agent/bootstrap';
+process.env.GLOBAL_AGENT_HTTP_PROXY = 'http://proxy:3128';
+```
+Run node with: `node -r global-agent/bootstrap yourApp.js`
+
+## Usage
+```ts
+import { Connection } from '@nanolink/mirrors';
+
+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));
+
+async function start() {
+  const users = await conn.getMirror('users', /* GraphQL subscription */ `
+    subscription Users($version: Long!) {
+      users(version: $version) { type total deleteId deleteVersion data { id version name } }
+    }
+  `, {});
+
+  // Waits until first DONE; then you can read:
+  console.log('Initial size', users.size);
+  for (const [id, user] of users) console.log(user);
+}
+start();
+```
+
+## Events
+`SubscriptionClient` emits:
+- connecting, connected, reconnected, disconnected, retry, error
+
+`Connection` re‑emits mirror events as `mirror:<event>` with payload `{ mirrorName, ... }`:
+- start, updated, deleted, done, versionError, resubscribe, error, removed, 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()`
+
+## 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.
+
+## Build
+TypeScript compiles to `dist/`. Published package exposes `dist/index.js` and types.
+
+## License
+MIT

package/dist/DelegateMap.d.ts

@@ -0,0 +1,23 @@
+export interface ReadonlyMapView<K, V> extends Iterable<[K, V]> {
+    readonly size: number;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    forEach(callbackfn: (value: V, key: K, map: ReadonlyMapView<K, V>) => void, thisArg?: any): void;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}
+export declare class DelegatingMap<K, V> implements ReadonlyMapView<K, V> {
+    private readonly resolver;
+    constructor(resolver: () => Map<K, V>);
+    private t;
+    get size(): number;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    forEach(callbackfn: (value: V, key: K, map: ReadonlyMapView<K, V>) => void, thisArg?: any): void;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}

package/dist/DelegateMap.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegatingMap = void 0;
+class DelegatingMap {
+    constructor(resolver) {
+        this.resolver = resolver;
+    }
+    t() { return this.resolver(); }
+    get size() { return this.t().size; }
+    get(key) { return this.t().get(key); }
+    has(key) { return this.t().has(key); }
+    entries() { return this.t().entries(); }
+    keys() { return this.t().keys(); }
+    values() { return this.t().values(); }
+    forEach(callbackfn, thisArg) {
+        this.t().forEach(((v, k) => callbackfn(v, k, this)), thisArg);
+    }
+    [Symbol.iterator]() { return this.t()[Symbol.iterator](); }
+}
+exports.DelegatingMap = DelegatingMap;
+//# sourceMappingURL=DelegateMap.js.map

package/dist/DelegateMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DelegateMap.js","sourceRoot":"","sources":["../src/DelegateMap.ts"],"names":[],"mappings":";;;AAYA,MAAa,aAAa;IACxB,YAA6B,QAAyB;QAAzB,aAAQ,GAAR,QAAQ,CAAiB;IAAI,CAAC;IACnD,CAAC,KAAgB,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAClD,IAAI,IAAI,KAAa,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5C,GAAG,CAAC,GAAM,IAAmB,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACxD,GAAG,CAAC,GAAM,IAAa,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,KAA+B,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAClE,IAAI,KAA0B,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACvD,MAAM,KAA0B,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC3D,OAAO,CAAC,UAAkE,EAAE,OAAa;QACvF,IAAI,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAI,EAAE,CAAI,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAQ,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC;IACD,CAAC,MAAM,CAAC,QAAQ,CAAC,KAA+B,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;CACtF;AAbD,sCAaC"}

package/dist/MirrorSync.d.ts

@@ -0,0 +1,100 @@
+import { ReadonlyMapView } from './DelegateMap';
+import { SubscriptionClient } from './SubscriptionClient';
+import EventEmitter from 'eventemitter3';
+export declare enum SyncType {
+    DELETED = "DELETED",
+    UPDATED = "UPDATED",
+    START = "START",
+    DONE = "DONE",
+    VERSION_ERROR = "VERSION_ERROR"
+}
+export interface CacheSyncResult {
+    type: SyncType;
+    total?: number | null;
+    deleteId?: string;
+    data?: any;
+    deleteVersion?: number;
+    deleteOpVersion?: string;
+    opVersion?: string;
+}
+export interface MirrorSyncOptions {
+    /** Subscription document (query string) */
+    subscription: string;
+    /** Optional logger */
+    /** Custom variables base (besides version) */
+    baseVariables?: Record<string, unknown>;
+}
+export interface MirrorStats {
+    version: number;
+    opVersion?: string | null;
+    size: number;
+    fullSyncInProgress: boolean;
+    totalHint?: number | null;
+}
+export interface MirrorSyncEvents {
+    start: (info: {
+        full: boolean;
+    }) => void;
+    updated: (item: MirrorItem, isFullPhase: boolean) => void;
+    deleted: (info: {
+        id: string;
+        version: number | undefined;
+    }) => void;
+    done: (info: {
+        full: boolean;
+    }) => void;
+    versionError: (info: {
+        currentVersion: number;
+    }) => void;
+    resubscribe: (info: {
+        fromVersion: number;
+    }) => void;
+    error?: (errors: any) => void;
+}
+export interface MirrorItem {
+    id: string;
+    version?: number;
+    opVersion?: string;
+    [k: string]: any;
+}
+/**
+ * MirrorSync maintains an in-memory mirror of server state based on CacheSyncResult messages.
+ * Generic TBase is the item shape (must include id & version).
+ */
+export declare class MirrorSync extends EventEmitter {
+    private client;
+    private options;
+    private mirror;
+    private buffer;
+    private currentVersion;
+    private currentOpVersion;
+    private unsub;
+    private fullSyncPhase;
+    private log?;
+    private dmap;
+    /** Deferred promise resolved on first DONE after a (re)start full sync cycle. Reset on constructor, start(), and VERSION_ERROR re-init. */
+    loaded: Promise<ReadonlyMapView<string, any>>;
+    private resolveLoaded?;
+    constructor(client: SubscriptionClient, options: MirrorSyncOptions & {
+        log?: (msg: string, meta?: any) => void;
+    });
+    private l;
+    private attachClientEvents;
+    private needsFullSync;
+    private targetMap;
+    private advanceNumeric;
+    private advanceOp;
+    private subscribe;
+    private resubscribe;
+    private start;
+    load(): Promise<ReadonlyMapView<string, any>>;
+    private resetLoaded;
+    private handlePayload;
+    private normalizeItems;
+    private applyUpdated;
+    private applyDeleted;
+    get(id: string): any | undefined;
+    values(): any[];
+    stats(): MirrorStats;
+    stop(): void;
+}

package/dist/MirrorSync.js

@@ -0,0 +1,221 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MirrorSync = exports.SyncType = void 0;
+const DelegateMap_1 = require("./DelegateMap");
+const eventemitter3_1 = __importDefault(require("eventemitter3"));
+// SyncType enum as described
+var SyncType;
+(function (SyncType) {
+    SyncType["DELETED"] = "DELETED";
+    SyncType["UPDATED"] = "UPDATED";
+    SyncType["START"] = "START";
+    SyncType["DONE"] = "DONE";
+    SyncType["VERSION_ERROR"] = "VERSION_ERROR";
+})(SyncType || (exports.SyncType = SyncType = {}));
+/**
+ * MirrorSync maintains an in-memory mirror of server state based on CacheSyncResult messages.
+ * Generic TBase is the item shape (must include id & version).
+ */
+class MirrorSync extends eventemitter3_1.default {
+    constructor(client, options) {
+        super();
+        this.mirror = new Map();
+        this.buffer = null; // used during full/resubscription phase
+        this.currentVersion = -1; // numeric cursor (-1 => full sync needed)
+        this.currentOpVersion = null; // op cursor (null => full sync needed)
+        this.unsub = null;
+        this.fullSyncPhase = false; // only true during START..DONE when initiating from version -1
+        this.dmap = new DelegateMap_1.DelegatingMap(() => this.mirror);
+        this.client = client;
+        this.options = options;
+        this.log = options.log;
+        this.attachClientEvents();
+        this.resetLoaded();
+    }
+    l(msg, meta) { if (this.log)
+        this.log(msg, meta); }
+    attachClientEvents() {
+        this.client.on('reconnected', () => {
+            // On reconnect start a resubscription from currentVersion
+            this.emit('resubscribe', { fromVersion: this.currentVersion }); // keep existing event shape (no new events)
+            this.resubscribe();
+        });
+        // Handle first successful connection if start was invoked early
+        this.client.on('connected', () => {
+            if ((this.currentVersion === -1 || this.currentOpVersion === null) && !this.unsub) {
+                this.l('initial connected subscribe', { version: this.currentVersion, opVersion: this.currentOpVersion });
+                this.subscribe(this.currentVersion, this.currentOpVersion);
+            }
+        });
+    }
+    needsFullSync() { return this.currentVersion === -1 || this.currentOpVersion === null; }
+    targetMap() { return (this.fullSyncPhase && this.buffer) ? this.buffer : this.mirror; }
+    advanceNumeric(v) { if (typeof v === 'number' && v > this.currentVersion)
+        this.currentVersion = v; }
+    advanceOp(v) { if (v && (!this.currentOpVersion || v > this.currentOpVersion))
+        this.currentOpVersion = v; }
+    subscribe(version, opVersion) {
+        if (!this.client)
+            throw new Error('SubscriptionClient missing');
+        if (this.unsub) {
+            this.unsub();
+            this.unsub = null;
+        }
+        const variables = { version, opVersion, ...(this.options.baseVariables || {}) };
+        this.l('subscribe', { version, opVersion });
+        this.unsub = this.client.subscribe({ query: this.options.subscription, variables }, {
+            next: (envelope) => {
+                if (envelope.errors) {
+                    this.l('graphql errors', envelope.errors);
+                    this.emit('error', envelope.errors);
+                }
+                const payload = envelope.data;
+                if (payload)
+                    this.handlePayload(payload);
+            },
+            error: (err) => this.l('subscription error', err),
+            complete: () => this.l('subscription complete'),
+        });
+    }
+    resubscribe() {
+        // Resubscribe starting from current cursors
+        this.subscribe(this.currentVersion, this.currentOpVersion);
+    }
+    start() {
+        if (!this.client.isConnected()) {
+            this.l('start deferred (not connected)');
+            return;
+        }
+        this.subscribe(this.currentVersion, this.currentOpVersion);
+    }
+    load() {
+        if (!this.unsub)
+            this.start();
+        return this.loaded;
+    }
+    resetLoaded() {
+        this.loaded = new Promise(resolve => {
+            this.resolveLoaded = resolve;
+        });
+    }
+    handlePayload(raw) {
+        if (!raw)
+            return;
+        // Always pick the first field in the payload object regardless of configured rootField
+        const firstKey = Object.keys(raw)[0];
+        if (!firstKey)
+            return;
+        const msg = raw[firstKey];
+        if (!msg)
+            return;
+        const { type } = msg;
+        switch (type) {
+            case SyncType.START: {
+                const isFull = this.needsFullSync();
+                this.fullSyncPhase = isFull;
+                // Only allocate a new buffer for a true full sync; for delta/resubscribe we append directly
+                this.buffer = isFull ? new Map() : null;
+                const payload = { full: isFull };
+                this.emit('start', payload);
+                break;
+            }
+            case SyncType.UPDATED:
+                this.applyUpdated(msg.data, this.fullSyncPhase);
+                break;
+            case SyncType.DELETED:
+                this.applyDeleted(msg.deleteId, msg.deleteVersion, msg.deleteOpVersion);
+                break;
+            case SyncType.DONE: {
+                const wasFull = this.fullSyncPhase;
+                if (wasFull && this.buffer) {
+                    this.mirror = this.buffer;
+                    this.buffer = null;
+                }
+                this.fullSyncPhase = false;
+                const d = { full: wasFull };
+                this.emit('done', d);
+                // Resolve deferred if pending
+                if (this.resolveLoaded) {
+                    const r = this.resolveLoaded;
+                    this.resolveLoaded = undefined;
+                    r(this.dmap);
+                }
+                break;
+            }
+            case SyncType.VERSION_ERROR:
+                const ve = { currentVersion: this.currentVersion };
+                this.emit('versionError', ve);
+                // restart as full sync
+                this.currentVersion = -1;
+                this.currentOpVersion = null;
+                this.buffer = null;
+                this.resetLoaded();
+                this.subscribe(this.currentVersion, this.currentOpVersion);
+                break;
+        }
+    }
+    normalizeItems(data) {
+        if (!data)
+            return [];
+        return Array.isArray(data) ? data : [data];
+    }
+    applyUpdated(data, isFullPhase) {
+        for (const item of this.normalizeItems(data)) {
+            if (!item || typeof item.id !== 'string')
+                continue;
+            const hasNumeric = typeof item.version === 'number';
+            const hasOp = typeof item.opVersion === 'string';
+            if (!hasNumeric && !hasOp)
+                continue;
+            const existing = this.targetMap().get(item.id);
+            const newerNumeric = hasNumeric && (!existing?.version || item.version >= existing.version);
+            const newerOp = hasOp && (!existing?.opVersion || item.opVersion >= existing.opVersion);
+            if (!existing || newerNumeric || newerOp) {
+                this.targetMap().set(item.id, item);
+                this.advanceNumeric(item.version);
+                this.advanceOp(item.opVersion);
+                this.emit('updated', item, isFullPhase);
+            }
+        }
+    }
+    applyDeleted(id, deleteVersion, deleteOpVersion) {
+        if (!id)
+            return;
+        const numericStale = !this.fullSyncPhase && typeof deleteVersion === 'number' && this.currentVersion >= 0 && deleteVersion < this.currentVersion;
+        const opStale = !this.fullSyncPhase && deleteOpVersion && this.currentOpVersion && deleteOpVersion < this.currentOpVersion;
+        if (numericStale && opStale) {
+            this.l?.('skip stale delete', { id, deleteVersion, deleteOpVersion });
+            return;
+        }
+        this.targetMap().delete(id);
+        this.advanceNumeric(deleteVersion);
+        this.advanceOp(deleteOpVersion);
+        const del = { id, version: deleteVersion };
+        if (deleteOpVersion)
+            del.opVersion = deleteOpVersion;
+        this.emit('deleted', del);
+    }
+    get(id) { return this.mirror.get(id); }
+    values() { return Array.from(this.mirror.values()); }
+    stats() { return { version: this.currentVersion, opVersion: this.currentOpVersion, size: this.mirror.size, fullSyncInProgress: this.fullSyncPhase }; }
+    stop() {
+        if (this.unsub) {
+            this.unsub();
+            this.unsub = null;
+        }
+        this.currentVersion = -1;
+        this.currentOpVersion = null;
+        this.buffer = null;
+        if (this.resolveLoaded) {
+            const r = this.resolveLoaded;
+            this.resolveLoaded = undefined;
+            r(this.dmap);
+        }
+        this.resetLoaded();
+    }
+}
+exports.MirrorSync = MirrorSync;
+//# sourceMappingURL=MirrorSync.js.map

package/dist/MirrorSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MirrorSync.js","sourceRoot":"","sources":["../src/MirrorSync.ts"],"names":[],"mappings":"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"}

package/dist/SubscriptionClient.d.ts

@@ -0,0 +1,77 @@
+import { ClientOptions } from 'graphql-ws';
+import EventEmitter from 'eventemitter3';
+/** Events emitted by SubscriptionClient
+ * connecting   - before opening a socket (initial or reconnect attempt)
+ * connected    - first successful connection
+ * reconnected  - a subsequent successful connection after a disconnect
+ * disconnected - socket closed ( { code, reason, wasClean } )
+ * error        - protocol or network error (Error)
+ * retry        - about to attempt reconnect ( { attempt } )
+ */
+export interface SubscriptionClientEvents {
+    connecting: () => void;
+    connected: () => void;
+    reconnected: () => void;
+    disconnected: (info: {
+        code: number;
+        reason: string;
+        wasClean: boolean;
+    }) => void;
+    error: (err: unknown) => void;
+    retry: (info: {
+        attempt: number;
+    }) => void;
+}
+export interface SubscriptionClientOptions {
+    url: string;
+    /** optional async or sync connection params */
+    connectionParams?: ClientOptions['connectionParams'];
+    /** number of reconnect attempts, default Infinity */
+    maxReconnectAttempts?: number;
+    /** initial delay ms before first retry (exponential backoff) */
+    retryDelayMs?: number;
+    /** max backoff cap */
+    maxRetryDelayMs?: number;
+    /** idle timeout for operations (optional) */
+    operationTimeoutMs?: number;
+    /** optional custom WebSocket implementation */
+    webSocketImpl?: any;
+    /** optional logger */
+    log?: (msg: string, meta?: any) => void;
+}
+export interface SubscribeOptions<TData = any, TVars = Record<string, unknown>> {
+    query: string;
+    variables?: TVars;
+    /** optional per-subscription timeout override */
+    timeoutMs?: number;
+    operationName?: string;
+    extensions?: Record<string, any>;
+}
+export interface Observer<T> {
+    next?: (data: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+}
+export declare class SubscriptionClient extends EventEmitter {
+    private options;
+    private client;
+    private connectAttempt;
+    private closedExplicitly;
+    private reconnecting;
+    private hasEverConnected;
+    constructor(opts: SubscriptionClientOptions);
+    private resolveWebSocketImpl;
+    /** Returns true if an underlying websocket client exists (connected or in-flight). */
+    isConnected(): boolean;
+    private log;
+    private createClientIfNeeded;
+    /** Establish the WebSocket connection if not already created. Idempotent. */
+    connect(): void;
+    private scheduleReconnect;
+    subscribe<TData = any, TVars extends Record<string, unknown> = Record<string, unknown>>(options: SubscribeOptions<TData, TVars>, observer: Observer<{
+        data?: TData;
+        errors?: any;
+    }>): () => void;
+    close(code?: number, reason?: string): Promise<void>;
+}
+export default SubscriptionClient;