@nostr-wot/graph 0.2.0 → 0.3.0

package/README.md

@@ -43,7 +43,8 @@ wg.filterByWoT(pubkeys);  // trusted subset, sorted by score desc
 |---|---|
 | `load()` | Hydrate the cached graph from IndexedDB. |
 | `crawl(root, opts)` | BFS-fetch kind:3 to build/refresh the graph. Concurrent calls share one in-flight promise. |
-| `getDistance(pubkey)` | `{ hops, paths }` from the crawled root, or `null`. |
+| `getDistance(pubkey, maxHops=6)` | `{ hops, paths }` from the crawled root, or `null`. |
+| `getDistances(pubkeys, maxHops=6)` | Batch distances sharing one traversal. |
 | `getScore(pubkey)` | Trust score `0..1` (`calculateScore`). |
 | `isInWoT(pubkey, maxHops=2)` | Within `maxHops` of the root. |
 | `filterByWoT(pubkeys, opts?)` | Trusted subset, sorted by score descending. |
@@ -58,13 +59,14 @@ wg.filterByWoT(pubkeys);  // trusted subset, sorted by score desc
 
 ```ts
 crawl(rootPubkey, {
-  maxDepth?: number;            // default 2
+  maxDepth?: number;            // inclusive fetched author depth, default 2
+  maxHops?: number;             // optional hop boundary; overrides maxDepth
   onProgress?: (p) => void;     // { depth, fetched, queued }
   signal?: AbortSignal;         // cancel
 }): Promise<CrawlResult>;       // { fetched, nodes, edges, depth, durationMs, stoppedEarly }
 ```
 
-Crawls tolerate unreachable relays and only throw `CrawlError` if **zero** relays are configured. In Node without an IndexedDB polyfill the store runs memory-only (crawl/query work, nothing persists).
+Crawls tolerate missing relay responses. Zero configured relays throw `CrawlError`; invalid options, transport exceptions and persistence failures propagate. In Node without an IndexedDB polyfill the store runs memory-only (crawl/query work, nothing persists).
 
 ## React (`/react`)
 
@@ -102,3 +104,44 @@ await wot.getDistance(target);
 ## License
 
 MIT
+
+
+## Graph efficiency and compatibility
+
+Crawling batches up to 100 authors per subscription (configurable through
+`GraphCrawler.batchSize`). The filter has no global event limit, so one author's
+history cannot consume another author's slot. The newest kind:3 wins by timestamp,
+then lowest event ID; versions persist with follow rows so stale refreshes cannot
+replace a newer list. A missing response retains cached follows for traversal.
+Unrequested authors, other kinds and timestamps more than 60 seconds in the future
+are ignored. The supplied pool remains responsible for event signature verification.
+
+`maxDepth` keeps its existing inclusive author-depth meaning: `maxDepth: 1` fetches
+the root and its direct follows, discovering people two hops away. Use `maxHops: 2`
+to fetch just the lists needed for two-hop reachability; authors at distance two
+are not fetched. `maxHops: 0` sends no requests. Query defaults remain six hops;
+pass an explicit query bound when exploring further.
+
+Storage interns keys, deduplicates adjacency and maintains edge counts as rows
+change. IndexedDB schema version 2 writes delta-varint rows; existing version-1
+fixed-width rows load without a full rewrite and migrate when updated. Older SDK
+versions cannot reopen an upgraded namespace (IndexedDB reports `VersionError`),
+so rolling back requires a different namespace or clearing the upgraded database.
+Transactions preserve pending rows on failure, serialize flushes, and atomically
+write each batch of follow rows with its key mappings and event versions. Metadata
+writes use one separate transaction. A crawl is **not** a whole-graph transaction:
+partial results remain queryable, and stopped crawls are marked stale.
+
+One numeric BFS serves repeated queries and shallower bounds until edges change
+or a deeper traversal is needed. Duplicate follows do not inflate paths. Distances
+use 32-bit arrays and path counts use 64-bit floats, saturated at
+`Number.MAX_SAFE_INTEGER`; this uses more traversal memory than the former 8-bit
+hops/32-bit paths while avoiding overflow. No TTL-based incremental relay sync,
+root-based pruning or cross-instance live cache synchronization is implemented.
+
+Run `npm run benchmark -w @nostr-wot/graph` from the repository root for reproducible
+synthetic construction, cold traversal and warm retrieval timings. Regression
+fixtures verify 251 authors use 4 requests instead of 251 (98.4% fewer), 1,000 dense
+follow IDs use 1,000 encoded bytes instead of 4,000 (75% smaller payload), and 1,000
+unchanged queries traverse a three-node graph only once. These figures describe
+fixtures; relay latency and IndexedDB record overhead are not included.