@crdt-sync/react 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @crdt-sync/react
+
+A high-level React adapter for `crdt-sync`. This package exposes the `useCrdtState` hook, which allows you to bind CRDT-powered, collaborative state directly to your React components.
+
+## Installation
+
+You need both the framework-agnostic core and the React adapter. The Wasm binaries are bundled within the `@crdt-sync/core` package.
+
+```bash
+npm install @crdt-sync/core @crdt-sync/react
+```
+
+## Quick Start: `useCrdtState`
+
+The `useCrdtState` hook magically handles:
+- **Wasm Initialization**: Bootstraps the rust-generated `crdt-sync` bindings automatically.
+- **Networking**: Connects via WebSocket out-of-the-box.
+- **State Proxying**: Wraps your state with JavaScript proxies that automatically broadcast operations seamlessly upon assignment.
+- **Reactivity**: Automatically hooks up to React's lifecycle to re-render when remote changes are received.
+
+### Example
+
+Here's how to create a simple connected component:
+
+```tsx
+import { useCrdtState } from '@crdt-sync/react';
+
+// Define the shape of your state
+type MyState = {
+  robot: {
+    speed: number;
+    active: boolean;
+  };
+};
+
+export function RobotDashboard() {
+  // Bind the Wasm engine and network directly to React state
+  const { state, proxy, status } = useCrdtState<MyState>(
+    'wss://api.example.com/sync',
+    {
+       robot: { speed: 0, active: true } // Initial State
+    }
+  );
+
+  if (status === 'connecting') {
+    return <p>Connecting to sync engine...</p>;
+  }
+
+  if (status === 'error') {
+    return <p>Failed to connect to the sync server!</p>;
+  }
+
+  return (
+    <div>
+      <h1>Robot Speed: {state.robot.speed}</h1>
+      {/* 
+        Direct mutation is intercepted, applied as a CRDT operation, 
+        broadcast over WebSocket, and triggers a local React re-render.
+      */}
+      <button 
+        onClick={() => {
+          // Mutate the state using the returned proxy wrapper
+          if (proxy) {
+            proxy.state.robot.speed += 10;
+          }
+        }}
+      >
+        Increase Speed
+      </button>
+
+      <button
+        onClick={() => {
+          if (proxy) {
+            proxy.state.robot.active = !proxy.state.robot.active;
+          }
+        }}
+      >
+        Toggle Active Status ({state.robot.active ? 'Active' : 'Idle'})
+      </button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### `useCrdtState<T>(url: string, initialState: T)`
+
+Accepts a TypeScript generic `T` that extends `Record<string, unknown>`.
+
+#### Parameters:
+- `url` (`string`): The WebSocket URL to connect to the backend sync service.
+- `initialState` (`T`): The default state to build the proxy structure over. 
+
+#### Returns (`UseCrdtStateResult<T>`):
+- `state`: The plain Javascript object representation of your state. You should use `state` for reading values when rendering.
+- `proxy`: The `CrdtStateProxy` object. You **must** perform all mutations on `proxy.state`. Mutating `state` directly will not trigger network events.
+- `status`: Connective status indicator (`'connecting'` | `'open'` | `'error'`).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { useCrdtState } from './useCrdtState';
+export type { CrdtStatus, UseCrdtStateResult } from './useCrdtState';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCrdtState = void 0;
+var useCrdtState_1 = require("./useCrdtState");
+Object.defineProperty(exports, "useCrdtState", { enumerable: true, get: function () { return useCrdtState_1.useCrdtState; } });

package/dist/useCrdtState.d.ts

@@ -0,0 +1,8 @@
+import { CrdtStateProxy } from '@crdt-sync/core';
+export type CrdtStatus = 'connecting' | 'open' | 'error';
+export interface UseCrdtStateResult<T> {
+    state: T;
+    proxy: CrdtStateProxy | null;
+    status: CrdtStatus;
+}
+export declare function useCrdtState<T extends Record<string, unknown>>(url: string, initialState: T): UseCrdtStateResult<T>;

package/dist/useCrdtState.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCrdtState = useCrdtState;
+const react_1 = require("react");
+const core_1 = require("@crdt-sync/core");
+// @ts-ignore: Wasm module will be generated during the full build
+const crdt_sync_js_1 = __importStar(require("@crdt-sync/core/pkg/web/crdt_sync.js"));
+function useCrdtState(url, initialState) {
+    const [proxy, setProxy] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)('connecting');
+    const [, setTick] = (0, react_1.useState)(0);
+    // Note: we're ignoring initialState updates (this behaves like useState).
+    const [initialRef] = (0, react_1.useState)(initialState);
+    (0, react_1.useEffect)(() => {
+        let active = true;
+        let manager = null;
+        let currentProxy = null;
+        async function setup() {
+            try {
+                await (0, crdt_sync_js_1.default)();
+                if (!active)
+                    return;
+                // Create a unique client ID
+                const clientId = 'client-' + Math.random().toString(36).substring(2, 11);
+                const store = new crdt_sync_js_1.WasmStateStore(clientId);
+                currentProxy = new core_1.CrdtStateProxy(store);
+                // Initialize state
+                for (const [key, value] of Object.entries(initialRef)) {
+                    currentProxy.state[key] = value;
+                }
+                if (!active)
+                    return;
+                setProxy(currentProxy);
+                const ws = new WebSocket(url);
+                ws.onopen = () => {
+                    if (active)
+                        setStatus('open');
+                };
+                ws.onerror = () => {
+                    if (active)
+                        setStatus('error');
+                };
+                ws.onclose = () => {
+                    if (active)
+                        setStatus('connecting');
+                };
+                manager = new core_1.WebSocketManager(store, currentProxy, ws);
+            }
+            catch (err) {
+                console.error('Failed to initialize CRDT sync:', err);
+                if (active)
+                    setStatus('error');
+            }
+        }
+        setup();
+        return () => {
+            active = false;
+            if (manager)
+                manager.disconnect();
+        };
+    }, [url, initialRef]);
+    (0, react_1.useEffect)(() => {
+        if (!proxy)
+            return;
+        // Subscribe to proxy updates to trigger React re-renders.
+        return proxy.onUpdate(() => {
+            setTick(t => t + 1);
+        });
+    }, [proxy]);
+    const state = proxy ? proxy.state : initialRef;
+    return { state, proxy, status };
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "@crdt-sync/react",
+    "version": "0.1.0",
+    "description": "React hook adapter for crdt-sync",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc"
+    },
+    "peerDependencies": {
+        "react": ">=16.8",
+        "react-dom": ">=16.8"
+    },
+    "dependencies": {
+        "@crdt-sync/core": "*"
+    },
+    "devDependencies": {
+        "@types/react": "^18.0.0",
+        "@types/react-dom": "^18.0.0",
+        "typescript": "^5.4.5"
+    },
+    "license": "MIT"
+}