@crdt-sync/core 0.1.2 → 0.2.1

package/dist/WebSocketManager.d.ts

@@ -1,115 +0,0 @@
-import { CrdtStateProxy } from './CrdtStateProxy.js';
-import type { WasmStateStore } from './CrdtStateProxy.js';
-/**
- * Minimal subset of the browser `WebSocket` API used by `WebSocketManager`.
- *
- * The real browser `WebSocket` satisfies this interface out-of-the-box.
- * In tests, a plain mock object can be used instead.
- */
-export interface WebSocketLike {
-    /** Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). */
-    readonly readyState: number;
-    /** Send a UTF-8 string frame to the server. */
-    send(data: string): void;
-    /** Initiate the closing handshake. */
-    close(): void;
-    /** Fired when a message frame is received. */
-    onmessage: ((event: {
-        data: string;
-    }) => void) | null;
-    /** Fired when the connection is established. */
-    onopen: ((event: unknown) => void) | null;
-    /** Fired when the connection is closed. */
-    onclose: ((event: unknown) => void) | null;
-    /** Fired when an error occurs. */
-    onerror: ((event: unknown) => void) | null;
-}
-/**
- * Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT
- * operation produced locally is broadcast to peers, and every envelope
- * received from a peer is applied to the local store.
- *
- * ## Data flow
- *
- * ```
- * Local write
- *   → CrdtStateProxy.onUpdate  (envelope collected in _pendingEnvelopes)
- *   → requestAnimationFrame / setTimeout schedules a batch flush
- *   → WebSocket.send(JSON.stringify(envelopes))   // one payload per frame
- *
- * Incoming message (single envelope or JSON array of envelopes)
- *   → WebSocket.onmessage
- *   → WasmStateStore.apply_envelope()    // merge into local store
- * ```
- *
- * ## Throttling / batching
- *
- * Multiple proxy writes that occur within the same JavaScript task (e.g. a
- * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single
- * JSON array payload on the next animation frame (browser) or the next
- * `setTimeout(fn, 0)` tick (Node.js / non-browser environments).  This keeps
- * network traffic proportional to frame rate rather than to the raw mutation
- * rate.
- *
- * ## Usage
- *
- * ```ts
- * import init, { WasmStateStore } from './crdt_sync.js';
- * import { CrdtStateProxy, WebSocketManager } from './index.js';
- *
- * await init();
- * const store = new WasmStateStore('node-1');
- * const proxy = new CrdtStateProxy(store);
- * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));
- *
- * // Writes are automatically batched and broadcast to peers.
- * proxy.state.robot = { x: 10, y: 20 };
- *
- * // Clean up.
- * manager.disconnect();
- * ```
- */
-export declare class WebSocketManager {
-    private readonly _store;
-    private readonly _proxy;
-    private readonly _ws;
-    private _unsubscribe;
-    /** Envelopes collected in the current frame, waiting for the batch flush. */
-    private _pendingEnvelopes;
-    /** Cancels the currently scheduled batch flush (rAF or setTimeout handle). */
-    private _cancelFlush;
-    /** Envelopes queued while the socket is not open, flushed on reconnection. */
-    private _offlineQueue;
-    /**
-     * Create a `WebSocketManager` and attach it to the given WebSocket.
-     *
-     * @param store - The Wasm state store. Incoming peer envelopes will be
-     *   applied to this store via `apply_envelope`.
-     * @param proxy - The CRDT state proxy. Outgoing envelopes produced by
-     *   `set_register` calls will be read from the proxy's `onUpdate` events.
-     * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).
-     */
-    constructor(store: WasmStateStore, proxy: CrdtStateProxy, ws: WebSocketLike);
-    private _attach;
-    /**
-     * Schedule a single batch flush for the current frame.  Subsequent calls
-     * before the flush fires are no-ops (only one flush is ever outstanding).
-     *
-     * Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),
-     * falling back to `setTimeout(fn, 0)` in non-browser environments.
-     */
-    private _scheduleBatchFlush;
-    /**
-     * Send all pending envelopes as a single JSON-array payload, or move them
-     * to the offline queue if the socket is not currently open.
-     */
-    private _flushBatch;
-    /**
-     * Unsubscribe from proxy updates, discard any buffered envelopes, and close
-     * the WebSocket connection.
-     *
-     * Safe to call more than once.
-     */
-    disconnect(): void;
-}
-//# sourceMappingURL=WebSocketManager.d.ts.map

package/dist/WebSocketManager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"WebSocketManager.d.ts","sourceRoot":"","sources":["../src/WebSocketManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sCAAsC;IACtC,KAAK,IAAI,IAAI,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACtD,gDAAgD;IAChD,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,2CAA2C;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,kCAAkC;IAClC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,YAAY,CAA6B;IACjD,6EAA6E;IAC7E,OAAO,CAAC,iBAAiB,CAAgB;IACzC,8EAA8E;IAC9E,OAAO,CAAC,YAAY,CAA6B;IACjD,8EAA8E;IAC9E,OAAO,CAAC,aAAa,CAAgB;IAErC;;;;;;;;OAQG;gBACS,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,aAAa;IAS3E,OAAO,CAAC,OAAO;IAoDf;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAcnB;;;;;OAKG;IACH,UAAU,IAAI,IAAI;CASnB"}

package/dist/WebSocketManager.js

@@ -1,179 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketManager = void 0;
-/**
- * Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT
- * operation produced locally is broadcast to peers, and every envelope
- * received from a peer is applied to the local store.
- *
- * ## Data flow
- *
- * ```
- * Local write
- *   → CrdtStateProxy.onUpdate  (envelope collected in _pendingEnvelopes)
- *   → requestAnimationFrame / setTimeout schedules a batch flush
- *   → WebSocket.send(JSON.stringify(envelopes))   // one payload per frame
- *
- * Incoming message (single envelope or JSON array of envelopes)
- *   → WebSocket.onmessage
- *   → WasmStateStore.apply_envelope()    // merge into local store
- * ```
- *
- * ## Throttling / batching
- *
- * Multiple proxy writes that occur within the same JavaScript task (e.g. a
- * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single
- * JSON array payload on the next animation frame (browser) or the next
- * `setTimeout(fn, 0)` tick (Node.js / non-browser environments).  This keeps
- * network traffic proportional to frame rate rather than to the raw mutation
- * rate.
- *
- * ## Usage
- *
- * ```ts
- * import init, { WasmStateStore } from './crdt_sync.js';
- * import { CrdtStateProxy, WebSocketManager } from './index.js';
- *
- * await init();
- * const store = new WasmStateStore('node-1');
- * const proxy = new CrdtStateProxy(store);
- * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));
- *
- * // Writes are automatically batched and broadcast to peers.
- * proxy.state.robot = { x: 10, y: 20 };
- *
- * // Clean up.
- * manager.disconnect();
- * ```
- */
-class WebSocketManager {
-    /**
-     * Create a `WebSocketManager` and attach it to the given WebSocket.
-     *
-     * @param store - The Wasm state store. Incoming peer envelopes will be
-     *   applied to this store via `apply_envelope`.
-     * @param proxy - The CRDT state proxy. Outgoing envelopes produced by
-     *   `set_register` calls will be read from the proxy's `onUpdate` events.
-     * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).
-     */
-    constructor(store, proxy, ws) {
-        this._unsubscribe = null;
-        /** Envelopes collected in the current frame, waiting for the batch flush. */
-        this._pendingEnvelopes = [];
-        /** Cancels the currently scheduled batch flush (rAF or setTimeout handle). */
-        this._cancelFlush = null;
-        /** Envelopes queued while the socket is not open, flushed on reconnection. */
-        this._offlineQueue = [];
-        this._store = store;
-        this._proxy = proxy;
-        this._ws = ws;
-        this._attach();
-    }
-    // ── Internal setup ────────────────────────────────────────────────────
-    _attach() {
-        const ws = this._ws;
-        // Collect envelopes and schedule a batch flush once per frame so that
-        // multiple synchronous writes (e.g. a 60 FPS game loop) are coalesced
-        // into a single network payload instead of one message per mutation.
-        this._unsubscribe = this._proxy.onUpdate(({ envelope }) => {
-            this._pendingEnvelopes.push(envelope);
-            this._scheduleBatchFlush();
-        });
-        // On (re)connection, immediately flush pending envelopes together with any
-        // envelopes that were queued while the socket was offline.
-        ws.onopen = () => {
-            // Cancel any scheduled flush — we will drain everything right now.
-            this._cancelFlush?.();
-            this._cancelFlush = null;
-            const offline = this._offlineQueue;
-            const pending = this._pendingEnvelopes;
-            this._offlineQueue = [];
-            this._pendingEnvelopes = [];
-            const batch = [...offline, ...pending];
-            if (batch.length > 0) {
-                ws.send(JSON.stringify(batch));
-            }
-        };
-        // Apply envelopes received from peers.  Peers may send either a single
-        // envelope JSON string or a JSON array of envelope strings (batch format).
-        ws.onmessage = (event) => {
-            let parsed;
-            try {
-                parsed = JSON.parse(event.data);
-            }
-            catch {
-                parsed = null;
-            }
-            if (Array.isArray(parsed)) {
-                for (const env of parsed) {
-                    this._store.apply_envelope(env);
-                }
-            }
-            else {
-                // Fallback: treat the raw frame data as a single envelope string.
-                this._store.apply_envelope(event.data);
-            }
-        };
-        // On close or error the subscription stays active so that writes made
-        // while offline are buffered and flushed when the socket reconnects.
-        ws.onclose = () => { };
-        ws.onerror = () => { };
-    }
-    /**
-     * Schedule a single batch flush for the current frame.  Subsequent calls
-     * before the flush fires are no-ops (only one flush is ever outstanding).
-     *
-     * Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),
-     * falling back to `setTimeout(fn, 0)` in non-browser environments.
-     */
-    _scheduleBatchFlush() {
-        if (this._cancelFlush !== null)
-            return; // already scheduled
-        const doFlush = () => {
-            this._cancelFlush = null;
-            this._flushBatch();
-        };
-        if (typeof requestAnimationFrame === 'function') {
-            const id = requestAnimationFrame(doFlush);
-            this._cancelFlush = () => cancelAnimationFrame(id);
-        }
-        else {
-            const id = setTimeout(doFlush, 0);
-            this._cancelFlush = () => clearTimeout(id);
-        }
-    }
-    /**
-     * Send all pending envelopes as a single JSON-array payload, or move them
-     * to the offline queue if the socket is not currently open.
-     */
-    _flushBatch() {
-        const envelopes = this._pendingEnvelopes.splice(0);
-        if (envelopes.length === 0)
-            return;
-        const ws = this._ws;
-        if (ws.readyState === 1 /* OPEN */) {
-            ws.send(JSON.stringify(envelopes));
-        }
-        else {
-            this._offlineQueue.push(...envelopes);
-        }
-    }
-    // ── Public API ────────────────────────────────────────────────────────
-    /**
-     * Unsubscribe from proxy updates, discard any buffered envelopes, and close
-     * the WebSocket connection.
-     *
-     * Safe to call more than once.
-     */
-    disconnect() {
-        this._unsubscribe?.();
-        this._unsubscribe = null;
-        this._cancelFlush?.();
-        this._cancelFlush = null;
-        this._pendingEnvelopes = [];
-        this._offlineQueue = [];
-        this._ws.close();
-    }
-}
-exports.WebSocketManager = WebSocketManager;
-//# sourceMappingURL=WebSocketManager.js.map

package/dist/WebSocketManager.js.map

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

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}