@automerge/automerge-repo 1.1.4 → 1.1.8

package/src/Repo.ts

@@ -2,15 +2,18 @@ import { next as Automerge } from "@automerge/automerge"
 import debug from "debug"
 import { EventEmitter } from "eventemitter3"
 import {
-    generateAutomergeUrl,
-    interpretAsDocumentId,
-    parseAutomergeUrl,
+  generateAutomergeUrl,
+  interpretAsDocumentId,
+  parseAutomergeUrl,
 } from "./AutomergeUrl.js"
 import { DocHandle, DocHandleEncodedChangePayload } from "./DocHandle.js"
 import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { throttle } from "./helpers/throttle.js"
-import { NetworkAdapterInterface, type PeerMetadata } from "./network/NetworkAdapterInterface.js"
+import {
+  NetworkAdapterInterface,
+  type PeerMetadata,
+} from "./network/NetworkAdapterInterface.js"
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js"
 import { RepoMessage } from "./network/messages.js"
 import { StorageAdapterInterface } from "./storage/StorageAdapterInterface.js"
@@ -57,12 +60,12 @@ export class Repo extends EventEmitter<RepoEvents> {
 
   constructor({
     storage,
-    network,
+    network = [],
     peerId,
     sharePolicy,
     isEphemeral = storage === undefined,
     enableRemoteHeadsGossiping = false,
-  }: RepoConfig) {
+  }: RepoConfig = {}) {
     super()
     this.#remoteHeadsGossipingEnabled = enableRemoteHeadsGossiping
     this.#log = debug(`automerge-repo:repo`)
@@ -502,6 +505,30 @@ export class Repo extends EventEmitter<RepoEvents> {
       return this.storageSubsystem.id()
     }
   }
+
+  /**
+   * Writes Documents to a disk.
+   * @hidden this API is experimental and may change.
+   * @param documents - if provided, only writes the specified documents.
+   * @returns Promise<void>
+   */
+  async flush(documents?: DocumentId[]): Promise<void> {
+    if (!this.storageSubsystem) {
+      return
+    }
+    const handles = documents
+      ? documents.map(id => this.#handleCache[id])
+      : Object.values(this.#handleCache)
+    await Promise.all(
+      handles.map(async handle => {
+        const doc = handle.docSync()
+        if (!doc) {
+          return
+        }
+        return this.storageSubsystem!.saveDoc(handle.documentId, doc)
+      })
+    )
+  }
 }
 
 export interface RepoConfig {
@@ -515,8 +542,8 @@ export interface RepoConfig {
   /** A storage adapter can be provided, or not */
   storage?: StorageAdapterInterface
 
-  /** One or more network adapters must be provided */
-  network: NetworkAdapterInterface[]
+  /** A list of network adapters (more can be added at runtime). */
+  network?: NetworkAdapterInterface[]
 
   /**
    * Normal peers typically share generously with everyone (meaning we sync all our documents with

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

@@ -17,7 +17,7 @@ import { pause } from "../pause.js"
  * - `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: SetupFn, title?: string): void {
+export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
   // Wrap the provided setup function
   const setup = async () => {
     const { adapters, teardown = NO_OP } = await _setup()
@@ -28,7 +28,9 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
     return { adapters: [a, b, c], teardown }
   }
 
-  describe(`Adapter acceptance tests ${title ? `(${title})` : ""}`, () => {
+  describe(`Network adapter acceptance tests ${
+    title ? `(${title})` : ""
+  }`, () => {
     it("can sync 2 repos", async () => {
       const doTest = async (
         a: NetworkAdapterInterface[],

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

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest"
+
+import type { StorageAdapterInterface } from "../../storage/StorageAdapterInterface.js"
+
+const PAYLOAD_A = () => new Uint8Array([0, 1, 127, 99, 154, 235])
+const PAYLOAD_B = () => new Uint8Array([1, 76, 160, 53, 57, 10, 230])
+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 }
+  }
+
+  describe(`Storage adapter acceptance tests ${
+    title ? `(${title})` : ""
+  }`, () => {
+    describe("load", () => {
+      it("should return undefined if there is no data", async () => {
+        const { adapter, teardown } = await setup()
+
+        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()
+
+        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()
+
+        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()
+
+        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()
+
+        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()
+
+        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()
+      })
+
+      it("should only load values that match they key", async () => {
+        const { adapter, teardown } = await setup()
+
+        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()
+      })
+    })
+
+    describe("save and remove", () => {
+      it("after removing, should be empty", async () => {
+        const { adapter, teardown } = await setup()
+
+        await adapter.save(["AAAAA", "snapshot", "xxxxx"], PAYLOAD_A())
+        await adapter.remove(["AAAAA", "snapshot", "xxxxx"])
+
+        expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([])
+        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()
+
+        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()
+
+        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())
+
+        await adapter.removeRange(["AAAAA", "sync-state"])
+
+        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()
+
+        await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A())
+        await adapter.save(["BBBBB", "sync-state", "zzzzz"], PAYLOAD_B())
+
+        await adapter.removeRange(["AAAAA"])
+
+        const actual = await adapter.loadRange(["BBBBB"])
+        expect(actual).toStrictEqual([
+          { key: ["BBBBB", "sync-state", "zzzzz"], data: PAYLOAD_B() },
+        ])
+
+        teardown()
+      })
+    })
+  })
+}
+
+const NO_OP = () => {}
+
+export type SetupFn = () => Promise<{
+  adapter: StorageAdapterInterface
+  teardown?: () => void
+}>

package/src/index.ts

@@ -90,3 +90,46 @@ export type {
 } from "./storage/types.js"
 
 export * from "./types.js"
+
+// export commonly used data types
+export type { Counter, RawString, Cursor } from "@automerge/automerge/next"
+
+// export some automerge API types
+export type {
+  Doc,
+  Heads,
+  Patch,
+  PatchCallback,
+  Prop,
+  ActorId,
+  Change,
+  ChangeFn,
+  Mark,
+  MarkSet,
+  MarkRange,
+  MarkValue,
+} from "@automerge/automerge/next"
+
+// export a few utility functions that aren't in automerge-repo
+// NB that these should probably all just be available via the dochandle
+export {
+  getChanges,
+  getAllChanges,
+  applyChanges,
+  view,
+  getConflicts,
+} from "@automerge/automerge/next"
+
+// export type-specific utility functions
+// these mostly can't be on the data-type in question because
+// JS strings can't have methods added to them
+export {
+  getCursor,
+  getCursorPosition,
+  splice,
+  updateText,
+  insertAt,
+  deleteAt,
+  mark,
+  unmark,
+} from "@automerge/automerge/next"

package/src/synchronizer/DocSynchronizer.ts

@@ -228,7 +228,7 @@ export class DocSynchronizer extends Synchronizer {
 
   beginSync(peerIds: PeerId[]) {
     const noPeersWithDocument = peerIds.every(
-      (peerId) => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]
+      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

package/test/CollectionSynchronizer.test.ts

@@ -8,9 +8,7 @@ describe("CollectionSynchronizer", () => {
   let synchronizer: CollectionSynchronizer
 
   beforeEach(() => {
-    repo = new Repo({
-      network: [],
-    })
+    repo = new Repo()
     synchronizer = new CollectionSynchronizer(repo)
   })
 

package/test/DocHandle.test.ts

@@ -72,6 +72,24 @@ describe("DocHandle", () => {
     assert.equal(doc?.foo, "bar")
   })
 
+  it("should return the heads when requested", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, {
+      isNew: true,
+      initialValue: { foo: "bar" },
+    })
+    assert.equal(handle.isReady(), true)
+
+    const heads = A.getHeads(handle.docSync())
+    assert.notDeepEqual(handle.heads(), [])
+    assert.deepEqual(heads, handle.heads())
+  })
+
+  it("should return undefined if the heads aren't loaded", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+    assert.equal(handle.isReady(), false)
+    assert.deepEqual(handle.heads(), undefined)
+  })
+
   /**
    * Once there's a Repo#stop API this case should be covered in accompanying
    * tests and the following test removed.
@@ -319,7 +337,7 @@ describe("DocHandle", () => {
       doc.foo = "bar"
     })
 
-    const headsBefore = A.getHeads(handle.docSync()!)
+    const headsBefore = handle.heads()!
 
     handle.change(doc => {
       doc.foo = "rab"

package/test/DocSynchronizer.test.ts

@@ -68,10 +68,7 @@ describe("DocSynchronizer", () => {
 
     assert.equal(message2.peerId, "alice")
     assert.equal(message2.documentId, handle.documentId)
-    assert.deepEqual(
-      message2.syncState.lastSentHeads,
-      A.getHeads(handle.docSync())
-    )
+    assert.deepEqual(message2.syncState.lastSentHeads, handle.heads())
   })
 
   it("still syncs with a peer after it disconnects and reconnects", async () => {

package/test/DummyStorageAdapter.test.ts

@@ -0,0 +1,11 @@
+import { beforeEach, describe } from "vitest"
+import { DummyStorageAdapter } from "./helpers/DummyStorageAdapter.js"
+import { runStorageAdapterTests } from "../src/helpers/tests/storage-adapter-tests.js"
+
+describe("DummyStorageAdapter", () => {
+  const setup = async () => ({
+    adapter: new DummyStorageAdapter(),
+  })
+
+  runStorageAdapterTests(setup, "DummyStorageAdapter")
+})