@automerge/automerge-repo 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/Repo.ts

@@ -2,11 +2,20 @@ import { next as Automerge } from "@automerge/automerge/slim"
 import debug from "debug"
 import { EventEmitter } from "eventemitter3"
 import {
+  encodeHeads,
   generateAutomergeUrl,
   interpretAsDocumentId,
+  isValidAutomergeUrl,
   parseAutomergeUrl,
 } from "./AutomergeUrl.js"
-import { DocHandle, DocHandleEncodedChangePayload } from "./DocHandle.js"
+import {
+  DELETED,
+  DocHandle,
+  DocHandleEncodedChangePayload,
+  READY,
+  UNAVAILABLE,
+  UNLOADED,
+} from "./DocHandle.js"
 import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { throttle } from "./helpers/throttle.js"
@@ -20,8 +29,16 @@ import { StorageAdapterInterface } from "./storage/StorageAdapterInterface.js"
 import { StorageSubsystem } from "./storage/StorageSubsystem.js"
 import { StorageId } from "./storage/types.js"
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
-import { SyncStatePayload } from "./synchronizer/Synchronizer.js"
-import type { AnyDocumentId, DocumentId, PeerId } from "./types.js"
+import {
+  DocSyncMetrics,
+  SyncStatePayload,
+} from "./synchronizer/Synchronizer.js"
+import type {
+  AnyDocumentId,
+  AutomergeUrl,
+  DocumentId,
+  PeerId,
+} from "./types.js"
 
 function randomPeerId() {
   return ("peer-" + Math.random().toString(36).slice(4)) as PeerId
@@ -49,7 +66,8 @@ export class Repo extends EventEmitter<RepoEvents> {
 
   #handleCache: Record<DocumentId, DocHandle<any>> = {}
 
-  #synchronizer: CollectionSynchronizer
+  /** @hidden */
+  synchronizer: CollectionSynchronizer
 
   /** By default, we share generously with all peers. */
   /** @hidden */
@@ -69,39 +87,13 @@ export class Repo extends EventEmitter<RepoEvents> {
     sharePolicy,
     isEphemeral = storage === undefined,
     enableRemoteHeadsGossiping = false,
+    denylist = [],
   }: RepoConfig = {}) {
     super()
     this.#remoteHeadsGossipingEnabled = enableRemoteHeadsGossiping
     this.#log = debug(`automerge-repo:repo`)
     this.sharePolicy = sharePolicy ?? this.sharePolicy
 
-    // DOC COLLECTION
-
-    // The `document` event is fired by the DocCollection any time we create a new document or look
-    // up a document by ID. We listen for it in order to wire up storage and network synchronization.
-    this.on("document", async ({ handle }) => {
-      if (storageSubsystem) {
-        // Save when the document changes, but no more often than saveDebounceRate.
-        const saveFn = ({
-          handle,
-          doc,
-        }: DocHandleEncodedChangePayload<any>) => {
-          void storageSubsystem.saveDoc(handle.documentId, doc)
-        }
-        handle.on("heads-changed", throttle(saveFn, this.saveDebounceRate))
-      }
-
-      handle.on("unavailable", () => {
-        this.#log("document unavailable", { documentId: handle.documentId })
-        this.emit("unavailable-document", {
-          documentId: handle.documentId,
-        })
-      })
-
-      // Register the document with the synchronizer. This advertises our interest in the document.
-      this.#synchronizer.addDocument(handle.documentId)
-    })
-
     this.on("delete-document", ({ documentId }) => {
       // TODO Pass the delete on to the network
       // synchronizer.removeDocument(documentId)
@@ -115,16 +107,19 @@ export class Repo extends EventEmitter<RepoEvents> {
 
     // SYNCHRONIZER
     // The synchronizer uses the network subsystem to keep documents in sync with peers.
-    this.#synchronizer = new CollectionSynchronizer(this)
+    this.synchronizer = new CollectionSynchronizer(this, denylist)
 
     // When the synchronizer emits messages, send them to peers
-    this.#synchronizer.on("message", message => {
+    this.synchronizer.on("message", message => {
       this.#log(`sending ${message.type} message to ${message.targetId}`)
       networkSubsystem.send(message)
     })
 
+    // Forward metrics from doc synchronizers
+    this.synchronizer.on("metrics", event => this.emit("doc-metrics", event))
+
     if (this.#remoteHeadsGossipingEnabled) {
-      this.#synchronizer.on("open-doc", ({ peerId, documentId }) => {
+      this.synchronizer.on("open-doc", ({ peerId, documentId }) => {
         this.#remoteHeadsSubscriptions.subscribePeerToDoc(peerId, documentId)
       })
     }
@@ -132,6 +127,12 @@ export class Repo extends EventEmitter<RepoEvents> {
     // STORAGE
     // The storage subsystem has access to some form of persistence, and deals with save and loading documents.
     const storageSubsystem = storage ? new StorageSubsystem(storage) : undefined
+    if (storageSubsystem) {
+      storageSubsystem.on("document-loaded", event =>
+        this.emit("doc-metrics", { type: "doc-loaded", ...event })
+      )
+    }
+
     this.storageSubsystem = storageSubsystem
 
     // NETWORK
@@ -167,12 +168,12 @@ export class Repo extends EventEmitter<RepoEvents> {
           console.log("error in share policy", { err })
         })
 
-      this.#synchronizer.addPeer(peerId)
+      this.synchronizer.addPeer(peerId)
     })
 
     // When a peer disconnects, remove it from the synchronizer
     networkSubsystem.on("peer-disconnected", ({ peerId }) => {
-      this.#synchronizer.removePeer(peerId)
+      this.synchronizer.removePeer(peerId)
       this.#remoteHeadsSubscriptions.removePeer(peerId)
     })
 
@@ -181,7 +182,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       this.#receiveMessage(msg)
     })
 
-    this.#synchronizer.on("sync-state", message => {
+    this.synchronizer.on("sync-state", message => {
       this.#saveSyncState(message)
 
       const handle = this.#handleCache[message.documentId]
@@ -194,16 +195,20 @@ export class Repo extends EventEmitter<RepoEvents> {
       const heads = handle.getRemoteHeads(storageId)
       const haveHeadsChanged =
         message.syncState.theirHeads &&
-        (!heads || !headsAreSame(heads, message.syncState.theirHeads))
+        (!heads ||
+          !headsAreSame(heads, encodeHeads(message.syncState.theirHeads)))
 
       if (haveHeadsChanged && message.syncState.theirHeads) {
-        handle.setRemoteHeads(storageId, message.syncState.theirHeads)
+        handle.setRemoteHeads(
+          storageId,
+          encodeHeads(message.syncState.theirHeads)
+        )
 
         if (storageId && this.#remoteHeadsGossipingEnabled) {
           this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(
             message.documentId,
             storageId,
-            message.syncState.theirHeads
+            encodeHeads(message.syncState.theirHeads)
           )
         }
       }
@@ -243,6 +248,32 @@ export class Repo extends EventEmitter<RepoEvents> {
     }
   }
 
+  // The `document` event is fired by the DocCollection any time we create a new document or look
+  // up a document by ID. We listen for it in order to wire up storage and network synchronization.
+  #registerHandleWithSubsystems(handle: DocHandle<any>) {
+    const { storageSubsystem } = this
+    if (storageSubsystem) {
+      // Save when the document changes, but no more often than saveDebounceRate.
+      const saveFn = ({ handle, doc }: DocHandleEncodedChangePayload<any>) => {
+        void storageSubsystem.saveDoc(handle.documentId, doc)
+      }
+      handle.on("heads-changed", throttle(saveFn, this.saveDebounceRate))
+    }
+
+    handle.on("unavailable", () => {
+      this.#log("document unavailable", { documentId: handle.documentId })
+      this.emit("unavailable-document", {
+        documentId: handle.documentId,
+      })
+    })
+
+    // Register the document with the synchronizer. This advertises our interest in the document.
+    this.synchronizer.addDocument(handle.documentId)
+
+    // Preserve the old event in case anyone was using it.
+    this.emit("document", { handle })
+  }
+
   #receiveMessage(message: RepoMessage) {
     switch (message.type) {
       case "remote-subscription-change":
@@ -259,7 +290,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       case "request":
       case "ephemeral":
       case "doc-unavailable":
-        this.#synchronizer.receiveMessage(message).catch(err => {
+        this.synchronizer.receiveMessage(message).catch(err => {
           console.log("error receiving message", { err })
         })
     }
@@ -324,7 +355,7 @@ export class Repo extends EventEmitter<RepoEvents> {
 
   /** Returns a list of all connected peer ids */
   get peers(): PeerId[] {
-    return this.#synchronizer.peers
+    return this.synchronizer.peers
   }
 
   getStorageIdOfPeer(peerId: PeerId): StorageId | undefined {
@@ -343,7 +374,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       documentId,
     }) as DocHandle<T>
 
-    this.emit("document", { handle })
+    this.#registerHandleWithSubsystems(handle)
 
     handle.update(() => {
       let nextDoc: Automerge.Doc<T>
@@ -378,7 +409,7 @@ export class Repo extends EventEmitter<RepoEvents> {
     if (!clonedHandle.isReady()) {
       throw new Error(
         `Cloned handle is not yet in ready state.
-        (Try await handle.waitForReady() first.)`
+        (Try await handle.whenReady() first.)`
       )
     }
 
@@ -405,19 +436,22 @@ export class Repo extends EventEmitter<RepoEvents> {
     /** The url or documentId of the handle to retrieve */
     id: AnyDocumentId
   ): DocHandle<T> {
-    const documentId = interpretAsDocumentId(id)
+    const { documentId, heads } = isValidAutomergeUrl(id)
+      ? parseAutomergeUrl(id)
+      : { documentId: interpretAsDocumentId(id), heads: undefined }
 
-    // If we have the handle cached, return it
-    if (this.#handleCache[documentId]) {
-      if (this.#handleCache[documentId].isUnavailable()) {
+    const cachedHandle = this.#handleCache[documentId]
+    if (cachedHandle) {
+      if (cachedHandle.isUnavailable()) {
         // this ensures that the event fires after the handle has been returned
         setTimeout(() => {
-          this.#handleCache[documentId].emit("unavailable", {
-            handle: this.#handleCache[documentId],
+          cachedHandle.emit("unavailable", {
+            handle: cachedHandle,
           })
         })
       }
-      return this.#handleCache[documentId]
+      // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+      return heads ? cachedHandle.view(heads) : cachedHandle
     }
 
     // If we don't already have the handle, make an empty one and try loading it
@@ -425,30 +459,32 @@ export class Repo extends EventEmitter<RepoEvents> {
       documentId,
     }) as DocHandle<T>
 
-    // Try to load from disk before telling anyone else about it
-    if (this.storageSubsystem) {
-      void this.storageSubsystem.loadDoc(handle.documentId).then(loadedDoc => {
+    // Loading & network is going to be asynchronous no matter what,
+    // but we want to return the handle immediately.
+    const attemptLoad = this.storageSubsystem
+      ? this.storageSubsystem.loadDoc(handle.documentId)
+      : Promise.resolve(null)
+
+    attemptLoad
+      .then(async loadedDoc => {
         if (loadedDoc) {
           // uhhhh, sorry if you're reading this because we were lying to the type system
           handle.update(() => loadedDoc as Automerge.Doc<T>)
           handle.doneLoading()
         } else {
-          this.networkSubsystem
-            .whenReady()
-            .then(() => {
-              handle.request()
-            })
-            .catch(err => {
-              this.#log("error waiting for network", { err })
-            })
-          this.emit("document", { handle })
+          // we want to wait for the network subsystem to be ready before
+          // we request the document. this prevents entering unavailable during initialization.
+          await this.networkSubsystem.whenReady()
+          handle.request()
         }
+        this.#registerHandleWithSubsystems(handle)
       })
-    } else {
-      handle.request()
-      this.emit("document", { handle })
-    }
-    return handle
+      .catch(err => {
+        this.#log("error waiting for network", { err })
+      })
+
+    // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+    return heads ? handle.view(heads) : handle
   }
 
   delete(
@@ -539,12 +575,49 @@ export class Repo extends EventEmitter<RepoEvents> {
     )
   }
 
+  /**
+   * Removes a DocHandle from the handleCache.
+   * @hidden this API is experimental and may change.
+   * @param documentId - documentId of the DocHandle to remove from handleCache, if present in cache.
+   * @returns Promise<void>
+   */
+  async removeFromCache(documentId: DocumentId) {
+    if (!this.#handleCache[documentId]) {
+      this.#log(
+        `WARN: removeFromCache called but handle not found in handleCache for documentId: ${documentId}`
+      )
+      return
+    }
+    const handle = this.#getHandle({ documentId })
+    const doc = await handle.doc([READY, UNLOADED, DELETED, UNAVAILABLE])
+    if (doc) {
+      if (handle.isReady()) {
+        handle.unload()
+      } else {
+        this.#log(
+          `WARN: removeFromCache called but handle for documentId: ${documentId} in unexpected state: ${handle.state}`
+        )
+      }
+      delete this.#handleCache[documentId]
+      // TODO: remove document from synchronizer when removeDocument is implemented
+      // this.synchronizer.removeDocument(documentId)
+    } else {
+      this.#log(
+        `WARN: removeFromCache called but doc undefined for documentId: ${documentId}`
+      )
+    }
+  }
+
   shutdown(): Promise<void> {
     this.networkSubsystem.adapters.forEach(adapter => {
       adapter.disconnect()
     })
     return this.flush()
   }
+
+  metrics(): { documents: { [key: string]: any } } {
+    return { documents: this.synchronizer.metrics() }
+  }
 }
 
 export interface RepoConfig {
@@ -571,6 +644,13 @@ export interface RepoConfig {
    * Whether to enable the experimental remote heads gossiping feature
    */
   enableRemoteHeadsGossiping?: boolean
+
+  /**
+   * A list of automerge URLs which should never be loaded regardless of what
+   * messages are received or what the share policy is. This is useful to avoid
+   * loading documents that are known to be too resource intensive.
+   */
+  denylist?: AutomergeUrl[]
 }
 
 /** A function that determines whether we should share a document with a peer
@@ -594,6 +674,7 @@ export interface RepoEvents {
   "delete-document": (arg: DeleteDocumentPayload) => void
   /** A document was marked as unavailable (we don't have it and none of our peers have it) */
   "unavailable-document": (arg: DeleteDocumentPayload) => void
+  "doc-metrics": (arg: DocMetrics) => void
 }
 
 export interface DocumentPayload {
@@ -603,3 +684,17 @@ export interface DocumentPayload {
 export interface DeleteDocumentPayload {
   documentId: DocumentId
 }
+
+export type DocMetrics =
+  | DocSyncMetrics
+  | {
+      type: "doc-loaded"
+      documentId: DocumentId
+      durationMillis: number
+      numOps: number
+      numChanges: number
+    }
+  | {
+      type: "doc-denied"
+      documentId: DocumentId
+    }

package/src/entrypoints/fullfat.ts

@@ -7,5 +7,4 @@ export * from "../index.js"
 // disable
 //
 // eslint-disable-next-line automerge-slimport/enforce-automerge-slim-import
-import { next as Am } from "@automerge/automerge"
-Am.init()
+import "@automerge/automerge"

package/src/helpers/bufferFromHex.ts

@@ -0,0 +1,14 @@
+export const uint8ArrayFromHexString = (hexString: string): Uint8Array => {
+  if (hexString.length % 2 !== 0) {
+    throw new Error("Hex string must have an even length")
+  }
+  const bytes = new Uint8Array(hexString.length / 2)
+  for (let i = 0; i < hexString.length; i += 2) {
+    bytes[i >> 1] = parseInt(hexString.slice(i, i + 2), 16)
+  }
+  return bytes
+}
+
+export const uint8ArrayToHexString = (data: Uint8Array): string => {
+  return Array.from(data, byte => byte.toString(16).padStart(2, "0")).join("")
+}

package/src/helpers/headsAreSame.ts

@@ -1,6 +1,6 @@
-import { Heads } from "@automerge/automerge/slim/next"
 import { arraysAreEqual } from "./arraysAreEqual.js"
+import type { UrlHeads } from "../types.js"
 
-export const headsAreSame = (a: Heads, b: Heads) => {
+export const headsAreSame = (a: UrlHeads, b: UrlHeads) => {
   return arraysAreEqual(a, b)
 }

package/src/helpers/tests/storage-adapter-tests.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest"
+import { describe, expect, beforeEach, it as _it } from "vitest"
 
 import type { StorageAdapterInterface } from "../../storage/StorageAdapterInterface.js"
 
@@ -8,120 +8,90 @@ const PAYLOAD_C = () => new Uint8Array([2, 111, 74, 131, 236, 96, 142, 193])
 
 const LARGE_PAYLOAD = new Uint8Array(100000).map(() => Math.random() * 256)
 
-export function runStorageAdapterTests(_setup: SetupFn, title?: string): void {
-  const setup = async () => {
-    const { adapter, teardown = NO_OP } = await _setup()
-    return { adapter, teardown }
-  }
+type AdapterTestContext = {
+  adapter: StorageAdapterInterface
+}
+
+const it = _it<AdapterTestContext>
+
+export function runStorageAdapterTests(setup: SetupFn, title?: string): void {
+  beforeEach<AdapterTestContext>(async ctx => {
+    const { adapter, teardown = NO_OP } = await setup()
+    ctx.adapter = adapter
+    return teardown
+  })
 
   describe(`Storage adapter acceptance tests ${
     title ? `(${title})` : ""
   }`, () => {
     describe("load", () => {
-      it("should return undefined if there is no data", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should return undefined if there is no data", async ({ adapter }) => {
         const actual = await adapter.load(["AAAAA", "sync-state", "xxxxx"])
         expect(actual).toBeUndefined()
-
-        teardown()
       })
     })
 
     describe("save and load", () => {
-      it("should return data that was saved", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should return data that was saved", async ({ adapter }) => {
         await adapter.save(["storage-adapter-id"], PAYLOAD_A())
         const actual = await adapter.load(["storage-adapter-id"])
         expect(actual).toStrictEqual(PAYLOAD_A())
-
-        teardown()
       })
 
-      it("should work with composite keys", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should work with composite keys", async ({ adapter }) => {
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A())
         const actual = await adapter.load(["AAAAA", "sync-state", "xxxxx"])
         expect(actual).toStrictEqual(PAYLOAD_A())
-
-        teardown()
       })
 
-      it("should work with a large payload", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should work with a large payload", async ({ adapter }) => {
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], LARGE_PAYLOAD)
         const actual = await adapter.load(["AAAAA", "sync-state", "xxxxx"])
         expect(actual).toStrictEqual(LARGE_PAYLOAD)
-
-        teardown()
       })
     })
 
     describe("loadRange", () => {
-      it("should return an empty array if there is no data", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should return an empty array if there is no data", async ({
+        adapter,
+      }) => {
         expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([])
-
-        teardown()
       })
     })
 
     describe("save and loadRange", () => {
-      it("should return all the data that matches the key", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should return all the data that matches the key", async ({
+        adapter,
+      }) => {
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A())
         await adapter.save(["AAAAA", "snapshot", "yyyyy"], PAYLOAD_B())
         await adapter.save(["AAAAA", "sync-state", "zzzzz"], PAYLOAD_C())
 
-        expect(await adapter.loadRange(["AAAAA"])).toStrictEqual(
-          expect.arrayContaining([
-            { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-            { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
-            { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-          ])
-        )
-
-        expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual(
-          expect.arrayContaining([
-            { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-            { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-          ])
-        )
-
-        teardown()
-      })
+        expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([
+          { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
+          { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
+          { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
+        ])
 
-      it("should only load values that match they key", async () => {
-        const { adapter, teardown } = await setup()
+        expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual([
+          { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
+          { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
+        ])
+      })
 
+      it("should only load values that match they key", async ({ adapter }) => {
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A())
         await adapter.save(["BBBBB", "sync-state", "zzzzz"], PAYLOAD_C())
 
         const actual = await adapter.loadRange(["AAAAA"])
-        expect(actual).toStrictEqual(
-          expect.arrayContaining([
-            { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-          ])
-        )
-        expect(actual).toStrictEqual(
-          expect.not.arrayContaining([
-            { key: ["BBBBB", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-          ])
-        )
-
-        teardown()
+        expect(actual).toStrictEqual([
+          { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
+        ])
       })
     })
 
     describe("save and remove", () => {
-      it("after removing, should be empty", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("after removing, should be empty", async ({ adapter }) => {
         await adapter.save(["AAAAA", "snapshot", "xxxxx"], PAYLOAD_A())
         await adapter.remove(["AAAAA", "snapshot", "xxxxx"])
 
@@ -129,30 +99,24 @@ export function runStorageAdapterTests(_setup: SetupFn, title?: string): void {
         expect(
           await adapter.load(["AAAAA", "snapshot", "xxxxx"])
         ).toBeUndefined()
-
-        teardown()
       })
     })
 
     describe("save and save", () => {
-      it("should overwrite data saved with the same key", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should overwrite data saved with the same key", async ({
+        adapter,
+      }) => {
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A())
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_B())
 
         expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual([
           { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_B() },
         ])
-
-        teardown()
       })
     })
 
     describe("removeRange", () => {
-      it("should remove a range of records", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should remove a range of records", async ({ adapter }) => {
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A())
         await adapter.save(["AAAAA", "snapshot", "yyyyy"], PAYLOAD_B())
         await adapter.save(["AAAAA", "sync-state", "zzzzz"], PAYLOAD_C())
@@ -162,13 +126,9 @@ export function runStorageAdapterTests(_setup: SetupFn, title?: string): void {
         expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([
           { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
         ])
-
-        teardown()
       })
 
-      it("should not remove records that don't match", async () => {
-        const { adapter, teardown } = await setup()
-
+      it("should not remove records that don't match", async ({ adapter }) => {
         await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A())
         await adapter.save(["BBBBB", "sync-state", "zzzzz"], PAYLOAD_B())
 
@@ -178,8 +138,6 @@ export function runStorageAdapterTests(_setup: SetupFn, title?: string): void {
         expect(actual).toStrictEqual([
           { key: ["BBBBB", "sync-state", "zzzzz"], data: PAYLOAD_B() },
         ])
-
-        teardown()
       })
     })
   })
@@ -189,5 +147,5 @@ const NO_OP = () => {}
 
 export type SetupFn = () => Promise<{
   adapter: StorageAdapterInterface
-  teardown?: () => void
+  teardown?: () => void | Promise<void>
 }>

package/src/index.ts

@@ -34,6 +34,8 @@ export {
   stringifyAutomergeUrl,
   interpretAsDocumentId,
   generateAutomergeUrl,
+  encodeHeads,
+  decodeHeads,
 } from "./AutomergeUrl.js"
 export { Repo } from "./Repo.js"
 export { NetworkAdapter } from "./network/NetworkAdapter.js"