dignity.js 0.3.0 → 0.5.1

package/docs/openapi-like.json

@@ -1,19 +1,43 @@
 {
   "name": "dignity.js",
-  "version": "0.1.0",
+  "version": "0.5.1",
   "description": "REST-like object API over peer-to-peer replication",
   "resources": {
     "collections/{collection}/{id}": {
       "create": {
         "method": "create(collection, data, options)",
-        "owner": "actor that creates the object"
+        "owner": "actor that creates the object",
+        "options": {
+          "id": "optional stable id",
+          "collaborators": "optional peer id list",
+          "broadcastScope": "scoped broadcast password namespace",
+          "connectToPeers": "optional; defaults to collaborators on PeerJS mesh"
+        }
       },
       "read": {
         "method": "read(collection, id)"
       },
       "update": {
-        "method": "update(collection, id, patch)",
-        "authorization": "owner-only"
+        "method": "update(collection, id, patch, options)",
+        "authorization": "owner or collaborator",
+        "options": {
+          "expectedVersion": "optional number; throws VERSION_CONFLICT when mismatched",
+          "broadcastScope": "optional scoped broadcast password namespace",
+          "collaborators": "owner may replace collaborator list",
+          "connectToPeers": "optional; defaults to owner + collaborators"
+        }
+      },
+      "updateWithRetry": {
+        "method": "updateWithRetry(collection, id, patchFn, options)",
+        "description": "read-modify-write helper with automatic retry on version conflicts"
+      },
+      "pushRecordSnapshot": {
+        "method": "pushRecordSnapshot(collection, id, options)",
+        "description": "broadcast full record for late joiners who missed the initial create"
+      },
+      "getRecordPeerIds": {
+        "method": "getRecordPeerIds(collection, id, options)",
+        "description": "returns owner + collaborator peer ids for connectToPeers"
       },
       "delete": {
         "method": "remove(collection, id)",
@@ -24,8 +48,46 @@
       "list": {
         "method": "list(collection, options)"
       }
+    },
+    "peers": {
+      "connectToPeer": "open PeerJS data channel to peer id",
+      "getConnectionStats": "{ openCount, peerIds }",
+      "ensureConnectedToPeers": "connect to many peers before broadcast",
+      "joinDiscovery": "scoped presence; options.bootstrapPeerIds connects before announce",
+      "broadcastMessage": "custom app messages; options.connectToPeers"
     }
   },
+  "events": {
+    "change": "object create/update/delete/snapshot applied",
+    "conflict": "local or remote version mismatch",
+    "warning": "orphan-operation, peer-connect-failed, presence failures",
+    "peerdiscovered": "peer joined discovery scope",
+    "peerleft": "peer left or timed out",
+    "message": "custom decrypted message received"
+  },
+  "persistence": {
+    "IndexedDBPersistence": {
+      "method": "attach(node)",
+      "options": [
+        "dbName",
+        "storeName",
+        "collections"
+      ]
+    }
+  },
+  "react": {
+    "entrypoint": "dignity.js/react",
+    "hooks": [
+      "useDignity",
+      "useCollection",
+      "useObject",
+      "usePeers",
+      "useDiscovery",
+      "useConnectionStats",
+      "useRoom",
+      "useMessages"
+    ]
+  },
   "signaling": {
     "defaults": {
       "cloudflare": "enabled by default",
@@ -45,13 +107,18 @@
       "signingEnabled": true,
       "encryptionEnabled": true,
       "powEnabled": true,
-      "powTargetMs": 1000
+      "powSteps": 22,
+      "powTargetMs": 1000,
+      "kdfIterations": 100000,
+      "banDurationMs": 172800000
     },
     "broadcast": {
-      "encryption": "aes-256-gcm with appPassword-derived key"
+      "encryption": "AES secretbox with PBKDF2-SHA256 derived key",
+      "scopePasswords": "broadcastPasswords map keyed by broadcastScope",
+      "legacyKdf": "single-hash fallback accepted for older peers"
     },
     "direct": {
-      "encryption": "aes-256-gcm payload + rsa-oaep wrapped session key"
+      "encryption": "NaCl box (X25519 + XSalsa20-Poly1305) to recipient public key"
     },
     "pow": {
       "algorithm": "Sloth VDF",

package/examples/decentralized-chess-lite.js

@@ -11,6 +11,7 @@ function initialBoard() {
 
 async function runDemo() {
   const hub = new InMemoryNetworkHub();
+  const scope = 'room:chess-lite';
 
   const host = new DignityP2P({
     nodeId: 'host',
@@ -21,8 +22,27 @@ async function runDemo() {
     }
   });
 
-  const observer = new DignityP2P({
-    nodeId: 'observer',
+  await host.start();
+  await host.joinDiscovery(scope, {
+    metadata: { nickname: 'host', role: 'owner' },
+    heartbeatIntervalMs: 100000,
+    ttlMs: 30000
+  });
+
+  // Host creates before joiner is online — joiner never receives the create op.
+  await host.create(
+    'matches',
+    {
+      type: 'chess-lite',
+      board: initialBoard(),
+      moveHistory: [],
+      status: 'waiting'
+    },
+    { id: 'match-1', broadcastScope: scope }
+  );
+
+  const joiner = new DignityP2P({
+    nodeId: 'joiner',
     networkAdapter: new InMemoryNetworkAdapter(hub),
     security: {
       appPassword: 'demo-shared-password',
@@ -30,38 +50,40 @@ async function runDemo() {
     }
   });
 
-  await host.start();
-  await observer.start();
-  await host.joinDiscovery('room:chess-lite', {
-    metadata: { nickname: 'host', role: 'owner' },
-    heartbeatIntervalMs: 100000,
-    ttlMs: 30000
-  });
-  await observer.joinDiscovery('room:chess-lite', {
-    metadata: { nickname: 'observer', role: 'viewer' },
+  await joiner.start();
+  await joiner.joinDiscovery(scope, {
+    metadata: { nickname: 'joiner', role: 'player' },
+    bootstrapPeerIds: ['host'],
     heartbeatIntervalMs: 100000,
     ttlMs: 30000
   });
 
-  console.log(
-    '\nPeers visible from host in room:chess-lite:',
-    host.listPeers('room:chess-lite', { includeSelf: false }).map((peer) => peer.peerId)
-  );
+  console.log('\nJoiner before snapshot:', joiner.read('matches', 'match-1'));
 
-  await host.create(
+  const warnings = [];
+  joiner.on('warning', (event) => warnings.push(event));
+
+  await host.update(
     'matches',
+    'match-1',
+    { status: 'playing', blackPlayerId: 'joiner' },
     {
-      type: 'chess-lite',
-      board: initialBoard(),
-      moveHistory: []
-    },
-    { id: 'match-1', broadcastScope: 'room:chess-lite' }
+      broadcastScope: scope,
+      collaborators: ['host', 'joiner']
+    }
   );
 
+  console.log('\nJoiner after update (still missing create):', joiner.read('matches', 'match-1'));
+  console.log('Orphan warnings:', warnings.filter((event) => event.type === 'orphan-operation').length);
+
+  await host.pushRecordSnapshot('matches', 'match-1', {
+    broadcastScope: scope,
+    connectToPeers: ['joiner']
+  });
+
   const scriptedMoves = [
     { from: 'a2', to: 'a4', piece: 'whitePawnA' },
-    { from: 'a7', to: 'a5', piece: 'blackPawnA' },
-    { from: 'e1', to: 'e2', piece: 'whiteKing' }
+    { from: 'a7', to: 'a5', piece: 'blackPawnA' }
   ];
 
   for (const move of scriptedMoves) {
@@ -77,23 +99,23 @@ async function runDemo() {
         moveHistory,
         lastMove: move
       },
-      { broadcastScope: 'room:chess-lite' }
+      { broadcastScope: scope }
     );
   }
 
   const hostState = host.read('matches', 'match-1');
-  const observerState = observer.read('matches', 'match-1');
+  const joinerState = joiner.read('matches', 'match-1');
 
   console.log('\nHost state:');
   console.log(JSON.stringify(hostState.data, null, 2));
 
-  console.log('\nObserver replicated state:');
-  console.log(JSON.stringify(observerState.data, null, 2));
+  console.log('\nJoiner replicated state (after snapshot + moves):');
+  console.log(JSON.stringify(joinerState.data, null, 2));
 
-  await host.leaveDiscovery('room:chess-lite');
-  await observer.leaveDiscovery('room:chess-lite');
+  await host.leaveDiscovery(scope);
+  await joiner.leaveDiscovery(scope);
   await host.stop();
-  await observer.stop();
+  await joiner.stop();
 }
 
 runDemo().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dignity.js",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "P2P object API for decentralized JavaScript applications",
   "main": "dist/dignity.cjs.js",
   "module": "dist/dignity.esm.js",
@@ -12,6 +12,11 @@
       "require": "./dist/dignity.cjs.js",
       "import": "./dist/dignity.esm.js",
       "default": "./dist/dignity.esm.js"
+    },
+    "./react": {
+      "require": "./src/react/index.js",
+      "import": "./src/react/index.js",
+      "default": "./src/react/index.js"
     }
   },
   "files": [
@@ -26,8 +31,13 @@
     "test:cloudflare-live": "RUN_CLOUDFLARE_LIVE_TESTS=1 jest tests/integration/cloudflare-signaling-live.test.js --runInBand",
     "test:pow-calibrate": "jest tests/unit/sloth-vdf-timing.test.js --runInBand",
     "build": "node scripts/build.js",
-    "docs:serve": "npx http-server docs -p 4173 -o",
-    "docs:check": "node -e \"require('fs').accessSync('docs/index.html')\"",
+    "build:chess": "node scripts/build-chess-demo.js",
+    "docs:favicon": "node scripts/generate-favicon.js",
+    "docs:build": "npm run build:chess",
+    "docs:dev": "node scripts/serve-docs.js",
+    "docs:serve": "node scripts/serve-docs.js",
+    "docs:stop": "node scripts/stop-docs.js",
+    "docs:check": "node -e \"const fs=require('fs');['docs/index.html','docs/favicon.ico','docs/chess/index.html','docs/chess/favicon.ico','docs/assets/favicon.svg','docs/chess/assets/chess-app.js','docs/assets/highlight/highlight.min.js','docs/assets/highlight/github.min.css','docs/assets/highlight/github-dark.min.css'].forEach(p=>fs.accessSync(p));\"",
     "example:tictactoe": "node examples/decentralized-tictactoe.js",
     "example:chess": "node examples/decentralized-chess-lite.js",
     "prepublishOnly": "npm test && npm run build"
@@ -40,9 +50,25 @@
     "objects"
   ],
   "license": "Apache 2.0",
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "chess.js": "^1.4.0",
     "esbuild": "^0.28.0",
-    "jest": "^29.7.0"
+    "fake-indexeddb": "^6.0.0",
+    "http-server": "^14.1.1",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "three": "^0.184.0"
   },
   "dependencies": {
     "peerjs": "^1.5.5",