npm - dignity.js - Versions diffs - 0.7.1 → 0.8.1 - Mend

dignity.js 0.7.1 → 0.8.1

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

package/README.md +48 -3
package/dist/dignity.cjs.js +899 -8
package/dist/dignity.cjs.js.map +4 -4
package/dist/dignity.esm.js +899 -8
package/dist/dignity.esm.js.map +3 -3
package/dist/dignity.min.js +18 -18
package/docs/assets/dignity.esm.js +899 -8
package/docs/assets/playground-demos.js +56 -0
package/docs/index.html +64 -10
package/docs/openapi-like.json +61 -8
package/package.json +2 -2
package/src/core/dignity-p2p.js +428 -6
package/src/cqrs/bulk-relay.js +35 -0
package/src/cqrs/domain-events.js +285 -0
package/src/cqrs/peer-group-tiers.js +46 -0
package/src/cqrs/query-replica.js +213 -0
package/src/gossip/peer-group.js +1 -1
package/src/index.js +34 -1

package/docs/assets/playground-demos.js CHANGED Viewed

@@ -338,5 +338,61 @@ log('keys upgraded:', bob.getPeerIdentityState('alice')?.publicKey?.signingPubli
 await alice.stop();
 await bob.stop();`
+  },
+  {
+    id: 'cqrs-replica',
+    title: 'CQRS — publisher + query replica',
+    description: 'Domain events from a tiered PeerGroup hydrate a read-only DignityQueryReplica.',
+    code: `const { DignityP2P, DignityQueryReplica, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+const publisher = new DignityP2P({
+  nodeId: 'publisher',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security
+});
+const reader = new DignityP2P({
+  nodeId: 'reader',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security
+});
+helpers.track(publisher, reader);
+await publisher.start();
+await reader.start();
+await publisher.joinPeerGroup('feed:demo', {
+  role: 'publisher',
+  tiered: true,
+  liveCap: 100,
+  domainEvents: true,
+  fanout: 2,
+  maxActivePeers: 4
+});
+const replica = new DignityQueryReplica(reader, {
+  groupId: 'feed:demo',
+  collections: ['posts'],
+  publisherId: 'publisher'
+});
+await replica.start({ bootstrapPeerIds: ['publisher'] });
+await helpers.sleep(40);
+await publisher.create('posts', { text: 'CQRS demo post' }, {
+  id: 'p1',
+  peerGroupId: 'feed:demo'
+});
+await helpers.sleep(60);
+const record = replica.read('posts', 'p1');
+log('replica read:', JSON.stringify(record?.data));
+log('chain ok:', replica.verifyChain().ok);
+log('stats:', JSON.stringify(replica.getViewStats()));
+await replica.stop();
+await publisher.stop();
+await reader.stop();`
   }
 ];

package/docs/index.html CHANGED Viewed

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="dignity.js v0.7.1 — REST-like P2P object API for decentralized JavaScript applications." />
+    <meta name="description" content="dignity.js v0.8.0 — REST-like P2P object API for decentralized JavaScript applications." />
     <title>dignity.js · Documentation</title>
     <link rel="icon" href="./assets/favicon.svg" type="image/svg+xml" />
     <link rel="icon" href="./favicon.ico" sizes="32x32" />
@@ -16,7 +16,7 @@
       <a class="site-header__brand" href="#overview">
         <img src="./assets/dignity-logo.svg" alt="" width="344" height="80" />
         <!-- <span>dignity.js</span> -->
-        <span class="site-header__version">v0.7.1</span>
+        <span class="site-header__version">v0.8.0</span>
       </a>
       <div class="site-header__links">
         <a href="https://www.npmjs.com/package/dignity.js" target="_blank" rel="noopener noreferrer">npm</a>
@@ -47,6 +47,7 @@
             <a href="#object-api">Object API</a>
             <a href="#discovery">Room discovery</a>
             <a href="#peer-groups">PeerGroup gossip</a>
+            <a href="#cqrs-tiers">CQRS tiers</a>
             <a href="#messaging">Direct messaging</a>
             <a href="#concurrency">Concurrency</a>
             <a href="#content-hashes">Content hashes</a>
@@ -96,6 +97,10 @@
                 <h3>Content hashes</h3>
                 <p><code>record.hash</code> — <code>sha512:</code> digests over canonical <code>data</code> via <code>stableStringify</code>.</p>
               </article>
+              <article class="card">
+                <h3>CQRS PeerGroups (v0.8+)</h3>
+                <p>Live + bulk tiers, signed domain events, and <code>DignityQueryReplica</code> read views for massive audiences.</p>
+              </article>
             </div>
           </section>
@@ -480,7 +485,7 @@ await node.leaveDiscovery('team:red');</code></pre>
   bootstrapPeerIds: [hostPeerId],
   fanout: 3,
   maxActivePeers: 8,
-  maxHops: 6,
+  maxHops: 64,
   metadata: { role: 'spectator' }
 });
@@ -521,6 +526,14 @@ node.getPeerGroupStats();
                     <td><code>record:snapshot</code></td>
                     <td>Late-joiner catch-up</td>
                   </tr>
+                  <tr>
+                    <td><code>domain:event</code></td>
+                    <td>Signed, versioned write event (auto-published on CRUD when <code>domainEvents: true</code>)</td>
+                  </tr>
+                  <tr>
+                    <td><code>domain:checkpoint</code></td>
+                    <td>Bulk-tier catch-up anchor (<code>lastEventHash</code>, <code>recordCount</code>)</td>
+                  </tr>
                   <tr>
                     <td>App-defined</td>
                     <td>Custom payloads via <code>publishToPeerGroup</code> (emits <code>peergroupmessage</code>)</td>
@@ -539,6 +552,46 @@ node.getPeerGroupStats();
               <li>Set <code>relayEnabled: false</code> on a group to receive updates without re-forwarding.</li>
             </ul>
+            <h3 id="cqrs-tiers">CQRS tiers &amp; query replicas (v0.8+)</h3>
+            <p>
+              For audiences above ~5&nbsp;000 subscribers <em>per publisher</em>, use the command/query split:
+              publishers write locally and emit signed domain events; subscribers maintain read-only materialized views.
+            </p>
+            <ul>
+              <li><strong>Live tier</strong> — first <code>liveCap</code> subscribers (default 5&nbsp;000) receive real-time gossip via <code>publishToPeerGroup</code>.</li>
+              <li><strong>Bulk tier</strong> — overflow subscribers receive batched updates via <code>publishPeerGroupBulk</code> and elected bulk relays.</li>
+              <li><strong>Domain events</strong> — every <code>create</code> / <code>update</code> / <code>remove</code> on a publisher group auto-emits <code>domain:event</code> with hash-chain linking.</li>
+              <li><strong>Query replica</strong> — <code>DignityQueryReplica</code> hydrates local <code>read</code> / <code>list</code> views without contacting the owner.</li>
+            </ul>
+            <div class="code-block">
+              <pre><code class="language-javascript">const { DignityP2P, DignityQueryReplica } = dignity;
+// Publisher (command path)
+await publisher.joinPeerGroup('feed:alice', {
+  role: 'publisher',
+  tiered: true,
+  liveCap: 5000,
+  domainEvents: true
+});
+await publisher.create('posts', { text: 'hello' }, {
+  id: 'p1',
+  peerGroupId: 'feed:alice'   // auto-publishes domain:event
+});
+// Read-only replica (query path)
+const replica = new DignityQueryReplica(reader, {
+  groupId: 'feed:alice',
+  collections: ['posts'],
+  publisherId: 'alice'
+});
+await replica.start({ bootstrapPeerIds: ['alice'] });
+replica.read('posts', 'p1');
+replica.verifyChain();  // hash-chain consistency</code></pre>
+            </div>
+            <p>
+              Try the <a href="./playground/index.html">live playground</a> demo <em>CQRS — publisher + query replica</em>.
+            </p>
             <h3>Chess spectators</h3>
             <p>
               The <a href="./chess/index.html">3D Chess demo</a> mixes both replication modes:
@@ -573,8 +626,8 @@ node.getPeerGroupStats();
                   </tr>
                   <tr>
                     <td><code>maxHops</code></td>
-                    <td>6</td>
-                    <td>Covers large graphs with low diameter</td>
+                    <td>64</td>
+                    <td>Covers large graphs (fanout³×⁶⁴) without per-group tuning</td>
                   </tr>
                   <tr>
                     <td><code>globalMaxOpenConnections</code></td>
@@ -591,7 +644,8 @@ node.getPeerGroupStats();
             </div>
             <h3>Roadmap</h3>
-            <p><strong>v0.7.1 (current)</strong> — live docs playground, demo fixes, syntax highlighting.</p>
+            <p><strong>v0.8.0 (current)</strong> — CQRS tiered PeerGroups, domain events, DignityQueryReplica, hash chains, bulk relay, maxHops 64.</p>
+            <p><strong>v0.7.1</strong> — live docs playground, demo fixes, syntax highlighting.</p>
             <p><strong>v0.7.0 (shipped)</strong> — credential-derived keys, identity rotation, PeerGroup hardening, stress harness.</p>
             <p><strong>v0.6.0 (shipped)</strong> — core gossip, chess spectators, unit + e2e tests.</p>
             <p><strong>v0.6.x polish</strong> — <code>subscribeObjectFeed</code> wrapper, connection LRU trim, IndexedDB joined-group persistence, React <code>usePeerGroup</code> hook, 50+ node integration test.</p>
@@ -914,7 +968,7 @@ const pool = createDefaultSignalingPool({
                 <tbody>
                   <tr>
                     <td><code>dignity.js</code></td>
-                    <td><code>DignityP2P</code>, <code>IndexedDBPersistence</code>, signaling providers, in-memory adapters, security utilities</td>
+                    <td><code>DignityP2P</code>, <code>DignityQueryReplica</code>, <code>IndexedDBPersistence</code>, signaling providers, in-memory adapters, PeerGroup + CQRS helpers (<code>domain-events</code>, <code>peer-group-tiers</code>, <code>bulk-relay</code>), security utilities</td>
                   </tr>
                   <tr>
                     <td><code>dignity.js/react</code></td>
@@ -965,10 +1019,10 @@ const pool = createDefaultSignalingPool({
           <section id="development" class="section">
             <h2>Development</h2>
             <div class="code-block">
-              <pre><code class="language-bash"># Run tests (237+ passing, ~91% line coverage)
+              <pre><code class="language-bash"># Run tests (289+ passing)
 npm test
-# PeerGroup unit + e2e tests only
+# PeerGroup + CQRS unit + integration tests
 npm run test:peer-group
 # Build browser + Node bundles
@@ -985,7 +1039,7 @@ npm run example:chess</code></pre>
           <footer class="site-footer">
             <p>
-              dignity.js v0.7.1 ·
+              dignity.js v0.8.0 ·
               <a href="https://github.com/jose-compu/dignity.js/blob/main/LICENSE">Apache 2.0</a> ·
               <a href="https://github.com/jose-compu/dignity.js">GitHub</a> ·
               <a href="https://www.npmjs.com/package/dignity.js">npm</a>

package/docs/openapi-like.json CHANGED Viewed

@@ -1,7 +1,11 @@
 {
   "name": "dignity.js",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "REST-like object API over peer-to-peer replication",
+  "lifecycle": {
+    "start": "attach network message handler and begin receiving",
+    "stop": "leave discovery scopes and detach handler"
+  },
   "resources": {
     "collections/{collection}/{id}": {
       "create": {
@@ -11,7 +15,8 @@
           "id": "optional stable id",
           "collaborators": "optional peer id list",
           "broadcastScope": "scoped broadcast password namespace",
-          "connectToPeers": "optional; defaults to collaborators on PeerJS mesh"
+          "connectToPeers": "optional; defaults to collaborators on PeerJS mesh",
+          "peerGroupId": "optional; auto-publish signed domain event to this PeerGroup (v0.8+, publisher role)"
         }
       },
       "read": {
@@ -43,7 +48,17 @@
       },
       "delete": {
         "method": "remove(collection, id)",
-        "authorization": "owner-only"
+        "authorization": "owner-only",
+        "options": {
+          "peerGroupId": "optional; auto-publish domain event when publisher (v0.8+)"
+        }
+      },
+      "transferOwnership": {
+        "method": "transferOwnership(collection, id, newOwnerId, options)",
+        "authorization": "owner-only",
+        "options": {
+          "keepAsCollaborator": "default true; previous owner stays collaborator"
+        }
       }
     },
     "collections/{collection}": {
@@ -57,24 +72,62 @@
       "getConnectionStats": "{ openCount, peerIds }",
       "ensureConnectedToPeers": "connect to many peers before broadcast",
       "joinDiscovery": "scoped presence; options.bootstrapPeerIds connects before announce",
-      "broadcastMessage": "custom app messages; options.connectToPeers"
+      "leaveDiscovery": "stop heartbeat and remove local presence from scope",
+      "listPeers": "list presence entries in a discovery scope",
+      "announcePresence": "manual presence heartbeat for a joined scope",
+      "broadcastMessage": "custom app messages; options.connectToPeers",
+      "sendDirectMessage": "encrypted direct message to targetId",
+      "registerPeerPublicKey": "trust peer signing/encryption keys with optional generation",
+      "trustPeerPublicKey": "register trusted keys without generation metadata",
+      "getPublicKey": "returns this node's public key bundle",
+      "unbanPeer": "clear manual or automatic peer ban",
+      "getBanInfo": "returns ban expiry and reason for peerId, or null"
+    },
+    "identity": {
+      "getPeerIdentityGeneration": "trusted identity generation for peerId",
+      "getPeerIdentityState": "public key + generation state for peerId",
+      "adoptDerivedIdentityKeyPair": "install credential-derived keys locally",
+      "deriveAndAdoptIdentity": "derive keys from username/password and adopt",
+      "broadcastIdentityRotation": "broadcast signed identity:rotate to peers",
+      "enrollAndBroadcastColdRecovery": "enroll cold recovery key and announce",
+      "revokeAndRotateDerivedIdentity": "compromise recovery rotation helper",
+      "rotateDerivedIdentityPassword": "password-change rotation helper",
+      "applyPeerIdentityRotation": "apply remote identity:rotate message",
+      "applyPeerColdRecoveryEnrollment": "apply remote cold-recovery enrollment"
     },
     "peerGroups": {
-      "joinPeerGroup": "join scalable gossip group (multiplexed); options.fanout, maxActivePeers, bootstrapPeerIds",
+      "joinPeerGroup": "join scalable gossip group; options: fanout, maxActivePeers, maxHops (default 64), role, tiered, liveCap, tierMode, domainEvents, publisherId",
       "leavePeerGroup": "leave gossip group and scoped presence",
       "listPeerGroupMembers": "list presence in gossip:{groupId} scope",
-      "publishToPeerGroup": "epidemic publish with bounded fanout; inner types: operation, record:snapshot, custom",
+      "publishToPeerGroup": "epidemic publish to live tier when tiered; inner types: operation, record:snapshot, domain:event, custom",
+      "publishPeerGroupBulk": "bulk-tier publish (publisher only); batched domain events and checkpoints",
+      "publishPeerGroupCheckpoint": "publish domain-event chain checkpoint to bulk tier",
       "publishRecordToPeerGroup": "publish normalized record snapshot into gossip group",
+      "getPeerGroupConfig": "returns joined group config including tier and domainEvents flags",
       "getPeerGroupStats": "{ joinedGroups, seenGossipCount, openConnectionCount, globalMaxOpenConnections }"
+    },
+    "cqrs": {
+      "DignityQueryReplica": "read-only materialized view from domain events; methods: start, stop, read, list, verifyChain, getViewStats",
+      "domainEvents": "operationToDomainEvent, verifyDomainEvent, verifyEventChain, DOMAIN_EVENT_SCHEMA_VERSION",
+      "tiers": "assignPeerGroupTier, DEFAULT_LIVE_CAP (5000), filterPeersByTier",
+      "bulkRelay": "electBulkRelays, DEFAULT_BULK_RELAY_COUNT"
     }
   },
   "events": {
     "change": "object create/update/delete/snapshot applied",
     "conflict": "local or remote version mismatch",
-    "warning": "orphan-operation, peer-connect-failed, presence failures, content-hash-mismatch",
+    "warning": "orphan-operation, peer-connect-failed, presence failures, content-hash-mismatch, domain-event-rejected",
+    "domainevent": "signed domain event applied or emitted locally",
+    "chainbroken": "domain event hash chain verification failed",
+    "bulkrelaychanged": "bulk relay peer set changed for a tiered group",
+    "checkpointpublished": "publisher published domain-event checkpoint",
     "peerdiscovered": "peer joined discovery scope",
+    "peergroupjoined": "local node joined a PeerGroup",
+    "peergroupleft": "local node left a PeerGroup",
     "peerleft": "peer left or timed out",
-    "message": "custom decrypted message received"
+    "message": "custom decrypted message received",
+    "securityerror": "signature, PoW, or decrypt failure on incoming message",
+    "messageignored": "message dropped (wrong target, banned peer, etc.)"
   },
   "recordShape": {
     "active": {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dignity.js",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "P2P object API for decentralized JavaScript applications",
   "homepage": "https://jose-compu.github.io/dignity.js/",
   "repository": {
@@ -41,7 +41,7 @@
   "scripts": {
     "test": "jest --coverage",
     "test:unit": "jest tests/unit --runInBand",
-    "test:peer-group": "jest tests/unit/peer-group-gossip.test.js tests/unit/peer-group-helpers.test.js tests/integration/peer-group-gossip-e2e.test.js --runInBand --coverage=false",
+    "test:peer-group": "jest tests/unit/peer-group-gossip.test.js tests/unit/peer-group-helpers.test.js tests/unit/domain-events.test.js tests/unit/peer-group-tiers.test.js tests/unit/query-replica.test.js tests/unit/view-consistency.test.js tests/integration/peer-group-gossip-e2e.test.js tests/integration/cqrs-tiered-peergroup.test.js --runInBand --coverage=false",
     "test:stress-peer-group": "RUN_STRESS_TESTS=1 jest tests/stress/peer-group-scale.test.js --runInBand --coverage=false",
     "stress:peer-group": "node scripts/stress-peer-group.js",
     "test:cloudflare-live": "RUN_CLOUDFLARE_LIVE_TESTS=1 jest tests/integration/cloudflare-signaling-live.test.js --runInBand",