@brass-build/client 0.3.0 → 0.4.1

package/dist/documents.js

@@ -8,7 +8,7 @@
 //   2. The `getOwnPropertyDescriptor` trap participates in
 //      `Object.keys`; doing `loroMap.keys().includes(key)` there makes
 //      `Object.keys()` O(N^2). It reads a single `loroMap.get(key)`.
-import { LoroDoc, LoroMap, VersionVector, decodeImportBlobMeta, } from 'loro-crdt';
+import { LoroDoc, LoroMap, VersionVector, decodeImportBlobMeta, } from './wasm-runtime.js';
 import { PAGING_COMMIT_ORIGIN, UndoController } from './undo.js';
 import { createOrderedMapHandle, createRootListHandle, createRootMapHandle, rebindRootListAnchor, rebindRootMapAnchor, resyncRootHandle, snapshotRootMapKeys, teardownRootHandle, } from './handles.js';
 import { flattenPagedLookup, isPagedMarker, META_KEY, pagedRootKey, } from './record-paging.js';
@@ -25,6 +25,31 @@ import { createEmitter } from './emitter.js';
 // The stream name `doc.stream()` resolves to the document's own default
 // state; mirrors the server's reserved name.
 export const DEFAULT_STREAM_NAME = 'default';
+// Loro names a container's type in its id (`cid:root-notes:Map`), so the kind
+// comes off the enumeration itself and costs no read. A type this package
+// cannot hand anyone a handle for, and cannot describe as text either, is
+// left out rather than guessed at, so every entry a reader gets is one they
+// can act on.
+function rootKindOf(containerId) {
+    const type = containerId.slice(containerId.lastIndexOf(':') + 1);
+    if (type === 'Map')
+        return 'map';
+    if (type === 'MovableList' || type === 'List')
+        return 'list';
+    if (type === 'Text')
+        return 'text';
+    return null;
+}
+// Maps count entries, lists and text count length. Both are the container's
+// own counter rather than a projection of what it holds.
+function rootIsEmpty(container) {
+    const sized = container;
+    if (typeof sized.size === 'number')
+        return sized.size === 0;
+    if (typeof sized.length === 'number')
+        return sized.length === 0;
+    return false;
+}
 // Commit-origin tags stamped on every locally-produced commit via Loro's
 // `setNextCommitOrigin`, so `origin.source` can be recovered off the
 // event. Stamping the commit (not a JS-side flag) survives a
@@ -52,6 +77,26 @@ function changeSourceOf(event) {
         return 'redo';
     return 'local';
 }
+// Whether a text container stores `value` unchanged. Loro's text is UTF-8, so
+// an unpaired surrogate is stored as U+FFFD and what the document holds is
+// not the string that was written. Scanned here rather than through
+// `String.prototype.isWellFormed`, which is younger than the browsers this
+// package runs in.
+function storedVerbatim(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        const unit = value.charCodeAt(i);
+        if (unit < 0xd800 || unit > 0xdfff)
+            continue;
+        // A trailing surrogate reached before its lead is unpaired by itself.
+        if (unit > 0xdbff)
+            return false;
+        i += 1;
+        const low = i < value.length ? value.charCodeAt(i) : 0;
+        if (low < 0xdc00 || low > 0xdfff)
+            return false;
+    }
+    return true;
+}
 // Per-chunk cap on a blob this Document pushes as several ops: a durability
 // resync's missing slice (`computeResyncPush`) and a local commit no write
 // budget bounded (`splitLocalUpdate`).
@@ -61,11 +106,10 @@ function changeSourceOf(event) {
 // the HTTP op write. Sizing the chunk to a WebSocket frame instead is what
 // makes a heal the most expensive write the SDK performs: the slice a bulk
 // write leaves behind is the whole document, and at frame size that is
-// thousands of ops, each one landing on the document's single storage
-// partition at exactly the size that stays inline on its row. Measured, a
-// 40 MB divergence healed in 16 KB chunks throttled the partition and left
-// the join a tail it refused to serve. The same divergence at this size is
-// tens of ops whose bytes go to the bucket instead.
+// thousands of ops written one after another against the same document.
+// Measured, a 40 MB divergence healed in 16 KB chunks overwhelmed that
+// document's write path and left the join a tail it refused to serve. The
+// same divergence at this size is tens of ops.
 const RESYNC_PUSH_MAX_BYTES = 512 * 1024;
 // Hard ceiling for a single irreducible op (one Loro op, unsplittable),
 // beyond which the chunk is skipped with a warning rather than retried
@@ -245,10 +289,11 @@ const READ_ONLY_MESSAGES = {
     app: 'Document is read-only: this app is not permitted to edit it.',
     unsaved: 'Document is read-only: a change could not be saved, so this copy holds ' +
         'work the platform does not. Brass is replacing it with the platform copy.',
+    capacity: 'Stream is read-only: it reached the largest size the platform can keep. ' +
+        'Reopen it to keep working from the saved state.',
+    no_connection: 'Document is read-only: it opened with no live connection, so a change ' +
+        'would stay on this device.',
 };
-// Public Document class. Wraps a LoroDoc; exposes mutate / subscribe /
-// toJSON / close. Construction is cheap: the Loro subscriber attaches
-// lazily (see `_ensureLoroSubscribed`).
 export class Document {
     _doc;
     _rootKey;
@@ -435,6 +480,11 @@ export class Document {
     // surfaces a terminally-rejected op here so a "could not be saved" outcome
     // reaches the app instead of being a silent forever-retry.
     _errorReporter = null;
+    // Set when this document was opened expecting a live transport that was not
+    // available. A write then changes local state and reaches no server, so the
+    // first one is reported rather than dropped in silence.
+    _transportExpected = false;
+    _transportUnavailableReported = false;
     _closed = false;
     // Set true when the Document is parked in the SDK's per-(docId, branchId)
     // cache after an app-level `close()`. The underlying LoroDoc, UndoController,
@@ -447,6 +497,14 @@ export class Document {
     // next session). `_resume()`
     // flips the flag back when the SDK hands the Doc to a new open() call.
     _suspended = false;
+    // How many times this instance has been handed to an open. The park cache
+    // hands the SAME Document back on a reopen, so "this document is open" is
+    // not one interval per instance and a per-instance mark cannot say which
+    // open it was made in. Anything that spends a once-per-open budget on a
+    // Document (the import runner's one attempt) records this alongside its
+    // mark and re-reads it, so a reopen is a new open rather than the old one
+    // continuing.
+    _openEpoch = 0;
     // Live = neither closed nor parked. This is the public-surface gate;
     // internal ingress (remote ops, status emits) deliberately checks
     // `_closed` alone, because a parked doc keeps applying remote state.
@@ -610,6 +668,126 @@ export class Document {
     // Built over the same `map(mapKey)` / `list(orderKey)` handles, so the
     // paged-store presentation and subscriptions carry through.
     _orderedMapHandles = new Map();
+    /**
+     * A handle on the top-level text container at `key`, which `roots()` reports
+     * as kind `'text'`.
+     *
+     * Cached per key, so `doc.text('x') === doc.text('x')` holds as it does for
+     * `doc.map`, and a subscriber registered through one keeps firing across a
+     * version checkout.
+     */
+    text(key) {
+        this._assertOpen();
+        const cacheKey = `text:${key}`;
+        const existing = this._rootHandles.get(cacheKey);
+        if (existing)
+            return existing.handle;
+        const owner = this._handleOwner;
+        const activeSource = () => this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        // Reads and writes resolve the active source per call, so a checkout
+        // needs no rebinding for them. A SUBSCRIPTION cannot work that way: it
+        // anchors a listener to one container, and a checkout preview is a
+        // different LoroDoc, so the anchor has to be moved. That is what makes
+        // this handle cached and registered like a map or a list, rather than a
+        // fresh object per call: the app holds the object the rebind reaches.
+        let anchor = activeSource().getText(key);
+        const subscribers = new Set();
+        let detach = null;
+        // The string this handle's own `update` has just written, armed only
+        // across the synchronous window in which `commit` fires the Loro
+        // subscriber. Materializing a text container is the one cost here that
+        // grows with a document's accumulated edit history rather than with its
+        // length, and `update` has already paid it once to diff against, so a
+        // fanout that materialized again would double the per-keystroke cost of
+        // exactly the field the README teaches. Anything else, a remote op or a
+        // checkout, finds it null and materializes.
+        let justWrote = null;
+        const fanout = (origin) => {
+            // Read for the local write alone. A change from any other source
+            // describes a container this handle did not write, so its value comes
+            // from the container even while a local write is arming one.
+            const value = (origin?.source === 'local' ? justWrote : null) ?? anchor.toString();
+            // Fired off a snapshot: a subscriber may unsubscribe (or register
+            // another) while it runs, and the set it is iterating is the one that
+            // changes underneath it.
+            const current = Array.from(subscribers);
+            for (const cb of current)
+                cb(value, origin);
+        };
+        const attach = () => {
+            if (detach !== null || subscribers.size === 0)
+                return;
+            detach = anchor.subscribe((event) => {
+                fanout({ source: owner.originOf(event) });
+            });
+        };
+        const handle = {
+            read: () => {
+                owner.assertReadable();
+                return activeSource().getText(key).toString();
+            },
+            update: (next) => {
+                owner.assertWritable();
+                owner.ensureLocalUpdatesSubscribed();
+                activeSource().getText(key).update(next);
+                // Armed after the write, so the container already holds `next` for
+                // every subscriber the commit reaches, and cleared however the
+                // commit returns: outside this window the fanout has no way to know
+                // the value is still current, and reads it. Armed only for a string
+                // the container holds verbatim, so a subscriber is never handed a
+                // value the document and its peers disagree with.
+                justWrote = storedVerbatim(next) ? next : null;
+                try {
+                    owner.commitMutate();
+                }
+                finally {
+                    justWrote = null;
+                }
+            },
+            subscribe: (cb) => {
+                owner.assertReadable();
+                subscribers.add(cb);
+                attach();
+                // No origin: a registration fire describes no authored transition,
+                // matching what a map subscriber's first fire carries.
+                cb(anchor.toString(), undefined);
+                return () => {
+                    subscribers.delete(cb);
+                    if (subscribers.size === 0 && detach !== null) {
+                        detach();
+                        detach = null;
+                    }
+                };
+            },
+            _rebind: (next) => {
+                if (detach !== null) {
+                    detach();
+                    detach = null;
+                }
+                anchor = next;
+                attach();
+            },
+            // A checkout or a return to head swaps the container rather than
+            // writing into it, so the catch-up fire carries no origin.
+            _resync: () => {
+                fanout(undefined);
+            },
+            // Detach the container subscription and forget the callbacks behind it,
+            // as a map or a list handle does: the Document drops its handle cache
+            // here, so an app still holding this one subscribes onto a handle
+            // nothing else reaches, and every callback registered before the park
+            // would come back with it.
+            _teardown: () => {
+                if (detach !== null) {
+                    detach();
+                    detach = null;
+                }
+                subscribers.clear();
+            },
+        };
+        this._rootHandles.set(cacheKey, { kind: 'text', key, handle });
+        return handle;
+    }
     orderedMap(mapKey, orderKey) {
         this._assertOpen();
         const cacheKey = `${mapKey}\u0000${orderKey}`;
@@ -1243,12 +1421,18 @@ export class Document {
             if (entry.kind === 'map') {
                 rebindRootMapAnchor(entry.handle, source.getMap(entry.key));
             }
-            else {
+            else if (entry.kind === 'list') {
                 rebindRootListAnchor(entry.handle, source.getMovableList(entry.key));
             }
+            else {
+                entry.handle._rebind(source.getText(entry.key));
+            }
         }
         for (const entry of this._rootHandles.values()) {
-            resyncRootHandle(entry.handle);
+            if (entry.kind === 'text')
+                entry.handle._resync();
+            else
+                resyncRootHandle(entry.handle);
         }
     }
     /**
@@ -1519,11 +1703,24 @@ export class Document {
             }
             const inner = await runtime.openLine(info.line_id);
             const stream = new DocumentStream(name, inner, true);
-            // Opened while a version preview is active: bring the new stream to
-            // the same point in time rather than showing it live under a
-            // historical default.
-            if (this._checkout !== null) {
-                await stream._previewAt(this._checkoutStreamSeqs?.[info.line_id], true);
+            try {
+                // Opened while a version preview is active: bring the new stream to
+                // the same point in time rather than showing it live under a
+                // historical default.
+                if (this._checkout !== null) {
+                    await stream._previewAt(this._checkoutStreamSeqs?.[info.line_id], true);
+                }
+            }
+            catch (err) {
+                // The line is joined and subscribed by now, and a rejected open is
+                // dropped from the cache so the next call opens a second one. Nothing
+                // else holds this Document, and nothing else would ever close it: the
+                // parent closes the streams it has, and a stream whose open failed is
+                // not one of them. So the failure disposes what it is abandoning,
+                // rather than leaving a line applying remote ops for the life of the
+                // page.
+                stream._close();
+                throw err;
             }
             return stream;
         })();
@@ -1714,6 +1911,37 @@ export class Document {
         this._errorReporter = reporter;
         this._commandMenu.setErrorReporter(reporter);
     }
+    // Called by the factory when a document is opened with no live transport,
+    // which outside tests means `wsBaseUrl` was left unset. Marking it is what
+    // separates that from the snapshot reads and test stubs that legitimately
+    // have no transport and must stay quiet.
+    /** @internal */
+    markTransportUnavailable() {
+        this._transportExpected = true;
+    }
+    // A write on such a document reaches nothing: local state changes, the
+    // reader sees their edit, and no server ever hears about it, so the edit is
+    // gone on the next open with no failure anywhere. This is what makes that
+    // observable. Once per document, because the condition holds for as long as
+    // the document is open and repeating it per keystroke buries it.
+    _reportTransportUnavailable() {
+        if (!this._transportExpected)
+            return;
+        if (this._transportUnavailableReported)
+            return;
+        this._transportUnavailableReported = true;
+        // Lock the document as well as reporting it. The write that reached this
+        // point stays local, exactly as `unsaved` describes for a refused one, so
+        // the same gate closes: an app that disables on `readOnly` stops offering
+        // an editor that cannot save, and a later `mutate` throws a sentence
+        // naming the reason instead of succeeding into nothing. The lock lands
+        // after this write's own gate has passed, so the first one still runs
+        // locally and only what follows it is refused.
+        this._markReadOnly('no_connection');
+        this._reportError(new Error('This document has no live connection, so edits stay on this device and ' +
+            'reach no one else. Pass wsBaseUrl to Brass.init alongside the other ' +
+            'base URLs: naming any one of them leaves wsBaseUrl unset.'));
+    }
     _reportError(err) {
         if (this._errorReporter)
             this._errorReporter(err);
@@ -1788,8 +2016,9 @@ export class Document {
      * reconnects, and under which correlator, which is what separates a
      * connection that is answering nothing from one that is merely behind.
      *
-     * @internal Telemetry for Brass's own surfaces. An app reads `savingCount`
-     * to know a save is outstanding, and the SDK resolves a stuck one itself.
+     * @internal Read on demand by Brass's own surfaces. An app reads
+     * `savingCount` to know a save is outstanding, and the SDK resolves a stuck
+     * one itself.
      */
     diagnostics() {
         const own = this._diagnosticsProvider?.() ?? {
@@ -1985,8 +2214,10 @@ export class Document {
     _ensureLocalUpdatesSubscribed() {
         if (this._unsubLocal)
             return;
-        if (!this._localOpHook)
+        if (!this._localOpHook) {
+            this._reportTransportUnavailable();
             return;
+        }
         // Loro's `subscribeLocalUpdates` fires after every local commit
         // with the op-blob bytes for that commit. Importing a remote op
         // does NOT trigger this callback, so we don't risk feeding the
@@ -2357,6 +2588,45 @@ export class Document {
         }
         this._gone.mark(reason);
     }
+    /**
+     * The top-level collections of the stream this document is open at, keyed
+     * as it keys them, each naming the kind of handle that reads it.
+     *
+     * A partitioned document keeps its collections per stream, so this is the
+     * open stream's answer rather than every stream's. `listStreams` names the
+     * rest, and `stream.roots()` asks one of them the same question.
+     *
+     * `map` / `list` are get-or-create, and taking the wrong kind for a key
+     * materializes a second container beside the real one, so read this before
+     * taking a handle on a key you are unsure of. A collection holding nothing
+     * is not listed, which is what keeps a handle taken but never written from
+     * appearing as one.
+     *
+     * The cost is the number of collections rather than the size of the
+     * document. In checkout, it describes the version being previewed.
+     */
+    roots() {
+        this._assertNotClosed();
+        const source = this._checkout !== null ? this._checkout.previewDoc : this._doc;
+        const found = [];
+        for (const [key, containerId] of Object.entries(source.getShallowValue())) {
+            const kind = rootKindOf(containerId);
+            if (kind === null)
+                continue;
+            // Reading the container's own count, rather than its value, is what
+            // keeps this off the projection: an empty collection is skipped without
+            // anything being decoded.
+            const container = source.getContainerById(containerId);
+            if (container === undefined || rootIsEmpty(container))
+                continue;
+            found.push([key, kind]);
+        }
+        // Loro reports roots in registration order, which is an accident of who
+        // wrote what first. Inserting in key order makes a reader's iteration
+        // stable across opens.
+        found.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        return Object.fromEntries(found);
+    }
     // Plain-JS projection of the current state.
     toJSON() {
         this._assertNotClosed();
@@ -2590,7 +2860,7 @@ export class Document {
     // undo step, so a bulk write that correctly split into many ops comes back
     // as one op the size of the entire write. Past `MAX_OP_BLOB_CHARS` that op
     // is refused outright and the redone edit never persists, and below it, it
-    // still lands as a single large row on the document's one storage partition.
+    // still lands as one very large write against the document.
     //
     // The ops already exist, so the only lever left is which spans they ship in.
     // The blob names the counter range it covers, and re-exporting a sub-range
@@ -2690,7 +2960,10 @@ export class Document {
         // the app's callback on a doc it has closed. Detaching first stops that;
         // fresh handles are minted on resume + next access.
         for (const entry of this._rootHandles.values()) {
-            teardownRootHandle(entry.handle);
+            if (entry.kind === 'text')
+                entry.handle._teardown();
+            else
+                teardownRootHandle(entry.handle);
         }
         this._rootHandles.clear();
         // Drop the ordered-map cache too. Each wrapper holds the specific root
@@ -2706,6 +2979,7 @@ export class Document {
     /** @internal */
     _resume() {
         this._suspended = false;
+        this._openEpoch += 1;
         this._setStreamsSuspended(false);
         // Pair of the `_suspend` presence gate: reopen the presence controller's
         // outbound path and re-advertise this client's cursor on the resumed open.
@@ -2722,6 +2996,12 @@ export class Document {
     get _isSuspended() {
         return this._suspended;
     }
+    /** @internal Which open this Document is currently in (see `_openEpoch`).
+     *  Read by anything holding a per-open mark on a Document, since a park hit
+     *  hands the same instance to the next open. */
+    get _openGeneration() {
+        return this._openEpoch;
+    }
     close() {
         if (this._closed)
             return;
@@ -2761,7 +3041,10 @@ export class Document {
         // per-container Loro subscription outlives the cache reference, and
         // `_doc.free()` must not run with subscriptions still attached.
         for (const entry of this._rootHandles.values()) {
-            teardownRootHandle(entry.handle);
+            if (entry.kind === 'text')
+                entry.handle._teardown();
+            else
+                teardownRootHandle(entry.handle);
         }
         this._rootHandles.clear();
         this._orderedMapHandles.clear();