{"_id":"@cryptforge/automerge-repo","name":"@cryptforge/automerge-repo","dist-tags":{"latest":"2.5.2-cryptforge.1"},"versions":{"2.5.2-cryptforge.1":{"name":"@cryptforge/automerge-repo","version":"2.5.2-cryptforge.1","description":"A repository object to manage a collection of automerge documents (CryptForge fork)","repository":{"type":"git","url":"git+ssh://git@github.com/viktor-albus/automerge-repo.git","directory":"packages/automerge-repo"},"author":{"name":"Peter van Hardenberg","email":"pvh@pvh.ca"},"contributors":[{"name":"Viktor Albus","email":"viktor@cryptforge.io"}],"license":"MIT","type":"module","main":"dist/index.js","browser":{"crypto":false},"devDependencies":{"@types/debug":"^4.1.12","http-server":"^14.1.0","ts-node":"^10.9.2","vite":"^5.0.8"},"dependencies":{"@automerge/automerge":"2.2.8 - 3","bs58check":"^3.0.1","cbor-x":"^1.3.0","debug":"^4.3.4","eventemitter3":"^5.0.1","fast-sha256":"^1.3.0","uuid":"^13.0.0","xstate":"^5.9.1"},"exports":{".":"./dist/entrypoints/fullfat.js","./slim":"./dist/entrypoints/slim.js","./helpers/*.js":"./dist/helpers/*.js"},"watch":{"build":{"patterns":"./src/**/*","extensions":[".ts"]},"test":{"quiet":true,"patterns":["./src/**/*","./test/**/*"],"extensions":[".ts"]}},"publishConfig":{"access":"public"},"keywords":["automerge","crdt","collaboration","cryptforge","fork"],"scripts":{"build":"tsc","watch":"npm-watch build","test:coverage":"c8 --reporter=lcov --reporter=html --reporter=text pnpm test","test":"vitest","test:watch":"npm-watch test","fuzz":"ts-node --esm --experimentalSpecifierResolution=node fuzz/fuzz.ts"},"_id":"@cryptforge/automerge-repo@2.5.2-cryptforge.1","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/viktor-albus/automerge-repo/issues"},"homepage":"https://github.com/viktor-albus/automerge-repo#readme","_integrity":"sha512-ugw/zs9UyYVYv+qPtb4/lW9XsmakHMSKXRXCZyzg8IW1lzzioBN9Qn+sE4frYkcCIZjNXYZfv30VTJC9eDEeyQ==","_resolved":"/private/var/folders/y2/4jhvk3q54cg7p2svdtcjmvxc0000gn/T/92d04429033294b4e785c4761bce1a8f/cryptforge-automerge-repo-2.5.2-cryptforge.1.tgz","_from":"file:cryptforge-automerge-repo-2.5.2-cryptforge.1.tgz","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-ugw/zs9UyYVYv+qPtb4/lW9XsmakHMSKXRXCZyzg8IW1lzzioBN9Qn+sE4frYkcCIZjNXYZfv30VTJC9eDEeyQ==","shasum":"9c04a6db8e08de72544ab1d8cf5d08388232cff0","tarball":"https://registry.npmjs.org/@cryptforge/automerge-repo/-/automerge-repo-2.5.2-cryptforge.1.tgz","fileCount":129,"unpackedSize":296581,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH/KOHmasrILEtMmZsxrr/GflbS/kbwfumfE0RSb0T6FAiEAq5xr8HW0mPxn6WtUs2yjHtU5p7VmlSgv2VVODya1ynE="}]},"_npmUser":{"name":"void.primordia","email":"void.primordia@proton.me"},"directories":{},"maintainers":[{"name":"void.primordia","email":"void.primordia@proton.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/automerge-repo_2.5.2-cryptforge.1_1766470191765_0.8667849092909912"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-23T06:09:51.661Z","2.5.2-cryptforge.1":"2025-12-23T06:09:51.971Z","modified":"2025-12-23T06:09:52.303Z"},"maintainers":[{"name":"void.primordia","email":"void.primordia@proton.me"}],"description":"A repository object to manage a collection of automerge documents (CryptForge fork)","homepage":"https://github.com/viktor-albus/automerge-repo#readme","keywords":["automerge","crdt","collaboration","cryptforge","fork"],"repository":{"type":"git","url":"git+ssh://git@github.com/viktor-albus/automerge-repo.git","directory":"packages/automerge-repo"},"contributors":[{"name":"Viktor Albus","email":"viktor@cryptforge.io"}],"author":{"name":"Peter van Hardenberg","email":"pvh@pvh.ca"},"bugs":{"url":"https://github.com/viktor-albus/automerge-repo/issues"},"license":"MIT","readme":"# Automerge Repo\n\n---\n\n> **🔱 Fork Notice**\n> \n> This is a fork of [`@automerge/automerge-repo`](https://github.com/automerge/automerge-repo) \n> maintained by the [CryptForge](https://github.com/viktor-albus/cryptforge-sdk) team.\n> \n> - **Original Project**: https://github.com/automerge/automerge-repo\n> - **Base Version**: 2.5.2-alpha.1\n> - **Published As**: `@cryptforge/automerge-repo`\n> \n> This fork contains minimal modifications required for the CryptForge SDK. \n> We maintain compatibility with the upstream project and sync regularly with updates.\n> \n> **For the original package**, install `@automerge/automerge-repo`  \n> **For CryptForge integration**, install `@cryptforge/automerge-repo`\n\n---\n\nThis is a wrapper for the [Automerge](https://github.com/automerge/automerge) CRDT library which\nprovides facilities to support working with many documents at once, as well as pluggable networking\nand storage.\n\nThis is the core library. It handles dispatch of events and provides shared functionality such as\ndeciding which peers to connect to or when to write data out to storage.\n\nOther packages in this monorepo include:\n\n- [@automerge/automerge-repo-demo-counter](/packages/automerge-repo-demo-counter/): A React-based demonstration\n  application.\n- [@automerge/automerge-repo-react-hooks](/packages/automerge-repo-react-hooks/): Example hooks for use with\n  React.\n\n#### Storage adapters\n\n- [@automerge/automerge-repo-storage-indexeddb](/packages/automerge-repo-storage-indexeddb/): A storage\n  adapter to persist data in a browser\n- [@automerge/automerge-repo-storage-nodefs](/packages/automerge-repo-storage-nodefs/): A storage adapter to\n  write changes to the filesystem\n\n#### Network adapters\n\n- [@automerge/automerge-repo-network-websocket](/packages/automerge-repo-network-websocket/): Network adapters\n  for both sides of a client/server configuration over websocket\n- [@automerge/automerge-repo-network-messagechannel](/packages/automerge-repo-network-messagechannel/): A\n  network adapter that uses the [MessageChannel\n  API](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel) to communicate between tabs\n- [@automerge/automerge-repo-network-broadcastchannel](/packages/automerge-repo-network-broadcastchannel/):\n  Likely only useful for experimentation, but allows simple (inefficient) tab-to-tab data\n  synchronization\n\n## Usage\n\nThis library provides two main components: the `Repo` itself, and the `DocHandle`s it contains.\n\nA `Repo` exposes these methods:\n\n- `create<T>(initialValue: T?)`\n  Creates a new `Automerge.Doc` and returns a `DocHandle` for it. Accepts an optional initial value for the document. Produces an empty document (potentially violating the type!) otherwise.\n- `find<T>(docId: DocumentId): Promise<DocHandle<T>>`  \n  Looks up a given document either on the local machine or (if necessary) over any configured\n  networks. Returns a promise that resolves when the document is loaded or throws if load fails.\n- `delete(docId: DocumentId)`  \n  Deletes the local copy of a document from the local cache and local storage. _This does not currently delete the document from any other peers_.\n- `import(binary: Uint8Array)`  \n  Imports a document binary (from `export()` or `Automerge.save(doc)`) into the repo, returning a new handle\n- `export(docId: DocumentId)`  \n  Exports the document. Returns a Promise containing either the Uint8Array of the document or undefined if the document is currently unavailable. See the [Automerge binary format spec](https://automerge.org/automerge-binary-format-spec/) for more details on the shape of the Uint8Array.\n- `.on(\"document\", ({handle: DocHandle}) => void)`  \n  Registers a callback to be fired each time a new document is loaded or created.\n- `.on(\"delete-document\", ({handle: DocHandle}) => void)`  \n  Registers a callback to be fired each time a new document is deleted.\n\nA `DocHandle` is a wrapper around an `Automerge.Doc`. Its primary function is to dispatch changes to\nthe document.\n\n- `handle.doc()`\n  Returns a `Doc<T>` that will contain the current value of the document.\n  Throws an error if the document is deleted.\n- `handle.change((doc: T) => void)`  \n  Calls the provided callback with an instrumented mutable object\n  representing the document. Any changes made to the document will be recorded and distributed to\n  other nodes.\n\nA `DocHandle` also emits these events:\n\n- `change({handle: DocHandle, patches: Patch[], patchInfo: PatchInfo})`\n  Called whenever the document changes, the handle's .doc\n- `delete`  \n  Called when the document is deleted locally.\n\n## Creating a repo\n\nThe repo needs to be configured with storage and network adapters. If you give it neither, it will\nstill work, but you won't be able to find any data and data created won't outlast the process.\n\nMultiple network adapters (even of the same type) can be added to a repo, even after it is created.\n\nA repo currently only supports a single storage adapter, and it must be provided at creation.\n\nHere is an example of creating a repo with a indexeddb storage adapter and a broadcast channel\nnetwork adapter:\n\n```ts\nconst repo = new Repo({\n  network: [new BroadcastChannelNetworkAdapter()],\n  storage: new IndexedDBStorageAdapter(),\n  sharePolicy: async (peerId: PeerId, documentId: DocumentId) => true, // this is the default\n})\n```\n\n### Share Policy\n\nThe share policy is used to determine which document in your repo should be _automatically_ shared with other peers. **The default setting is to share all documents with all peers.**\n\n> **Warning**\n> If your local repo has deleted a document, a connecting peer with the default share policy will still share that document with you.\n\nYou can override this by providing a custom share policy. The function should return a promise resolving to a boolean value indicating whether the document should be shared with the peer.\n\nThe share policy will not stop a document being _requested_ by another peer by its `DocumentId`.\n\n## Starting the demo app\n\n```bash\nyarn\nyarn dev\n```\n\n## Quickstart\n\nThe following instructions will get you a working React app running in a browser.\n\n```bash\nyarn create vite\n# Project name: hello-automerge-repo\n# Select a framework: React\n# Select a variant: TypeScript\n\ncd hello-automerge-repo\nyarn\nyarn add @automerge/automerge @automerge/automerge-repo-react-hooks @automerge/automerge-repo-network-broadcastchannel @automerge/automerge-repo-storage-indexeddb vite-plugin-wasm\n```\n\nEdit the `vite.config.ts`. (This is all needed to work around packaging hiccups due to WASM. We look\nforward to the day that we can delete this step entirely.)\n\n```ts\n// vite.config.ts\nimport { defineConfig } from \"vite\"\nimport react from \"@vitejs/plugin-react\"\nimport wasm from \"vite-plugin-wasm\"\n\nexport default defineConfig({\n  plugins: [wasm(), react()],\n\n  worker: {\n    format: \"es\",\n    plugins: () => [wasm()],\n  },\n})\n```\n\nNow set up the repo in `src/main.tsx` by importing the bits, creating the repo, and passing down a\nRepoContext. We also create a document and store its `documentId` in localStorage.\n\n```tsx\n// src/main.tsx\nimport React from \"react\"\nimport ReactDOM from \"react-dom/client\"\nimport App from \"./App.js\"\nimport { Repo } from \"@automerge/automerge-repo\"\nimport { BroadcastChannelNetworkAdapter } from \"@automerge/automerge-repo-network-broadcastchannel\"\nimport { IndexedDBStorageAdapter } from \"@automerge/automerge-repo-storage-indexeddb\"\nimport { RepoContext } from \"@automerge/automerge-repo-react-hooks\"\n\nconst repo = new Repo({\n  network: [new BroadcastChannelNetworkAdapter()],\n  storage: new IndexedDBStorageAdapter(),\n})\n\nlet rootDocId = localStorage.rootDocId\nif (!rootDocId) {\n  const handle = repo.create()\n  localStorage.rootDocId = rootDocId = handle.documentId\n}\n\nReactDOM.createRoot(document.getElementById(\"root\") as HTMLElement).render(\n  <RepoContext.Provider value={repo}>\n    <React.StrictMode>\n      <App documentId={rootDocId} />\n    </React.StrictMode>\n  </RepoContext.Provider>\n)\n```\n\nNow update `App.tsx` to load the document from the Repo based on the documentId passed in. Then, use\nthe document to render a button that increments the count.\n\n```tsx\n// App.tsx\nimport { useDocument } from \"@automerge/automerge-repo-react-hooks\"\nimport { DocumentId } from \"@automerge/automerge-repo\"\n\ninterface Doc {\n  count: number\n}\n\nexport default function App(props: { documentId: DocumentId }) {\n  const [doc, changeDoc] = useDocument<Doc>(props.documentId)\n\n  return (\n    <button\n      onClick={() => {\n        changeDoc((d: any) => {\n          d.count = (d.count || 0) + 1\n        })\n      }}\n    >\n      count is: {doc?.count ?? 0}\n    </button>\n  )\n}\n```\n\nYou should now have a working React application using Automerge. Try running it with `yarn dev`, and\nopen it in two browser windows. You should see the count increment in both windows.\n\n![](/images/hello-automerge-repo.gif)\n\nThis application is also available as a package in this repo in\n[automerge-repo-demo-counter](/packages/automerge-repo-demo-counter). You can run it with `yarn\ndev:demo`.\n\n### Adding a sync server\n\nFirst, get a sync-server running locally, following the instructions for the\n[automerge-repo-sync-server](https://github.com/automerge/automerge-repo-sync-server) package.\n\nNext, update your application to synchronize with it:\n\nInstall the websocket network adapter:\n\n```bash\nyarn add automerge-repo-network-websocket\n```\n\nNow import it and add it to your list of network adapters:\n\n```ts\n// main.tsx\nimport { WebSocketClientAdapter } from \"@automerge/automerge-repo-network-websocket\" // <-- add this line\n\n// ...\n\nconst repo = new Repo({\n  network: [\n    new BroadcastChannelNetworkAdapter(),\n    new WebSocketClientAdapter(\"ws://localhost:3030\"), // <-- add this line\n  ],\n  storage: new IndexedDBStorageAdapter(),\n})\n\n// ...\n```\n\nAnd you're finished! You can test that your sync server is opening the same document in two\ndifferent browsers (e.g. Chrome and Firefox). (Note that with our current trivial implementation\nyou'll need to manually copy the `rootDocId` value between the browsers.)\n\n## Acknowledgements\n\nOriginally authored by Peter van Hardenberg.\n\nWith gratitude for contributions by:\n\n- Herb Caudill\n- Jeremy Rose\n- Alex Currie-Clark\n- Dylan Mackenzie\n- Maciek Sakrejda\n- George Su\n- Neftaly Hernandez\n- Bijela Gora\n- Mykola Veremchuk\n- Blaine Cook\n","readmeFilename":"README.md","_rev":"1-5157ea0634c33c2cd24d1f8e081df9c5"}