@loro-dev/flock 2.1.1 → 3.0.0

package/README.md

@@ -19,8 +19,8 @@ The library ships ESM, CommonJS, and TypeScript declaration files. It has no run
 ```ts
 import { Flock } from "@loro-dev/flock";
 
-// Each replica uses a stable 32-byte peer id to maintain version vectors.
-const peerId = crypto.getRandomValues(new Uint8Array(32));
+// Each replica uses a stable UTF-8 peer id (<128 bytes) to maintain version vectors.
+const peerId = crypto.randomUUID();
 const store = new Flock(peerId);
 
 store.put(["users", "42"], { name: "Ada", online: true });
@@ -59,7 +59,7 @@ unsubscribe();
 - `KeyPart`: `string | number | boolean`. Keys are arrays of parts (e.g. `["users", 42]`). Invalid keys raise at runtime.
 - `ExportRecord`: `{ c: string; d?: Value }` – CRDT payload with hybrid logical clock data.
 - `ExportBundle`: `Record<string, ExportRecord>` mapping composite keys to last-writer metadata.
-- `VersionVector`: `Record<string, { physicalTime: number; logicalCounter: number }>` indexed by hex peer identifiers.
+- `VersionVector`: `Record<string, { physicalTime: number; logicalCounter: number }>` indexed by peer identifiers (UTF-8 strings ordered by their byte representation).
 - `ScanRow`: `{ key: KeyPart[]; raw: ExportRecord; value?: Value }` returned by `scan()`.
 - `EventBatch`: `{ source: string; events: Array<{ key: KeyPart[]; value?: Value }> }` emitted to subscribers.
 
@@ -69,17 +69,17 @@ All types are exported from the package entry point for use in TypeScript projec
 
 ### Constructor
 
-`new Flock(peerId?: Uint8Array)` – creates a replica. When omitted, a random 256-bit peer id is generated. The id persists only in memory; persist it yourself for durable replicas.
+`new Flock(peerId?: string)` – creates a replica. When omitted, a random 64-character hex peer id is generated. The id persists only in memory; persist it yourself for durable replicas.
 
 ### Static Members
 
-- `Flock.fromJson(bundle: ExportBundle, peerId: Uint8Array): Flock` – instantiate directly from a full snapshot bundle.
+- `Flock.fromJson(bundle: ExportBundle, peerId: string): Flock` – instantiate directly from a full snapshot bundle.
 - `Flock.checkConsistency(a: Flock, b: Flock): boolean` – deep equality check useful for tests; returns `true` when both replicas expose the same key/value pairs and metadata.
 
 ### Replica Management
 
-- `setPeerId(peerId: Uint8Array): void` – replace the current peer id. Use cautiously; changing ids affects causality tracking.
-- `peerId(): Uint8Array` – returns the 32-byte identifier for the replica.
+- `setPeerId(peerId: string): void` – replace the current peer id. Use cautiously; changing ids affects causality tracking.
+- `peerId(): string` – returns the identifier for the replica.
 - `getMaxPhysicalTime(): number` – highest physical timestamp observed by this replica (same units as the timestamps you pass to `now`, e.g. `Date.now()` output). Helpful for synchronising clocks and diagnosing divergence.
 - `version(): VersionVector` – current version vector including logical counters per peer.
 - `checkInvariants(): void` – throws if internal CRDT invariants are violated. Intended for assertions in tests or diagnostics, not for production control flow.
@@ -109,7 +109,7 @@ All types are exported from the package entry point for use in TypeScript projec
 
 ### Events
 
-- `subscribe(listener: (batch: EventBatch) => void): () => void` – register for mutation batches. Each callback receives the `source` ("local" for writes on this replica, peer id for remote batches when available) and an ordered list of events. Return value unsubscribes the listener.
+- `subscribe(listener: (batch: EventBatch) => void): () => void` – register for mutation batches. Each callback receives the `source` ("local" for writes on this replica, peer id string for remote batches when available) and an ordered list of events. Return value unsubscribes the listener.
 
 ### Utilities