@automerge/automerge-repo 2.0.0-alpha.22 → 2.0.0-alpha.26

package/README.md

@@ -232,14 +232,14 @@ Now import it and add it to your list of network adapters:
 
 ```ts
 // main.tsx
-import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket" // <-- add this line
+import { WebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket" // <-- add this line
 
 // ...
 
 const repo = new Repo({
   network: [
     new BroadcastChannelNetworkAdapter(),
-    new BrowserWebSocketClientAdapter("ws://localhost:3030"), // <-- add this line
+    new WebSocketClientAdapter("ws://localhost:3030"), // <-- add this line
   ],
   storage: new IndexedDBStorageAdapter(),
 })
@@ -261,3 +261,4 @@ With gratitude for contributions by:
 - Jeremy Rose
 - Alex Currie-Clark
 - Dylan Mackenzie
+- Maciek Sakrejda

package/dist/DocHandle.d.ts

@@ -64,15 +64,6 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      * checking `inState()`.
      */
     whenReady(awaitStates?: HandleState[]): Promise<void>;
-    /**
-     * @returns the current state of this handle's Automerge document.
-     *
-     * This is the recommended way to access a handle's document. Note that this waits for the handle
-     * to be ready if necessary. If loading (or synchronization) fails, this will never resolve.
-     */
-    legacyAsyncDoc(
-    /** states to wait for, such as "LOADING". mostly for internal use. */
-    awaitStates?: HandleState[]): Promise<A.Doc<T> | undefined>;
     /**
      * Returns the current state of the Automerge document this handle manages.
      *
@@ -159,7 +150,7 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      */
     doneLoading(): void;
     /**
-     * Called by the repo either when a doc handle changes or we receive new remote heads.
+     * Called by the repo when a doc handle changes or we receive new remote heads.
      * @hidden
      */
     setRemoteHeads(storageId: StorageId, heads: UrlHeads): void;
@@ -199,11 +190,12 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     /** the handle of the document to merge into this one */
     otherHandle: DocHandle<T>): void;
     /**
-     * Used in testing to mark this document as unavailable.
+     * Updates the internal state machine to mark the document unavailable.
      * @hidden
      */
     unavailable(): void;
-    /** Called by the repo when the document is not found in storage.
+    /**
+     * Called by the repo either when the document is not found in storage.
      * @hidden
      * */
     request(): void;

package/dist/DocHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}

package/dist/DocHandle.js

@@ -33,6 +33,8 @@ export class DocHandle extends EventEmitter {
     #timeoutDelay = 60_000;
     /** A dictionary mapping each peer to the last heads we know they have. */
     #remoteHeads = {};
+    /** Cache for view handles, keyed by the stringified heads */
+    #viewCache = new Map();
     /** @hidden */
     constructor(documentId, options = {}) {
         super();
@@ -228,26 +230,6 @@ export class DocHandle extends EventEmitter {
     async whenReady(awaitStates = ["ready"]) {
         await withTimeout(this.#statePromise(awaitStates), this.#timeoutDelay);
     }
-    /**
-     * @returns the current state of this handle's Automerge document.
-     *
-     * This is the recommended way to access a handle's document. Note that this waits for the handle
-     * to be ready if necessary. If loading (or synchronization) fails, this will never resolve.
-     */
-    async legacyAsyncDoc(
-    /** states to wait for, such as "LOADING". mostly for internal use. */
-    awaitStates = ["ready", "unavailable"]) {
-        try {
-            // wait for the document to enter one of the desired states
-            await this.#statePromise(awaitStates);
-        }
-        catch (error) {
-            // if we timed out, return undefined
-            return undefined;
-        }
-        // Return the document
-        return !this.isUnavailable() ? this.#doc : undefined;
-    }
     /**
      * Returns the current state of the Automerge document this handle manages.
      *
@@ -322,6 +304,13 @@ export class DocHandle extends EventEmitter {
         if (!this.isReady()) {
             throw new Error(`DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling view().`);
         }
+        // Create a cache key from the heads
+        const cacheKey = JSON.stringify(heads);
+        // Check if we have a cached handle for these heads
+        const cachedHandle = this.#viewCache.get(cacheKey);
+        if (cachedHandle) {
+            return cachedHandle;
+        }
         // Create a new handle with the same documentId but fixed heads
         const handle = new DocHandle(this.documentId, {
             heads,
@@ -329,6 +318,8 @@ export class DocHandle extends EventEmitter {
         });
         handle.update(() => A.clone(this.#doc));
         handle.doneLoading();
+        // Store in cache
+        this.#viewCache.set(cacheKey, handle);
         return handle;
     }
     /**
@@ -409,7 +400,7 @@ export class DocHandle extends EventEmitter {
         this.#machine.send({ type: DOC_READY });
     }
     /**
-     * Called by the repo either when a doc handle changes or we receive new remote heads.
+     * Called by the repo when a doc handle changes or we receive new remote heads.
      * @hidden
      */
     setRemoteHeads(storageId, heads) {
@@ -498,13 +489,14 @@ export class DocHandle extends EventEmitter {
         });
     }
     /**
-     * Used in testing to mark this document as unavailable.
+     * Updates the internal state machine to mark the document unavailable.
      * @hidden
      */
     unavailable() {
         this.#machine.send({ type: DOC_UNAVAILABLE });
     }
-    /** Called by the repo when the document is not found in storage.
+    /**
+     * Called by the repo either when the document is not found in storage.
      * @hidden
      * */
     request() {
@@ -533,7 +525,7 @@ export class DocHandle extends EventEmitter {
     broadcast(message) {
         this.emit("ephemeral-message-outbound", {
             handle: this,
-            data: encode(message),
+            data: new Uint8Array(encode(message)),
         });
     }
     metrics() {

package/dist/storage/StorageSubsystem.d.ts

@@ -39,6 +39,10 @@ export declare class StorageSubsystem extends EventEmitter<StorageSubsystemEvent
     namespace: string, 
     /** Key to remove. Typically a UUID or other unique identifier, but could be any string. */
     key: string): Promise<void>;
+    /**
+     * Loads and combines document chunks from storage, with snapshots first.
+     */
+    loadDocData(documentId: DocumentId): Promise<Uint8Array | null>;
     /**
      * Loads the Automerge document with the given ID from storage.
      */

package/dist/storage/StorageSubsystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAInD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,KAAK,sBAAsB,GAAG;IAC5B,iBAAiB,EAAE,CAAC,GAAG,EAAE;QACvB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,IAAI,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAe5D,cAAc,EAAE,uBAAuB;IAK7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA0ClE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IAkEhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAW7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}
+{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAInD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAG7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,KAAK,sBAAsB,GAAG;IAC5B,iBAAiB,EAAE,CAAC,GAAG,EAAE;QACvB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,IAAI,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAe5D,cAAc,EAAE,uBAAuB;IAK7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAgDrE;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAqBlE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAezE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IAkEhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAW7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}

package/dist/storage/StorageSubsystem.js

@@ -3,7 +3,6 @@ import debug from "debug";
 import { headsAreSame } from "../helpers/headsAreSame.js";
 import { mergeArrays } from "../helpers/mergeArrays.js";
 import { keyHash, headsHash } from "./keyHash.js";
-import { chunkTypeFromKey } from "./chunkTypeFromKey.js";
 import * as Uuid from "uuid";
 import { EventEmitter } from "eventemitter3";
 import { encodeHeads } from "../AutomergeUrl.js";
@@ -76,31 +75,58 @@ export class StorageSubsystem extends EventEmitter {
     }
     // AUTOMERGE DOCUMENT STORAGE
     /**
-     * Loads the Automerge document with the given ID from storage.
+     * Loads and combines document chunks from storage, with snapshots first.
      */
-    async loadDoc(documentId) {
-        // Load all the chunks for this document
-        const chunks = await this.#storageAdapter.loadRange([documentId]);
+    async loadDocData(documentId) {
+        // Load snapshots first
+        const snapshotChunks = await this.#storageAdapter.loadRange([
+            documentId,
+            "snapshot",
+        ]);
+        const incrementalChunks = await this.#storageAdapter.loadRange([
+            documentId,
+            "incremental",
+        ]);
         const binaries = [];
         const chunkInfos = [];
-        for (const chunk of chunks) {
-            // chunks might have been deleted in the interim
+        // Process snapshots first
+        for (const chunk of snapshotChunks) {
             if (chunk.data === undefined)
                 continue;
-            const chunkType = chunkTypeFromKey(chunk.key);
-            if (chunkType == null)
+            chunkInfos.push({
+                key: chunk.key,
+                type: "snapshot",
+                size: chunk.data.length,
+            });
+            binaries.push(chunk.data);
+        }
+        // Then process incrementals
+        for (const chunk of incrementalChunks) {
+            if (chunk.data === undefined)
                 continue;
             chunkInfos.push({
                 key: chunk.key,
-                type: chunkType,
+                type: "incremental",
                 size: chunk.data.length,
             });
             binaries.push(chunk.data);
         }
+        // Store chunk infos for future reference
         this.#chunkInfos.set(documentId, chunkInfos);
+        // If no chunks were found, return null
+        if (binaries.length === 0) {
+            return null;
+        }
         // Merge the chunks into a single binary
-        const binary = mergeArrays(binaries);
-        if (binary.length === 0)
+        return mergeArrays(binaries);
+    }
+    /**
+     * Loads the Automerge document with the given ID from storage.
+     */
+    async loadDoc(documentId) {
+        // Load and combine chunks
+        const binary = await this.loadDocData(documentId);
+        if (!binary)
             return null;
         // Load into an Automerge document
         const start = performance.now();

package/dist/synchronizer/DocSynchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAGnD,OAAO,EACL,SAAS,EAKV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,gBAAgB,EAEhB,WAAW,EACX,cAAc,EACd,WAAW,EAEZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD,KAAK,kBAAkB,GAAG,SAAS,GAAG,KAAK,GAAG,aAAa,GAAG,OAAO,CAAA;AAOrE,UAAU,qBAAqB;IAC7B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAE/C,gBAAgB,SAAM;gBAyBV,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,qBAAqB;IA0BtE,IAAI,UAAU,uCAEb;IAED,IAAI,UAAU,qCAEb;IAiID,OAAO,CAAC,MAAM,EAAE,MAAM;IAIhB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IAwDjC,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,cAAc,CAAC,OAAO,EAAE,WAAW;IAkBnC,uBAAuB,CAAC,OAAO,EAAE,gBAAgB;IAuBjD,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc;IAwFxD,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAM7E"}
+{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAGnD,OAAO,EACL,SAAS,EAKV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,gBAAgB,EAEhB,WAAW,EACX,cAAc,EACd,WAAW,EAEZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD,KAAK,kBAAkB,GAAG,SAAS,GAAG,KAAK,GAAG,aAAa,GAAG,OAAO,CAAA;AAOrE,UAAU,qBAAqB;IAC7B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAE/C,gBAAgB,SAAM;gBAyBV,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,qBAAqB;IAyBtE,IAAI,UAAU,uCAEb;IAED,IAAI,UAAU,qCAEb;IAqID,OAAO,CAAC,MAAM,EAAE,MAAM;IAIhB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IA8DjC,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,cAAc,CAAC,OAAO,EAAE,WAAW;IAkBnC,uBAAuB,CAAC,OAAO,EAAE,gBAAgB;IAuBjD,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc;IAwFxD,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAM7E"}

package/dist/synchronizer/DocSynchronizer.js

@@ -37,7 +37,6 @@ export class DocSynchronizer extends Synchronizer {
         handle.on("ephemeral-message-outbound", payload => this.#broadcastToPeers(payload));
         // Process pending sync messages immediately after the handle becomes ready.
         void (async () => {
-            await handle.whenReady([READY, REQUESTING]);
             this.#processAllPendingSyncMessages();
         })();
     }
@@ -49,10 +48,14 @@ export class DocSynchronizer extends Synchronizer {
     }
     /// PRIVATE
     async #syncWithPeers() {
-        const doc = await this.#handle.legacyAsyncDoc(); // XXX THIS ONE IS WEIRD
-        if (doc === undefined)
-            return;
-        this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
+        try {
+            await this.#handle.whenReady();
+            const doc = this.#handle.doc(); // XXX THIS ONE IS WEIRD
+            this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
+        }
+        catch (e) {
+            console.log("sync with peers threw an exception");
+        }
     }
     async #broadcastToPeers({ data, }) {
         this.#log(`broadcastToPeers`, this.#peers);
@@ -155,22 +158,16 @@ export class DocSynchronizer extends Synchronizer {
         return this.#peers.includes(peerId);
     }
     async beginSync(peerIds) {
-        const noPeersWithDocument = peerIds.every(peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]);
-        // At this point if we don't have anything in our storage, we need to use an empty doc to sync
-        // with; but we don't want to surface that state to the front end
-        const docPromise = this.#handle // TODO THIS IS ALSO WEIRD
-            .legacyAsyncDoc([READY, REQUESTING, UNAVAILABLE])
-            .then(doc => {
-            // we register out peers first, then say that sync has started
+        void this.#handle
+            .whenReady([READY, REQUESTING, UNAVAILABLE])
+            .then(() => {
+            this.#syncStarted = true;
+            this.#checkDocUnavailable();
+        })
+            .catch(e => {
+            console.log("caught whenready", e);
             this.#syncStarted = true;
             this.#checkDocUnavailable();
-            const wasUnavailable = doc === undefined;
-            if (wasUnavailable && noPeersWithDocument) {
-                return;
-            }
-            // If the doc is unavailable we still need a blank document to generate
-            // the sync message from
-            return doc ?? A.init();
         });
         const peersWithDocument = this.#peers.some(peerId => {
             return this.#peerDocumentStatuses[peerId] == "has";
@@ -186,11 +183,22 @@ export class DocSynchronizer extends Synchronizer {
                 // TODO: cover that case with a test and remove this hack
                 const reparsedSyncState = A.decodeSyncState(A.encodeSyncState(syncState));
                 this.#setSyncState(peerId, reparsedSyncState);
-                docPromise
-                    .then(doc => {
-                    if (doc) {
-                        this.#sendSyncMessage(peerId, doc);
+                // At this point if we don't have anything in our storage, we need to use an empty doc to sync
+                // with; but we don't want to surface that state to the front end
+                this.#handle
+                    .whenReady([READY, REQUESTING, UNAVAILABLE])
+                    .then(() => {
+                    const doc = this.#handle.isReady()
+                        ? this.#handle.doc()
+                        : A.init();
+                    const noPeersWithDocument = peerIds.every(peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]);
+                    const wasUnavailable = doc === undefined;
+                    if (wasUnavailable && noPeersWithDocument) {
+                        return;
                     }
+                    // If the doc is unavailable we still need a blank document to generate
+                    // the sync message from
+                    this.#sendSyncMessage(peerId, doc ?? A.init());
                 })
                     .catch(err => {
                     this.#log(`Error loading doc for ${peerId}: ${err}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.0.0-alpha.22",
+  "version": "2.0.0-alpha.26",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -20,6 +20,7 @@
   },
   "devDependencies": {
     "http-server": "^14.1.0",
+    "ts-node": "^10.9.2",
     "vite": "^5.0.8"
   },
   "dependencies": {
@@ -29,8 +30,6 @@
     "debug": "^4.3.4",
     "eventemitter3": "^5.0.1",
     "fast-sha256": "^1.3.0",
-    "tiny-typed-emitter": "^2.1.0",
-    "ts-node": "^10.9.1",
     "uuid": "^9.0.0",
     "xstate": "^5.9.1"
   },
@@ -60,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b30af9827bed4615ba3c5e9ee93ca483915e4016"
+  "gitHead": "3d3e0f6fb267080a5bd8d12315efb85b8a2ada70"
 }

package/src/DocHandle.ts

@@ -45,6 +45,9 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   /** A dictionary mapping each peer to the last heads we know they have. */
   #remoteHeads: Record<StorageId, UrlHeads> = {}
 
+  /** Cache for view handles, keyed by the stringified heads */
+  #viewCache: Map<string, DocHandle<T>> = new Map()
+
   /** @hidden */
   constructor(
     public documentId: DocumentId,
@@ -275,27 +278,6 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     await withTimeout(this.#statePromise(awaitStates), this.#timeoutDelay)
   }
 
-  /**
-   * @returns the current state of this handle's Automerge document.
-   *
-   * This is the recommended way to access a handle's document. Note that this waits for the handle
-   * to be ready if necessary. If loading (or synchronization) fails, this will never resolve.
-   */
-  async legacyAsyncDoc(
-    /** states to wait for, such as "LOADING". mostly for internal use. */
-    awaitStates: HandleState[] = ["ready", "unavailable"]
-  ) {
-    try {
-      // wait for the document to enter one of the desired states
-      await this.#statePromise(awaitStates)
-    } catch (error) {
-      // if we timed out, return undefined
-      return undefined
-    }
-    // Return the document
-    return !this.isUnavailable() ? this.#doc : undefined
-  }
-
   /**
    * Returns the current state of the Automerge document this handle manages.
    *
@@ -380,6 +362,16 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
         `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling view().`
       )
     }
+
+    // Create a cache key from the heads
+    const cacheKey = JSON.stringify(heads)
+
+    // Check if we have a cached handle for these heads
+    const cachedHandle = this.#viewCache.get(cacheKey)
+    if (cachedHandle) {
+      return cachedHandle
+    }
+
     // Create a new handle with the same documentId but fixed heads
     const handle = new DocHandle<T>(this.documentId, {
       heads,
@@ -388,6 +380,9 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     handle.update(() => A.clone(this.#doc))
     handle.doneLoading()
 
+    // Store in cache
+    this.#viewCache.set(cacheKey, handle)
+
     return handle
   }
 
@@ -484,7 +479,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * Called by the repo either when a doc handle changes or we receive new remote heads.
+   * Called by the repo when a doc handle changes or we receive new remote heads.
    * @hidden
    */
   setRemoteHeads(storageId: StorageId, heads: UrlHeads) {
@@ -596,14 +591,15 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * Used in testing to mark this document as unavailable.
+   * Updates the internal state machine to mark the document unavailable.
    * @hidden
    */
   unavailable() {
     this.#machine.send({ type: DOC_UNAVAILABLE })
   }
 
-  /** Called by the repo when the document is not found in storage.
+  /**
+   * Called by the repo either when the document is not found in storage.
    * @hidden
    * */
   request() {
@@ -635,7 +631,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   broadcast(message: unknown) {
     this.emit("ephemeral-message-outbound", {
       handle: this,
-      data: encode(message),
+      data: new Uint8Array(encode(message)),
     })
   }
 

package/src/storage/StorageSubsystem.ts

@@ -6,7 +6,6 @@ import { type DocumentId } from "../types.js"
 import { StorageAdapterInterface } from "./StorageAdapterInterface.js"
 import { ChunkInfo, StorageKey, StorageId } from "./types.js"
 import { keyHash, headsHash } from "./keyHash.js"
-import { chunkTypeFromKey } from "./chunkTypeFromKey.js"
 import * as Uuid from "uuid"
 import { EventEmitter } from "eventemitter3"
 import { encodeHeads } from "../AutomergeUrl.js"
@@ -113,33 +112,63 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
   // AUTOMERGE DOCUMENT STORAGE
 
   /**
-   * Loads the Automerge document with the given ID from storage.
+   * Loads and combines document chunks from storage, with snapshots first.
    */
-  async loadDoc<T>(documentId: DocumentId): Promise<A.Doc<T> | null> {
-    // Load all the chunks for this document
-    const chunks = await this.#storageAdapter.loadRange([documentId])
-    const binaries = []
+  async loadDocData(documentId: DocumentId): Promise<Uint8Array | null> {
+    // Load snapshots first
+    const snapshotChunks = await this.#storageAdapter.loadRange([
+      documentId,
+      "snapshot",
+    ])
+    const incrementalChunks = await this.#storageAdapter.loadRange([
+      documentId,
+      "incremental",
+    ])
+
+    const binaries: Uint8Array[] = []
     const chunkInfos: ChunkInfo[] = []
 
-    for (const chunk of chunks) {
-      // chunks might have been deleted in the interim
+    // Process snapshots first
+    for (const chunk of snapshotChunks) {
       if (chunk.data === undefined) continue
+      chunkInfos.push({
+        key: chunk.key,
+        type: "snapshot",
+        size: chunk.data.length,
+      })
+      binaries.push(chunk.data)
+    }
 
-      const chunkType = chunkTypeFromKey(chunk.key)
-      if (chunkType == null) continue
-
+    // Then process incrementals
+    for (const chunk of incrementalChunks) {
+      if (chunk.data === undefined) continue
       chunkInfos.push({
         key: chunk.key,
-        type: chunkType,
+        type: "incremental",
         size: chunk.data.length,
       })
       binaries.push(chunk.data)
     }
+
+    // Store chunk infos for future reference
     this.#chunkInfos.set(documentId, chunkInfos)
 
+    // If no chunks were found, return null
+    if (binaries.length === 0) {
+      return null
+    }
+
     // Merge the chunks into a single binary
-    const binary = mergeArrays(binaries)
-    if (binary.length === 0) return null
+    return mergeArrays(binaries)
+  }
+
+  /**
+   * Loads the Automerge document with the given ID from storage.
+   */
+  async loadDoc<T>(documentId: DocumentId): Promise<A.Doc<T> | null> {
+    // Load and combine chunks
+    const binary = await this.loadDocData(documentId)
+    if (!binary) return null
 
     // Load into an Automerge document
     const start = performance.now()
@@ -169,6 +198,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     if (!this.#shouldSave(documentId, doc)) return
 
     const sourceChunks = this.#chunkInfos.get(documentId) ?? []
+
     if (this.#shouldCompact(sourceChunks)) {
       await this.#saveTotal(documentId, doc, sourceChunks)
     } else {

package/src/synchronizer/DocSynchronizer.ts

@@ -86,7 +86,6 @@ export class DocSynchronizer extends Synchronizer {
 
     // Process pending sync messages immediately after the handle becomes ready.
     void (async () => {
-      await handle.whenReady([READY, REQUESTING])
       this.#processAllPendingSyncMessages()
     })()
   }
@@ -102,9 +101,13 @@ export class DocSynchronizer extends Synchronizer {
   /// PRIVATE
 
   async #syncWithPeers() {
-    const doc = await this.#handle.legacyAsyncDoc() // XXX THIS ONE IS WEIRD
-    if (doc === undefined) return
-    this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc))
+    try {
+      await this.#handle.whenReady()
+      const doc = this.#handle.doc() // XXX THIS ONE IS WEIRD
+      this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc))
+    } catch (e) {
+      console.log("sync with peers threw an exception")
+    }
   }
 
   async #broadcastToPeers({
@@ -231,27 +234,16 @@ export class DocSynchronizer extends Synchronizer {
   }
 
   async beginSync(peerIds: PeerId[]) {
-    const noPeersWithDocument = peerIds.every(
-      peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]
-    )
-
-    // At this point if we don't have anything in our storage, we need to use an empty doc to sync
-    // with; but we don't want to surface that state to the front end
-    const docPromise = this.#handle // TODO THIS IS ALSO WEIRD
-      .legacyAsyncDoc([READY, REQUESTING, UNAVAILABLE])
-      .then(doc => {
-        // we register out peers first, then say that sync has started
+    void this.#handle
+      .whenReady([READY, REQUESTING, UNAVAILABLE])
+      .then(() => {
+        this.#syncStarted = true
+        this.#checkDocUnavailable()
+      })
+      .catch(e => {
+        console.log("caught whenready", e)
         this.#syncStarted = true
         this.#checkDocUnavailable()
-
-        const wasUnavailable = doc === undefined
-        if (wasUnavailable && noPeersWithDocument) {
-          return
-        }
-
-        // If the doc is unavailable we still need a blank document to generate
-        // the sync message from
-        return doc ?? A.init<unknown>()
       })
 
     const peersWithDocument = this.#peers.some(peerId => {
@@ -273,11 +265,28 @@ export class DocSynchronizer extends Synchronizer {
         )
         this.#setSyncState(peerId, reparsedSyncState)
 
-        docPromise
-          .then(doc => {
-            if (doc) {
-              this.#sendSyncMessage(peerId, doc)
+        // At this point if we don't have anything in our storage, we need to use an empty doc to sync
+        // with; but we don't want to surface that state to the front end
+        this.#handle
+          .whenReady([READY, REQUESTING, UNAVAILABLE])
+          .then(() => {
+            const doc = this.#handle.isReady()
+              ? this.#handle.doc()
+              : A.init<unknown>()
+
+            const noPeersWithDocument = peerIds.every(
+              peerId =>
+                this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]
+            )
+
+            const wasUnavailable = doc === undefined
+            if (wasUnavailable && noPeersWithDocument) {
+              return
             }
+
+            // If the doc is unavailable we still need a blank document to generate
+            // the sync message from
+            this.#sendSyncMessage(peerId, doc ?? A.init<unknown>())
           })
           .catch(err => {
             this.#log(`Error loading doc for ${peerId}: ${err}`)

package/test/DocHandle.test.ts

@@ -259,8 +259,6 @@ describe("DocHandle", () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
     assert.equal(handle.isReady(), false)
 
-    handle.legacyAsyncDoc()
-
     assert(vi.getTimerCount() > timerCount)
 
     // simulate loading from storage
@@ -522,4 +520,71 @@ describe("DocHandle", () => {
       assert.deepStrictEqual(decode(data), message)
     })
   })
+
+  it("should cache view handles based on heads", async () => {
+    // Create and setup a document with some data
+    const handle = setup()
+    handle.change(doc => {
+      doc.foo = "Hello"
+    })
+    const heads1 = handle.heads()
+
+    // Make another change to get a different set of heads
+    handle.change(doc => {
+      doc.foo = "Hello, World!"
+    })
+
+    // Create a view at the first set of heads
+    const view1 = handle.view(heads1)
+
+    // Request the same view again
+    const view2 = handle.view(heads1)
+
+    // Verify we got the same handle instance back (cached version)
+    expect(view1).toBe(view2)
+
+    // Verify the contents are correct
+    expect(view1.doc().foo).toBe("Hello")
+
+    // Test with a different set of heads
+    const view3 = handle.view(handle.heads())
+    expect(view3).not.toBe(view1)
+    expect(view3.doc().foo).toBe("Hello, World!")
+  })
+
+  it("should improve performance when requesting the same view multiple times", () => {
+    // Create and setup a document with some data
+    const handle = setup()
+    handle.change(doc => {
+      doc.foo = "Hello"
+    })
+    const heads = handle.heads()
+
+    // First, measure time without cache (first access)
+    const startTimeNoCached = performance.now()
+    const firstView = handle.view(heads)
+    const endTimeNoCached = performance.now()
+
+    // Now measure with cache (subsequent accesses)
+    const startTimeCached = performance.now()
+    for (let i = 0; i < 100; i++) {
+      handle.view(heads)
+    }
+    const endTimeCached = performance.now()
+
+    // Assert that all views are the same instance
+    for (let i = 0; i < 10; i++) {
+      expect(handle.view(heads)).toBe(firstView)
+    }
+
+    // Calculate average times
+    const timeForFirstAccess = endTimeNoCached - startTimeNoCached
+    const timeForCachedAccesses = (endTimeCached - startTimeCached) / 100
+
+    console.log(`Time for first view (no cache): ${timeForFirstAccess}ms`)
+    console.log(`Average time per cached view: ${timeForCachedAccesses}ms`)
+
+    // Cached access should be significantly faster
+    expect(timeForCachedAccesses).toBeLessThan(timeForFirstAccess / 10)
+  })
 })

package/test/Repo.test.ts

@@ -33,6 +33,7 @@ import {
 import { getRandomItem } from "./helpers/getRandomItem.js"
 import { TestDoc } from "./types.js"
 import { StorageId, StorageKey } from "../src/storage/types.js"
+import { chunkTypeFromKey } from "../src/storage/chunkTypeFromKey.js"
 
 describe("Repo", () => {
   describe("constructor", () => {
@@ -255,7 +256,6 @@ describe("Repo", () => {
       await repo.flush()
 
       const bobHandle = await repo2.find<TestDoc>(handle.url)
-      await bobHandle.whenReady()
       assert.deepEqual(bobHandle.doc(), { foo: "saved" })
     })
 
@@ -306,7 +306,6 @@ describe("Repo", () => {
         d.foo = "bar"
       })
       assert.equal(handle.isReady(), true)
-      await handle.whenReady()
 
       await pause()
       repo.delete(handle.url)
@@ -1063,11 +1062,6 @@ describe("Repo", () => {
             : // tails, pick a random doc
               (getRandomItem(docs) as DocHandle<TestDoc>)
 
-        // make sure the doc is ready
-        if (!doc.isReady()) {
-          await doc.whenReady()
-        }
-
         // make a random change to it
         doc.change(d => {
           d.foo = Math.random().toString()
@@ -1240,7 +1234,6 @@ describe("Repo", () => {
       })
 
       const charlieHandle = await charlieRepo.find<TestDoc>(handle.url)
-      await charlieHandle.whenReady()
 
       // make a change on charlie
       charlieHandle.change(d => {

package/test/StorageSubsystem.test.ts

@@ -4,13 +4,15 @@ import assert from "assert"
 import fs from "fs"
 import os from "os"
 import path from "path"
-import { describe, it } from "vitest"
+import { describe, it, expect } from "vitest"
 import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import { PeerId, cbor } from "../src/index.js"
 import { StorageSubsystem } from "../src/storage/StorageSubsystem.js"
 import { StorageId } from "../src/storage/types.js"
 import { DummyStorageAdapter } from "../src/helpers/DummyStorageAdapter.js"
 import * as Uuid from "uuid"
+import { chunkTypeFromKey } from "../src/storage/chunkTypeFromKey.js"
+import { DocumentId } from "../src/types.js"
 
 const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "automerge-repo-tests"))
 
@@ -243,6 +245,83 @@ describe("StorageSubsystem", () => {
           assert.strictEqual(id1, id2)
         })
       })
+
+      describe("loadDoc", () => {
+        it("maintains correct document state when loading chunks in order", async () => {
+          const storageAdapter = new DummyStorageAdapter()
+          const storage = new StorageSubsystem(storageAdapter)
+
+          // Create a document with multiple changes
+          const doc = A.init<{ foo: string }>()
+          const doc1 = A.change(doc, d => {
+            d.foo = "first"
+          })
+          const doc2 = A.change(doc1, d => {
+            d.foo = "second"
+          })
+          const doc3 = A.change(doc2, d => {
+            d.foo = "third"
+          })
+
+          // Save the document with multiple changes
+          const documentId = "test-doc" as DocumentId
+          await storage.saveDoc(documentId, doc3)
+
+          // Load the document
+          const loadedDoc = await storage.loadDoc<{ foo: string }>(documentId)
+
+          // Verify the document state is correct
+          expect(loadedDoc?.foo).toBe("third")
+        })
+
+        it("combines chunks with snapshot first", async () => {
+          const storageAdapter = new DummyStorageAdapter()
+          const storage = new StorageSubsystem(storageAdapter)
+
+          // Create a document with multiple changes
+          const doc = A.init<{ foo: string }>()
+          const doc1 = A.change(doc, d => {
+            d.foo = "first"
+          })
+          const doc2 = A.change(doc1, d => {
+            d.foo = Array(10000)
+              .fill(0)
+              .map(() =>
+                String.fromCharCode(Math.floor(Math.random() * 26) + 97)
+              )
+              .join("")
+          })
+
+          // Save the document with multiple changes
+          const documentId = "test-doc" as DocumentId
+          await storage.saveDoc(documentId, doc2)
+
+          const doc3 = A.change(doc2, d => {
+            d.foo = "third"
+          })
+          await storage.saveDoc(documentId, doc3)
+
+          // Load the document
+          const loadedDoc = await storage.loadDoc<{ foo: string }>(documentId)
+
+          // Verify the document state is correct
+          expect(loadedDoc?.foo).toBe(doc3.foo)
+
+          // Get the raw binary data from storage
+          const binary = await storage.loadDocData(documentId)
+          expect(binary).not.toBeNull()
+          if (!binary) return
+
+          // Verify the binary starts with the Automerge magic value
+          expect(binary[0]).toBe(0x85)
+          expect(binary[1]).toBe(0x6f)
+          expect(binary[2]).toBe(0x4a)
+          expect(binary[3]).toBe(0x83)
+
+          // Verify the chunk type is CHUNK_TYPE_DOCUMENT (0x00)
+          expect(binary[8]).toBe(0x00)
+        })
+      })
     })
   }
 })