@automerge/automerge-repo 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+export type DocumentId = string & {
+    __documentId: true;
+};
+export type PeerId = string & {
+    __peerId: false;
+};
+export type ChannelId = string & {
+    __channelId: false;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AACxD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAA;AACjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,KAAK,CAAA;CAAE,CAAA"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/fuzz/fuzz.ts

@@ -0,0 +1,129 @@
+import assert from "assert"
+import { MessageChannelNetworkAdapter } from "@automerge/automerge-repo-network-messagechannel"
+import * as Automerge from "@automerge/automerge"
+
+import { ChannelId, DocHandle, DocumentId, PeerId, SharePolicy } from "../src"
+import { eventPromise } from "../src/helpers/eventPromise.js"
+import { pause } from "../src/helpers/pause.js"
+import { Repo } from "../src/Repo.js"
+import { DummyNetworkAdapter } from "../test/helpers/DummyNetworkAdapter.js"
+import { DummyStorageAdapter } from "../test/helpers/DummyStorageAdapter.js"
+import { getRandomItem } from "../test/helpers/getRandomItem.js"
+
+interface TestDoc {
+  [key: string]: any
+}
+
+const setup = async () => {
+  // Set up three repos; connect Alice to Bob, and Bob to Charlie
+
+  const aliceBobChannel = new MessageChannel()
+  const bobCharlieChannel = new MessageChannel()
+
+  const { port1: aliceToBob, port2: bobToAlice } = aliceBobChannel
+  const { port1: bobToCharlie, port2: charlieToBob } = bobCharlieChannel
+
+  const excludedDocuments: DocumentId[] = []
+
+  const sharePolicy: SharePolicy = async (peerId, documentId) => {
+    if (documentId === undefined) return false
+
+    // make sure that charlie never gets excluded documents
+    if (excludedDocuments.includes(documentId) && peerId === "charlie")
+      return false
+
+    return true
+  }
+
+  const aliceRepo = new Repo({
+    network: [new MessageChannelNetworkAdapter(aliceToBob)],
+    peerId: "A" as PeerId,
+    sharePolicy,
+  })
+
+  const bobRepo = new Repo({
+    network: [
+      new MessageChannelNetworkAdapter(bobToAlice),
+      new MessageChannelNetworkAdapter(bobToCharlie),
+    ],
+    peerId: "B" as PeerId,
+    sharePolicy,
+  })
+
+  const charlieRepo = new Repo({
+    network: [new MessageChannelNetworkAdapter(charlieToBob)],
+    peerId: "C" as PeerId,
+  })
+
+  const aliceHandle = aliceRepo.create<TestDoc>()
+  aliceHandle.change(d => {
+    d.foo = "bar"
+  })
+
+  const notForCharlieHandle = aliceRepo.create<TestDoc>()
+  const notForCharlie = notForCharlieHandle.documentId
+  excludedDocuments.push(notForCharlie)
+  notForCharlieHandle.change(d => {
+    d.foo = "baz"
+  })
+
+  await Promise.all([
+    eventPromise(aliceRepo.networkSubsystem, "peer"),
+    eventPromise(bobRepo.networkSubsystem, "peer"),
+    eventPromise(charlieRepo.networkSubsystem, "peer"),
+  ])
+
+  const teardown = () => {
+    aliceBobChannel.port1.close()
+    bobCharlieChannel.port1.close()
+  }
+
+  return {
+    aliceRepo,
+    bobRepo,
+    charlieRepo,
+    aliceHandle,
+    notForCharlie,
+    teardown,
+  }
+}
+
+const { aliceRepo, bobRepo, charlieRepo, teardown } = await setup()
+
+// HACK: yield to give repos time to get the one doc that aliceRepo created
+await pause(50)
+
+for (let i = 0; i < 100000; i++) {
+  // pick a repo
+  const repo = getRandomItem([aliceRepo, bobRepo, charlieRepo])
+  const docs = Object.values(repo.handles)
+  const doc = getRandomItem(docs) as DocHandle<TestDoc>
+
+  doc.change(d => {
+    d.timestamp = Date.now()
+    d.foo = { bar: Math.random().toString() }
+  })
+
+  await pause(0)
+  const a = await aliceRepo.find(doc.documentId).value()
+  const b = await bobRepo.find(doc.documentId).value()
+  const c = await charlieRepo.find(doc.documentId).value()
+  assert.deepStrictEqual(a, b, "A and B should be equal")
+  assert.deepStrictEqual(b, c, "B and C should be equal")
+
+  const bin = Automerge.save(b)
+  const load = Automerge.load(bin)
+  assert.deepStrictEqual(b, load)
+
+  console.log(
+    "Changes:",
+    Automerge.getAllChanges(a).length,
+    Automerge.getAllChanges(b).length,
+    Automerge.getAllChanges(c).length
+  )
+}
+
+console.log("DONE")
+await pause(500)
+
+teardown()

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@automerge/automerge-repo",
+  "version": "0.0.1",
+  "description": "A repository object to manage a collection of automerge documents",
+  "repository": "https://github.com/pvh/automerge-repo",
+  "author": "Peter van Hardenberg <pvh@pvh.ca>",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "watch": "npm-watch build",
+    "test:coverage": "c8 --reporter=lcov --reporter=html --reporter=text yarn test",
+    "test": "mocha --no-warnings --experimental-specifier-resolution=node --exit",
+    "test:watch": "npm-watch test",
+    "test:log": "cross-env DEBUG='automerge-repo:*' yarn test",
+    "fuzz": "ts-node --esm --experimentalSpecifierResolution=node fuzz/fuzz.ts"
+  },
+  "browser": {
+    "crypto": false
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.7",
+    "@types/uuid": "^8.3.4",
+    "@types/ws": "^8.5.3",
+    "@typescript-eslint/eslint-plugin": "^5.33.0",
+    "@typescript-eslint/parser": "^5.33.0",
+    "http-server": "^14.1.0"
+  },
+  "peerDependencies": {
+    "@automerge/automerge": "^2.1.0-alpha.5"
+  },
+  "dependencies": {
+    "cbor-x": "^1.3.0",
+    "debug": "^4.3.4",
+    "eventemitter3": "^4.0.7",
+    "tiny-typed-emitter": "^2.1.0",
+    "ts-node": "^10.9.1",
+    "uuid": "^8.3.2",
+    "xstate": "^4.37.0"
+  },
+  "watch": {
+    "build": {
+      "patterns": "./src/**/*",
+      "extensions": [
+        ".ts"
+      ]
+    },
+    "test": {
+      "quiet": true,
+      "patterns": [
+        "./src/**/*",
+        "./test/**/*"
+      ],
+      "extensions": [
+        ".ts"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "e572f26ae416140b025c3ba557d9f781abbdada1"
+}

package/src/DocCollection.ts

@@ -0,0 +1,123 @@
+import EventEmitter from "eventemitter3"
+import { v4 as uuid } from "uuid"
+import { DocHandle } from "./DocHandle.js"
+import { type DocumentId } from "./types.js"
+import { type SharePolicy } from "./Repo.js"
+
+/**
+ * A DocCollection is a collection of DocHandles. It supports creating new documents and finding
+ * documents by ID.
+ * */
+export class DocCollection extends EventEmitter<DocCollectionEvents> {
+  #handleCache: Record<DocumentId, DocHandle<any>> = {}
+
+  /** By default, we share generously with all peers. */
+  sharePolicy: SharePolicy = async () => true
+
+  constructor() {
+    super()
+  }
+
+  /** Returns an existing handle if we have it; creates one otherwise. */
+  #getHandle<T>(
+    /** The documentId of the handle to look up or create */
+    documentId: DocumentId,
+
+    /** If we know we're creating a new document, specify this so we can have access to it immediately */
+    isNew: boolean
+  ) {
+    // If we have the handle cached, return it
+    if (this.#handleCache[documentId]) return this.#handleCache[documentId]
+
+    // If not, create a new handle, cache it, and return it
+    const handle = new DocHandle<T>(documentId, { isNew })
+    this.#handleCache[documentId] = handle
+    return handle
+  }
+
+  /** Returns all the handles we have cached. */
+  get handles() {
+    return this.#handleCache
+  }
+
+  /**
+   * Creates a new document and returns a handle to it. The initial value of the document is
+   * an empty object `{}`. Its documentId is generated by the system. we emit a `document` event
+   * to advertise interest in the document.
+   */
+  create<T>(): DocHandle<T> {
+    // TODO:
+    // either
+    // - pass an initial value and do something like this to ensure that you get a valid initial value
+
+    // const myInitialValue = {
+    //   tasks: [],
+    //   filter: "all",
+    //
+    // const guaranteeInitialValue = (doc: any) => {
+    // if (!doc.tasks) doc.tasks = []
+    // if (!doc.filter) doc.filter = "all"
+
+    //   return { ...myInitialValue, ...doc }
+    // }
+
+    // or
+    // - pass a "reify" function that takes a `<any>` and returns `<T>`
+
+    const documentId = uuid() as DocumentId
+    const handle = this.#getHandle<T>(documentId, true) as DocHandle<T>
+    this.emit("document", { handle })
+    return handle
+  }
+
+  /**
+   * Retrieves a document by id. It gets data from the local system, but also emits a `document`
+   * event to advertise interest in the document.
+   */
+  find<T>(
+    /** The documentId of the handle to retrieve */
+    documentId: DocumentId
+  ): DocHandle<T> {
+    // TODO: we want a way to make sure we don't yield intermediate document states during initial synchronization
+
+    // If we already have a handle, return it
+    if (this.#handleCache[documentId])
+      return this.#handleCache[documentId] as DocHandle<T>
+
+    // Otherwise, create a new handle
+    const handle = this.#getHandle<T>(documentId, false) as DocHandle<T>
+
+    // we don't directly initialize a value here because the StorageSubsystem and Synchronizers go
+    // and get the data asynchronously and block on read instead of on create
+
+    // emit a document event to advertise interest in this document
+    this.emit("document", { handle })
+
+    return handle
+  }
+
+  delete(
+    /** The documentId of the handle to delete */
+    documentId: DocumentId
+  ) {
+    const handle = this.#getHandle(documentId, false)
+    handle.delete()
+
+    delete this.#handleCache[documentId]
+    this.emit("delete-document", { documentId })
+  }
+}
+
+// events & payloads
+interface DocCollectionEvents {
+  document: (arg: DocumentPayload) => void
+  "delete-document": (arg: DeleteDocumentPayload) => void
+}
+
+interface DocumentPayload {
+  handle: DocHandle<any>
+}
+
+interface DeleteDocumentPayload {
+  documentId: DocumentId
+}