dignity.js 0.3.0 → 0.4.0

package/README.md

@@ -11,10 +11,12 @@
 </p>
 
 <p align="center">
+  <a href="https://jose-compu.github.io/dignity.js/"><img src="https://img.shields.io/badge/docs-online-5B7FFF" alt="documentation"></a>
   <a href="https://www.npmjs.com/package/dignity.js"><img src="https://img.shields.io/npm/v/dignity.js?color=cb3837&label=npm" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/dignity.js"><img src="https://img.shields.io/npm/dm/dignity.js?color=blue" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/tests-122%20passing-brightgreen" alt="tests passing">
-  <img src="https://img.shields.io/badge/coverage-97%25-brightgreen" alt="coverage">
+  <a href="https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml"><img src="https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/tests-150%2B%20passing-brightgreen" alt="tests passing">
+  <img src="https://img.shields.io/badge/coverage-99%25-brightgreen" alt="coverage">
   <img src="https://img.shields.io/badge/license-Apache%202.0-black" alt="license">
 </p>
 
@@ -34,6 +36,9 @@ REST-like P2P object API for decentralized JavaScript applications.
   - default `powSteps: 22` (calibrated on this machine to about 1000ms)
   - automatic peer ban on invalid signature/PoW (`48h` default)
 - Team/subapp scoped broadcast passwords (`broadcastScope` + `broadcastPasswords`)
+- Optimistic concurrency helpers (`expectedVersion`, `updateWithRetry`, `conflict` events)
+- Optional IndexedDB persistence for browser reload survival
+- Optional React hooks via `dignity.js/react`
 - Browser-first: published npm package includes IIFE, ESM, and CJS builds
 
 ## Install
@@ -145,6 +150,57 @@ bob.registerPeerPublicKey('alice', alice.getPublicKey());
 await alice.sendDirectMessage('bob', 'dm', { text: 'private payload' });
 ```
 
+## Optimistic Concurrency
+
+Updates carry a monotonic `version`. Remote peers reject stale operations when `baseVersion` does not match.
+
+```js
+node.on('conflict', (event) => {
+  console.log('conflict', event.phase, event.expectedVersion, event.currentVersion);
+});
+
+await node.update('games', 'g1', { score: 10 }, { expectedVersion: 3 });
+
+await node.updateWithRetry('games', 'g1', (current) => ({
+  score: current.data.score + 1
+}));
+```
+
+Use `expectedVersion` for fail-fast local writes. Use `updateWithRetry` for read-modify-write loops in fast multiplayer state.
+
+## IndexedDB Persistence
+
+Persist replicated collections across page reloads:
+
+```js
+const { DignityP2P, IndexedDBPersistence } = require('dignity.js');
+
+const node = new DignityP2P({ nodeId, networkAdapter, security });
+const persistence = new IndexedDBPersistence({
+  dbName: 'my-app',
+  collections: ['games', 'matches']
+});
+
+await node.start();
+await persistence.attach(node);
+```
+
+## React Hooks
+
+Optional React integration (`react >= 18` peer dependency):
+
+```js
+import { useDignity, useCollection, usePeers } from 'dignity.js/react';
+
+function Room() {
+  const { node, status } = useDignity(config);
+  const games = useCollection(node, 'games');
+  const peers = usePeers(node, 'room:chess', { includeSelf: false });
+
+  return <pre>{JSON.stringify({ status, games, peers }, null, 2)}</pre>;
+}
+```
+
 ## Browser Usage
 
 The published npm package includes pre-built bundles (IIFE, ESM, CJS) generated at publish time. The `dist/` folder is not checked into the repository.
@@ -195,7 +251,8 @@ npm run test:pow-calibrate
 
 ## Docs and Examples
 
-- Docs site source: `docs/index.html`
+- **Documentation:** [jose-compu.github.io/dignity.js](https://jose-compu.github.io/dignity.js/)
+- Docs site source: `docs/index.html` (serve locally with `npm run docs:serve`)
 - API metadata: `docs/openapi-like.json`
 - Minimal demos:
   - `examples/decentralized-tictactoe.js`

package/dist/dignity.cjs.js

@@ -2980,6 +2980,21 @@ var require_dignity_p2p = __commonJS({
         if (existing.ownerId !== this.nodeId) {
           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",
@@ -3000,6 +3015,27 @@ var require_dignity_p2p = __commonJS({
         });
         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);
         if (!existing || existing.deletedAt) {
@@ -3277,6 +3313,29 @@ var require_dignity_p2p = __commonJS({
       isPeerBanned(peerId) {
         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;
@@ -3307,6 +3366,15 @@ var require_dignity_p2p = __commonJS({
           return false;
         }
         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;
         }
         if (operation.kind === "update") {
@@ -10384,6 +10452,163 @@ var require_in_memory_network = __commonJS({
   }
 });
 
+// src/persistence/indexeddb-persistence.js
+var require_indexeddb_persistence = __commonJS({
+  "src/persistence/indexeddb-persistence.js"(exports2, module2) {
+    var IndexedDBPersistence2 = class {
+      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);
+        }));
+      }
+    };
+    module2.exports = IndexedDBPersistence2;
+  }
+});
+
 // src/index.js
 var DignityP2P = require_dignity_p2p();
 var createDefaultSignalingPool = require_create_default_signaling_pool();
@@ -10394,6 +10619,7 @@ var {
   InMemoryNetworkHub,
   InMemoryNetworkAdapter
 } = require_in_memory_network();
+var IndexedDBPersistence = require_indexeddb_persistence();
 var {
   DEFAULT_CLOUDFLARE_SIGNALING_URLS,
   DEFAULT_SIGNALING_FALLBACK_URLS
@@ -10412,6 +10638,7 @@ module.exports = {
   PeerJSSignalingProvider,
   InMemoryNetworkHub,
   InMemoryNetworkAdapter,
+  IndexedDBPersistence,
   DEFAULT_CLOUDFLARE_SIGNALING_URLS,
   DEFAULT_SIGNALING_FALLBACK_URLS,
   VDF,