dignity.js 0.5.3 → 0.6.0

package/README.md

@@ -6,8 +6,8 @@
 [![npm version](https://img.shields.io/npm/v/dignity.js?color=cb3837&label=npm)](https://www.npmjs.com/package/dignity.js)
 [![npm downloads](https://img.shields.io/npm/dm/dignity.js?color=blue)](https://www.npmjs.com/package/dignity.js)
 [![CI](https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml/badge.svg)](https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml)
-![tests](https://img.shields.io/badge/tests-150%2B%20passing-brightgreen)
-![coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)
+![tests](https://img.shields.io/badge/tests-213%2B%20passing-brightgreen)
+![coverage](https://img.shields.io/badge/coverage-92%25-brightgreen)
 ![license](https://img.shields.io/badge/license-Apache%202.0-black)
 
 REST-like P2P object API for decentralized JavaScript applications.
@@ -29,6 +29,7 @@ REST-like P2P object API for decentralized JavaScript applications.
 - Optimistic concurrency helpers (`expectedVersion`, `updateWithRetry`, `conflict` events)
 - PeerJS mesh bootstrap: connect before announce/broadcast, auto `publicKey` in presence
 - Late-joiner sync via `pushRecordSnapshot` (full record catch-up when create was missed)
+- Content hashes on active records via `record.hash` (`sha512:` over canonicalized `data`)
 - Auto `connectToPeers` on create/update/delete replication (owner + collaborators)
 - Optional IndexedDB persistence for browser reload survival
 - Optional React hooks via `dignity.js/react`
@@ -40,6 +41,10 @@ REST-like P2P object API for decentralized JavaScript applications.
 npm install dignity.js
 ```
 
+## Tutorial
+
+**New to dignity.js?** Start with [TUTORIAL.md](./TUTORIAL.md) — eight short lessons from two in-memory peers to browser PeerJS and PeerGroup spectators. The [docs site tutorial](https://jose-compu.github.io/dignity.js/#tutorial) covers the same path.
+
 ## Quick Start
 
 ```js
@@ -119,6 +124,24 @@ await node.create('matches', { mode: 'coop' }, {
 
 Peers with a different password for `coop:red` cannot decrypt that broadcast traffic.
 
+## PeerGroup Gossip (scalable PubSub)
+
+For high-fanout object updates (millions of subscribers per published object), use multiplexed gossip groups. Each peer keeps a bounded number of active transports (`maxActivePeers` per group, `globalMaxOpenConnections` per node).
+
+```js
+// Follow 200 accounts = 200 joined groups, few connections each
+await node.joinPeerGroup('feed:alice', {
+  bootstrapPeerIds: ['publisher-peer-id'],
+  fanout: 3,
+  maxActivePeers: 8
+});
+
+await node.publishRecordToPeerGroup('feed:alice', 'posts', 'post-1');
+await node.leavePeerGroup('feed:alice');
+```
+
+Small collaborations (chess players, document co-editing) should keep using direct `connectToPeers` mesh. Large read-only audiences (chess spectators, public timelines) should use PeerGroup gossip. See the [docs PeerGroup section](https://jose-compu.github.io/dignity.js/#peer-groups).
+
 ## Room / Team Discovery
 
 Use scoped discovery to find active peers in a room (for example `main`, `team:red`, `raid-42`).
@@ -161,6 +184,23 @@ await node.updateWithRetry('games', 'g1', (current) => ({
 
 Use `expectedVersion` for fail-fast local writes. Use `updateWithRetry` for read-modify-write loops in fast multiplayer state.
 
+## Record Content Hashes
+
+Active records returned by `create`, `read`, `list`, `update`, and `pushRecordSnapshot` include a `hash` field:
+
+```js
+const record = await node.create('notes', { title: 'hello' }, { id: 'n1' });
+console.log(record.hash); // sha512:...
+```
+
+Hash details:
+
+- The algorithm is `sha512`, matching `tweetnacl.hash` in both browser and Node builds.
+- The digest covers only `record.data`, not `id`, `ownerId`, timestamps, collaborators, or version.
+- Data is canonicalized with `stableStringify`, so object key order does not affect the hash.
+- Snapshot restore recomputes the digest locally and emits a `warning` with type `content-hash-mismatch` if a remote advertised hash does not match the received `data`.
+- Deleted tombstones returned by `list(collection, { includeDeleted: true })` intentionally omit `hash`.
+
 ## IndexedDB Persistence
 
 Persist replicated collections across page reloads:
@@ -291,6 +331,24 @@ The joiner applies the snapshot via `restoreRecord`, then subsequent move update
 
 ## Development
 
+| Script | Purpose | Notes |
+| --- | --- | --- |
+| `npm test` | Run the full Jest suite with coverage. | Standard local validation before opening a PR or publishing. |
+| `npm run test:unit` | Run the unit-test subset only. | Useful for faster local iteration. |
+| `npm run test:cloudflare-live` | Run the live Cloudflare signaling integration test. | Opt-in; set `RUN_CLOUDFLARE_LIVE_TESTS=1`. |
+| `npm run test:pow-calibrate` | Run the Sloth VDF timing calibration test without coverage. | Opt-in; set `RUN_POW_CALIBRATE=1`. |
+| `npm run build` | Build the published package bundles into `dist/`. | Run after changing library source files. |
+| `npm run build:chess` | Rebuild the browser chess demo bundle only. | Used by the docs site and local chess demo. |
+| `npm run docs:favicon` | Regenerate the docs favicon assets. | Docs maintenance helper. |
+| `npm run docs:build` | Build the docs-specific assets. | Currently rebuilds the chess demo bundle. |
+| `npm run docs:dev` | Start the local docs server. | Serves the main docs and chess demo; auto-builds chess if needed. |
+| `npm run docs:serve` | Start the same local docs server via an alias. | Equivalent to `docs:dev`. |
+| `npm run docs:stop` | Stop the background docs server from a previous run. | Useful if port `4173` is stuck. |
+| `npm run docs:check` | Verify the generated docs assets exist. | Good quick check after docs asset generation. |
+| `npm run example:tictactoe` | Run the Node tic-tac-toe example. | Demonstrates a minimal replicated game flow. |
+| `npm run example:chess` | Run the Node chess example. | Demonstrates the lighter-weight chess sample. |
+| `npm run prepublishOnly` | Run the publish gate locally. | Publish/CI-oriented hook; runs tests and build before `npm publish`. |
+
 ```bash
 npm test
 npm run build
@@ -324,7 +382,7 @@ If 4173 is busy, `docs:dev` auto-picks the next free port (4174, 4175, …) and
 
 - **Documentation:** [jose-compu.github.io/dignity.js](https://jose-compu.github.io/dignity.js/)
 - Docs site source: `docs/index.html` (local: `npm run docs:dev`)
-- **3D Chess demo:** `docs/chess/` → [local chess demo](http://127.0.0.1:4173/chess/) when `docs:dev` is running
+- **3D Chess demo:** `docs/chess/` — PeerJS mesh, dual-signed resume links, IndexedDB → [local chess demo](http://127.0.0.1:4173/chess/) when `docs:dev` is running
 - API metadata: `docs/openapi-like.json`
 - Minimal demos:
   - `examples/decentralized-tictactoe.js`