@lazily-hub/lazily-js 0.20.0 → 0.21.0

package/BENCHMARKS.md

@@ -19,7 +19,7 @@ like-for-like single-process counterpart here and are intentionally omitted.
 
 <!-- benchmark-results:start -->
 
-Generated for package `@lazily-hub/lazily-js` version `0.19.0`.
+Generated for package `@lazily-hub/lazily-js` version `0.20.0`.
 
 Environment: Node.js `26.4.0` on `linux x64`.
 
@@ -33,16 +33,34 @@ Mean wall-clock time per iteration; 95% CI half-width from the standard error.
 
 | Group | Case | Mean | 95% CI | p75 | p99 | Samples |
 |---|---|---:|---:|---:|---:|---:|
-| cached_reads | context | 31.707 ns | ± 1.826 ns | 29.867 ns | 78.222 ns | 100 |
-| cold_first_get | context | 698.810 ns | ± 46.591 ns | 600.000 ns | 1.410 us | 100 |
-| dependency_fan_out | context / 32 | 5.263 us | ± 858.863 ns | 4.753 us | 16.289 us | 100 |
-| dependency_fan_out | context / 256 | 47.575 us | ± 3.908 us | 45.595 us | 132.218 us | 100 |
-| set_cell_invalidation | high_fan_out / 512 | 6.692 us | ± 3.311 us | 5.840 us | 111.143 us | 100 |
-| memo_equality_suppression | context | 2.546 us | ± 256.417 ns | 2.553 us | 5.435 us | 100 |
-| effect_flushing | context | 129.166 ns | ± 11.208 ns | 131.217 ns | 406.377 ns | 100 |
-| batch_storms | context / 64 | 12.092 us | ± 123.522 ns | 12.286 us | 14.168 us | 100 |
-| typed_cache_reads | context_cell | 33.701 ns | ± 2.005 ns | 32.755 ns | 55.480 ns | 100 |
-| typed_cache_reads | context_slot | 42.440 ns | ± 2.855 ns | 40.074 ns | 106.268 ns | 100 |
+| cached_reads | context | 31.966 ns | ± 1.575 ns | 30.743 ns | 70.839 ns | 100 |
+| cold_first_get | context | 742.710 ns | ± 126.218 ns | 612.500 ns | 1.899 us | 100 |
+| dependency_fan_out | context / 32 | 6.129 us | ± 1.563 us | 5.023 us | 41.656 us | 100 |
+| dependency_fan_out | context / 256 | 48.997 us | ± 3.461 us | 47.868 us | 130.607 us | 100 |
+| set_cell_invalidation | high_fan_out / 512 | 5.482 us | ± 1.327 us | 6.410 us | 18.184 us | 100 |
+| memo_equality_suppression | context | 2.191 us | ± 356.052 ns | 3.813 us | 4.961 us | 100 |
+| effect_flushing | context | 149.841 ns | ± 15.108 ns | 148.815 ns | 452.666 ns | 100 |
+| batch_storms | context / 64 | 13.088 us | ± 281.500 ns | 13.352 us | 17.526 us | 100 |
+| typed_cache_reads | context_cell | 29.928 ns | ± 0.847 ns | 29.585 ns | 46.606 ns | 100 |
+| typed_cache_reads | context_slot | 46.437 ns | ± 5.381 ns | 39.915 ns | 179.573 ns | 100 |
+| textcrdt_insert_str | 64 | 8.939 us | ± 2.581 us | 7.678 us | 50.727 us | 100 |
+| textcrdt_insert_str | 256 | 28.383 us | ± 1.991 us | 25.568 us | 63.137 us | 100 |
+| textcrdt_insert_str | 1024 | 111.611 us | ± 6.489 us | 124.136 us | 205.387 us | 100 |
+| textcrdt_repeated_text | 64 | 40.149 us | ± 2.146 us | 36.146 us | 74.301 us | 100 |
+| textcrdt_repeated_text | 256 | 181.856 us | ± 13.068 us | 187.465 us | 331.261 us | 100 |
+| textcrdt_repeated_text | 1024 | 864.585 us | ± 45.266 us | 996.343 us | 1.519 ms | 100 |
+| textcrdt_merge | 64 | 12.103 us | ± 798.827 ns | 12.955 us | 24.361 us | 100 |
+| textcrdt_merge | 256 | 53.192 us | ± 4.002 us | 52.265 us | 143.726 us | 100 |
+| textcrdt_merge | 1024 | 270.364 us | ± 17.669 us | 268.422 us | 593.144 us | 100 |
+| textcrdt_delta_sync | 64 | 19.106 us | ± 1.372 us | 20.792 us | 29.232 us | 100 |
+| textcrdt_delta_sync | 256 | 67.860 us | ± 5.469 us | 62.273 us | 196.534 us | 100 |
+| textcrdt_delta_sync | 1024 | 262.078 us | ± 11.701 us | 257.410 us | 473.407 us | 100 |
+| seqcrdt_insert_back | 64 | 82.803 us | ± 7.276 us | 79.240 us | 226.953 us | 100 |
+| seqcrdt_insert_back | 256 | 1.561 ms | ± 57.393 us | 1.724 ms | 2.313 ms | 100 |
+| seqcrdt_insert_back | 1024 | 43.643 ms | ± 971.721 us | 44.688 ms | 50.468 ms | 20 |
+| seqcrdt_merge | 64 | 7.361 us | ± 624.875 ns | 8.053 us | 19.173 us | 100 |
+| seqcrdt_merge | 256 | 26.977 us | ± 2.251 us | 30.373 us | 73.848 us | 100 |
+| seqcrdt_merge | 1024 | 113.428 us | ± 6.981 us | 121.168 us | 252.144 us | 100 |
 
 <!-- benchmark-results:end -->
 

package/bench/crdt.bench.mjs

@@ -0,0 +1,129 @@
+// CRDT-plane benchmarks for lazily-js — TextCrdt and SeqCrdt hot paths.
+//
+// The reactive-core benches (`context.bench.mjs`) do not cover the CRDT plane;
+// the Phase 1 plan (#lztextordcache, #lztextinsertchain, #lzopidkeytuple,
+// #lzseqstringifyeq) needed a baseline + regression target. Mirrors the
+// `bench/harness.mjs` criterion-style API used by `context.bench.mjs` so the
+// output table is directly comparable.
+//
+// Run: `node bench/crdt.bench.mjs`
+
+import { bench, blackBox, run } from "./harness.mjs";
+import { TextCrdt } from "../src/text-crdt.js";
+import { SeqCrdt } from "../src/seq-crdt.js";
+
+const INSERT_STR_SIZES = [64, 256, 1024];
+const REPEATED_READ_ITERS = 100;
+
+// --- TextCrdt: bulk insertStr (#lztextinsertchain is the main lever) -------
+for (const size of INSERT_STR_SIZES) {
+  const payload = "a".repeat(size);
+  bench.batched(
+    "textcrdt_insert_str",
+    `${size}`,
+    () => new TextCrdt(1),
+    (crdt) => {
+      crdt.insertStr(0, payload);
+      blackBox(crdt.len());
+    },
+  );
+}
+
+// --- TextCrdt: repeated text() reads between mutations (#lztextordcache) ---
+// One mutation, then N reads. Pre-cache this should be O(N log N) per read;
+// post-cache it is O(1) per read after the first.
+for (const size of INSERT_STR_SIZES) {
+  const payload = "a".repeat(size);
+  bench.batched(
+    "textcrdt_repeated_text",
+    `${size}`,
+    () => {
+      const crdt = new TextCrdt(1);
+      crdt.insertStr(0, payload);
+      return crdt;
+    },
+    (crdt) => {
+      let last = "";
+      for (let i = 0; i < REPEATED_READ_ITERS; i++) {
+        last = crdt.text();
+      }
+      blackBox(last);
+    },
+  );
+}
+
+// --- TextCrdt: state-based merge ------------------------------------------
+// Two peers each insert N chars; merge b into a.
+for (const size of INSERT_STR_SIZES) {
+  bench.batched(
+    "textcrdt_merge",
+    `${size}`,
+    () => {
+      const a = new TextCrdt(1);
+      const b = new TextCrdt(2);
+      a.insertStr(0, "a".repeat(size));
+      b.insertStr(0, "b".repeat(size));
+      return { a, b };
+    },
+    ({ a, b }) => {
+      blackBox(a.merge(b));
+    },
+  );
+}
+
+// --- TextCrdt: delta sync round-trip --------------------------------------
+for (const size of INSERT_STR_SIZES) {
+  bench.batched(
+    "textcrdt_delta_sync",
+    `${size}`,
+    () => {
+      const a = new TextCrdt(1);
+      a.insertStr(0, "a".repeat(size));
+      const b = new TextCrdt(2);
+      return { a, b };
+    },
+    ({ a, b }) => {
+      const delta = a.deltaSince({});
+      blackBox(b.applyDelta(delta));
+    },
+  );
+}
+
+// --- SeqCrdt: bulk insertBack ---------------------------------------------
+for (const size of INSERT_STR_SIZES) {
+  bench.batched(
+    "seqcrdt_insert_back",
+    `${size}`,
+    () => new SeqCrdt(1),
+    (crdt) => {
+      for (let i = 0; i < size; i++) {
+        crdt.insertBack(`id${i}`, i, i + 1);
+      }
+      blackBox(crdt.entryCount());
+    },
+  );
+}
+
+// --- SeqCrdt: merge with primitive values (#lzseqstringifyeq) -------------
+for (const size of INSERT_STR_SIZES) {
+  bench.batched(
+    "seqcrdt_merge",
+    `${size}`,
+    () => {
+      const a = new SeqCrdt(1);
+      const b = new SeqCrdt(2);
+      for (let i = 0; i < size; i++) {
+        a.insertBack(`a${i}`, i, i + 1);
+        b.insertBack(`b${i}`, i * 10, i + 1);
+      }
+      return { a, b };
+    },
+    ({ a, b }) => {
+      blackBox(a.merge(b, Date.now() * 1000));
+    },
+  );
+}
+
+await run({
+  format: process.env.BENCH_FORMAT === "json" ? "json" : "markdown",
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), sync/async/thread-safe keyed reactive maps (ReactiveMap/CellMap/SlotMap), the lazily-spec IPC wire types + C-ABI FFI boundary (isomorphic channel + Node native binding), keyed cell collections + LIS reconciliation, the memoized semantic tree, the move-aware sequence CRDT, the Fugue/RGA text CRDT, manufactured text identity, full-Harel state charts, an FFI state-projection consumer, and an in-library instrumentation/benchmark API.",
   "license": "MIT",
   "repository": {

package/src/seq-crdt.js

@@ -93,6 +93,13 @@ export class LwwRegister {
   }
 }
 
+// Structural deep equality (#lzseqstringifyeq): replaces JSON.stringify-based
+// comparison (one of V8's slowest paths) with a typed dispatch that handles the
+// common cases — primitives, Position, arrays, plain objects — without
+// allocating a serialized string per side per comparison. Behavior is
+// equivalent to JSON.stringify equality for plain JSON values, while skipping
+// JSON's NaN/Infinity/null coercion and toJSON dispatch (neither is exercised
+// by the values stored in SeqCrdt registers today).
 function valuesEqual(a, b) {
   if (a === b) {
     return true;
@@ -103,7 +110,32 @@ function valuesEqual(a, b) {
   if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
     return a === b;
   }
-  return JSON.stringify(a) === JSON.stringify(b);
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+      return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+      if (!valuesEqual(a[i], b[i])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) {
+    return false;
+  }
+  for (let i = 0; i < ka.length; i++) {
+    const k = ka[i];
+    if (!Object.prototype.hasOwnProperty.call(b, k)) {
+      return false;
+    }
+    if (!valuesEqual(a[k], b[k])) {
+      return false;
+    }
+  }
+  return true;
 }
 
 // Position: fractional-index byte key + originating peer.

package/src/text-crdt.js

@@ -12,6 +12,10 @@ export class OpId {
   constructor(counter, peer) {
     this.counter = counter;
     this.peer = peer;
+    // Cached string key — avoids per-lookup allocation across the lifetime of
+    // an OpId (#lzopidkeytuple). Set before freeze so the field is immutable
+    // alongside the rest of the instance.
+    this._key = `${counter}:${peer}`;
     Object.freeze(this);
   }
   compareTo(other) {
@@ -29,7 +33,10 @@ export class OpId {
 }
 
 class Elem {
-  constructor(ch, origin, deleted = null) {
+  // `id` is stored on the Elem so iteration over the map values can recover
+  // the OpId without re-parsing the string key (#lzopidkeytuple).
+  constructor(id, ch, origin, deleted = null) {
+    this.id = id; // OpId
     this.ch = ch;
     this.origin = origin; // OpId | null (null = document start)
     this.deleted = deleted; // OpId | null (the delete op id, or null = live)
@@ -37,9 +44,16 @@ class Elem {
 }
 
 export class TextCrdt {
-  #elems = new Map(); // OpId-keyed (serialized as "counter:peer")
+  // String-keyed map (OpId._key -> Elem). The string is cached on each OpId at
+  // construction so this is a hash lookup with zero per-op allocation.
+  #elems = new Map();
   #peer;
   #counter = 0;
+  // Cached visible orderings (#lztextordcache). Both are invalidated by every
+  // mutation; populated lazily on the next read. Repeated `text()` between
+  // mutations is O(1) instead of O(N log N).
+  #orderedLiveCache = null; // OpId[] | null (excludes tombstones)
+  #orderedAllCache = null; // OpId[] | null (includes tombstones)
 
   constructor(peer) {
     this.#peer = peer;
@@ -55,8 +69,9 @@ export class TextCrdt {
   fork(peer) {
     const copy = new TextCrdt(peer);
     copy.#counter = this.#counter;
-    for (const [key, elem] of this.#elems) {
-      copy.#elems.set(key, new Elem(elem.ch, elem.origin, elem.deleted));
+    for (const elem of this.#elems.values()) {
+      const e = new Elem(elem.id, elem.ch, elem.origin, elem.deleted);
+      copy.#elems.set(e.id._key, e);
     }
     return copy;
   }
@@ -70,22 +85,30 @@ export class TextCrdt {
     return new OpId(this.#counter, this.#peer);
   }
 
-  #key(id) {
-    return `${id.counter}:${id.peer}`;
+  #invalidateOrdered() {
+    this.#orderedLiveCache = null;
+    this.#orderedAllCache = null;
   }
 
   #orderedIds(includeDeleted) {
-    // Group by origin.
-    const children = new Map(); // originKey -> OpId[]
-    for (const [key, elem] of this.#elems) {
-      const originKey = elem.origin ? this.#key(elem.origin) : "<root>";
+    // Cache hit (#lztextordcache).
+    if (includeDeleted) {
+      if (this.#orderedAllCache !== null) return this.#orderedAllCache;
+    } else {
+      if (this.#orderedLiveCache !== null) return this.#orderedLiveCache;
+    }
+
+    // Group by origin. Keys are origin._key (or "<root>"); values are OpId[]
+    // recovered directly from Elem.id — no string parse (#lzopidkeytuple).
+    const children = new Map();
+    for (const elem of this.#elems.values()) {
+      const originKey = elem.origin ? elem.origin._key : "<root>";
       let list = children.get(originKey);
       if (!list) {
         list = [];
         children.set(originKey, list);
       }
-      // Recover the OpId from the map iteration key is not stored, so store it.
-      list.push(this.#idFromKey(key));
+      list.push(elem.id);
     }
     // Sort each sibling list DESCENDING by OpId.
     for (const list of children.values()) {
@@ -97,14 +120,14 @@ export class TextCrdt {
     const stack = [...roots].sort(OpId.desc); // highest pops first
     while (stack.length > 0) {
       const id = stack.pop();
-      const elem = this.#elems.get(this.#key(id));
+      const elem = this.#elems.get(id._key);
       if (!elem) {
         continue;
       }
       if (includeDeleted || elem.deleted === null) {
         out.push(id);
       }
-      const kids = children.get(this.#key(id));
+      const kids = children.get(id._key);
       if (kids) {
         // Push reversed so the highest-OpId child pops first.
         for (let i = kids.length - 1; i >= 0; i--) {
@@ -112,26 +135,36 @@ export class TextCrdt {
         }
       }
     }
+    if (includeDeleted) {
+      this.#orderedAllCache = out;
+    } else {
+      this.#orderedLiveCache = out;
+    }
     return out;
   }
 
-  #idFromKey(key) {
-    const [counter, peer] = key.split(":");
-    return new OpId(Number(counter), Number(peer));
-  }
-
   insert(index, ch) {
     const visible = this.#orderedIds(false);
     const origin = index === 0 ? null : visible[index - 1] ?? null;
     const id = this.#nextId();
-    this.#elems.set(this.#key(id), new Elem(ch, origin, null));
+    this.#invalidateOrdered();
+    this.#elems.set(id._key, new Elem(id, ch, origin, null));
   }
 
+  // Bulk insert with origin chaining (#lztextinsertchain): one `orderedIds()`
+  // pass + N chain appends instead of N full-tree rebuilds. Sequential chars
+  // chain naturally — char i+1's left-origin is char i's just-minted OpId —
+  // so the DFS visits them in chain order (counter strictly increases under
+  // one peer). Concurrent inserts at the same point still sort by the peer
+  // tiebreak, preserving the standard CRDT convergence contract.
   insertStr(index, str) {
-    let i = 0;
+    const visible = this.#orderedIds(false);
+    let origin = index === 0 ? null : visible[index - 1] ?? null;
+    this.#invalidateOrdered();
     for (const ch of String(str)) {
-      this.insert(index + i, ch);
-      i++;
+      const id = this.#nextId();
+      this.#elems.set(id._key, new Elem(id, ch, origin, null));
+      origin = id; // chain: next char's left-origin is this id
     }
   }
 
@@ -142,16 +175,18 @@ export class TextCrdt {
       return; // no-op if out of range
     }
     const del = this.#nextId(); // always advance the clock (matches lazily-rs)
-    const elem = this.#elems.get(this.#key(id));
+    const elem = this.#elems.get(id._key);
     if (elem && elem.deleted === null) {
+      this.#invalidateOrdered();
       elem.deleted = del;
     }
   }
 
   text() {
+    const ordered = this.#orderedIds(false);
     let out = "";
-    for (const id of this.#orderedIds(false)) {
-      out += this.#elems.get(this.#key(id)).ch;
+    for (const id of ordered) {
+      out += this.#elems.get(id._key).ch;
     }
     return out;
   }
@@ -190,26 +225,38 @@ export class TextCrdt {
   // the smaller delete id. Returns whether visible text changed.
   merge(other) {
     const before = this.text();
-    for (const [key, oe] of other.#elems) {
-      const id = other.#idFromKey(key);
-      this.#counter = Math.max(this.#counter, id.counter);
+    let anyChange = false;
+    for (const oe of other.#elems.values()) {
+      this.#counter = Math.max(this.#counter, oe.id.counter);
       if (oe.deleted) {
         this.#counter = Math.max(this.#counter, oe.deleted.counter);
       }
-      const existing = this.#elems.get(key);
+      const existing = this.#elems.get(oe.id._key);
       if (existing) {
         if (existing.deleted && oe.deleted) {
-          existing.deleted =
+          const merged =
             existing.deleted.compareTo(oe.deleted) <= 0
               ? existing.deleted
               : oe.deleted;
-        } else if (oe.deleted) {
+          if (merged !== existing.deleted) {
+            existing.deleted = merged;
+            anyChange = true;
+          }
+        } else if (oe.deleted && existing.deleted === null) {
           existing.deleted = oe.deleted;
+          anyChange = true;
         }
       } else {
-        this.#elems.set(key, new Elem(oe.ch, oe.origin, oe.deleted));
+        // Adopt the elem with its existing OpId identity so later concurrent
+        // edits merge without duplication.
+        const adopted = new Elem(oe.id, oe.ch, oe.origin, oe.deleted);
+        this.#elems.set(oe.id._key, adopted);
+        anyChange = true;
       }
     }
+    if (anyChange) {
+      this.#invalidateOrdered();
+    }
     return this.text() !== before;
   }
 
@@ -234,7 +281,7 @@ export class TextCrdt {
       const referenced = new Set();
       for (const elem of this.#elems.values()) {
         if (elem.origin) {
-          referenced.add(this.#key(elem.origin));
+          referenced.add(elem.origin._key);
         }
       }
       const collectable = [];
@@ -251,6 +298,9 @@ export class TextCrdt {
         removed++;
       }
     }
+    if (removed > 0) {
+      this.#invalidateOrdered();
+    }
     return removed;
   }
 
@@ -260,13 +310,11 @@ export class TextCrdt {
   // compact frontier a replica sends so a partner can compute the ops it lacks.
   versionVector() {
     const vv = {};
-    const bump = (id) => {
+    for (const elem of this.#elems.values()) {
+      const id = elem.id;
       vv[id.peer] = Math.max(vv[id.peer] ?? 0, id.counter);
-    };
-    for (const [key, elem] of this.#elems) {
-      bump(this.#idFromKey(key));
       if (elem.deleted) {
-        bump(elem.deleted);
+        vv[elem.deleted.peer] = Math.max(vv[elem.deleted.peer] ?? 0, elem.deleted.counter);
       }
     }
     return vv;
@@ -279,8 +327,8 @@ export class TextCrdt {
     const seen = (id) => id.counter <= (theirVv[id.peer] ?? 0);
     const wire = (id) => (id ? { counter: id.counter, peer: id.peer } : null);
     const out = [];
-    for (const [key, elem] of this.#elems) {
-      const id = this.#idFromKey(key);
+    for (const elem of this.#elems.values()) {
+      const id = elem.id;
       const insertNew = !seen(id);
       const deleteNew = elem.deleted !== null && !seen(elem.deleted);
       if (insertNew || deleteNew) {
@@ -301,6 +349,7 @@ export class TextCrdt {
   // concurrent edits merge without duplication. Returns whether text changed.
   applyDelta(ops) {
     const before = this.text();
+    let anyChange = false;
     for (const op of ops) {
       const id = new OpId(op.id.counter, op.id.peer);
       const origin = op.origin ? new OpId(op.origin.counter, op.origin.peer) : null;
@@ -309,19 +358,27 @@ export class TextCrdt {
       if (deleted) {
         this.#counter = Math.max(this.#counter, deleted.counter);
       }
-      const key = this.#key(id);
-      const existing = this.#elems.get(key);
+      const existing = this.#elems.get(id._key);
       if (existing) {
         if (existing.deleted && deleted) {
-          existing.deleted =
+          const merged =
             existing.deleted.compareTo(deleted) <= 0 ? existing.deleted : deleted;
-        } else if (deleted) {
+          if (merged !== existing.deleted) {
+            existing.deleted = merged;
+            anyChange = true;
+          }
+        } else if (deleted && existing.deleted === null) {
           existing.deleted = deleted;
+          anyChange = true;
         }
       } else {
-        this.#elems.set(key, new Elem(op.ch, origin, deleted));
+        this.#elems.set(id._key, new Elem(id, op.ch, origin, deleted));
+        anyChange = true;
       }
     }
+    if (anyChange) {
+      this.#invalidateOrdered();
+    }
     return this.text() !== before;
   }
 }