@brass-build/client 0.1.0 → 0.3.0

package/src/mutate-batching.ts

@@ -12,12 +12,17 @@
 // converges normally and stays one undo step.
 
 // A batch closes once the values assigned since the last commit reach
-// roughly this much JSON, which keeps each op in the tens of KB: an
-// encoded op runs close to the JSON length of its values, and base64 adds
-// a third. Budgeting on size rather than on a record count is what keeps
-// that true for narrow and wide records alike, so where it splits depends
-// on width (measured: ~800 spreadsheet cells, ~200 wider rows).
-export const MUTATE_BATCH_JSON_BUDGET_CHARS = 48 * 1024;
+// roughly this much JSON, so op size tracks the budget rather than the
+// mutation, for narrow and wide records alike.
+//
+// The budget answers to STORAGE, not to the socket: an op past the frame cap
+// takes the HTTP write, which carries about 190x a frame. What storage meters
+// is op COUNT (a seq allocation and HEAD update on the document's one
+// partition, plus an entry in the join's tail budget). Measured on a
+// 500,000-element write, 48 KB produces 526 ops and 512 KB produces 158, past
+// which the budget stops binding for that shape, while encode time stays flat
+// throughout: a smaller budget spends op count and buys nothing.
+export const MUTATE_BATCH_JSON_BUDGET_CHARS = 512 * 1024;
 
 /** Rough size of one assigned value. Runs on every assignment, so it only
  *  has to be proportional; an unserializable value counts as nominal
@@ -41,23 +46,67 @@ function approximateChars(value: unknown): number {
  */
 export class MutateBatcher {
   private _chars = 0;
+  // The record keys whose writes have landed since the last commit, handed to
+  // the flush so a caller with something to land BESIDE those records (an
+  // ordered map's order entries) can name exactly the ones this commit
+  // carries. A paged write assembles its whole overlay before it writes any of
+  // it, so the mutation's added keys are all known by the time the first
+  // commit comes round; without this the order list would be appended whole at
+  // that first commit, which is the oversized op the split exists to avoid.
+  private _keys: string[] = [];
+  // Run just before each commit. A paged write registers one here to seal
+  // the pages it has accumulated, so they ride the same commit rather than
+  // arriving after it.
+  private _before: (() => void) | null = null;
+
+  constructor(private readonly _flush: (keys: readonly string[]) => void) {}
 
-  constructor(private readonly _flush: () => void) {}
+  /** Register work to run immediately before every commit this batcher
+   *  takes, including the caller's final one via `flushNow`. */
+  onFlush(before: () => void): void {
+    this._before = before;
+  }
+
+  /** Name the record keys a write that has just landed covers. Called AFTER
+   *  the write, so a key is never named to a commit that precedes it. */
+  noteKeys(keys: Iterable<string>): void {
+    for (const key of keys) this._keys.push(key);
+  }
 
   /** Account for one assignment, from the proxy's set trap. */
   record(value: unknown): void {
-    const chars = approximateChars(value);
+    this.recordChars(approximateChars(value));
+  }
+
+  /** Account for a write whose caller already knows its size in the same
+   *  unit `record` charges, the UNCOMPRESSED JSON the write carries.
+   *
+   *  A page is stored gzipped, so charging the bytes it occupies would price
+   *  the same records about five times cheaper than the map path prices them,
+   *  and the same write would produce ops an order of magnitude apart
+   *  depending on whether the store was already paged when it arrived. The
+   *  budget answers for the records a commit carries, so a page charges what
+   *  it packs. */
+  recordChars(chars: number): void {
     // Commit BEFORE adding, so one assignment larger than the whole budget
     // lands in a batch of its own instead of dragging its neighbours over
     // the line with it.
     if (this._chars > 0 && this._chars + chars > MUTATE_BATCH_JSON_BUDGET_CHARS) {
-      this._flush();
+      this._before?.();
+      const keys = this._keys;
+      this._keys = [];
+      this._flush(keys);
       this._chars = 0;
     }
     this._chars += chars;
   }
 
-  recordDelete(): void {
-    this.record(null);
+  /** Account for one deletion. What a delete puts in the op is its KEY, so
+   *  that is what it costs: charging a flat nominal instead prices a bulk
+   *  delete at a fraction of the bytes it writes, and a store big enough to
+   *  page is big enough for the difference to carry the whole delete into one
+   *  op. */
+  recordDelete(key: string): void {
+    this.record(key);
   }
 }