npm - @crdt-sync/core - Versions diffs - 0.2.2 → 0.3.0 - Mend

@crdt-sync/core 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/index.d.mts CHANGED Viewed

@@ -1,3 +1,5 @@
+export { WasmStateStore, default as initWasm } from '../pkg/web/crdt_sync.js';
 /**
  * TypeScript interface matching the Wasm-bindgen-generated `WasmStateStore`.
  *
@@ -18,7 +20,7 @@ interface WasmStateStore {
  * through the proxy.
  */
 interface UpdateEvent {
-    /** Dot-separated key path that was updated (e.g. `"robot.speed"`). */
+    /** The register key that was updated (e.g. `"speed"` or `"robot.speed"`). */
     key: string;
     /** The new JavaScript value. */
     value: unknown;
@@ -32,50 +34,42 @@ interface UpdateEvent {
 type UpdateHandler = (event: UpdateEvent) => void;
 /**
  * A TypeScript proxy wrapper around `WasmStateStore` that gives frontend
- * developers a **magical, object-oriented** experience.
+ * developers a transparent, object-oriented experience.
  *
- * ## How it works
+ * ## Reading state
  *
- * 1. **JS `Proxy` interception** – accessing a nested path on `state` returns
- *    another `Proxy`.  Assigning a value anywhere in the tree intercepts the
- *    write and forwards it to the underlying Wasm store via
- *    `set_register(dotPath, JSON.stringify(value))`.
+ * Access any registered key directly on `proxy.state`:
  *
- * 2. **Wasm call** – the interceptor immediately calls
- *    `WasmStateStore.set_register()` so the CRDT operation is recorded and
- *    returns an `Envelope` JSON string ready for broadcasting.
+ * ```ts
+ * proxy.state.speed        // returns the registered value, or undefined
+ * proxy.state["robot.speed"] // dot-path keys via bracket notation
+ * ```
  *
- * 3. **Event emitter** – every write fires all `onUpdate` listeners with the
- *    full `UpdateEvent` (key, value, envelope), enabling React / Vue and other
- *    UI frameworks to react to state changes.
+ * ## Writing state
  *
- * ## Usage
+ * Assign any value — primitives, objects, arrays:
  *
  * ```ts
- * import init, { WasmStateStore } from './crdt_sync.js';
- * import { CrdtStateProxy } from './CrdtStateProxy.js';
- *
- * await init();
- * const store = new WasmStateStore('node-1');
- * const proxy = new CrdtStateProxy(store);
+ * proxy.state.speed = 100;
+ * proxy.state.robot = { x: 10, y: 20 };    // store the whole object
+ * proxy.state["robot.speed"] = 100;         // dot-path key
+ * ```
  *
- * // Register a listener (e.g. trigger a React re-render).
- * const unsubscribe = proxy.onUpdate(({ key, value, envelope }) => {
- *   console.log(`${key} =`, value);
- *   broadcast(envelope); // send to peers
- * });
+ * ## Listening for changes
  *
- * // Write through the proxy — the interceptor handles everything.
- * proxy.state.speed = 100;
- * proxy.state.robot.x = 42;
+ * - `onUpdate(handler)` — fires on **local** writes with the full `UpdateEvent`
+ *   (key, value, envelope). Used by `WebSocketManager` to collect outgoing envelopes.
+ * - `onChange(handler)` — fires on **any** change: local writes _and_ remote
+ *   `apply_envelope` notifications. Use this in UI frameworks to trigger re-renders.
  *
- * // Clean up when done.
- * unsubscribe();
+ * ```ts
+ * const unsubscribe = proxy.onChange(() => setTick(t => t + 1));
  * ```
  */
 declare class CrdtStateProxy {
     private readonly _store;
     private readonly _handlers;
+    private readonly _changeHandlers;
     private readonly _state;
     /**
      * Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.
@@ -86,35 +80,56 @@ declare class CrdtStateProxy {
     /**
      * The proxied state object.
      *
-     * Assigning any property (or nested property) on this object will
-     * automatically call `WasmStateStore.set_register` and fire `onUpdate`
-     * listeners.
-     *
-     * ```ts
-     * proxy.state.speed = 100;       // key: "speed"
-     * proxy.state.robot.speed = 100; // key: "robot.speed"
-     * ```
+     * Reading a key returns the registered value, or `undefined` if it has
+     * not been set yet.  Assigning a value calls `WasmStateStore.set_register`
+     * and fires all `onUpdate` and `onChange` listeners.
      */
     get state(): Record<string, unknown>;
     /**
-     * Register a listener that is called whenever a property is written through
-     * `proxy.state`.
+     * Register a listener that fires whenever a value is written through
+     * `proxy.state` (local writes only).
      *
-     * @param handler - Callback receiving an `UpdateEvent`.
-     * @returns An unsubscribe function — call it to remove the listener.
+     * The `UpdateEvent` carries the register key, new value, and the CRDT
+     * envelope — forward the envelope to peers via `apply_envelope`.
+     *
+     * @returns An unsubscribe function.
      */
     onUpdate(handler: UpdateHandler): () => void;
     /**
-     * Recursively build a `Proxy` for the given dot-path `prefix`.
+     * Register a listener that fires whenever state changes — whether from a
+     * local write or an incoming remote update (after `notifyRemoteUpdate`).
+     *
+     * Use this in UI frameworks to trigger re-renders:
+     *
+     * ```ts
+     * proxy.onChange(() => setTick(t => t + 1));
+     * ```
      *
-     * - **`get` trap**: returns a child proxy for the nested path so that deep
-     *   assignments like `proxy.state.robot.speed = 100` work correctly.
+     * @returns An unsubscribe function.
+     */
+    onChange(handler: () => void): () => void;
+    /**
+     * Notify all `onChange` listeners that remote state has been applied to the
+     * store.  Called by `WebSocketManager` after every `apply_envelope` so that
+     * UI frameworks re-render with the latest state.
+     */
+    notifyRemoteUpdate(): void;
+    /**
+     * Build the state `Proxy`.
+     *
+     * - **`get` trap**: reads the value from the WASM store via `get_register`.
+     *   Returns the parsed value, or `undefined` if the key has not been registered.
      * - **`set` trap**: serialises the value, calls `set_register`, and fires
-     *   all `onUpdate` listeners.
+     *   all `onUpdate` and `onChange` listeners.
+     *
+     * Keys may be dot-separated paths (e.g. `"robot.speed"`) when using bracket
+     * notation: `proxy.state["robot.speed"] = 100`.
      */
     private _makeProxy;
-    /** Dispatch an `UpdateEvent` to all registered handlers. */
+    /** Dispatch an `UpdateEvent` to all `onUpdate` handlers. */
     private _emit;
+    /** Notify all `onChange` handlers of a state change. */
+    private _emitChange;
 }
 /**
@@ -230,4 +245,4 @@ declare class WebSocketManager {
     disconnect(): void;
 }
-export { CrdtStateProxy, type UpdateEvent, type UpdateHandler, type WasmStateStore, type WebSocketLike, WebSocketManager };
+export { CrdtStateProxy, type UpdateEvent, type UpdateHandler, type WebSocketLike, WebSocketManager };

package/dist/index.d.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+export { WasmStateStore, default as initWasm } from '../pkg/web/crdt_sync.js';
 /**
  * TypeScript interface matching the Wasm-bindgen-generated `WasmStateStore`.
  *
@@ -18,7 +20,7 @@ interface WasmStateStore {
  * through the proxy.
  */
 interface UpdateEvent {
-    /** Dot-separated key path that was updated (e.g. `"robot.speed"`). */
+    /** The register key that was updated (e.g. `"speed"` or `"robot.speed"`). */
     key: string;
     /** The new JavaScript value. */
     value: unknown;
@@ -32,50 +34,42 @@ interface UpdateEvent {
 type UpdateHandler = (event: UpdateEvent) => void;
 /**
  * A TypeScript proxy wrapper around `WasmStateStore` that gives frontend
- * developers a **magical, object-oriented** experience.
+ * developers a transparent, object-oriented experience.
  *
- * ## How it works
+ * ## Reading state
  *
- * 1. **JS `Proxy` interception** – accessing a nested path on `state` returns
- *    another `Proxy`.  Assigning a value anywhere in the tree intercepts the
- *    write and forwards it to the underlying Wasm store via
- *    `set_register(dotPath, JSON.stringify(value))`.
+ * Access any registered key directly on `proxy.state`:
  *
- * 2. **Wasm call** – the interceptor immediately calls
- *    `WasmStateStore.set_register()` so the CRDT operation is recorded and
- *    returns an `Envelope` JSON string ready for broadcasting.
+ * ```ts
+ * proxy.state.speed        // returns the registered value, or undefined
+ * proxy.state["robot.speed"] // dot-path keys via bracket notation
+ * ```
  *
- * 3. **Event emitter** – every write fires all `onUpdate` listeners with the
- *    full `UpdateEvent` (key, value, envelope), enabling React / Vue and other
- *    UI frameworks to react to state changes.
+ * ## Writing state
  *
- * ## Usage
+ * Assign any value — primitives, objects, arrays:
  *
  * ```ts
- * import init, { WasmStateStore } from './crdt_sync.js';
- * import { CrdtStateProxy } from './CrdtStateProxy.js';
- *
- * await init();
- * const store = new WasmStateStore('node-1');
- * const proxy = new CrdtStateProxy(store);
+ * proxy.state.speed = 100;
+ * proxy.state.robot = { x: 10, y: 20 };    // store the whole object
+ * proxy.state["robot.speed"] = 100;         // dot-path key
+ * ```
  *
- * // Register a listener (e.g. trigger a React re-render).
- * const unsubscribe = proxy.onUpdate(({ key, value, envelope }) => {
- *   console.log(`${key} =`, value);
- *   broadcast(envelope); // send to peers
- * });
+ * ## Listening for changes
  *
- * // Write through the proxy — the interceptor handles everything.
- * proxy.state.speed = 100;
- * proxy.state.robot.x = 42;
+ * - `onUpdate(handler)` — fires on **local** writes with the full `UpdateEvent`
+ *   (key, value, envelope). Used by `WebSocketManager` to collect outgoing envelopes.
+ * - `onChange(handler)` — fires on **any** change: local writes _and_ remote
+ *   `apply_envelope` notifications. Use this in UI frameworks to trigger re-renders.
  *
- * // Clean up when done.
- * unsubscribe();
+ * ```ts
+ * const unsubscribe = proxy.onChange(() => setTick(t => t + 1));
  * ```
  */
 declare class CrdtStateProxy {
     private readonly _store;
     private readonly _handlers;
+    private readonly _changeHandlers;
     private readonly _state;
     /**
      * Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.
@@ -86,35 +80,56 @@ declare class CrdtStateProxy {
     /**
      * The proxied state object.
      *
-     * Assigning any property (or nested property) on this object will
-     * automatically call `WasmStateStore.set_register` and fire `onUpdate`
-     * listeners.
-     *
-     * ```ts
-     * proxy.state.speed = 100;       // key: "speed"
-     * proxy.state.robot.speed = 100; // key: "robot.speed"
-     * ```
+     * Reading a key returns the registered value, or `undefined` if it has
+     * not been set yet.  Assigning a value calls `WasmStateStore.set_register`
+     * and fires all `onUpdate` and `onChange` listeners.
      */
     get state(): Record<string, unknown>;
     /**
-     * Register a listener that is called whenever a property is written through
-     * `proxy.state`.
+     * Register a listener that fires whenever a value is written through
+     * `proxy.state` (local writes only).
      *
-     * @param handler - Callback receiving an `UpdateEvent`.
-     * @returns An unsubscribe function — call it to remove the listener.
+     * The `UpdateEvent` carries the register key, new value, and the CRDT
+     * envelope — forward the envelope to peers via `apply_envelope`.
+     *
+     * @returns An unsubscribe function.
      */
     onUpdate(handler: UpdateHandler): () => void;
     /**
-     * Recursively build a `Proxy` for the given dot-path `prefix`.
+     * Register a listener that fires whenever state changes — whether from a
+     * local write or an incoming remote update (after `notifyRemoteUpdate`).
+     *
+     * Use this in UI frameworks to trigger re-renders:
+     *
+     * ```ts
+     * proxy.onChange(() => setTick(t => t + 1));
+     * ```
      *
-     * - **`get` trap**: returns a child proxy for the nested path so that deep
-     *   assignments like `proxy.state.robot.speed = 100` work correctly.
+     * @returns An unsubscribe function.
+     */
+    onChange(handler: () => void): () => void;
+    /**
+     * Notify all `onChange` listeners that remote state has been applied to the
+     * store.  Called by `WebSocketManager` after every `apply_envelope` so that
+     * UI frameworks re-render with the latest state.
+     */
+    notifyRemoteUpdate(): void;
+    /**
+     * Build the state `Proxy`.
+     *
+     * - **`get` trap**: reads the value from the WASM store via `get_register`.
+     *   Returns the parsed value, or `undefined` if the key has not been registered.
      * - **`set` trap**: serialises the value, calls `set_register`, and fires
-     *   all `onUpdate` listeners.
+     *   all `onUpdate` and `onChange` listeners.
+     *
+     * Keys may be dot-separated paths (e.g. `"robot.speed"`) when using bracket
+     * notation: `proxy.state["robot.speed"] = 100`.
      */
     private _makeProxy;
-    /** Dispatch an `UpdateEvent` to all registered handlers. */
+    /** Dispatch an `UpdateEvent` to all `onUpdate` handlers. */
     private _emit;
+    /** Notify all `onChange` handlers of a state change. */
+    private _emitChange;
 }
 /**
@@ -230,4 +245,4 @@ declare class WebSocketManager {
     disconnect(): void;
 }
-export { CrdtStateProxy, type UpdateEvent, type UpdateHandler, type WasmStateStore, type WebSocketLike, WebSocketManager };
+export { CrdtStateProxy, type UpdateEvent, type UpdateHandler, type WebSocketLike, WebSocketManager };

package/dist/index.js CHANGED Viewed

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,13 +17,23 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   CrdtStateProxy: () => CrdtStateProxy,
-  WebSocketManager: () => WebSocketManager
+  WasmStateStore: () => import_crdt_sync.WasmStateStore,
+  WebSocketManager: () => WebSocketManager,
+  initWasm: () => import_crdt_sync.default
 });
 module.exports = __toCommonJS(index_exports);
@@ -34,31 +46,29 @@ var CrdtStateProxy = class {
    */
   constructor(store) {
     this._handlers = /* @__PURE__ */ new Set();
+    this._changeHandlers = /* @__PURE__ */ new Set();
     this._store = store;
-    this._state = this._makeProxy("");
+    this._state = this._makeProxy();
   }
   // ── Public API ────────────────────────────────────────────────────────
   /**
    * The proxied state object.
    *
-   * Assigning any property (or nested property) on this object will
-   * automatically call `WasmStateStore.set_register` and fire `onUpdate`
-   * listeners.
-   *
-   * ```ts
-   * proxy.state.speed = 100;       // key: "speed"
-   * proxy.state.robot.speed = 100; // key: "robot.speed"
-   * ```
+   * Reading a key returns the registered value, or `undefined` if it has
+   * not been set yet.  Assigning a value calls `WasmStateStore.set_register`
+   * and fires all `onUpdate` and `onChange` listeners.
    */
   get state() {
     return this._state;
   }
   /**
-   * Register a listener that is called whenever a property is written through
-   * `proxy.state`.
+   * Register a listener that fires whenever a value is written through
+   * `proxy.state` (local writes only).
    *
-   * @param handler - Callback receiving an `UpdateEvent`.
-   * @returns An unsubscribe function — call it to remove the listener.
+   * The `UpdateEvent` carries the register key, new value, and the CRDT
+   * envelope — forward the envelope to peers via `apply_envelope`.
+   *
+   * @returns An unsubscribe function.
    */
   onUpdate(handler) {
     this._handlers.add(handler);
@@ -66,45 +76,74 @@ var CrdtStateProxy = class {
       this._handlers.delete(handler);
     };
   }
+  /**
+   * Register a listener that fires whenever state changes — whether from a
+   * local write or an incoming remote update (after `notifyRemoteUpdate`).
+   *
+   * Use this in UI frameworks to trigger re-renders:
+   *
+   * ```ts
+   * proxy.onChange(() => setTick(t => t + 1));
+   * ```
+   *
+   * @returns An unsubscribe function.
+   */
+  onChange(handler) {
+    this._changeHandlers.add(handler);
+    return () => {
+      this._changeHandlers.delete(handler);
+    };
+  }
+  /**
+   * Notify all `onChange` listeners that remote state has been applied to the
+   * store.  Called by `WebSocketManager` after every `apply_envelope` so that
+   * UI frameworks re-render with the latest state.
+   */
+  notifyRemoteUpdate() {
+    this._emitChange();
+  }
   // ── Internal helpers ──────────────────────────────────────────────────
   /**
-   * Recursively build a `Proxy` for the given dot-path `prefix`.
+   * Build the state `Proxy`.
    *
-   * - **`get` trap**: returns a child proxy for the nested path so that deep
-   *   assignments like `proxy.state.robot.speed = 100` work correctly.
+   * - **`get` trap**: reads the value from the WASM store via `get_register`.
+   *   Returns the parsed value, or `undefined` if the key has not been registered.
    * - **`set` trap**: serialises the value, calls `set_register`, and fires
-   *   all `onUpdate` listeners.
+   *   all `onUpdate` and `onChange` listeners.
+   *
+   * Keys may be dot-separated paths (e.g. `"robot.speed"`) when using bracket
+   * notation: `proxy.state["robot.speed"] = 100`.
    */
-  _makeProxy(prefix) {
-    const children = {};
+  _makeProxy() {
     return new Proxy({}, {
       get: (_target, prop) => {
         if (typeof prop === "symbol") return void 0;
-        const key = prefix ? `${prefix}.${String(prop)}` : String(prop);
-        const raw = this._store.get_register(key);
-        if (raw !== void 0) {
-          return JSON.parse(raw);
-        }
-        if (!(prop in children)) {
-          children[prop] = this._makeProxy(key);
-        }
-        return children[prop];
+        const raw = this._store.get_register(String(prop));
+        return raw !== void 0 ? JSON.parse(raw) : void 0;
       },
       set: (_target, prop, value) => {
         if (typeof prop === "symbol") return false;
-        const key = prefix ? `${prefix}.${String(prop)}` : String(prop);
+        const key = String(prop);
         const envelope = this._store.set_register(key, JSON.stringify(value));
         this._emit({ key, value, envelope });
+        this._emitChange();
         return true;
       }
     });
   }
-  /** Dispatch an `UpdateEvent` to all registered handlers. */
+  /** Dispatch an `UpdateEvent` to all `onUpdate` handlers. */
   _emit(event) {
     this._handlers.forEach((handler) => handler(event));
   }
+  /** Notify all `onChange` handlers of a state change. */
+  _emitChange() {
+    this._changeHandlers.forEach((handler) => handler());
+  }
 };
+// src/index.ts
+var import_crdt_sync = __toESM(require("../pkg/web/crdt_sync.js"));
 // src/WebSocketManager.ts
 var WebSocketManager = class {
   /**
@@ -162,6 +201,7 @@ var WebSocketManager = class {
       } else {
         this._store.apply_envelope(event.data);
       }
+      this._proxy.notifyRemoteUpdate();
     };
     ws.onclose = () => {
     };
@@ -223,6 +263,8 @@ var WebSocketManager = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CrdtStateProxy,
-  WebSocketManager
+  WasmStateStore,
+  WebSocketManager,
+  initWasm
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/index.ts","../src/CrdtStateProxy.ts","../src/WebSocketManager.ts"],"sourcesContent":["export { CrdtStateProxy } from './CrdtStateProxy.js';\nexport type { WasmStateStore, UpdateEvent, UpdateHandler } from './CrdtStateProxy.js';\nexport { WebSocketManager } from './WebSocketManager.js';\nexport type { WebSocketLike } from './WebSocketManager.js';\n","/*\n TypeScript interface matching the Wasm-bindgen-generated `WasmStateStore`.\n \n In production, import the real `WasmStateStore` from the compiled Wasm\n * package (e.g. `import { WasmStateStore } from './crdt_sync.js'`).\n * In tests the interface can be satisfied by any mock object.\n /\nexport interface WasmStateStore {\n /* Write a JSON-encoded value to the named LWW register. Returns the Envelope JSON. /\n set_register(key: string, value_json: string): string;\n /* Read the current value of a named LWW register as a JSON string, or `undefined`. /\n get_register(key: string): string \| undefined;\n /* Apply a remote Envelope (serialised as JSON) to this store. /\n apply_envelope(envelope_json: string): void;\n}\n\n/\n Payload delivered to every `onUpdate` listener when a property is written\n * through the proxy.\n /\nexport interface UpdateEvent {\n /* Dot-separated key path that was updated (e.g. `\"robot.speed\"`). /\n key: string;\n /* The new JavaScript value. /\n value: unknown;\n /\n The CRDT Envelope returned by `WasmStateStore.set_register`, serialised\n * as a JSON string. Broadcast this to peer nodes via `apply_envelope`.\n /\n envelope: string;\n}\n\n/* Callback type for `onUpdate` listeners. /\nexport type UpdateHandler = (event: UpdateEvent) => void;\n\n/\n A TypeScript proxy wrapper around `WasmStateStore` that gives frontend\n * developers a magical, object-oriented experience.\n \n ## How it works\n \n 1. JS `Proxy` interception – accessing a nested path on `state` returns\n * another `Proxy`. Assigning a value anywhere in the tree intercepts the\n * write and forwards it to the underlying Wasm store via\n * `set_register(dotPath, JSON.stringify(value))`.\n \n 2. Wasm call – the interceptor immediately calls\n * `WasmStateStore.set_register()` so the CRDT operation is recorded and\n * returns an `Envelope` JSON string ready for broadcasting.\n \n 3. Event emitter – every write fires all `onUpdate` listeners with the\n * full `UpdateEvent` (key, value, envelope), enabling React / Vue and other\n * UI frameworks to react to state changes.\n \n ## Usage\n \n ```ts\n * import init, { WasmStateStore } from './crdt_sync.js';\n * import { CrdtStateProxy } from './CrdtStateProxy.js';\n \n await init();\n * const store = new WasmStateStore('node-1');\n * const proxy = new CrdtStateProxy(store);\n \n // Register a listener (e.g. trigger a React re-render).\n * const unsubscribe = proxy.onUpdate(({ key, value, envelope }) => {\n * console.log(`${key} =`, value);\n * broadcast(envelope); // send to peers\n * });\n \n // Write through the proxy — the interceptor handles everything.\n * proxy.state.speed = 100;\n * proxy.state.robot.x = 42;\n \n // Clean up when done.\n * unsubscribe();\n * ```\n /\nexport class CrdtStateProxy {\n private readonly _store: WasmStateStore;\n private readonly _handlers: Set<UpdateHandler> = new Set();\n private readonly _state: Record<string, unknown>;\n\n /\n Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.\n \n @param store - The Wasm state store instance to proxy.\n /\n constructor(store: WasmStateStore) {\n this._store = store;\n this._state = this._makeProxy('');\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n The proxied state object.\n \n Assigning any property (or nested property) on this object will\n * automatically call `WasmStateStore.set_register` and fire `onUpdate`\n * listeners.\n \n ```ts\n * proxy.state.speed = 100; // key: \"speed\"\n * proxy.state.robot.speed = 100; // key: \"robot.speed\"\n * ```\n /\n get state(): Record<string, unknown> {\n return this._state;\n }\n\n /\n Register a listener that is called whenever a property is written through\n * `proxy.state`.\n \n @param handler - Callback receiving an `UpdateEvent`.\n * @returns An unsubscribe function — call it to remove the listener.\n /\n onUpdate(handler: UpdateHandler): () => void {\n this._handlers.add(handler);\n return () => {\n this._handlers.delete(handler);\n };\n }\n\n // ── Internal helpers ──────────────────────────────────────────────────\n\n /\n Recursively build a `Proxy` for the given dot-path `prefix`.\n \n - `get` trap: returns a child proxy for the nested path so that deep\n * assignments like `proxy.state.robot.speed = 100` work correctly.\n * - `set` trap: serialises the value, calls `set_register`, and fires\n * all `onUpdate` listeners.\n /\n private _makeProxy(prefix: string): Record<string, unknown> {\n const children: Record<string, Record<string, unknown>> = {};\n\n return new Proxy({} as Record<string, unknown>, {\n get: (_target, prop) => {\n if (typeof prop === 'symbol') return undefined;\n const key = prefix ? `${prefix}.${String(prop)}` : String(prop);\n\n const raw = this._store.get_register(key);\n if (raw !== undefined) {\n return JSON.parse(raw);\n }\n\n if (!(prop in children)) {\n children[prop] = this._makeProxy(key);\n }\n return children[prop];\n },\n\n set: (_target, prop, value: unknown) => {\n if (typeof prop === 'symbol') return false;\n const key = prefix ? `${prefix}.${String(prop)}` : String(prop);\n const envelope = this._store.set_register(key, JSON.stringify(value));\n this._emit({ key, value, envelope });\n return true;\n },\n });\n }\n\n /* Dispatch an `UpdateEvent` to all registered handlers. /\n private _emit(event: UpdateEvent): void {\n this._handlers.forEach((handler) => handler(event));\n }\n}\n","import { CrdtStateProxy } from './CrdtStateProxy.js';\nimport type { WasmStateStore } from './CrdtStateProxy.js';\n\n/\n Minimal subset of the browser `WebSocket` API used by `WebSocketManager`.\n \n The real browser `WebSocket` satisfies this interface out-of-the-box.\n * In tests, a plain mock object can be used instead.\n /\nexport interface WebSocketLike {\n /* Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). /\n readonly readyState: number;\n /* Send a UTF-8 string frame to the server. /\n send(data: string): void;\n /* Initiate the closing handshake. /\n close(): void;\n /* Fired when a message frame is received. /\n onmessage: ((event: { data: string }) => void) \| null;\n /* Fired when the connection is established. /\n onopen: ((event: unknown) => void) \| null;\n /* Fired when the connection is closed. /\n onclose: ((event: unknown) => void) \| null;\n /* Fired when an error occurs. /\n onerror: ((event: unknown) => void) \| null;\n}\n\n/\n Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT\n * operation produced locally is broadcast to peers, and every envelope\n * received from a peer is applied to the local store.\n \n ## Data flow\n \n ```\n * Local write\n * → CrdtStateProxy.onUpdate (envelope collected in _pendingEnvelopes)\n * → requestAnimationFrame / setTimeout schedules a batch flush\n * → WebSocket.send(JSON.stringify(envelopes)) // one payload per frame\n \n Incoming message (single envelope or JSON array of envelopes)\n * → WebSocket.onmessage\n * → WasmStateStore.apply_envelope() // merge into local store\n * ```\n \n ## Throttling / batching\n \n Multiple proxy writes that occur within the same JavaScript task (e.g. a\n * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single\n * JSON array payload on the next animation frame (browser) or the next\n * `setTimeout(fn, 0)` tick (Node.js / non-browser environments). This keeps\n * network traffic proportional to frame rate rather than to the raw mutation\n * rate.\n \n ## Usage\n \n ```ts\n * import init, { WasmStateStore } from './crdt_sync.js';\n * import { CrdtStateProxy, WebSocketManager } from './index.js';\n \n await init();\n * const store = new WasmStateStore('node-1');\n * const proxy = new CrdtStateProxy(store);\n * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));\n \n // Writes are automatically batched and broadcast to peers.\n * proxy.state.robot = { x: 10, y: 20 };\n \n // Clean up.\n * manager.disconnect();\n * ```\n /\nexport class WebSocketManager {\n private readonly _store: WasmStateStore;\n private readonly _proxy: CrdtStateProxy;\n private readonly _ws: WebSocketLike;\n private _unsubscribe: (() => void) \| null = null;\n /* Envelopes collected in the current frame, waiting for the batch flush. /\n private _pendingEnvelopes: string[] = [];\n /* Cancels the currently scheduled batch flush (rAF or setTimeout handle). /\n private _cancelFlush: (() => void) \| null = null;\n /* Envelopes queued while the socket is not open, flushed on reconnection. /\n private _offlineQueue: string[] = [];\n\n /\n Create a `WebSocketManager` and attach it to the given WebSocket.\n \n @param store - The Wasm state store. Incoming peer envelopes will be\n * applied to this store via `apply_envelope`.\n * @param proxy - The CRDT state proxy. Outgoing envelopes produced by\n * `set_register` calls will be read from the proxy's `onUpdate` events.\n * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).\n /\n constructor(store: WasmStateStore, proxy: CrdtStateProxy, ws: WebSocketLike) {\n this._store = store;\n this._proxy = proxy;\n this._ws = ws;\n this._attach();\n }\n\n // ── Internal setup ────────────────────────────────────────────────────\n\n private _attach(): void {\n const ws = this._ws;\n\n // Collect envelopes and schedule a batch flush once per frame so that\n // multiple synchronous writes (e.g. a 60 FPS game loop) are coalesced\n // into a single network payload instead of one message per mutation.\n this._unsubscribe = this._proxy.onUpdate(({ envelope }) => {\n this._pendingEnvelopes.push(envelope);\n this._scheduleBatchFlush();\n });\n\n // On (re)connection, immediately flush pending envelopes together with any\n // envelopes that were queued while the socket was offline.\n ws.onopen = () => {\n // Cancel any scheduled flush — we will drain everything right now.\n this._cancelFlush?.();\n this._cancelFlush = null;\n const offline = this._offlineQueue;\n const pending = this._pendingEnvelopes;\n this._offlineQueue = [];\n this._pendingEnvelopes = [];\n const batch = [...offline, ...pending];\n if (batch.length > 0) {\n ws.send(JSON.stringify(batch));\n }\n };\n\n // Apply envelopes received from peers. Peers may send either a single\n // envelope JSON string or a JSON array of envelope strings (batch format).\n ws.onmessage = (event) => {\n let parsed: unknown;\n try {\n parsed = JSON.parse(event.data);\n } catch {\n parsed = null;\n }\n if (Array.isArray(parsed)) {\n for (const env of parsed) {\n this._store.apply_envelope(env as string);\n }\n } else {\n // Fallback: treat the raw frame data as a single envelope string.\n this._store.apply_envelope(event.data);\n }\n };\n\n // On close or error the subscription stays active so that writes made\n // while offline are buffered and flushed when the socket reconnects.\n ws.onclose = () => { / keep buffering / };\n ws.onerror = () => { / keep buffering / };\n }\n\n /\n Schedule a single batch flush for the current frame. Subsequent calls\n * before the flush fires are no-ops (only one flush is ever outstanding).\n \n Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),\n * falling back to `setTimeout(fn, 0)` in non-browser environments.\n /\n private _scheduleBatchFlush(): void {\n if (this._cancelFlush !== null) return; // already scheduled\n\n const doFlush = () => {\n this._cancelFlush = null;\n this._flushBatch();\n };\n\n if (typeof requestAnimationFrame === 'function') {\n const id = requestAnimationFrame(doFlush);\n this._cancelFlush = () => cancelAnimationFrame(id);\n } else {\n const id = setTimeout(doFlush, 0);\n this._cancelFlush = () => clearTimeout(id);\n }\n }\n\n /\n Send all pending envelopes as a single JSON-array payload, or move them\n * to the offline queue if the socket is not currently open.\n /\n private _flushBatch(): void {\n const envelopes = this._pendingEnvelopes.splice(0);\n if (envelopes.length === 0) return;\n\n const ws = this._ws;\n if (ws.readyState === 1 / OPEN /) {\n ws.send(JSON.stringify(envelopes));\n } else {\n this._offlineQueue.push(...envelopes);\n }\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n Unsubscribe from proxy updates, discard any buffered envelopes, and close\n * the WebSocket connection.\n \n Safe to call more than once.\n */\n disconnect(): void {\n this._unsubscribe?.();\n this._unsubscribe = null;\n this._cancelFlush?.();\n this._cancelFlush = null;\n this._pendingEnvelopes = [];\n this._offlineQueue = [];\n this._ws.close();\n }\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/index.ts","../src/CrdtStateProxy.ts","../src/WebSocketManager.ts"],"sourcesContent":["export { CrdtStateProxy } from './CrdtStateProxy.js';\nexport type { UpdateEvent, UpdateHandler } from './CrdtStateProxy.js';\nexport { default as initWasm, WasmStateStore } from '../pkg/web/crdt_sync.js';\nexport { WebSocketManager } from './WebSocketManager.js';\nexport type { WebSocketLike } from './WebSocketManager.js';\n","/*\n TypeScript interface matching the Wasm-bindgen-generated `WasmStateStore`.\n \n In production, import the real `WasmStateStore` from the compiled Wasm\n * package (e.g. `import { WasmStateStore } from './crdt_sync.js'`).\n * In tests the interface can be satisfied by any mock object.\n /\nexport interface WasmStateStore {\n /* Write a JSON-encoded value to the named LWW register. Returns the Envelope JSON. /\n set_register(key: string, value_json: string): string;\n /* Read the current value of a named LWW register as a JSON string, or `undefined`. /\n get_register(key: string): string \| undefined;\n /* Apply a remote Envelope (serialised as JSON) to this store. /\n apply_envelope(envelope_json: string): void;\n}\n\n/\n Payload delivered to every `onUpdate` listener when a property is written\n * through the proxy.\n /\nexport interface UpdateEvent {\n /* The register key that was updated (e.g. `\"speed\"` or `\"robot.speed\"`). /\n key: string;\n /* The new JavaScript value. /\n value: unknown;\n /\n The CRDT Envelope returned by `WasmStateStore.set_register`, serialised\n * as a JSON string. Broadcast this to peer nodes via `apply_envelope`.\n /\n envelope: string;\n}\n\n/* Callback type for `onUpdate` listeners. /\nexport type UpdateHandler = (event: UpdateEvent) => void;\n\n/\n A TypeScript proxy wrapper around `WasmStateStore` that gives frontend\n * developers a transparent, object-oriented experience.\n \n ## Reading state\n \n Access any registered key directly on `proxy.state`:\n \n ```ts\n * proxy.state.speed // returns the registered value, or undefined\n * proxy.state[\"robot.speed\"] // dot-path keys via bracket notation\n * ```\n \n ## Writing state\n \n Assign any value — primitives, objects, arrays:\n \n ```ts\n * proxy.state.speed = 100;\n * proxy.state.robot = { x: 10, y: 20 }; // store the whole object\n * proxy.state[\"robot.speed\"] = 100; // dot-path key\n * ```\n \n ## Listening for changes\n \n - `onUpdate(handler)` — fires on local writes with the full `UpdateEvent`\n * (key, value, envelope). Used by `WebSocketManager` to collect outgoing envelopes.\n * - `onChange(handler)` — fires on any change: local writes _and_ remote\n * `apply_envelope` notifications. Use this in UI frameworks to trigger re-renders.\n \n ```ts\n * const unsubscribe = proxy.onChange(() => setTick(t => t + 1));\n * ```\n /\nexport class CrdtStateProxy {\n private readonly _store: WasmStateStore;\n private readonly _handlers: Set<UpdateHandler> = new Set();\n private readonly _changeHandlers: Set<() => void> = new Set();\n private readonly _state: Record<string, unknown>;\n\n /\n Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.\n \n @param store - The Wasm state store instance to proxy.\n /\n constructor(store: WasmStateStore) {\n this._store = store;\n this._state = this._makeProxy();\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n The proxied state object.\n \n Reading a key returns the registered value, or `undefined` if it has\n * not been set yet. Assigning a value calls `WasmStateStore.set_register`\n * and fires all `onUpdate` and `onChange` listeners.\n /\n get state(): Record<string, unknown> {\n return this._state;\n }\n\n /\n Register a listener that fires whenever a value is written through\n * `proxy.state` (local writes only).\n \n The `UpdateEvent` carries the register key, new value, and the CRDT\n * envelope — forward the envelope to peers via `apply_envelope`.\n \n @returns An unsubscribe function.\n /\n onUpdate(handler: UpdateHandler): () => void {\n this._handlers.add(handler);\n return () => {\n this._handlers.delete(handler);\n };\n }\n\n /\n Register a listener that fires whenever state changes — whether from a\n * local write or an incoming remote update (after `notifyRemoteUpdate`).\n \n Use this in UI frameworks to trigger re-renders:\n \n ```ts\n * proxy.onChange(() => setTick(t => t + 1));\n * ```\n \n @returns An unsubscribe function.\n /\n onChange(handler: () => void): () => void {\n this._changeHandlers.add(handler);\n return () => {\n this._changeHandlers.delete(handler);\n };\n }\n\n /\n Notify all `onChange` listeners that remote state has been applied to the\n * store. Called by `WebSocketManager` after every `apply_envelope` so that\n * UI frameworks re-render with the latest state.\n /\n notifyRemoteUpdate(): void {\n this._emitChange();\n }\n\n // ── Internal helpers ──────────────────────────────────────────────────\n\n /\n Build the state `Proxy`.\n \n - `get` trap: reads the value from the WASM store via `get_register`.\n * Returns the parsed value, or `undefined` if the key has not been registered.\n * - `set` trap: serialises the value, calls `set_register`, and fires\n * all `onUpdate` and `onChange` listeners.\n \n Keys may be dot-separated paths (e.g. `\"robot.speed\"`) when using bracket\n * notation: `proxy.state[\"robot.speed\"] = 100`.\n /\n private _makeProxy(): Record<string, unknown> {\n return new Proxy({} as Record<string, unknown>, {\n get: (_target, prop) => {\n if (typeof prop === 'symbol') return undefined;\n const raw = this._store.get_register(String(prop));\n return raw !== undefined ? JSON.parse(raw) : undefined;\n },\n\n set: (_target, prop, value: unknown) => {\n if (typeof prop === 'symbol') return false;\n const key = String(prop);\n const envelope = this._store.set_register(key, JSON.stringify(value));\n this._emit({ key, value, envelope });\n this._emitChange();\n return true;\n },\n });\n }\n\n /* Dispatch an `UpdateEvent` to all `onUpdate` handlers. /\n private _emit(event: UpdateEvent): void {\n this._handlers.forEach((handler) => handler(event));\n }\n\n /* Notify all `onChange` handlers of a state change. /\n private _emitChange(): void {\n this._changeHandlers.forEach((handler) => handler());\n }\n}\n","import { CrdtStateProxy } from './CrdtStateProxy.js';\nimport type { WasmStateStore } from './CrdtStateProxy.js';\n\n/\n Minimal subset of the browser `WebSocket` API used by `WebSocketManager`.\n \n The real browser `WebSocket` satisfies this interface out-of-the-box.\n * In tests, a plain mock object can be used instead.\n /\nexport interface WebSocketLike {\n /* Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). /\n readonly readyState: number;\n /* Send a UTF-8 string frame to the server. /\n send(data: string): void;\n /* Initiate the closing handshake. /\n close(): void;\n /* Fired when a message frame is received. /\n onmessage: ((event: { data: string }) => void) \| null;\n /* Fired when the connection is established. /\n onopen: ((event: unknown) => void) \| null;\n /* Fired when the connection is closed. /\n onclose: ((event: unknown) => void) \| null;\n /* Fired when an error occurs. /\n onerror: ((event: unknown) => void) \| null;\n}\n\n/\n Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT\n * operation produced locally is broadcast to peers, and every envelope\n * received from a peer is applied to the local store.\n \n ## Data flow\n \n ```\n * Local write\n * → CrdtStateProxy.onUpdate (envelope collected in _pendingEnvelopes)\n * → requestAnimationFrame / setTimeout schedules a batch flush\n * → WebSocket.send(JSON.stringify(envelopes)) // one payload per frame\n \n Incoming message (single envelope or JSON array of envelopes)\n * → WebSocket.onmessage\n * → WasmStateStore.apply_envelope() // merge into local store\n * ```\n \n ## Throttling / batching\n \n Multiple proxy writes that occur within the same JavaScript task (e.g. a\n * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single\n * JSON array payload on the next animation frame (browser) or the next\n * `setTimeout(fn, 0)` tick (Node.js / non-browser environments). This keeps\n * network traffic proportional to frame rate rather than to the raw mutation\n * rate.\n \n ## Usage\n \n ```ts\n * import init, { WasmStateStore } from './crdt_sync.js';\n * import { CrdtStateProxy, WebSocketManager } from './index.js';\n \n await init();\n * const store = new WasmStateStore('node-1');\n * const proxy = new CrdtStateProxy(store);\n * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));\n \n // Writes are automatically batched and broadcast to peers.\n * proxy.state.robot = { x: 10, y: 20 };\n \n // Clean up.\n * manager.disconnect();\n * ```\n /\nexport class WebSocketManager {\n private readonly _store: WasmStateStore;\n private readonly _proxy: CrdtStateProxy;\n private readonly _ws: WebSocketLike;\n private _unsubscribe: (() => void) \| null = null;\n /* Envelopes collected in the current frame, waiting for the batch flush. /\n private _pendingEnvelopes: string[] = [];\n /* Cancels the currently scheduled batch flush (rAF or setTimeout handle). /\n private _cancelFlush: (() => void) \| null = null;\n /* Envelopes queued while the socket is not open, flushed on reconnection. /\n private _offlineQueue: string[] = [];\n\n /\n Create a `WebSocketManager` and attach it to the given WebSocket.\n \n @param store - The Wasm state store. Incoming peer envelopes will be\n * applied to this store via `apply_envelope`.\n * @param proxy - The CRDT state proxy. Outgoing envelopes produced by\n * `set_register` calls will be read from the proxy's `onUpdate` events.\n * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).\n /\n constructor(store: WasmStateStore, proxy: CrdtStateProxy, ws: WebSocketLike) {\n this._store = store;\n this._proxy = proxy;\n this._ws = ws;\n this._attach();\n }\n\n // ── Internal setup ────────────────────────────────────────────────────\n\n private _attach(): void {\n const ws = this._ws;\n\n // Collect envelopes and schedule a batch flush once per frame so that\n // multiple synchronous writes (e.g. a 60 FPS game loop) are coalesced\n // into a single network payload instead of one message per mutation.\n this._unsubscribe = this._proxy.onUpdate(({ envelope }) => {\n this._pendingEnvelopes.push(envelope);\n this._scheduleBatchFlush();\n });\n\n // On (re)connection, immediately flush pending envelopes together with any\n // envelopes that were queued while the socket was offline.\n ws.onopen = () => {\n // Cancel any scheduled flush — we will drain everything right now.\n this._cancelFlush?.();\n this._cancelFlush = null;\n const offline = this._offlineQueue;\n const pending = this._pendingEnvelopes;\n this._offlineQueue = [];\n this._pendingEnvelopes = [];\n const batch = [...offline, ...pending];\n if (batch.length > 0) {\n ws.send(JSON.stringify(batch));\n }\n };\n\n // Apply envelopes received from peers. Peers may send either a single\n // envelope JSON string or a JSON array of envelope strings (batch format).\n ws.onmessage = (event) => {\n let parsed: unknown;\n try {\n parsed = JSON.parse(event.data);\n } catch {\n parsed = null;\n }\n if (Array.isArray(parsed)) {\n for (const env of parsed) {\n this._store.apply_envelope(env as string);\n }\n } else {\n // Fallback: treat the raw frame data as a single envelope string.\n this._store.apply_envelope(event.data);\n }\n // Notify UI listeners (e.g. React) that remote state has been applied.\n this._proxy.notifyRemoteUpdate();\n };\n\n // On close or error the subscription stays active so that writes made\n // while offline are buffered and flushed when the socket reconnects.\n ws.onclose = () => { / keep buffering / };\n ws.onerror = () => { / keep buffering / };\n }\n\n /\n Schedule a single batch flush for the current frame. Subsequent calls\n * before the flush fires are no-ops (only one flush is ever outstanding).\n \n Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),\n * falling back to `setTimeout(fn, 0)` in non-browser environments.\n /\n private _scheduleBatchFlush(): void {\n if (this._cancelFlush !== null) return; // already scheduled\n\n const doFlush = () => {\n this._cancelFlush = null;\n this._flushBatch();\n };\n\n if (typeof requestAnimationFrame === 'function') {\n const id = requestAnimationFrame(doFlush);\n this._cancelFlush = () => cancelAnimationFrame(id);\n } else {\n const id = setTimeout(doFlush, 0);\n this._cancelFlush = () => clearTimeout(id);\n }\n }\n\n /\n Send all pending envelopes as a single JSON-array payload, or move them\n * to the offline queue if the socket is not currently open.\n /\n private _flushBatch(): void {\n const envelopes = this._pendingEnvelopes.splice(0);\n if (envelopes.length === 0) return;\n\n const ws = this._ws;\n if (ws.readyState === 1 / OPEN /) {\n ws.send(JSON.stringify(envelopes));\n } else {\n this._offlineQueue.push(...envelopes);\n }\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n Unsubscribe from proxy updates, discard any buffered envelopes, and close\n * the WebSocket connection.\n \n Safe to call more than once.\n */\n disconnect(): void {\n this._unsubscribe?.();\n this._unsubscribe = null;\n this._cancelFlush?.();\n this._cancelFlush = null;\n this._pendingEnvelopes = [];\n this._offlineQueue = [];\n this._ws.close();\n }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs CHANGED Viewed

@@ -7,31 +7,29 @@ var CrdtStateProxy = class {
    */
   constructor(store) {
     this._handlers = /* @__PURE__ */ new Set();
+    this._changeHandlers = /* @__PURE__ */ new Set();
     this._store = store;
-    this._state = this._makeProxy("");
+    this._state = this._makeProxy();
   }
   // ── Public API ────────────────────────────────────────────────────────
   /**
    * The proxied state object.
    *
-   * Assigning any property (or nested property) on this object will
-   * automatically call `WasmStateStore.set_register` and fire `onUpdate`
-   * listeners.
-   *
-   * ```ts
-   * proxy.state.speed = 100;       // key: "speed"
-   * proxy.state.robot.speed = 100; // key: "robot.speed"
-   * ```
+   * Reading a key returns the registered value, or `undefined` if it has
+   * not been set yet.  Assigning a value calls `WasmStateStore.set_register`
+   * and fires all `onUpdate` and `onChange` listeners.
    */
   get state() {
     return this._state;
   }
   /**
-   * Register a listener that is called whenever a property is written through
-   * `proxy.state`.
+   * Register a listener that fires whenever a value is written through
+   * `proxy.state` (local writes only).
    *
-   * @param handler - Callback receiving an `UpdateEvent`.
-   * @returns An unsubscribe function — call it to remove the listener.
+   * The `UpdateEvent` carries the register key, new value, and the CRDT
+   * envelope — forward the envelope to peers via `apply_envelope`.
+   *
+   * @returns An unsubscribe function.
    */
   onUpdate(handler) {
     this._handlers.add(handler);
@@ -39,45 +37,74 @@ var CrdtStateProxy = class {
       this._handlers.delete(handler);
     };
   }
+  /**
+   * Register a listener that fires whenever state changes — whether from a
+   * local write or an incoming remote update (after `notifyRemoteUpdate`).
+   *
+   * Use this in UI frameworks to trigger re-renders:
+   *
+   * ```ts
+   * proxy.onChange(() => setTick(t => t + 1));
+   * ```
+   *
+   * @returns An unsubscribe function.
+   */
+  onChange(handler) {
+    this._changeHandlers.add(handler);
+    return () => {
+      this._changeHandlers.delete(handler);
+    };
+  }
+  /**
+   * Notify all `onChange` listeners that remote state has been applied to the
+   * store.  Called by `WebSocketManager` after every `apply_envelope` so that
+   * UI frameworks re-render with the latest state.
+   */
+  notifyRemoteUpdate() {
+    this._emitChange();
+  }
   // ── Internal helpers ──────────────────────────────────────────────────
   /**
-   * Recursively build a `Proxy` for the given dot-path `prefix`.
+   * Build the state `Proxy`.
    *
-   * - **`get` trap**: returns a child proxy for the nested path so that deep
-   *   assignments like `proxy.state.robot.speed = 100` work correctly.
+   * - **`get` trap**: reads the value from the WASM store via `get_register`.
+   *   Returns the parsed value, or `undefined` if the key has not been registered.
    * - **`set` trap**: serialises the value, calls `set_register`, and fires
-   *   all `onUpdate` listeners.
+   *   all `onUpdate` and `onChange` listeners.
+   *
+   * Keys may be dot-separated paths (e.g. `"robot.speed"`) when using bracket
+   * notation: `proxy.state["robot.speed"] = 100`.
    */
-  _makeProxy(prefix) {
-    const children = {};
+  _makeProxy() {
     return new Proxy({}, {
       get: (_target, prop) => {
         if (typeof prop === "symbol") return void 0;
-        const key = prefix ? `${prefix}.${String(prop)}` : String(prop);
-        const raw = this._store.get_register(key);
-        if (raw !== void 0) {
-          return JSON.parse(raw);
-        }
-        if (!(prop in children)) {
-          children[prop] = this._makeProxy(key);
-        }
-        return children[prop];
+        const raw = this._store.get_register(String(prop));
+        return raw !== void 0 ? JSON.parse(raw) : void 0;
       },
       set: (_target, prop, value) => {
         if (typeof prop === "symbol") return false;
-        const key = prefix ? `${prefix}.${String(prop)}` : String(prop);
+        const key = String(prop);
         const envelope = this._store.set_register(key, JSON.stringify(value));
         this._emit({ key, value, envelope });
+        this._emitChange();
         return true;
       }
     });
   }
-  /** Dispatch an `UpdateEvent` to all registered handlers. */
+  /** Dispatch an `UpdateEvent` to all `onUpdate` handlers. */
   _emit(event) {
     this._handlers.forEach((handler) => handler(event));
   }
+  /** Notify all `onChange` handlers of a state change. */
+  _emitChange() {
+    this._changeHandlers.forEach((handler) => handler());
+  }
 };
+// src/index.ts
+import { default as default2, WasmStateStore } from "../pkg/web/crdt_sync.js";
 // src/WebSocketManager.ts
 var WebSocketManager = class {
   /**
@@ -135,6 +162,7 @@ var WebSocketManager = class {
       } else {
         this._store.apply_envelope(event.data);
       }
+      this._proxy.notifyRemoteUpdate();
     };
     ws.onclose = () => {
     };
@@ -195,6 +223,8 @@ var WebSocketManager = class {
 };
 export {
   CrdtStateProxy,
-  WebSocketManager
+  WasmStateStore,
+  WebSocketManager,
+  default2 as initWasm
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/CrdtStateProxy.ts","../src/WebSocketManager.ts"],"sourcesContent":["/*\n TypeScript interface matching the Wasm-bindgen-generated `WasmStateStore`.\n \n In production, import the real `WasmStateStore` from the compiled Wasm\n * package (e.g. `import { WasmStateStore } from './crdt_sync.js'`).\n * In tests the interface can be satisfied by any mock object.\n /\nexport interface WasmStateStore {\n /* Write a JSON-encoded value to the named LWW register. Returns the Envelope JSON. /\n set_register(key: string, value_json: string): string;\n /* Read the current value of a named LWW register as a JSON string, or `undefined`. /\n get_register(key: string): string \| undefined;\n /* Apply a remote Envelope (serialised as JSON) to this store. /\n apply_envelope(envelope_json: string): void;\n}\n\n/\n Payload delivered to every `onUpdate` listener when a property is written\n * through the proxy.\n /\nexport interface UpdateEvent {\n /* Dot-separated key path that was updated (e.g. `\"robot.speed\"`). /\n key: string;\n /* The new JavaScript value. /\n value: unknown;\n /\n The CRDT Envelope returned by `WasmStateStore.set_register`, serialised\n * as a JSON string. Broadcast this to peer nodes via `apply_envelope`.\n /\n envelope: string;\n}\n\n/* Callback type for `onUpdate` listeners. /\nexport type UpdateHandler = (event: UpdateEvent) => void;\n\n/\n A TypeScript proxy wrapper around `WasmStateStore` that gives frontend\n * developers a magical, object-oriented experience.\n \n ## How it works\n \n 1. JS `Proxy` interception – accessing a nested path on `state` returns\n * another `Proxy`. Assigning a value anywhere in the tree intercepts the\n * write and forwards it to the underlying Wasm store via\n * `set_register(dotPath, JSON.stringify(value))`.\n \n 2. Wasm call – the interceptor immediately calls\n * `WasmStateStore.set_register()` so the CRDT operation is recorded and\n * returns an `Envelope` JSON string ready for broadcasting.\n \n 3. Event emitter – every write fires all `onUpdate` listeners with the\n * full `UpdateEvent` (key, value, envelope), enabling React / Vue and other\n * UI frameworks to react to state changes.\n \n ## Usage\n \n ```ts\n * import init, { WasmStateStore } from './crdt_sync.js';\n * import { CrdtStateProxy } from './CrdtStateProxy.js';\n \n await init();\n * const store = new WasmStateStore('node-1');\n * const proxy = new CrdtStateProxy(store);\n \n // Register a listener (e.g. trigger a React re-render).\n * const unsubscribe = proxy.onUpdate(({ key, value, envelope }) => {\n * console.log(`${key} =`, value);\n * broadcast(envelope); // send to peers\n * });\n \n // Write through the proxy — the interceptor handles everything.\n * proxy.state.speed = 100;\n * proxy.state.robot.x = 42;\n \n // Clean up when done.\n * unsubscribe();\n * ```\n /\nexport class CrdtStateProxy {\n private readonly _store: WasmStateStore;\n private readonly _handlers: Set<UpdateHandler> = new Set();\n private readonly _state: Record<string, unknown>;\n\n /\n Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.\n \n @param store - The Wasm state store instance to proxy.\n /\n constructor(store: WasmStateStore) {\n this._store = store;\n this._state = this._makeProxy('');\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n The proxied state object.\n \n Assigning any property (or nested property) on this object will\n * automatically call `WasmStateStore.set_register` and fire `onUpdate`\n * listeners.\n \n ```ts\n * proxy.state.speed = 100; // key: \"speed\"\n * proxy.state.robot.speed = 100; // key: \"robot.speed\"\n * ```\n /\n get state(): Record<string, unknown> {\n return this._state;\n }\n\n /\n Register a listener that is called whenever a property is written through\n * `proxy.state`.\n \n @param handler - Callback receiving an `UpdateEvent`.\n * @returns An unsubscribe function — call it to remove the listener.\n /\n onUpdate(handler: UpdateHandler): () => void {\n this._handlers.add(handler);\n return () => {\n this._handlers.delete(handler);\n };\n }\n\n // ── Internal helpers ──────────────────────────────────────────────────\n\n /\n Recursively build a `Proxy` for the given dot-path `prefix`.\n \n - `get` trap: returns a child proxy for the nested path so that deep\n * assignments like `proxy.state.robot.speed = 100` work correctly.\n * - `set` trap: serialises the value, calls `set_register`, and fires\n * all `onUpdate` listeners.\n /\n private _makeProxy(prefix: string): Record<string, unknown> {\n const children: Record<string, Record<string, unknown>> = {};\n\n return new Proxy({} as Record<string, unknown>, {\n get: (_target, prop) => {\n if (typeof prop === 'symbol') return undefined;\n const key = prefix ? `${prefix}.${String(prop)}` : String(prop);\n\n const raw = this._store.get_register(key);\n if (raw !== undefined) {\n return JSON.parse(raw);\n }\n\n if (!(prop in children)) {\n children[prop] = this._makeProxy(key);\n }\n return children[prop];\n },\n\n set: (_target, prop, value: unknown) => {\n if (typeof prop === 'symbol') return false;\n const key = prefix ? `${prefix}.${String(prop)}` : String(prop);\n const envelope = this._store.set_register(key, JSON.stringify(value));\n this._emit({ key, value, envelope });\n return true;\n },\n });\n }\n\n /* Dispatch an `UpdateEvent` to all registered handlers. /\n private _emit(event: UpdateEvent): void {\n this._handlers.forEach((handler) => handler(event));\n }\n}\n","import { CrdtStateProxy } from './CrdtStateProxy.js';\nimport type { WasmStateStore } from './CrdtStateProxy.js';\n\n/\n Minimal subset of the browser `WebSocket` API used by `WebSocketManager`.\n \n The real browser `WebSocket` satisfies this interface out-of-the-box.\n * In tests, a plain mock object can be used instead.\n /\nexport interface WebSocketLike {\n /* Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). /\n readonly readyState: number;\n /* Send a UTF-8 string frame to the server. /\n send(data: string): void;\n /* Initiate the closing handshake. /\n close(): void;\n /* Fired when a message frame is received. /\n onmessage: ((event: { data: string }) => void) \| null;\n /* Fired when the connection is established. /\n onopen: ((event: unknown) => void) \| null;\n /* Fired when the connection is closed. /\n onclose: ((event: unknown) => void) \| null;\n /* Fired when an error occurs. /\n onerror: ((event: unknown) => void) \| null;\n}\n\n/\n Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT\n * operation produced locally is broadcast to peers, and every envelope\n * received from a peer is applied to the local store.\n \n ## Data flow\n \n ```\n * Local write\n * → CrdtStateProxy.onUpdate (envelope collected in _pendingEnvelopes)\n * → requestAnimationFrame / setTimeout schedules a batch flush\n * → WebSocket.send(JSON.stringify(envelopes)) // one payload per frame\n \n Incoming message (single envelope or JSON array of envelopes)\n * → WebSocket.onmessage\n * → WasmStateStore.apply_envelope() // merge into local store\n * ```\n \n ## Throttling / batching\n \n Multiple proxy writes that occur within the same JavaScript task (e.g. a\n * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single\n * JSON array payload on the next animation frame (browser) or the next\n * `setTimeout(fn, 0)` tick (Node.js / non-browser environments). This keeps\n * network traffic proportional to frame rate rather than to the raw mutation\n * rate.\n \n ## Usage\n \n ```ts\n * import init, { WasmStateStore } from './crdt_sync.js';\n * import { CrdtStateProxy, WebSocketManager } from './index.js';\n \n await init();\n * const store = new WasmStateStore('node-1');\n * const proxy = new CrdtStateProxy(store);\n * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));\n \n // Writes are automatically batched and broadcast to peers.\n * proxy.state.robot = { x: 10, y: 20 };\n \n // Clean up.\n * manager.disconnect();\n * ```\n /\nexport class WebSocketManager {\n private readonly _store: WasmStateStore;\n private readonly _proxy: CrdtStateProxy;\n private readonly _ws: WebSocketLike;\n private _unsubscribe: (() => void) \| null = null;\n /* Envelopes collected in the current frame, waiting for the batch flush. /\n private _pendingEnvelopes: string[] = [];\n /* Cancels the currently scheduled batch flush (rAF or setTimeout handle). /\n private _cancelFlush: (() => void) \| null = null;\n /* Envelopes queued while the socket is not open, flushed on reconnection. /\n private _offlineQueue: string[] = [];\n\n /\n Create a `WebSocketManager` and attach it to the given WebSocket.\n \n @param store - The Wasm state store. Incoming peer envelopes will be\n * applied to this store via `apply_envelope`.\n * @param proxy - The CRDT state proxy. Outgoing envelopes produced by\n * `set_register` calls will be read from the proxy's `onUpdate` events.\n * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).\n /\n constructor(store: WasmStateStore, proxy: CrdtStateProxy, ws: WebSocketLike) {\n this._store = store;\n this._proxy = proxy;\n this._ws = ws;\n this._attach();\n }\n\n // ── Internal setup ────────────────────────────────────────────────────\n\n private _attach(): void {\n const ws = this._ws;\n\n // Collect envelopes and schedule a batch flush once per frame so that\n // multiple synchronous writes (e.g. a 60 FPS game loop) are coalesced\n // into a single network payload instead of one message per mutation.\n this._unsubscribe = this._proxy.onUpdate(({ envelope }) => {\n this._pendingEnvelopes.push(envelope);\n this._scheduleBatchFlush();\n });\n\n // On (re)connection, immediately flush pending envelopes together with any\n // envelopes that were queued while the socket was offline.\n ws.onopen = () => {\n // Cancel any scheduled flush — we will drain everything right now.\n this._cancelFlush?.();\n this._cancelFlush = null;\n const offline = this._offlineQueue;\n const pending = this._pendingEnvelopes;\n this._offlineQueue = [];\n this._pendingEnvelopes = [];\n const batch = [...offline, ...pending];\n if (batch.length > 0) {\n ws.send(JSON.stringify(batch));\n }\n };\n\n // Apply envelopes received from peers. Peers may send either a single\n // envelope JSON string or a JSON array of envelope strings (batch format).\n ws.onmessage = (event) => {\n let parsed: unknown;\n try {\n parsed = JSON.parse(event.data);\n } catch {\n parsed = null;\n }\n if (Array.isArray(parsed)) {\n for (const env of parsed) {\n this._store.apply_envelope(env as string);\n }\n } else {\n // Fallback: treat the raw frame data as a single envelope string.\n this._store.apply_envelope(event.data);\n }\n };\n\n // On close or error the subscription stays active so that writes made\n // while offline are buffered and flushed when the socket reconnects.\n ws.onclose = () => { / keep buffering / };\n ws.onerror = () => { / keep buffering / };\n }\n\n /\n Schedule a single batch flush for the current frame. Subsequent calls\n * before the flush fires are no-ops (only one flush is ever outstanding).\n \n Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),\n * falling back to `setTimeout(fn, 0)` in non-browser environments.\n /\n private _scheduleBatchFlush(): void {\n if (this._cancelFlush !== null) return; // already scheduled\n\n const doFlush = () => {\n this._cancelFlush = null;\n this._flushBatch();\n };\n\n if (typeof requestAnimationFrame === 'function') {\n const id = requestAnimationFrame(doFlush);\n this._cancelFlush = () => cancelAnimationFrame(id);\n } else {\n const id = setTimeout(doFlush, 0);\n this._cancelFlush = () => clearTimeout(id);\n }\n }\n\n /\n Send all pending envelopes as a single JSON-array payload, or move them\n * to the offline queue if the socket is not currently open.\n /\n private _flushBatch(): void {\n const envelopes = this._pendingEnvelopes.splice(0);\n if (envelopes.length === 0) return;\n\n const ws = this._ws;\n if (ws.readyState === 1 / OPEN /) {\n ws.send(JSON.stringify(envelopes));\n } else {\n this._offlineQueue.push(...envelopes);\n }\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n Unsubscribe from proxy updates, discard any buffered envelopes, and close\n * the WebSocket connection.\n \n Safe to call more than once.\n */\n disconnect(): void {\n this._unsubscribe?.();\n this._unsubscribe = null;\n this._cancelFlush?.();\n this._cancelFlush = null;\n this._pendingEnvelopes = [];\n this._offlineQueue = [];\n this._ws.close();\n }\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/CrdtStateProxy.ts","../src/index.ts","../src/WebSocketManager.ts"],"sourcesContent":["/*\n TypeScript interface matching the Wasm-bindgen-generated `WasmStateStore`.\n \n In production, import the real `WasmStateStore` from the compiled Wasm\n * package (e.g. `import { WasmStateStore } from './crdt_sync.js'`).\n * In tests the interface can be satisfied by any mock object.\n /\nexport interface WasmStateStore {\n /* Write a JSON-encoded value to the named LWW register. Returns the Envelope JSON. /\n set_register(key: string, value_json: string): string;\n /* Read the current value of a named LWW register as a JSON string, or `undefined`. /\n get_register(key: string): string \| undefined;\n /* Apply a remote Envelope (serialised as JSON) to this store. /\n apply_envelope(envelope_json: string): void;\n}\n\n/\n Payload delivered to every `onUpdate` listener when a property is written\n * through the proxy.\n /\nexport interface UpdateEvent {\n /* The register key that was updated (e.g. `\"speed\"` or `\"robot.speed\"`). /\n key: string;\n /* The new JavaScript value. /\n value: unknown;\n /\n The CRDT Envelope returned by `WasmStateStore.set_register`, serialised\n * as a JSON string. Broadcast this to peer nodes via `apply_envelope`.\n /\n envelope: string;\n}\n\n/* Callback type for `onUpdate` listeners. /\nexport type UpdateHandler = (event: UpdateEvent) => void;\n\n/\n A TypeScript proxy wrapper around `WasmStateStore` that gives frontend\n * developers a transparent, object-oriented experience.\n \n ## Reading state\n \n Access any registered key directly on `proxy.state`:\n \n ```ts\n * proxy.state.speed // returns the registered value, or undefined\n * proxy.state[\"robot.speed\"] // dot-path keys via bracket notation\n * ```\n \n ## Writing state\n \n Assign any value — primitives, objects, arrays:\n \n ```ts\n * proxy.state.speed = 100;\n * proxy.state.robot = { x: 10, y: 20 }; // store the whole object\n * proxy.state[\"robot.speed\"] = 100; // dot-path key\n * ```\n \n ## Listening for changes\n \n - `onUpdate(handler)` — fires on local writes with the full `UpdateEvent`\n * (key, value, envelope). Used by `WebSocketManager` to collect outgoing envelopes.\n * - `onChange(handler)` — fires on any change: local writes _and_ remote\n * `apply_envelope` notifications. Use this in UI frameworks to trigger re-renders.\n \n ```ts\n * const unsubscribe = proxy.onChange(() => setTick(t => t + 1));\n * ```\n /\nexport class CrdtStateProxy {\n private readonly _store: WasmStateStore;\n private readonly _handlers: Set<UpdateHandler> = new Set();\n private readonly _changeHandlers: Set<() => void> = new Set();\n private readonly _state: Record<string, unknown>;\n\n /\n Create a new `CrdtStateProxy` backed by the given `WasmStateStore`.\n \n @param store - The Wasm state store instance to proxy.\n /\n constructor(store: WasmStateStore) {\n this._store = store;\n this._state = this._makeProxy();\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n The proxied state object.\n \n Reading a key returns the registered value, or `undefined` if it has\n * not been set yet. Assigning a value calls `WasmStateStore.set_register`\n * and fires all `onUpdate` and `onChange` listeners.\n /\n get state(): Record<string, unknown> {\n return this._state;\n }\n\n /\n Register a listener that fires whenever a value is written through\n * `proxy.state` (local writes only).\n \n The `UpdateEvent` carries the register key, new value, and the CRDT\n * envelope — forward the envelope to peers via `apply_envelope`.\n \n @returns An unsubscribe function.\n /\n onUpdate(handler: UpdateHandler): () => void {\n this._handlers.add(handler);\n return () => {\n this._handlers.delete(handler);\n };\n }\n\n /\n Register a listener that fires whenever state changes — whether from a\n * local write or an incoming remote update (after `notifyRemoteUpdate`).\n \n Use this in UI frameworks to trigger re-renders:\n \n ```ts\n * proxy.onChange(() => setTick(t => t + 1));\n * ```\n \n @returns An unsubscribe function.\n /\n onChange(handler: () => void): () => void {\n this._changeHandlers.add(handler);\n return () => {\n this._changeHandlers.delete(handler);\n };\n }\n\n /\n Notify all `onChange` listeners that remote state has been applied to the\n * store. Called by `WebSocketManager` after every `apply_envelope` so that\n * UI frameworks re-render with the latest state.\n /\n notifyRemoteUpdate(): void {\n this._emitChange();\n }\n\n // ── Internal helpers ──────────────────────────────────────────────────\n\n /\n Build the state `Proxy`.\n \n - `get` trap: reads the value from the WASM store via `get_register`.\n * Returns the parsed value, or `undefined` if the key has not been registered.\n * - `set` trap: serialises the value, calls `set_register`, and fires\n * all `onUpdate` and `onChange` listeners.\n \n Keys may be dot-separated paths (e.g. `\"robot.speed\"`) when using bracket\n * notation: `proxy.state[\"robot.speed\"] = 100`.\n /\n private _makeProxy(): Record<string, unknown> {\n return new Proxy({} as Record<string, unknown>, {\n get: (_target, prop) => {\n if (typeof prop === 'symbol') return undefined;\n const raw = this._store.get_register(String(prop));\n return raw !== undefined ? JSON.parse(raw) : undefined;\n },\n\n set: (_target, prop, value: unknown) => {\n if (typeof prop === 'symbol') return false;\n const key = String(prop);\n const envelope = this._store.set_register(key, JSON.stringify(value));\n this._emit({ key, value, envelope });\n this._emitChange();\n return true;\n },\n });\n }\n\n /* Dispatch an `UpdateEvent` to all `onUpdate` handlers. /\n private _emit(event: UpdateEvent): void {\n this._handlers.forEach((handler) => handler(event));\n }\n\n /* Notify all `onChange` handlers of a state change. /\n private _emitChange(): void {\n this._changeHandlers.forEach((handler) => handler());\n }\n}\n","export { CrdtStateProxy } from './CrdtStateProxy.js';\nexport type { UpdateEvent, UpdateHandler } from './CrdtStateProxy.js';\nexport { default as initWasm, WasmStateStore } from '../pkg/web/crdt_sync.js';\nexport { WebSocketManager } from './WebSocketManager.js';\nexport type { WebSocketLike } from './WebSocketManager.js';\n","import { CrdtStateProxy } from './CrdtStateProxy.js';\nimport type { WasmStateStore } from './CrdtStateProxy.js';\n\n/\n Minimal subset of the browser `WebSocket` API used by `WebSocketManager`.\n \n The real browser `WebSocket` satisfies this interface out-of-the-box.\n * In tests, a plain mock object can be used instead.\n /\nexport interface WebSocketLike {\n /* Current connection state (0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED). /\n readonly readyState: number;\n /* Send a UTF-8 string frame to the server. /\n send(data: string): void;\n /* Initiate the closing handshake. /\n close(): void;\n /* Fired when a message frame is received. /\n onmessage: ((event: { data: string }) => void) \| null;\n /* Fired when the connection is established. /\n onopen: ((event: unknown) => void) \| null;\n /* Fired when the connection is closed. /\n onclose: ((event: unknown) => void) \| null;\n /* Fired when an error occurs. /\n onerror: ((event: unknown) => void) \| null;\n}\n\n/\n Bridges a `CrdtStateProxy` to a WebSocket connection so that every CRDT\n * operation produced locally is broadcast to peers, and every envelope\n * received from a peer is applied to the local store.\n \n ## Data flow\n \n ```\n * Local write\n * → CrdtStateProxy.onUpdate (envelope collected in _pendingEnvelopes)\n * → requestAnimationFrame / setTimeout schedules a batch flush\n * → WebSocket.send(JSON.stringify(envelopes)) // one payload per frame\n \n Incoming message (single envelope or JSON array of envelopes)\n * → WebSocket.onmessage\n * → WasmStateStore.apply_envelope() // merge into local store\n * ```\n \n ## Throttling / batching\n \n Multiple proxy writes that occur within the same JavaScript task (e.g. a\n * 60 FPS game loop) are collected in `_pendingEnvelopes` and sent as a single\n * JSON array payload on the next animation frame (browser) or the next\n * `setTimeout(fn, 0)` tick (Node.js / non-browser environments). This keeps\n * network traffic proportional to frame rate rather than to the raw mutation\n * rate.\n \n ## Usage\n \n ```ts\n * import init, { WasmStateStore } from './crdt_sync.js';\n * import { CrdtStateProxy, WebSocketManager } from './index.js';\n \n await init();\n * const store = new WasmStateStore('node-1');\n * const proxy = new CrdtStateProxy(store);\n * const manager = new WebSocketManager(store, proxy, new WebSocket('wss://example.com/sync'));\n \n // Writes are automatically batched and broadcast to peers.\n * proxy.state.robot = { x: 10, y: 20 };\n \n // Clean up.\n * manager.disconnect();\n * ```\n /\nexport class WebSocketManager {\n private readonly _store: WasmStateStore;\n private readonly _proxy: CrdtStateProxy;\n private readonly _ws: WebSocketLike;\n private _unsubscribe: (() => void) \| null = null;\n /* Envelopes collected in the current frame, waiting for the batch flush. /\n private _pendingEnvelopes: string[] = [];\n /* Cancels the currently scheduled batch flush (rAF or setTimeout handle). /\n private _cancelFlush: (() => void) \| null = null;\n /* Envelopes queued while the socket is not open, flushed on reconnection. /\n private _offlineQueue: string[] = [];\n\n /\n Create a `WebSocketManager` and attach it to the given WebSocket.\n \n @param store - The Wasm state store. Incoming peer envelopes will be\n * applied to this store via `apply_envelope`.\n * @param proxy - The CRDT state proxy. Outgoing envelopes produced by\n * `set_register` calls will be read from the proxy's `onUpdate` events.\n * @param ws - An open or connecting WebSocket (or any `WebSocketLike` object).\n /\n constructor(store: WasmStateStore, proxy: CrdtStateProxy, ws: WebSocketLike) {\n this._store = store;\n this._proxy = proxy;\n this._ws = ws;\n this._attach();\n }\n\n // ── Internal setup ────────────────────────────────────────────────────\n\n private _attach(): void {\n const ws = this._ws;\n\n // Collect envelopes and schedule a batch flush once per frame so that\n // multiple synchronous writes (e.g. a 60 FPS game loop) are coalesced\n // into a single network payload instead of one message per mutation.\n this._unsubscribe = this._proxy.onUpdate(({ envelope }) => {\n this._pendingEnvelopes.push(envelope);\n this._scheduleBatchFlush();\n });\n\n // On (re)connection, immediately flush pending envelopes together with any\n // envelopes that were queued while the socket was offline.\n ws.onopen = () => {\n // Cancel any scheduled flush — we will drain everything right now.\n this._cancelFlush?.();\n this._cancelFlush = null;\n const offline = this._offlineQueue;\n const pending = this._pendingEnvelopes;\n this._offlineQueue = [];\n this._pendingEnvelopes = [];\n const batch = [...offline, ...pending];\n if (batch.length > 0) {\n ws.send(JSON.stringify(batch));\n }\n };\n\n // Apply envelopes received from peers. Peers may send either a single\n // envelope JSON string or a JSON array of envelope strings (batch format).\n ws.onmessage = (event) => {\n let parsed: unknown;\n try {\n parsed = JSON.parse(event.data);\n } catch {\n parsed = null;\n }\n if (Array.isArray(parsed)) {\n for (const env of parsed) {\n this._store.apply_envelope(env as string);\n }\n } else {\n // Fallback: treat the raw frame data as a single envelope string.\n this._store.apply_envelope(event.data);\n }\n // Notify UI listeners (e.g. React) that remote state has been applied.\n this._proxy.notifyRemoteUpdate();\n };\n\n // On close or error the subscription stays active so that writes made\n // while offline are buffered and flushed when the socket reconnects.\n ws.onclose = () => { / keep buffering / };\n ws.onerror = () => { / keep buffering / };\n }\n\n /\n Schedule a single batch flush for the current frame. Subsequent calls\n * before the flush fires are no-ops (only one flush is ever outstanding).\n \n Uses `requestAnimationFrame` when available (browser, ~60 FPS cadence),\n * falling back to `setTimeout(fn, 0)` in non-browser environments.\n /\n private _scheduleBatchFlush(): void {\n if (this._cancelFlush !== null) return; // already scheduled\n\n const doFlush = () => {\n this._cancelFlush = null;\n this._flushBatch();\n };\n\n if (typeof requestAnimationFrame === 'function') {\n const id = requestAnimationFrame(doFlush);\n this._cancelFlush = () => cancelAnimationFrame(id);\n } else {\n const id = setTimeout(doFlush, 0);\n this._cancelFlush = () => clearTimeout(id);\n }\n }\n\n /\n Send all pending envelopes as a single JSON-array payload, or move them\n * to the offline queue if the socket is not currently open.\n /\n private _flushBatch(): void {\n const envelopes = this._pendingEnvelopes.splice(0);\n if (envelopes.length === 0) return;\n\n const ws = this._ws;\n if (ws.readyState === 1 / OPEN /) {\n ws.send(JSON.stringify(envelopes));\n } else {\n this._offlineQueue.push(...envelopes);\n }\n }\n\n // ── Public API ────────────────────────────────────────────────────────\n\n /\n Unsubscribe from proxy updates, discard any buffered envelopes, and close\n * the WebSocket connection.\n \n Safe to call more than once.\n */\n disconnect(): void {\n this._unsubscribe?.();\n this._unsubscribe = null;\n this._cancelFlush?.();\n this._cancelFlush = null;\n this._pendingEnvelopes = [];\n this._offlineQueue = [];\n this._ws.close();\n }\n}\n"],"mappings":"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","names":["default"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@crdt-sync/core",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "TypeScript proxy wrapper for the crdt-sync Wasm StateStore",
   "main": "dist/index.js",
   "module": "dist/index.mjs",