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

@crdt-sync/core 0.3.0 → 0.3.2

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 (5) hide show

package/dist/index.d.mts CHANGED Viewed

@@ -66,7 +66,7 @@ type UpdateHandler = (event: UpdateEvent) => void;
  * const unsubscribe = proxy.onChange(() => setTick(t => t + 1));
  * ```
  */
-declare class CrdtStateProxy {
+declare class CrdtStateProxy<T extends Record<string, unknown> = Record<string, unknown>> {
     private readonly _store;
     private readonly _handlers;
     private readonly _changeHandlers;
@@ -84,7 +84,7 @@ declare class CrdtStateProxy {
      * not been set yet.  Assigning a value calls `WasmStateStore.set_register`
      * and fires all `onUpdate` and `onChange` listeners.
      */
-    get state(): Record<string, unknown>;
+    get state(): T;
     /**
      * Register a listener that fires whenever a value is written through
      * `proxy.state` (local writes only).

package/dist/index.d.ts CHANGED Viewed

@@ -66,7 +66,7 @@ type UpdateHandler = (event: UpdateEvent) => void;
  * const unsubscribe = proxy.onChange(() => setTick(t => t + 1));
  * ```
  */
-declare class CrdtStateProxy {
+declare class CrdtStateProxy<T extends Record<string, unknown> = Record<string, unknown>> {
     private readonly _store;
     private readonly _handlers;
     private readonly _changeHandlers;
@@ -84,7 +84,7 @@ declare class CrdtStateProxy {
      * not been set yet.  Assigning a value calls `WasmStateStore.set_register`
      * and fires all `onUpdate` and `onChange` listeners.
      */
-    get state(): Record<string, unknown>;
+    get state(): T;
     /**
      * Register a listener that fires whenever a value is written through
      * `proxy.state` (local writes only).

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 { 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":[]}
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<T extends Record<string, unknown> = Record<string, unknown>> {\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: T;\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(): T {\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(): T {\n return new Proxy({} as T, {\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.map CHANGED Viewed

	@@ -1 +1 @@
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"]}
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<T extends Record<string, unknown> = Record<string, unknown>> {\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: T;\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(): T {\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(): T {\n return new Proxy({} as T, {\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.3.0",
+  "version": "0.3.2",
   "description": "TypeScript proxy wrapper for the crdt-sync Wasm StateStore",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -28,6 +28,7 @@
     "build:wasm:bundler": "wasm-pack build ../.. --target bundler --out-dir packages/core/pkg/bundler",
     "build:wasm:web": "wasm-pack build ../.. --target web --out-dir packages/core/pkg/web",
     "build:wasm": "npm run build:wasm:bundler && npm run build:wasm:web && rm -f pkg/bundler/.gitignore pkg/web/.gitignore",
+    "prepublishOnly": "npm run build:wasm && npm run build",
     "test": "jest",
     "lint": "tsc --noEmit"
   },