@automerge/automerge-repo 0.0.1

package/dist/network/NetworkSubsystem.d.ts

@@ -0,0 +1,23 @@
+import EventEmitter from "eventemitter3";
+import { InboundMessagePayload, NetworkAdapter, PeerDisconnectedPayload } from "./NetworkAdapter.js";
+import { ChannelId, PeerId } from "../types.js";
+export declare class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
+    #private;
+    private adapters;
+    peerId: PeerId;
+    constructor(adapters: NetworkAdapter[], peerId?: PeerId);
+    addNetworkAdapter(networkAdapter: NetworkAdapter): void;
+    sendMessage(peerId: PeerId, channelId: ChannelId, message: Uint8Array, broadcast: boolean): void;
+    join(channelId: ChannelId): void;
+    leave(channelId: ChannelId): void;
+}
+export interface NetworkSubsystemEvents {
+    peer: (payload: PeerPayload) => void;
+    "peer-disconnected": (payload: PeerDisconnectedPayload) => void;
+    message: (payload: InboundMessagePayload) => void;
+}
+export interface PeerPayload {
+    peerId: PeerId;
+    channelId: ChannelId;
+}
+//# sourceMappingURL=NetworkSubsystem.d.ts.map

package/dist/network/NetworkSubsystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkSubsystem.d.ts","sourceRoot":"","sources":["../../src/network/NetworkSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAA;AACxC,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,uBAAuB,EACxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAI/C,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;IAMtE,OAAO,CAAC,QAAQ;IACT,MAAM;gBADL,QAAQ,EAAE,cAAc,EAAE,EAC3B,MAAM,SAAiB;IAQhC,iBAAiB,CAAC,cAAc,EAAE,cAAc;IAsDhD,WAAW,CACT,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,OAAO;IAkBpB,IAAI,CAAC,SAAS,EAAE,SAAS;IAMzB,KAAK,CAAC,SAAS,EAAE,SAAS;CAK3B;AAQD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IACpC,mBAAmB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAC/D,OAAO,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,SAAS,CAAA;CACrB"}

package/dist/network/NetworkSubsystem.js

@@ -0,0 +1,89 @@
+import EventEmitter from "eventemitter3";
+import debug from "debug";
+export class NetworkSubsystem extends EventEmitter {
+    adapters;
+    peerId;
+    #log;
+    #adaptersByPeer = {};
+    #channels;
+    constructor(adapters, peerId = randomPeerId()) {
+        super();
+        this.adapters = adapters;
+        this.peerId = peerId;
+        this.#log = debug(`automerge-repo:network:${this.peerId}`);
+        this.#channels = [];
+        this.adapters.forEach(a => this.addNetworkAdapter(a));
+    }
+    addNetworkAdapter(networkAdapter) {
+        networkAdapter.connect(this.peerId);
+        networkAdapter.on("peer-candidate", ({ peerId, channelId }) => {
+            this.#log(`peer candidate: ${peerId} `);
+            // TODO: This is where authentication would happen
+            if (!this.#adaptersByPeer[peerId]) {
+                // TODO: handle losing a server here
+                this.#adaptersByPeer[peerId] = networkAdapter;
+            }
+            this.emit("peer", { peerId, channelId });
+        });
+        networkAdapter.on("peer-disconnected", ({ peerId }) => {
+            this.#log(`peer disconnected: ${peerId} `);
+            delete this.#adaptersByPeer[peerId];
+            this.emit("peer-disconnected", { peerId });
+        });
+        networkAdapter.on("message", msg => {
+            const { senderId, channelId, broadcast, message } = msg;
+            this.#log(`message from ${senderId}`);
+            // If we receive a broadcast message from a network adapter we need to re-broadcast it to all
+            // our other peers. This is the world's worst gossip protocol.
+            // TODO: This relies on the network forming a tree! If there are cycles, this approach will
+            // loop messages around forever.
+            if (broadcast) {
+                Object.entries(this.#adaptersByPeer)
+                    .filter(([id]) => id !== senderId)
+                    .forEach(([id, peer]) => {
+                    peer.sendMessage(id, channelId, message, broadcast);
+                });
+            }
+            this.emit("message", msg);
+        });
+        networkAdapter.on("close", () => {
+            this.#log("adapter closed");
+            Object.entries(this.#adaptersByPeer).forEach(([peerId, other]) => {
+                if (other === networkAdapter) {
+                    delete this.#adaptersByPeer[peerId];
+                }
+            });
+        });
+        this.#channels.forEach(c => networkAdapter.join(c));
+    }
+    sendMessage(peerId, channelId, message, broadcast) {
+        if (broadcast) {
+            Object.entries(this.#adaptersByPeer).forEach(([id, peer]) => {
+                this.#log(`sending broadcast to ${id}`);
+                peer.sendMessage(id, channelId, message, true);
+            });
+        }
+        else {
+            const peer = this.#adaptersByPeer[peerId];
+            if (!peer) {
+                this.#log(`Tried to send message but peer not found: ${peerId}`);
+                return;
+            }
+            this.#log(`Sending message to ${peerId}`);
+            peer.sendMessage(peerId, channelId, message, false);
+        }
+    }
+    join(channelId) {
+        this.#log(`Joining channel ${channelId}`);
+        this.#channels.push(channelId);
+        this.adapters.forEach(a => a.join(channelId));
+    }
+    leave(channelId) {
+        this.#log(`Leaving channel ${channelId}`);
+        this.#channels = this.#channels.filter(c => c !== channelId);
+        this.adapters.forEach(a => a.leave(channelId));
+    }
+}
+function randomPeerId() {
+    return `user-${Math.round(Math.random() * 100000)}`;
+}

package/dist/storage/StorageAdapter.d.ts

@@ -0,0 +1,6 @@
+export declare abstract class StorageAdapter {
+    abstract load(docId: string): Promise<Uint8Array | null>;
+    abstract save(docId: string, data: Uint8Array): void;
+    abstract remove(docId: string): void;
+}
+//# sourceMappingURL=StorageAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StorageAdapter.d.ts","sourceRoot":"","sources":["../../src/storage/StorageAdapter.ts"],"names":[],"mappings":"AAAA,8BAAsB,cAAc;IAClC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IACpD,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CACrC"}

package/dist/storage/StorageAdapter.js

@@ -0,0 +1,2 @@
+export class StorageAdapter {
+}

package/dist/storage/StorageSubsystem.d.ts

@@ -0,0 +1,12 @@
+import * as A from "@automerge/automerge";
+import { DocumentId } from "../types.js";
+import { StorageAdapter } from "./StorageAdapter.js";
+export declare class StorageSubsystem {
+    #private;
+    constructor(storageAdapter: StorageAdapter);
+    loadBinary(documentId: DocumentId): Promise<Uint8Array>;
+    load<T>(documentId: DocumentId, prevDoc?: A.Doc<T>): Promise<A.Doc<T>>;
+    save(documentId: DocumentId, doc: A.Doc<unknown>): void;
+    remove(documentId: DocumentId): void;
+}
+//# sourceMappingURL=StorageSubsystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,sBAAsB,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,qBAAa,gBAAgB;;gBAIf,cAAc,EAAE,cAAc;IA+BpC,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAqBvD,IAAI,CAAC,CAAC,EACV,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAe,GAC9B,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAMpB,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;IAQhD,MAAM,CAAC,UAAU,EAAE,UAAU;CAY9B"}

package/dist/storage/StorageSubsystem.js

@@ -0,0 +1,65 @@
+import * as A from "@automerge/automerge";
+import { mergeArrays } from "../helpers/mergeArrays.js";
+export class StorageSubsystem {
+    #storageAdapter;
+    #changeCount = {};
+    constructor(storageAdapter) {
+        this.#storageAdapter = storageAdapter;
+    }
+    #saveIncremental(documentId, doc) {
+        const binary = A.saveIncremental(doc);
+        if (binary && binary.length > 0) {
+            if (!this.#changeCount[documentId]) {
+                this.#changeCount[documentId] = 0;
+            }
+            this.#storageAdapter.save(`${documentId}.incremental.${this.#changeCount[documentId]}`, binary);
+            this.#changeCount[documentId]++;
+        }
+    }
+    #saveTotal(documentId, doc) {
+        const binary = A.save(doc);
+        this.#storageAdapter.save(`${documentId}.snapshot`, binary);
+        for (let i = 0; i < this.#changeCount[documentId]; i++) {
+            this.#storageAdapter.remove(`${documentId}.incremental.${i}`);
+        }
+        this.#changeCount[documentId] = 0;
+    }
+    async loadBinary(documentId) {
+        const result = [];
+        let binary = await this.#storageAdapter.load(`${documentId}.snapshot`);
+        if (binary && binary.length > 0) {
+            result.push(binary);
+        }
+        let index = 0;
+        while ((binary = await this.#storageAdapter.load(`${documentId}.incremental.${index}`))) {
+            this.#changeCount[documentId] = index + 1;
+            if (binary && binary.length > 0)
+                result.push(binary);
+            index += 1;
+        }
+        return mergeArrays(result);
+    }
+    async load(documentId, prevDoc = A.init()) {
+        const doc = A.loadIncremental(prevDoc, await this.loadBinary(documentId));
+        A.saveIncremental(doc);
+        return doc;
+    }
+    save(documentId, doc) {
+        if (this.#shouldCompact(documentId)) {
+            this.#saveTotal(documentId, doc);
+        }
+        else {
+            this.#saveIncremental(documentId, doc);
+        }
+    }
+    remove(documentId) {
+        this.#storageAdapter.remove(`${documentId}.snapshot`);
+        for (let i = 0; i < this.#changeCount[documentId]; i++) {
+            this.#storageAdapter.remove(`${documentId}.incremental.${i}`);
+        }
+    }
+    // TODO: make this, you know, good.
+    #shouldCompact(documentId) {
+        return this.#changeCount[documentId] >= 20;
+    }
+}

package/dist/synchronizer/CollectionSynchronizer.d.ts

@@ -0,0 +1,24 @@
+import { DocCollection } from "../DocCollection.js";
+import { ChannelId, DocumentId, PeerId } from "../types.js";
+import { Synchronizer } from "./Synchronizer.js";
+/** A CollectionSynchronizer is responsible for synchronizing a DocCollection with peers. */
+export declare class CollectionSynchronizer extends Synchronizer {
+    #private;
+    private repo;
+    constructor(repo: DocCollection);
+    /**
+     * When we receive a sync message for a document we haven't got in memory, we
+     * register it with the repo and start synchronizing
+     */
+    receiveSyncMessage(peerId: PeerId, channelId: ChannelId, message: Uint8Array): Promise<void>;
+    /**
+     * Starts synchronizing the given document with all peers that we share it generously with.
+     */
+    addDocument(documentId: DocumentId): void;
+    removeDocument(documentId: DocumentId): void;
+    /** Adds a peer and maybe starts synchronizing with them */
+    addPeer(peerId: PeerId): void;
+    /** Removes a peer and stops synchronizing with them */
+    removePeer(peerId: PeerId): void;
+}
+//# sourceMappingURL=CollectionSynchronizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CollectionSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/CollectionSynchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKhD,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,YAAY;;IAO1C,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAiCvC;;;OAGG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,UAAU;IAgBrB;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,UAAU;IAUlC,cAAc,CAAC,UAAU,EAAE,UAAU;IAIrC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM;IAWtB,uDAAuD;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM;CAQ1B"}

package/dist/synchronizer/CollectionSynchronizer.js

@@ -0,0 +1,92 @@
+import { DocSynchronizer } from "./DocSynchronizer.js";
+import { Synchronizer } from "./Synchronizer.js";
+import debug from "debug";
+const log = debug("automerge-repo:collectionsync");
+/** A CollectionSynchronizer is responsible for synchronizing a DocCollection with peers. */
+export class CollectionSynchronizer extends Synchronizer {
+    repo;
+    /** The set of peers we are connected with */
+    #peers = new Set();
+    /** A map of documentIds to their synchronizers */
+    #docSynchronizers = {};
+    constructor(repo) {
+        super();
+        this.repo = repo;
+    }
+    /** Returns a synchronizer for the given document, creating one if it doesn't already exist.  */
+    #fetchDocSynchronizer(documentId) {
+        if (!this.#docSynchronizers[documentId]) {
+            const handle = this.repo.find(documentId);
+            this.#docSynchronizers[documentId] = this.#initDocSynchronizer(handle);
+        }
+        return this.#docSynchronizers[documentId];
+    }
+    /** Creates a new docSynchronizer and sets it up to propagate messages */
+    #initDocSynchronizer(handle) {
+        const docSynchronizer = new DocSynchronizer(handle);
+        docSynchronizer.on("message", event => this.emit("message", event));
+        return docSynchronizer;
+    }
+    /** returns an array of peerIds that we share this document generously with */
+    async #documentGenerousPeers(documentId) {
+        const peers = Array.from(this.#peers);
+        const generousPeers = [];
+        for (const peerId of peers) {
+            const okToShare = await this.repo.sharePolicy(peerId, documentId);
+            if (okToShare)
+                generousPeers.push(peerId);
+        }
+        return generousPeers;
+    }
+    // PUBLIC
+    /**
+     * When we receive a sync message for a document we haven't got in memory, we
+     * register it with the repo and start synchronizing
+     */
+    async receiveSyncMessage(peerId, channelId, message) {
+        log(`onSyncMessage: ${peerId}, ${channelId}, ${message.byteLength}bytes`);
+        const documentId = channelId;
+        const docSynchronizer = await this.#fetchDocSynchronizer(documentId);
+        await docSynchronizer.receiveSyncMessage(peerId, channelId, message);
+        // Initiate sync with any new peers
+        const peers = await this.#documentGenerousPeers(documentId);
+        peers
+            .filter(peerId => !docSynchronizer.hasPeer(peerId))
+            .forEach(peerId => docSynchronizer.beginSync(peerId));
+    }
+    /**
+     * Starts synchronizing the given document with all peers that we share it generously with.
+     */
+    addDocument(documentId) {
+        const docSynchronizer = this.#fetchDocSynchronizer(documentId);
+        void this.#documentGenerousPeers(documentId).then(peers => {
+            peers.forEach(peerId => {
+                docSynchronizer.beginSync(peerId);
+            });
+        });
+    }
+    // TODO: implement this
+    removeDocument(documentId) {
+        throw new Error("not implemented");
+    }
+    /** Adds a peer and maybe starts synchronizing with them */
+    addPeer(peerId) {
+        log(`adding ${peerId} & synchronizing with them`);
+        this.#peers.add(peerId);
+        for (const docSynchronizer of Object.values(this.#docSynchronizers)) {
+            const { documentId } = docSynchronizer;
+            void this.repo.sharePolicy(peerId, documentId).then(okToShare => {
+                if (okToShare)
+                    docSynchronizer.beginSync(peerId);
+            });
+        }
+    }
+    /** Removes a peer and stops synchronizing with them */
+    removePeer(peerId) {
+        log(`removing peer ${peerId}`);
+        this.#peers.delete(peerId);
+        for (const docSynchronizer of Object.values(this.#docSynchronizers)) {
+            docSynchronizer.endSync(peerId);
+        }
+    }
+}

package/dist/synchronizer/DocSynchronizer.d.ts

@@ -0,0 +1,18 @@
+import { DocHandle } from "../DocHandle.js";
+import { ChannelId, PeerId } from "../types.js";
+import { Synchronizer } from "./Synchronizer.js";
+/**
+ * DocSynchronizer takes a handle to an Automerge document, and receives & dispatches sync messages
+ * to bring it inline with all other peers' versions.
+ */
+export declare class DocSynchronizer extends Synchronizer {
+    #private;
+    private handle;
+    constructor(handle: DocHandle<any>);
+    get documentId(): import("../types.js").DocumentId;
+    hasPeer(peerId: PeerId): boolean;
+    beginSync(peerId: PeerId): void;
+    endSync(peerId: PeerId): void;
+    receiveSyncMessage(peerId: PeerId, channelId: ChannelId, message: Uint8Array): void;
+}
+//# sourceMappingURL=DocSynchronizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAanC,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC;IAgB1C,IAAI,UAAU,qCAEb;IAuED,OAAO,CAAC,MAAM,EAAE,MAAM;IAItB,SAAS,CAAC,MAAM,EAAE,MAAM;IAkBxB,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,UAAU;CAsCtB"}

package/dist/synchronizer/DocSynchronizer.js

@@ -0,0 +1,136 @@
+import * as A from "@automerge/automerge";
+import { Synchronizer } from "./Synchronizer.js";
+import debug from "debug";
+/**
+ * DocSynchronizer takes a handle to an Automerge document, and receives & dispatches sync messages
+ * to bring it inline with all other peers' versions.
+ */
+export class DocSynchronizer extends Synchronizer {
+    handle;
+    #log;
+    #conciseLog;
+    #opsLog;
+    /** Active peers */
+    #peers = [];
+    /** Sync state for each peer we've communicated with (including inactive peers) */
+    #syncStates = {};
+    #pendingSyncMessages = [];
+    constructor(handle) {
+        super();
+        this.handle = handle;
+        const docId = handle.documentId.slice(0, 5);
+        this.#conciseLog = debug(`automerge-repo:concise:docsync:${docId}`); // Only logs one line per receive/send
+        this.#log = debug(`automerge-repo:docsync:${docId}`);
+        this.#opsLog = debug(`automerge-repo:ops:docsync:${docId}`); // Log list of ops of each message
+        handle.on("change", () => this.#syncWithPeers());
+        // Process pending sync messages immediately after the handle becomes ready.
+        void (async () => {
+            await handle.loadAttemptedValue();
+            this.#processAllPendingSyncMessages();
+        })();
+    }
+    get documentId() {
+        return this.handle.documentId;
+    }
+    /// PRIVATE
+    async #syncWithPeers() {
+        this.#log(`syncWithPeers`);
+        const doc = await this.handle.value();
+        this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
+    }
+    #getSyncState(peerId) {
+        if (!this.#peers.includes(peerId)) {
+            this.#log("adding a new peer", peerId);
+            this.#peers.push(peerId);
+        }
+        return this.#syncStates[peerId] ?? A.initSyncState();
+    }
+    #setSyncState(peerId, syncState) {
+        // TODO: we maybe should be persisting sync states. But we want to be careful about how often we
+        // do that, because it can generate a lot of disk activity.
+        // TODO: we only need to do this on reconnect
+        this.#syncStates[peerId] = syncState;
+    }
+    #sendSyncMessage(peerId, doc) {
+        this.#log(`sendSyncMessage ->${peerId}`);
+        const syncState = this.#getSyncState(peerId);
+        const [newSyncState, message] = A.generateSyncMessage(doc, syncState);
+        this.#setSyncState(peerId, newSyncState);
+        if (message) {
+            this.#logMessage(`sendSyncMessage 🡒 ${peerId}`, message);
+            const channelId = this.handle.documentId;
+            this.emit("message", {
+                targetId: peerId,
+                channelId,
+                message,
+                broadcast: false,
+            });
+        }
+        else {
+            this.#log(`sendSyncMessage ->${peerId} [no message generated]`);
+        }
+    }
+    #logMessage = (label, message) => {
+        // This is real expensive...
+        return;
+        const size = message.byteLength;
+        const logText = `${label} ${size}b`;
+        const decoded = A.decodeSyncMessage(message);
+        this.#conciseLog(logText);
+        this.#log(logText, decoded);
+        // expanding is expensive, so only do it if we're logging at this level
+        const expanded = this.#opsLog.enabled
+            ? decoded.changes.flatMap(change => A.decodeChange(change).ops.map(op => JSON.stringify(op)))
+            : null;
+        this.#opsLog(logText, expanded);
+    };
+    /// PUBLIC
+    hasPeer(peerId) {
+        return this.#peers.includes(peerId);
+    }
+    beginSync(peerId) {
+        this.#log(`beginSync: ${peerId}`);
+        // 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
+        void this.handle.loadAttemptedValue().then(doc => {
+            // HACK: if we have a sync state already, we round-trip it through the encoding system to make
+            // sure state is preserved. This prevents an infinite loop caused by failed attempts to send
+            // messages during disconnection.
+            // TODO: cover that case with a test and remove this hack
+            const syncStateRaw = this.#getSyncState(peerId);
+            const syncState = A.decodeSyncState(A.encodeSyncState(syncStateRaw));
+            this.#setSyncState(peerId, syncState);
+            this.#sendSyncMessage(peerId, doc);
+        });
+    }
+    endSync(peerId) {
+        this.#log(`removing peer ${peerId}`);
+        this.#peers = this.#peers.filter(p => p !== peerId);
+    }
+    receiveSyncMessage(peerId, channelId, message) {
+        if (channelId !== this.documentId)
+            throw new Error(`channelId doesn't match documentId`);
+        // We need to block receiving the syncMessages until we've checked local storage
+        if (!this.handle.isReadyOrRequesting()) {
+            this.#pendingSyncMessages.push({ peerId, message });
+            return;
+        }
+        this.#processAllPendingSyncMessages();
+        this.#processSyncMessage(peerId, message);
+    }
+    #processSyncMessage(peerId, message) {
+        this.handle.update(doc => {
+            const [newDoc, newSyncState] = A.receiveSyncMessage(doc, this.#getSyncState(peerId), message);
+            this.#setSyncState(peerId, newSyncState);
+            // respond to just this peer (as required)
+            this.#sendSyncMessage(peerId, doc);
+            return newDoc;
+        });
+    }
+    #processAllPendingSyncMessages() {
+        for (const { peerId, message } of this.#pendingSyncMessages) {
+            this.#processSyncMessage(peerId, message);
+        }
+        this.#pendingSyncMessages = [];
+    }
+}

package/dist/synchronizer/Synchronizer.d.ts

@@ -0,0 +1,10 @@
+import EventEmitter from "eventemitter3";
+import { ChannelId, PeerId } from "../types.js";
+import { MessagePayload } from "../network/NetworkAdapter.js";
+export declare abstract class Synchronizer extends EventEmitter<SynchronizerEvents> {
+    abstract receiveSyncMessage(peerId: PeerId, channelId: ChannelId, message: Uint8Array): void;
+}
+export interface SynchronizerEvents {
+    message: (arg: MessagePayload) => void;
+}
+//# sourceMappingURL=Synchronizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAE7D,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,kBAAkB,CACzB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,UAAU,GAClB,IAAI;CACR;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CACvC"}

package/dist/synchronizer/Synchronizer.js

@@ -0,0 +1,3 @@
+import EventEmitter from "eventemitter3";
+export class Synchronizer extends EventEmitter {
+}

package/dist/test-utilities/adapter-tests.d.ts

@@ -0,0 +1,21 @@
+import { type NetworkAdapter } from "../index.js";
+/**
+ * Runs a series of tests against a set of three peers, each represented by one or more instantiated
+ * network adapters.
+ *
+ * The adapter `setup` function should return an object with the following properties:
+ *
+ * - `adapters`: A tuple representing three peers' network configuration. Each element can be either
+ *   a single adapter or an array of adapters. Each will be used to instantiate a Repo for that
+ *   peer.
+ * - `teardown`: An optional function that will be called after the tests have run. This can be used
+ *   to clean up any resources that were created during the test.
+ */
+export declare function runAdapterTests(_setup: SetupFn, title?: string): void;
+type Network = NetworkAdapter | NetworkAdapter[];
+export type SetupFn = () => Promise<{
+    adapters: [Network, Network, Network];
+    teardown?: () => void;
+}>;
+export {};
+//# sourceMappingURL=adapter-tests.d.ts.map

package/dist/test-utilities/adapter-tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-tests.d.ts","sourceRoot":"","sources":["../../src/test-utilities/adapter-tests.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,cAAc,EAAa,MAAM,aAAa,CAAA;AAQ1E;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA2HrE;AAID,KAAK,OAAO,GAAG,cAAc,GAAG,cAAc,EAAE,CAAA;AAEhD,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAClC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB,CAAC,CAAA"}

package/dist/test-utilities/adapter-tests.js

@@ -0,0 +1,117 @@
+import { Repo } from "../index.js";
+import { eventPromise, eventPromises, } from "../helpers/eventPromise.js";
+import { assert } from "chai";
+import { describe, it } from "mocha";
+/**
+ * Runs a series of tests against a set of three peers, each represented by one or more instantiated
+ * network adapters.
+ *
+ * The adapter `setup` function should return an object with the following properties:
+ *
+ * - `adapters`: A tuple representing three peers' network configuration. Each element can be either
+ *   a single adapter or an array of adapters. Each will be used to instantiate a Repo for that
+ *   peer.
+ * - `teardown`: An optional function that will be called after the tests have run. This can be used
+ *   to clean up any resources that were created during the test.
+ */
+export function runAdapterTests(_setup, title) {
+    // Wrap the provided setup function
+    const setup = async () => {
+        const { adapters, teardown = NO_OP } = await _setup();
+        // these might be individual adapters or arrays of adapters; normalize them to arrays
+        const [a, b, c] = adapters.map(toArray);
+        return { adapters: [a, b, c], teardown };
+    };
+    describe(`Adapter acceptance tests ${title ? `(${title})` : ""}`, () => {
+        it("can sync 2 repos", async () => {
+            const doTest = async (a, b) => {
+                const aliceRepo = new Repo({ network: a, peerId: alice });
+                const bobRepo = new Repo({ network: b, peerId: bob });
+                // Alice creates a document
+                const aliceHandle = aliceRepo.create();
+                // Bob receives the document
+                await eventPromise(bobRepo, "document");
+                const bobHandle = bobRepo.find(aliceHandle.documentId);
+                // Alice changes the document
+                aliceHandle.change(d => {
+                    d.foo = "bar";
+                });
+                // Bob receives the change
+                await eventPromise(bobHandle, "change");
+                assert.equal((await bobHandle.value()).foo, "bar");
+                // Bob changes the document
+                bobHandle.change(d => {
+                    d.foo = "baz";
+                });
+                // Alice receives the change
+                await eventPromise(aliceHandle, "change");
+                assert.equal((await aliceHandle.value()).foo, "baz");
+            };
+            // Run the test in both directions, in case they're different types of adapters
+            {
+                const { adapters, teardown } = await setup();
+                const [x, y] = adapters;
+                await doTest(x, y); // x is Alice
+                teardown();
+            }
+            {
+                const { adapters, teardown } = await setup();
+                const [x, y] = adapters;
+                await doTest(y, x); // y is Alice
+                teardown();
+            }
+        });
+        it("can sync 3 repos", async () => {
+            const { adapters, teardown } = await setup();
+            const [a, b, c] = adapters;
+            const aliceRepo = new Repo({ network: a, peerId: alice });
+            const bobRepo = new Repo({ network: b, peerId: bob });
+            const charlieRepo = new Repo({ network: c, peerId: charlie });
+            // Alice creates a document
+            const aliceHandle = aliceRepo.create();
+            const documentId = aliceHandle.documentId;
+            // Bob and Charlie receive the document
+            await eventPromises([bobRepo, charlieRepo], "document");
+            const bobHandle = bobRepo.find(documentId);
+            const charlieHandle = charlieRepo.find(documentId);
+            // Alice changes the document
+            aliceHandle.change(d => {
+                d.foo = "bar";
+            });
+            // Bob and Charlie receive the change
+            await eventPromises([bobHandle, charlieHandle], "change");
+            assert.equal((await bobHandle.value()).foo, "bar");
+            assert.equal((await charlieHandle.value()).foo, "bar");
+            // Charlie changes the document
+            charlieHandle.change(d => {
+                d.foo = "baz";
+            });
+            // Alice and Bob receive the change
+            await eventPromises([aliceHandle, bobHandle], "change");
+            assert.equal((await bobHandle.value()).foo, "baz");
+            assert.equal((await charlieHandle.value()).foo, "baz");
+            teardown();
+        });
+        // TODO: with BroadcastChannel, this test never ends, because it goes into an infinite loop,
+        // because the network has cycles (see #92)
+        it.skip("can broadcast a message", async () => {
+            const { adapters, teardown } = await setup();
+            const [a, b, c] = adapters;
+            const aliceRepo = new Repo({ network: a, peerId: alice });
+            const bobRepo = new Repo({ network: b, peerId: bob });
+            const charlieRepo = new Repo({ network: c, peerId: charlie });
+            await eventPromises([aliceRepo, bobRepo, charlieRepo].map(r => r.networkSubsystem), "peer");
+            const channelId = "broadcast";
+            const alicePresenceData = { presence: "alice" };
+            aliceRepo.ephemeralData.broadcast(channelId, alicePresenceData);
+            const { data } = await eventPromise(charlieRepo.ephemeralData, "data");
+            assert.deepStrictEqual(data, alicePresenceData);
+            teardown();
+        });
+    });
+}
+const NO_OP = () => { };
+const toArray = (x) => (Array.isArray(x) ? x : [x]);
+const alice = "alice";
+const bob = "bob";
+const charlie = "charlie";