dignity.js 0.3.0 → 0.4.0

package/docs/openapi-like.json

@@ -1,6 +1,6 @@
 {
   "name": "dignity.js",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "REST-like object API over peer-to-peer replication",
   "resources": {
     "collections/{collection}/{id}": {
@@ -12,8 +12,16 @@
         "method": "read(collection, id)"
       },
       "update": {
-        "method": "update(collection, id, patch)",
-        "authorization": "owner-only"
+        "method": "update(collection, id, patch, options)",
+        "authorization": "owner-only",
+        "options": {
+          "expectedVersion": "optional number; throws VERSION_CONFLICT when mismatched",
+          "broadcastScope": "optional scoped broadcast password namespace"
+        }
+      },
+      "updateWithRetry": {
+        "method": "updateWithRetry(collection, id, patchFn, options)",
+        "description": "read-modify-write helper with automatic retry on version conflicts"
       },
       "delete": {
         "method": "remove(collection, id)",
@@ -26,6 +34,31 @@
       }
     }
   },
+  "events": {
+    "change": "object create/update/delete applied",
+    "conflict": "local or remote version mismatch",
+    "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",
+      "usePeers"
+    ]
+  },
   "signaling": {
     "defaults": {
       "cloudflare": "enabled by default",
@@ -45,13 +78,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dignity.js",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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": [
@@ -27,7 +32,7 @@
     "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')\"",
+    "docs:check": "node -e \"const fs=require('fs');['docs/index.html','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 +45,22 @@
     "objects"
   ],
   "license": "Apache 2.0",
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@testing-library/react": "^16.3.0",
     "esbuild": "^0.28.0",
-    "jest": "^29.7.0"
+    "fake-indexeddb": "^6.0.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
   },
   "dependencies": {
     "peerjs": "^1.5.5",

package/src/core/dignity-p2p.js

@@ -178,6 +178,23 @@ class DignityP2P extends EventEmitter {
       throw new Error(`Only owner ${existing.ownerId} can update object ${id}`);
     }
 
+    if (typeof options.expectedVersion === 'number' && existing.version !== options.expectedVersion) {
+      this.emitConflict({
+        kind: 'update',
+        collection: collectionName,
+        id,
+        expectedVersion: options.expectedVersion,
+        currentVersion: existing.version,
+        phase: 'local'
+      });
+
+      const error = new Error(
+        `Version conflict on ${collectionName}/${id}: expected ${options.expectedVersion}, current ${existing.version}`
+      );
+      error.code = 'VERSION_CONFLICT';
+      throw error;
+    }
+
     const operation = {
       opId: this.idGenerator(),
       kind: 'update',
@@ -201,6 +218,31 @@ class DignityP2P extends EventEmitter {
     return this.read(collectionName, id);
   }
 
+  async updateWithRetry(collectionName, id, patchFn, options = {}) {
+    const maxAttempts = typeof options.maxAttempts === 'number' ? options.maxAttempts : 5;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const current = this.read(collectionName, id);
+      if (!current) {
+        throw new Error(`Object ${id} does not exist in ${collectionName}`);
+      }
+
+      const patch = await patchFn(current);
+      try {
+        return await this.update(collectionName, id, patch, {
+          ...options,
+          expectedVersion: current.version
+        });
+      } catch (error) {
+        if (error.code !== 'VERSION_CONFLICT' || attempt === maxAttempts - 1) {
+          throw error;
+        }
+      }
+    }
+
+    throw new Error(`Unable to update ${collectionName}/${id} after ${maxAttempts} attempts`);
+  }
+
   async remove(collectionName, id, options = {}) {
     const existing = this.getCollection(collectionName).get(id);
 
@@ -534,6 +576,34 @@ class DignityP2P extends EventEmitter {
     return this.getBanInfo(peerId) !== null;
   }
 
+  emitConflict(details) {
+    this.emit('conflict', details);
+  }
+
+  restoreRecord(collectionName, record) {
+    if (!record || !record.id) {
+      return false;
+    }
+
+    const collection = this.getCollection(collectionName);
+    const current = collection.get(record.id);
+    if (current && current.version >= record.version) {
+      return false;
+    }
+
+    collection.set(record.id, {
+      id: record.id,
+      ownerId: record.ownerId,
+      data: { ...(record.data || {}) },
+      createdAt: record.createdAt,
+      updatedAt: record.updatedAt,
+      deletedAt: record.deletedAt || null,
+      version: record.version
+    });
+
+    return true;
+  }
+
   applyOperation(operation) {
     if (!operation || !operation.opId || this.appliedOperations.has(operation.opId)) {
       return false;
@@ -571,6 +641,15 @@ class DignityP2P extends EventEmitter {
     }
 
     if (typeof operation.baseVersion === 'number' && operation.baseVersion !== current.version) {
+      this.emitConflict({
+        kind: operation.kind,
+        collection: operation.collectionName,
+        id: operation.id,
+        expectedVersion: operation.baseVersion,
+        currentVersion: current.version,
+        phase: 'remote',
+        operation
+      });
       return false;
     }
 

package/src/index.js

@@ -15,6 +15,7 @@ const {
   InMemoryNetworkHub,
   InMemoryNetworkAdapter
 } = require('./network/in-memory-network');
+const IndexedDBPersistence = require('./persistence/indexeddb-persistence');
 const {
   DEFAULT_CLOUDFLARE_SIGNALING_URLS,
   DEFAULT_SIGNALING_FALLBACK_URLS
@@ -34,6 +35,7 @@ module.exports = {
   PeerJSSignalingProvider,
   InMemoryNetworkHub,
   InMemoryNetworkAdapter,
+  IndexedDBPersistence,
   DEFAULT_CLOUDFLARE_SIGNALING_URLS,
   DEFAULT_SIGNALING_FALLBACK_URLS,
   VDF,

package/src/persistence/indexeddb-persistence.js

@@ -0,0 +1,182 @@
+class IndexedDBPersistence {
+  constructor({
+    dbName = 'dignity',
+    storeName = 'records',
+    collections = null,
+    indexedDB = typeof globalThis !== 'undefined' ? globalThis.indexedDB : null
+  } = {}) {
+    this.dbName = dbName;
+    this.storeName = storeName;
+    this.collections = collections;
+    this.indexedDB = indexedDB;
+    this.node = null;
+    this.changeHandler = null;
+  }
+
+  recordKey(collection, id) {
+    return `${collection}:${id}`;
+  }
+
+  shouldPersist(collection) {
+    if (!this.collections) {
+      return true;
+    }
+
+    return this.collections.includes(collection);
+  }
+
+  openDb() {
+    if (!this.indexedDB) {
+      return Promise.reject(new Error('IndexedDB is not available'));
+    }
+
+    return new Promise((resolve, reject) => {
+      const request = this.indexedDB.open(this.dbName, 1);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName, { keyPath: 'key' });
+        }
+      };
+
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error || new Error('Unable to open IndexedDB'));
+    });
+  }
+
+  runTransaction(mode, handler) {
+    return this.openDb().then((db) => new Promise((resolve, reject) => {
+      const transaction = db.transaction(this.storeName, mode);
+      const store = transaction.objectStore(this.storeName);
+
+      Promise.resolve(handler(store))
+        .then(resolve)
+        .catch(reject);
+
+      transaction.oncomplete = () => db.close();
+      transaction.onerror = () => reject(transaction.error || new Error('IndexedDB transaction failed'));
+      transaction.onabort = () => reject(transaction.error || new Error('IndexedDB transaction aborted'));
+    }));
+  }
+
+  serializeRecord(collection, id) {
+    const record = this.node.getCollection(collection).get(id);
+    if (!record) {
+      return null;
+    }
+
+    return {
+      key: this.recordKey(collection, id),
+      collection,
+      id,
+      ownerId: record.ownerId,
+      data: { ...record.data },
+      createdAt: record.createdAt,
+      updatedAt: record.updatedAt,
+      deletedAt: record.deletedAt,
+      version: record.version
+    };
+  }
+
+  async persistRecord(collection, id) {
+    if (!this.node || !this.shouldPersist(collection)) {
+      return;
+    }
+
+    const serialized = this.serializeRecord(collection, id);
+    const key = this.recordKey(collection, id);
+
+    if (!serialized) {
+      await this.runTransaction('readwrite', (store) => new Promise((resolve, reject) => {
+        const request = store.delete(key);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+      }));
+      return;
+    }
+
+    await this.runTransaction('readwrite', (store) => new Promise((resolve, reject) => {
+      const request = store.put(serialized);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    }));
+  }
+
+  persistChange(event) {
+    if (!event || !event.collection || !event.id) {
+      return;
+    }
+
+    this.persistRecord(event.collection, event.id).catch((error) => {
+      this.node.emit('warning', {
+        type: 'persistence-failed',
+        collection: event.collection,
+        id: event.id,
+        error
+      });
+    });
+  }
+
+  async loadAllRecords() {
+    return this.runTransaction('readonly', (store) => new Promise((resolve, reject) => {
+      const request = store.getAll();
+      request.onsuccess = () => resolve(request.result || []);
+      request.onerror = () => reject(request.error);
+    }));
+  }
+
+  async hydrate() {
+    if (!this.node) {
+      throw new Error('IndexedDBPersistence requires an attached node before hydrate');
+    }
+
+    const storedRecords = await this.loadAllRecords();
+    for (const stored of storedRecords) {
+      if (!this.shouldPersist(stored.collection)) {
+        continue;
+      }
+
+      this.node.restoreRecord(stored.collection, {
+        id: stored.id,
+        ownerId: stored.ownerId,
+        data: stored.data,
+        createdAt: stored.createdAt,
+        updatedAt: stored.updatedAt,
+        deletedAt: stored.deletedAt,
+        version: stored.version
+      });
+    }
+  }
+
+  async attach(node) {
+    if (!node) {
+      throw new Error('IndexedDBPersistence.attach requires a DignityP2P node');
+    }
+
+    this.node = node;
+    await this.hydrate();
+
+    this.changeHandler = (event) => this.persistChange(event);
+    node.on('change', this.changeHandler);
+  }
+
+  async detach() {
+    if (this.node && this.changeHandler) {
+      this.node.off('change', this.changeHandler);
+    }
+
+    this.changeHandler = null;
+    this.node = null;
+  }
+
+  async clear() {
+    await this.runTransaction('readwrite', (store) => new Promise((resolve, reject) => {
+      const request = store.clear();
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    }));
+  }
+}
+
+module.exports = IndexedDBPersistence;

package/src/react/index.js

@@ -0,0 +1,114 @@
+const { useCallback, useEffect, useState } = require('react');
+const DignityP2P = require('../core/dignity-p2p');
+
+function useDignity(config) {
+  const [node, setNode] = useState(null);
+  const [status, setStatus] = useState('idle');
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    if (!config) {
+      return undefined;
+    }
+
+    let cancelled = false;
+    const instance = new DignityP2P(config);
+    setNode(instance);
+    setStatus('starting');
+    setError(null);
+
+    instance.start()
+      .then(() => {
+        if (!cancelled) {
+          setStatus('running');
+        }
+      })
+      .catch((startError) => {
+        if (!cancelled) {
+          setError(startError);
+          setStatus('error');
+        }
+      });
+
+    return () => {
+      cancelled = true;
+      instance.stop()
+        .catch(() => undefined)
+        .finally(() => {
+          setStatus('stopped');
+          setNode(null);
+        });
+    };
+  }, [config]);
+
+  return {
+    node,
+    status,
+    error
+  };
+}
+
+function useCollection(node, collectionName) {
+  const [records, setRecords] = useState([]);
+
+  const refresh = useCallback(() => {
+    if (!node || !collectionName) {
+      setRecords([]);
+      return;
+    }
+
+    setRecords(node.list(collectionName));
+  }, [node, collectionName]);
+
+  useEffect(() => {
+    refresh();
+
+    if (!node) {
+      return undefined;
+    }
+
+    node.on('change', refresh);
+    return () => node.off('change', refresh);
+  }, [node, refresh]);
+
+  return records;
+}
+
+function usePeers(node, scope = 'main', options = {}) {
+  const includeSelf = options.includeSelf !== false;
+  const [peers, setPeers] = useState([]);
+
+  const refresh = useCallback(() => {
+    if (!node) {
+      setPeers([]);
+      return;
+    }
+
+    setPeers(node.listPeers(scope, { includeSelf }));
+  }, [node, scope, includeSelf]);
+
+  useEffect(() => {
+    refresh();
+
+    if (!node) {
+      return undefined;
+    }
+
+    const handlePresenceChange = () => refresh();
+    node.on('peerdiscovered', handlePresenceChange);
+    node.on('peerleft', handlePresenceChange);
+
+    return () => {
+      node.off('peerdiscovered', handlePresenceChange);
+      node.off('peerleft', handlePresenceChange);
+    };
+  }, [node, refresh]);
+
+  return peers;
+}
+
+module.exports = {
+  useDignity,
+  useCollection,
+  usePeers
+};