@automerge/automerge-repo 1.1.5 → 1.1.9

package/src/Repo.ts

@@ -60,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`)
@@ -507,30 +507,27 @@ export class Repo extends EventEmitter<RepoEvents> {
   }
 
   /**
-   * Waits for Repo to finish write changes to disk.
-   * @hidden this API is experimental and may change
-   * @param documents - if provided, only waits for the specified documents
-   * @param timeout - if provided, the maximum time to wait in milliseconds (rejects on timeout)
+   * 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[], timeout?: number): Promise<void> {
+  async flush(documents?: DocumentId[]): Promise<void> {
     if (!this.storageSubsystem) {
-      return Promise.resolve()
+      return
     }
     const handles = documents
       ? documents.map(id => this.#handleCache[id])
       : Object.values(this.#handleCache)
-    return Promise.all(
+    await Promise.all(
       handles.map(async handle => {
         const doc = handle.docSync()
         if (!doc) {
           return
         }
-        return this.storageSubsystem!.flush(handle.documentId, doc, timeout)
+        return this.storageSubsystem!.saveDoc(handle.documentId, doc)
       })
-    ).then(() => {
-      /* No-op. To return `voi`d and not `void[]` */
-    })
+    )
   }
 }
 
@@ -545,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/index.ts

@@ -90,3 +90,46 @@ export type {
 } from "./storage/types.js"
 
 export * from "./types.js"
+
+// export commonly used data types
+export { 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/storage/StorageSubsystem.ts

@@ -8,7 +8,6 @@ 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"
 
 /**
  * The storage subsystem is responsible for saving and loading Automerge documents to and from
@@ -29,8 +28,6 @@ export class StorageSubsystem {
 
   #log = debug(`automerge-repo:storage-subsystem`)
 
-  #saved = new EventEmitter<{ saved: () => void }>()
-
   constructor(storageAdapter: StorageAdapterInterface) {
     this.#storageAdapter = storageAdapter
   }
@@ -159,7 +156,6 @@ export class StorageSubsystem {
       await this.#saveIncremental(documentId, doc)
     }
     this.#storedHeads.set(documentId, A.getHeads(doc))
-    this.#saved.emit("saved")
   }
 
   /**
@@ -249,34 +245,6 @@ export class StorageSubsystem {
     await this.#storageAdapter.save(key, A.encodeSyncState(syncState))
   }
 
-  /**
-   * Waiting for document state to be written to disk.
-   * @deprecated because it will be changed soon.
-   */
-  async flush(documentId: DocumentId, doc: A.Doc<unknown>, timeout?: number) {
-    return new Promise<void>((resolve, reject) => {
-      let timeoutId: NodeJS.Timeout
-      if (timeout) {
-        timeoutId = setTimeout(() => {
-          this.#saved.off("saved", checkIfSaved)
-          reject(new Error("Timed out waiting for save"))
-        }, timeout)
-      }
-
-      const checkIfSaved = () => {
-        if (!this.#shouldSave(documentId, doc)) {
-          this.#saved.off("saved", checkIfSaved)
-          clearTimeout(timeoutId)
-          resolve()
-        }
-      }
-
-      this.#saved.on("saved", checkIfSaved)
-
-      checkIfSaved()
-    })
-  }
-
   /**
    * Returns true if the document has changed since the last time it was saved.
    */

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/Repo.test.ts

@@ -3,7 +3,6 @@ import { MessageChannelNetworkAdapter } from "../../automerge-repo-network-messa
 import assert from "assert"
 import * as Uuid from "uuid"
 import { describe, expect, it } from "vitest"
-import { HandleState, READY } from "../src/DocHandle.js"
 import { parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import {
   generateAutomergeUrl,
@@ -29,14 +28,12 @@ import {
 } from "./helpers/generate-large-object.js"
 import { getRandomItem } from "./helpers/getRandomItem.js"
 import { TestDoc } from "./types.js"
-import { StorageId } from "../src/storage/types.js"
+import { StorageId, StorageKey } from "../src/storage/types.js"
 
 describe("Repo", () => {
   describe("constructor", () => {
-    it("can be instantiated without network adapters", () => {
-      const repo = new Repo({
-        network: [],
-      })
+    it("can be instantiated without any configuration", () => {
+      const repo = new Repo()
       expect(repo).toBeInstanceOf(Repo)
     })
   })
@@ -126,8 +123,7 @@ describe("Repo", () => {
       })
       const v = await handle.doc()
       assert.equal(handle.isReady(), true)
-
-      assert.equal(v?.foo, "bar")
+      assert.equal(v.foo, "bar")
     })
 
     it("can clone a document", () => {
@@ -207,12 +203,11 @@ describe("Repo", () => {
       assert.equal(doc, undefined)
     })
 
-    it("fires an 'unavailable' event when you don't have the document locally and network to connect to", async () => {
+    it("emits an unavailable event when you don't have the document locally and are not connected to anyone", async () => {
       const { repo } = setup()
       const url = generateAutomergeUrl()
       const handle = repo.find<TestDoc>(url)
       assert.equal(handle.isReady(), false)
-
       await eventPromise(handle, "unavailable")
     })
 
@@ -255,7 +250,6 @@ describe("Repo", () => {
 
       const repo2 = new Repo({
         storage: storageAdapter,
-        network: [],
       })
 
       const bobHandle = repo2.find<TestDoc>(handle.url)
@@ -277,7 +271,6 @@ describe("Repo", () => {
 
       const repo2 = new Repo({
         storage: storageAdapter,
-        network: [],
       })
 
       const bobHandle = repo2.find<TestDoc>(handle.url)
@@ -364,7 +357,6 @@ describe("Repo", () => {
 
       const repo = new Repo({
         storage,
-        network: [],
       })
 
       const handle = repo.create<{ count: number }>()
@@ -382,7 +374,6 @@ describe("Repo", () => {
 
       const repo2 = new Repo({
         storage,
-        network: [],
       })
       const handle2 = repo2.find(handle.url)
       await handle2.doc()
@@ -395,7 +386,6 @@ describe("Repo", () => {
 
       const repo = new Repo({
         storage,
-        network: [],
       })
 
       const handle = repo.create<{ count: number }>()
@@ -410,7 +400,6 @@ describe("Repo", () => {
       for (let i = 0; i < 3; i++) {
         const repo2 = new Repo({
           storage,
-          network: [],
         })
         const handle2 = repo2.find(handle.url)
         await handle2.doc()
@@ -451,40 +440,66 @@ describe("Repo", () => {
       expect(A.getHistory(v)).toEqual(A.getHistory(updatedDoc))
     })
 
-    it("throws an error if we try to import an invalid document", async () => {
+    it("throws an error if we try to import a nonsensical byte array", async () => {
       const { repo } = setup()
       expect(() => {
-        repo.import<TestDoc>(A.init<TestDoc> as unknown as Uint8Array)
+        repo.import<TestDoc>(new Uint8Array([1, 2, 3]))
       }).toThrow()
     })
+
+    // TODO: not sure if this is the desired behavior from `import`.
+
+    it("makes an empty document if we try to import an automerge doc", async () => {
+      const { repo } = setup()
+      // @ts-ignore - passing something other than UInt8Array
+      const handle = repo.import<TestDoc>(A.from({ foo: 123 }))
+      const doc = await handle.doc()
+      expect(doc).toEqual({})
+    })
+
+    it("makes an empty document if we try to import a plain object", async () => {
+      const { repo } = setup()
+      // @ts-ignore - passing something other than UInt8Array
+      const handle = repo.import<TestDoc>({ foo: 123 })
+      const doc = await handle.doc()
+      expect(doc).toEqual({})
+    })
   })
 
   describe("flush behaviour", () => {
     const setup = () => {
-      let blockedSaves = []
-      let resume = () => {
-        blockedSaves.forEach(resolve => resolve())
-        blockedSaves = []
+      let blockedSaves = new Set<{ path: StorageKey; resolve: () => void }>()
+      let resume = (documentIds?: DocumentId[]) => {
+        const savesToUnblock = documentIds
+          ? Array.from(blockedSaves).filter(({ path }) =>
+              documentIds.some(documentId => path.includes(documentId))
+            )
+          : Array.from(blockedSaves)
+        savesToUnblock.forEach(({ resolve }) => resolve())
       }
       const pausedStorage = new DummyStorageAdapter()
       {
         const originalSave = pausedStorage.save.bind(pausedStorage)
         pausedStorage.save = async (...args) => {
-          await new Promise(resolve => {
-            console.log("made a promise", ...args[0])
-            blockedSaves.push(resolve)
+          await new Promise<void>(resolve => {
+            const blockedSave = {
+              path: args[0],
+              resolve: () => {
+                resolve()
+                blockedSaves.delete(blockedSave)
+              },
+            }
+            blockedSaves.add(blockedSave)
           })
           await pause(0)
           // otherwise all the save promises resolve together
           // which prevents testing flushing a single docID
-          console.log("resuming save", ...args[0])
           return originalSave(...args)
         }
       }
 
       const repo = new Repo({
         storage: pausedStorage,
-        network: [],
       })
 
       // Create a pair of handles
@@ -501,7 +516,6 @@ describe("Repo", () => {
       // Reload repo
       const repo2 = new Repo({
         storage: pausedStorage,
-        network: [],
       })
 
       // Could not find the document that is not yet saved because of slow storage.
@@ -524,7 +538,6 @@ describe("Repo", () => {
         // Reload repo
         const repo = new Repo({
           storage: pausedStorage,
-          network: [],
         })
 
         expect(
@@ -540,7 +553,7 @@ describe("Repo", () => {
       const { resume, pausedStorage, repo, handle, handle2 } = setup()
 
       const flushPromise = repo.flush([handle.documentId])
-      resume()
+      resume([handle.documentId])
       await flushPromise
 
       // Check that the data is now saved.
@@ -550,7 +563,6 @@ describe("Repo", () => {
         // Reload repo
         const repo = new Repo({
           storage: pausedStorage,
-          network: [],
         })
 
         expect(
@@ -564,14 +576,22 @@ describe("Repo", () => {
       }
     })
 
-    it("should time out with failure after a specified delay", async () => {
-      const { resume, pausedStorage, repo, handle, handle2 } = setup()
-
-      const flushPromise = repo.flush([handle.documentId], 10)
-      expect(flushPromise).rejects.toThrowError("Timed out waiting for save")
+    it("flush right before change should resolve correctly", async () => {
+      const repo = new Repo({
+        network: [],
+        storage: new DummyStorageAdapter(),
+      })
+      const handle = repo.create<{ field?: string }>()
 
-      // Check that the data is now saved.
-      expect(pausedStorage.keys().length).toBe(0)
+      for (let i = 0; i < 10; i++) {
+        const flushPromise = repo.flush([handle.documentId])
+        handle.change((doc: any) => {
+          doc.field += Array(1024)
+            .fill(Math.random() * 10)
+            .join("")
+        })
+        await flushPromise
+      }
     })
   })
 
@@ -810,9 +830,7 @@ describe("Repo", () => {
     it("charlieRepo can request a document not initially shared with it", async () => {
       const { charlieRepo, notForCharlie, teardown } = await setup()
 
-      const handle = charlieRepo.find<TestDoc>(
-        stringifyAutomergeUrl({ documentId: notForCharlie })
-      )
+      const handle = charlieRepo.find<TestDoc>(notForCharlie)
 
       await pause(50)
 
@@ -826,9 +844,7 @@ describe("Repo", () => {
     it("charlieRepo can request a document across a network of multiple peers", async () => {
       const { charlieRepo, notForBob, teardown } = await setup()
 
-      const handle = charlieRepo.find<TestDoc>(
-        stringifyAutomergeUrl({ documentId: notForBob })
-      )
+      const handle = charlieRepo.find<TestDoc>(notForBob)
 
       await pause(50)
 
@@ -850,7 +866,16 @@ describe("Repo", () => {
       teardown()
     })
 
-    it("fires an 'unavailable' event when a document is not available on the network", async () => {
+    it("emits an unavailable event when it's not found on the network", async () => {
+      const { aliceRepo, teardown } = await setup()
+      const url = generateAutomergeUrl()
+      const handle = aliceRepo.find(url)
+      assert.equal(handle.isReady(), false)
+      await eventPromise(handle, "unavailable")
+      teardown()
+    })
+
+    it("emits an unavailable event every time an unavailable doc is requested", async () => {
       const { charlieRepo, teardown } = await setup()
       const url = generateAutomergeUrl()
       const handle = charlieRepo.find<TestDoc>(url)
@@ -861,10 +886,13 @@ describe("Repo", () => {
         eventPromise(charlieRepo, "unavailable-document"),
       ])
 
-      // make sure it fires a second time if the doc is still unavailable
+      // make sure it emits a second time if the doc is still unavailable
       const handle2 = charlieRepo.find<TestDoc>(url)
       assert.equal(handle2.isReady(), false)
-      await eventPromise(handle2, "unavailable")
+      await Promise.all([
+        eventPromise(handle, "unavailable"),
+        eventPromise(charlieRepo, "unavailable-document"),
+      ])
 
       teardown()
     })
@@ -888,7 +916,7 @@ describe("Repo", () => {
 
       await eventPromise(aliceRepo.networkSubsystem, "peer")
 
-      const doc = await handle.doc([READY])
+      const doc = await handle.doc(["ready"])
       assert.deepStrictEqual(doc, { foo: "baz" })
 
       // an additional find should also return the correct resolved document
@@ -912,7 +940,6 @@ describe("Repo", () => {
       // we have a storage containing the document to pass to a new repo later
       const storage = new DummyStorageAdapter()
       const isolatedRepo = new Repo({
-        network: [],
         storage,
       })
       const unsyncedHandle = isolatedRepo.create<TestDoc>()
@@ -970,17 +997,6 @@ describe("Repo", () => {
       teardown()
     })
 
-    it("can emit an 'unavailable' event when it's not found on the network", async () => {
-      const { charlieRepo, teardown } = await setup()
-
-      const url = generateAutomergeUrl()
-      const handle = charlieRepo.find<TestDoc>(url)
-      assert.equal(handle.isReady(), false)
-
-      await eventPromise(handle, "unavailable")
-      teardown()
-    })
-
     it("syncs a bunch of changes", async () => {
       const { aliceRepo, bobRepo, charlieRepo, teardown } = await setup()
 
@@ -1064,8 +1080,7 @@ describe("Repo", () => {
         bobHandle.documentId,
         await charlieRepo!.storageSubsystem.id()
       )
-      const docHeads = A.getHeads(bobHandle.docSync())
-      assert.deepStrictEqual(storedSyncState.sharedHeads, docHeads)
+      assert.deepStrictEqual(storedSyncState.sharedHeads, bobHandle.heads())
 
       teardown()
     })
@@ -1118,7 +1133,6 @@ describe("Repo", () => {
       // setup new repo which uses bob's storage
       const bob2Repo = new Repo({
         storage: bobStorage,
-        network: [],
         peerId: "bob-2" as PeerId,
       })
 
@@ -1182,18 +1196,15 @@ describe("Repo", () => {
       // pause to let the sync happen
       await pause(100)
 
-      const charlieHeads = A.getHeads(charlieHandle.docSync())
-      const bobHeads = A.getHeads(handle.docSync())
-
-      assert.deepStrictEqual(charlieHeads, bobHeads)
+      assert.deepStrictEqual(charlieHandle.heads(), handle.heads())
 
       const nextRemoteHeads = await nextRemoteHeadsPromise
       assert.deepStrictEqual(nextRemoteHeads.storageId, charliedStorageId)
-      assert.deepStrictEqual(nextRemoteHeads.heads, charlieHeads)
+      assert.deepStrictEqual(nextRemoteHeads.heads, charlieHandle.heads())
 
       assert.deepStrictEqual(
         handle.getRemoteHeads(charliedStorageId),
-        A.getHeads(charlieHandle.docSync())
+        charlieHandle.heads()
       )
 
       teardown()
@@ -1230,14 +1241,14 @@ describe("Repo", () => {
 
     const bobDoc = bobRepo.find(aliceDoc.url)
     bobDoc.unavailable()
-    await bobDoc.whenReady([HandleState.UNAVAILABLE])
+    await eventPromise(bobDoc, "unavailable")
 
     aliceAdapter.peerCandidate(bob)
     // Bob isn't yet connected to Alice and can't respond to her sync message
     await pause(100)
     bobAdapter.peerCandidate(alice)
 
-    await bobDoc.whenReady([HandleState.READY])
+    await bobDoc.whenReady()
 
     assert.equal(bobDoc.isReady(), true)
   })

package/test/remoteHeads.test.ts

@@ -152,7 +152,7 @@ describe("DocHandle.remoteHeads", () => {
       // wait for alice's service worker to acknowledge the change
       const { heads } = await aliceSeenByBobPromise
 
-      assert.deepStrictEqual(heads, A.getHeads(aliceServiceWorkerDoc.docSync()))
+      assert.deepStrictEqual(heads, aliceServiceWorkerDoc.heads())
     })
 
     it("should report remoteHeads only for documents the subscriber has open", async () => {

package/tsconfig.json

@@ -10,6 +10,7 @@
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "strict": true,
+    "strictNullChecks": true,
     "skipLibCheck": true
   },
   "include": ["src/**/*.ts"],