A DocHandle is a wrapper around a single Automerge document that lets us listen for changes and +
A DocHandle is a wrapper around a single Automerge document that lets us listen for changes and notify the network and storage of new changes.
A DocHandle represents a document which is being managed by a Repo. You shouldn't ever
instantiate this yourself. To obtain DocHandle use Repo.find or Repo.create.
Repo that some change has occured and
the Repo will save any new changes to the attached StorageAdapter and send sync
messages to connected peers.
-Static prefixedOur documentId in Automerge URL form.
-Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional context: anyStatic prefixedOur documentId in Automerge URL form.
+Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional context: anySends an arbitrary ephemeral message out to all reachable peers who would receive sync messages from you. It has no guarantee of delivery, and is not persisted to the underlying automerge doc in any way. Messages will have a sending PeerId but this is not a useful user identifier (a user could have multiple tabs open and would appear as multiple PeerIds). Every message source must have a unique PeerId.
-All changes to an Automerge document should be made through this method. Inside the callback, the document should be treated as mutable: all edits will be recorded using a Proxy and translated into operations as part of a single recorded "change".
Note that assignment via ES6 spread operators will result in replacing the object @@ -57,10 +57,10 @@
Local changes will be stored (by the StorageSubsystem) and synchronized (by the DocSynchronizer) to any peers you are sharing it with.
Returns a set of Patch operations that will move a materialized document from one state to another +
Returns a set of Patch operations that will move a materialized document from one state to another if applied.
Automerge patches that go from one document state to the other
We allow specifying either:
@@ -70,11 +70,11 @@Error if the documents don't share history or if either document is not ready
-states to wait for, such as "LOADING". mostly for internal use.
+states to wait for, such as "LOADING". mostly for internal use.
the current state of this handle's Automerge document.
This is the recommended way to access a handle's document. Note that this waits for the handle to be ready if necessary. If loading (or synchronization) fails, this will never resolve.
-Synchronously returns the current state of the Automerge document this handle manages, or +
Synchronously returns the current state of the Automerge document this handle manages, or
undefined. Consider using await handle.doc() instead. Check isReady(), or use whenReady()
if you want to make sure loading is complete first.
Not to be confused with the SyncState of the document, which describes the state of the @@ -82,17 +82,17 @@
Error if the documents don't share history or if either do
Note that undefined is not a valid Automerge document, so the return from this function is
unambigous.
the current document, or undefined if the document is not ready.
-doneLoading is called by the repo after it decides it has all the changes
+
Calls each of the listeners registered for a given event.
+Calls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Return an array listing the events for which the emitter has registered listeners.
Returns an array of all past "heads" for the document in topological order.
+Returns an array of all past "heads" for the document in topological order.
UrlHeads[] - The individual heads for every change in the document. Each item is a tagged string[1].
A point-in-time in an automerge document is an array of heads since there may be concurrent edits. This API just returns a topologically sorted history of all edits @@ -100,32 +100,32 @@
Error if the documents don't share history or if either do history views would be quite large under concurrency (every thing in each branch against each other). There might be a clever way to think about this, but we haven't found it yet, so for now at least we present a single traversable view which excludes concurrency.
-true if the handle is in one of the given states.
-true if the handle is in one of the given states.
+Return the number of listeners listening to a given event.
+Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional context: anyOptional once: booleanAdd a listener for a given event.
+Optional fn: ((...args) => void)Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional context: anyOptional once: booleanAdd a listener for a given event.
Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional context: anyAdd a one-time listener for a given event.
Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional context: anyRemove the listeners of a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional context: anyOptional once: booleanCreates a new DocHandle with a fixed "view" at the given point in time represented
by the heads passed in. The return value is the same type as docSync() and will return
undefined if the object hasn't finished loading.
DocHandleheads
Error if the documents don't share history or if either do of Automerge doesn't check types at runtime, so if you go back to an old set of heads that doesn't match the heads here, Typescript will not save you.
heads - The heads to view the document at. See history().
-a promise that resolves when the document is in one of the given states (if no states +
a promise that resolves when the document is in one of the given states (if no states are passed, when the document is ready)
Use this to block until the document handle has finished loading. The async equivalent to
checking inState().
Abstract An interface representing some way to connect to other peers
+Abstract An interface representing some way to connect to other peers
The Repo uses one or more NetworkAdapters to connect to other peers.
Because the network may take some time to be ready the Repo will wait
until the adapter emits a ready event before it starts trying to use it
This utility class can be used as a base to build a custom network adapter. It is most useful as a simple way to add the necessary event emitter functionality
-Optional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAbstract connectCalled by the Repo to start the connection process
+Optional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAbstract connectCalled by the Repo to start the connection process
Optional peerMetadata: PeerMetadatapeerId - the peerId of this repo
peerMetadata - how this adapter should present itself to other peers
-Abstract disconnectCalled by the Repo to disconnect from the network
-Calls each of the listeners registered for a given event.
+Abstract disconnectCalled by the Repo to disconnect from the network
+Calls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Return an array listing the events for which the emitter has registered listeners.
-Abstract isReturn the number of listeners listening to a given event.
+Abstract isReturn the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAdd a one-time listener for a given event.
@@ -38,4 +38,4 @@peerMetadata - how this adapter should present itself to oth
Optional event: keyof NetworkAdapterEventsRemove the listeners of a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAbstract sendAbstract whenAbstract whenThe Repo is the main entry point of this library
The Repo is the main entry point of this library
To construct a Repo you will need an StorageAdapter and one or
more NetworkAdapters. Once you have a Repo you can use it to
obtain DocHandles.
Static prefixedReturns all the handles we have cached.
-Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyStatic prefixedReturns all the handles we have cached.
+Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyCreate a new DocHandle by cloning the history of an existing DocHandle.
This is a wrapper around the clone function in the Automerge library.
The new DocHandle will have a new URL but will share history with the original,
@@ -39,26 +39,26 @@
be notified of the newly created DocHandle.
if the cloned handle is not yet ready or if
clonedHandle.docSync() returns undefined (i.e. the handle is unavailable).
Creates a new document and returns a handle to it. The initial value of the document is an
empty object {} unless an initial value is provided. Its documentId is generated by the
system. we emit a document event to advertise interest in the document.
Optional initialValue: TThe url or documentId of the handle to delete
-The url or documentId of the handle to delete
+Calls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Return an array listing the events for which the emitter has registered listeners.
Exports a document to a binary format.
The url or documentId of the handle to export
Promise<Uint8Array | undefined> - A Promise containing the binary document, or undefined if the document is unavailable.
-Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
-Optional fn: ((...args) => void)Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
+Optional fn: ((...args) => void)Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyAdd a one-time listener for a given event.
Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyRemove the listeners of a given event.
-Optional fn: ((...args) => void)Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyOptional once: booleanOptional fn: ((...args) => void)Rest ...args: ArgumentMap<RepoEvents>[Extract<T, keyof RepoEvents>]Optional context: anyOptional once: booleanAbstract A storage adapter represents some way of storing binary data for a Repo
+Abstract A storage adapter represents some way of storing binary data for a Repo
StorageAdapters provide a key/value storage interface. The keys are arrays of strings
(StorageKey) and the values are binary blobs.
Abstract loadLoad the single value corresponding to key
Abstract loadLoad all values with keys that start with keyPrefix.
Abstract loadLoad all values with keys that start with keyPrefix.
The keyprefix will match any key that starts with the given array. For example:
[documentId, "incremental"] will match all incremental savesStorageAdapters provide a key/value storage inte
Be careful! [documentId] would also match something like [documentId, "syncState"]! We
aren't using this yet but keep it in mind.)
Abstract removeRemove the value corresponding to key
Abstract removeRemove all values with keys that start with keyPrefix
Abstract saveSave the value data to the key key
Abstract removeRemove the value corresponding to key
Abstract removeRemove all values with keys that start with keyPrefix
Abstract saveSave the value data to the key key
An interface representing some way to connect to other peers
+An interface representing some way to connect to other peers
The Repo uses one or more NetworkAdapters to connect to other peers.
Because the network may take some time to be ready the Repo will wait
until the adapter emits a ready event before it starts trying to use it
This utility class can be used as a base to build a custom network adapter. It is most useful as a simple way to add the necessary event emitter functionality
-Optional options: BroadcastChannelNetworkAdapterOptionsOptional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
+Optional options: BroadcastChannelNetworkAdapterOptionsOptional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
Optional peerMetadata: PeerMetadatapeerId - the peerId of this repo
peerMetadata - how this adapter should present itself to other peers
-Called by the Repo to disconnect from the network
-Calls each of the listeners registered for a given event.
+Called by the Repo to disconnect from the network
+Calls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Return an array listing the events for which the emitter has registered listeners.
-Return the number of listeners listening to a given event.
+Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAdd a one-time listener for a given event.
@@ -38,4 +38,4 @@peerMetadata - how this adapter should present itself to oth
Optional event: keyof NetworkAdapterEventsRemove the listeners of a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAn interface representing some way to connect to other peers
+An interface representing some way to connect to other peers
The Repo uses one or more NetworkAdapters to connect to other peers.
Because the network may take some time to be ready the Repo will wait
until the adapter emits a ready event before it starts trying to use it
This utility class can be used as a base to build a custom network adapter. It is most useful as a simple way to add the necessary event emitter functionality
-Optional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
+Optional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
Optional peerMetadata: PeerMetadatapeerId - the peerId of this repo
peerMetadata - how this adapter should present itself to other peers
-Called by the Repo to disconnect from the network
-Calls each of the listeners registered for a given event.
+Called by the Repo to disconnect from the network
+Calls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Return an array listing the events for which the emitter has registered listeners.
-Return the number of listeners listening to a given event.
+Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAdd a one-time listener for a given event.
@@ -40,4 +40,4 @@peerMetadata - how this adapter should present itself to oth
Optional event: keyof NetworkAdapterEventsRemove the listeners of a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanCalled by the Repo to send a message to a peer
message - the message to send
-Optional peerOptional peerOptional remoteReadonly retryOptional socketReadonly urlStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional peerMetadata: PeerMetadataCalls each of the listeners registered for a given event.
+Optional peerOptional peerOptional remoteReadonly retryOptional socketReadonly urlStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional peerMetadata: PeerMetadataCalls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Return an array listing the events for which the emitter has registered listeners.
-Return the number of listeners listening to a given event.
+Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
-Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAdd a one-time listener for a given event.
-Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyRemove all listeners, or those of the specified event.
+Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAdd a one-time listener for a given event.
+Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyRemove the listeners of a given event.
-Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanOptional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAn interface representing some way to connect to other peers
+An interface representing some way to connect to other peers
The Repo uses one or more NetworkAdapters to connect to other peers.
Because the network may take some time to be ready the Repo will wait
until the adapter emits a ready event before it starts trying to use it
This utility class can be used as a base to build a custom network adapter. It is most useful as a simple way to add the necessary event emitter functionality
-Optional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
+Optional peerOptional peerStatic prefixedRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
Optional peerMetadata: PeerMetadatapeerId - the peerId of this repo
peerMetadata - how this adapter should present itself to other peers
-Called by the Repo to disconnect from the network
-Calls each of the listeners registered for a given event.
+Called by the Repo to disconnect from the network
+Calls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Return an array listing the events for which the emitter has registered listeners.
-Return the number of listeners listening to a given event.
+Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAdd a one-time listener for a given event.
-Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyRemove all listeners, or those of the specified event.
+Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyRemove the listeners of a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanCalled by the Repo to send a message to a peer
message - the message to send
-A storage adapter represents some way of storing binary data for a Repo
+A storage adapter represents some way of storing binary data for a Repo
StorageAdapters provide a key/value storage interface. The keys are arrays of strings
(StorageKey) and the values are binary blobs.
Create a new IndexedDBStorageAdapter.
The name of the database to use. Defaults to "automerge".
The name of the object store to use. Defaults to "documents".
-Load all values with keys that start with keyPrefix.
Load all values with keys that start with keyPrefix.
The keyprefix will match any key that starts with the given array. For example:
[documentId, "incremental"] will match all incremental savesBe careful! [documentId] would also match something like [documentId, "syncState"]! We
aren't using this yet but keep it in mind.)
A storage adapter represents some way of storing binary data for a Repo
+A storage adapter represents some way of storing binary data for a Repo
StorageAdapters provide a key/value storage interface. The keys are arrays of strings
(StorageKey) and the values are binary blobs.
The path to the directory to store data in. Defaults to "./automerge-repo-data".
-Load the single value corresponding to key
Load all values with keys that start with keyPrefix.
Load the single value corresponding to key
Load all values with keys that start with keyPrefix.
The keyprefix will match any key that starts with the given array. For example:
[documentId, "incremental"] will match all incremental savesBe careful! [documentId] would also match something like [documentId, "syncState"]! We
aren't using this yet but keep it in mind.)
Save the value data to the key key
Save the value data to the key key
Apply changes received from another document
+Apply changes received from another document
doc will be updated to reflect the changes. If there are changes which
we do not have dependencies for yet those will be stored in the document and
applied when the depended on changes arrive.
You can use the ApplyOptions to pass a patchcallback which will be informed of any changes which occur as a result of applying the changes
-Returns a new Automerge URL with a random UUID documentId. Called by Repo.create(), and also used by tests.
-Returns a new Automerge URL with a random UUID documentId. Called by Repo.create(), and also used by tests.
+Get the changes which are in newState but not in oldState. The returned
+
Get the changes which are in newState but not in oldState. The returned
changes can be loaded in oldState via applyChanges.
Note that this will crash if there are changes in oldState which are not in newState.
Get the conflicts associated with a property
+Get the conflicts associated with a property
The values of properties in a map in automerge can be conflicted if there are concurrent "put" operations to the same key. Automerge chooses one value arbitrarily (but deterministically, any two nodes who have the same set of @@ -8,4 +8,4 @@ getConflicts to get the conflicts for the key.
import * as automerge from "@automerge/automerge"
type Profile = {
pets: Array<{name: string, type: string}>
}
let doc1 = automerge.init<Profile>("aaaa")
doc1 = automerge.change(doc1, d => {
d.pets = [{name: "Lassie", type: "dog"}]
})
let doc2 = automerge.init<Profile>("bbbb")
doc2 = automerge.merge(doc2, automerge.clone(doc1))
doc2 = automerge.change(doc2, d => {
d.pets[0].name = "Beethoven"
})
doc1 = automerge.change(doc1, d => {
d.pets[0].name = "Babe"
})
const doc3 = automerge.merge(doc1, doc2)
// Note that here we pass `doc3.pets`, not `doc3`
let conflicts = automerge.getConflicts(doc3.pets[0], "name")
// The two conflicting values are the keys of the conflicts object
assert.deepEqual(Object.values(conflicts), ["Babe", "Beethoven"])
Returns the current index of the cursor.
+Given any valid expression of a document ID, returns a DocumentId in base58check-encoded form.
+Given any valid expression of a document ID, returns a DocumentId in base58check-encoded form.
Currently supports:
Throws on invalid input.
-Given a string, returns true if it is a valid Automerge URL. This function also acts as a type +
Given a string, returns true if it is a valid Automerge URL. This function also acts as a type discriminator in Typescript.
-Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form
-Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form
+Given a documentId in either binary or base58check-encoded form, returns an Automerge URL. +
Given a documentId in either binary or base58check-encoded form, returns an Automerge URL. Throws on invalid input.
-A hook which returns a document identified by a URL and a function to change the document.
+A hook which returns a document identified by a URL and a function to change the document.
Optional id: AnyDocumentIda tuple of the document and a function to change the document.
The document will be undefined if the document is not available in storage or from any peers
This requires a RepoContext to be provided by a parent component.
-Maintains a map of document states, keyed by DocumentId. Useful for collections of related +
Maintains a map of document states, keyed by DocumentId. Useful for collections of related documents. Accepts either URLs or document IDs in the input array, but all get converted to IDs for the output map.
-Optional idsOrUrls: DocId[]Optional idsOrUrls: DocId[]A hook which returns a DocHandle identified by a URL.
+A hook which returns a DocHandle identified by a URL.
Optional id: AnyDocumentIdThis requires a RepoContext to be provided by a parent component.
-This hook maintains state for the local client. +
This hook maintains state for the local client. Like React.useState, it returns a [state, setState] array. It is intended to be used alongside useRemoteAwareness.
When state is changed it is broadcast to all clients. It also broadcasts a heartbeat to let other clients know it is online.
Note that userIds aren't secure (yet). Any client can lie about theirs.
[state, setState]
-This hook returns read-only state for remote clients. +
This hook returns read-only state for remote clients. It also returns their heartbeat status. It is intended to be used alongside useLocalAwareness.
[ peerStates: { [userId]: state, ... }, { [userId]: heartbeatEpochTime, ...} ]
-A React hook which returns the Automerge repo from RepoContext.
-A React hook which returns the Automerge repo from RepoContext.
+A Svelte store for an Automerge document.
+A Svelte store for an Automerge document.
The Automerge document ID
Optional repo: Repo(Optional) The Automerge repo to use. If not provided, the repo will be retrieved from context.
A Svelte store for the Automerge document.
Automerge Repo is a wrapper for the Automerge CRDT library which provides facilities to support working with many documents at once, as well as pluggable networking and storage.
+Automerge Repo is a wrapper for the Automerge CRDT library which provides facilities to support working with many documents at once, as well as pluggable networking and storage.
The core types of this library are in the automerge-repo package. The various automerge-repo-network-* packages contain network adapters for use with various transports whilst the automerge-repo-storage-* packages contain storage adapters. Check the documentation of automerge-repo for more info about network and storage adapters.
Emitted when this document has changed
-Emitted when this document has changed
+The value of the document after the change
-The handle that changed
-Information about the change
-The patches representing the change that occurred
-The handle that changed
+Information about the change
+The patches representing the change that occurred
+Emitted when this document's heads have changed
-Emitted when an ephemeral message is received for the document
-These are the events that this DocHandle emits to external listeners
-These are the events that this DocHandle emits to external listeners
+Emitted when an ephemeral message is sent for this document
-Emitted when we have new remote heads for this document
-Emitted when the network is closed
-Emitted when the network adapter receives a message from a peer
-Emitted when the network adapter learns about a new peer
-Emitted when the network adapter learns that a peer has disconnected
-Emitted when the network adapter receives a message from a peer
+Emitted when the network adapter learns about a new peer
+Emitted when the network adapter learns that a peer has disconnected
+An interface representing some way to connect to other peers
+An interface representing some way to connect to other peers
The Repo uses one or more NetworkAdapters to connect to other peers.
Because the network may take some time to be ready the Repo will wait
until the adapter emits a ready event before it starts trying to use it
The NetworkAdapter is an abstract class that can be used as a base to build a custom network adapter. It is most useful as a simple way to add the necessary event emitter functionality
-Optional peerOptional peerRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
+Optional peerOptional peerRest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyCalled by the Repo to start the connection process
Optional peerMetadata: PeerMetadatapeerId - the peerId of this repo
peerMetadata - how this adapter should present itself to other peers
-Called by the Repo to disconnect from the network
-Calls each of the listeners registered for a given event.
+Called by the Repo to disconnect from the network
+Calls each of the listeners registered for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Return an array listing the events for which the emitter has registered listeners.
-Return the number of listeners listening to a given event.
+Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanAdd a listener for a given event.
Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyAdd a one-time listener for a given event.
@@ -37,4 +37,4 @@peerMetadata - how this adapter should present itself to oth
Optional event: keyof NetworkAdapterEventsRemove the listeners of a given event.
Optional fn: ((...args) => void)Rest ...args: ArgumentMap<NetworkAdapterEvents>[Extract<T, keyof NetworkAdapterEvents>]Optional context: anyOptional once: booleanDescribes a peer intent to the system +
Describes a peer intent to the system storageId: the key for syncState to decide what the other peer already has isEphemeral: to decide if we bother recording this peer's sync state
-Optional isOptional storageOptional denylistA 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.
-Optional enableWhether to enable the experimental remote heads gossiping feature
-Optional isIndicates whether other peers should persist the sync state of this peer. +
Optional enableWhether to enable the experimental remote heads gossiping feature
+Optional isIndicates whether other peers should persist the sync state of this peer. Sync state is only persisted for non-ephemeral peers
-Optional networkA list of network adapters (more can be added at runtime).
-Optional peerOur unique identifier
-Optional shareNormal peers typically share generously with everyone (meaning we sync all our documents with +
Optional networkA list of network adapters (more can be added at runtime).
+Optional peerOur unique identifier
+Optional shareNormal peers typically share generously with everyone (meaning we sync all our documents with all peers). A server only syncs documents that a peer explicitly requests by ID.
-Optional storageA storage adapter can be provided, or not
-Optional storageA storage adapter can be provided, or not
+A document was deleted
-A new document was created or discovered
-A document was marked as unavailable (we don't have it and none of our peers have it)
-A new document was created or discovered
+A document was marked as unavailable (we don't have it and none of our peers have it)
+A storage adapter represents some way of storing binary data for a Repo
+A storage adapter represents some way of storing binary data for a Repo
StorageAdapters provide a key/value storage interface. The keys are arrays of strings
(StorageKey) and the values are binary blobs.
Load the single value corresponding to key
Load all values with keys that start with keyPrefix.
Load all values with keys that start with keyPrefix.
The keyprefix will match any key that starts with the given array. For example:
[documentId, "incremental"] will match all incremental savesBe careful! [documentId] would also match something like [documentId, "syncState"]! We
aren't using this yet but keep it in mind.)
Remove the value corresponding to key
Remove all values with keys that start with keyPrefix
Save the value data to the key key
Remove the value corresponding to key
Remove all values with keys that start with keyPrefix
Save the value data to the key key
Optional useThis is an optional parameter to use a weak ref to reference the message port that is passed to
the adapter. This option is useful when using a message channel with a shared worker. If you
use a network adapter with useWeakRef = true in the shared worker and in the main thread
network adapters with strong refs the network adapter will be automatically garbage collected
if you close a page. The garbage collection doesn't happen immediately; there might be some
time in between when the page is closed and when the port is garbage collected
The document handle to send ephemeral state on
-Optional heartbeatHow frequently to send heartbeats
-The initial state object/primitive we should advertise
-Our user ID *
-Optional heartbeatHow frequently to send heartbeats
+The initial state object/primitive we should advertise
+Our user ID *
+Optional getFunction to provide current epoch time
-The handle to receive ephemeral state on
-Optional localOur user ID
-Optional offlineHow long to wait (in ms) before marking a peer as offline
-The handle to receive ephemeral state on
+Optional localOur user ID
+Optional offlineHow long to wait (in ms) before marking a peer as offline
+The automerge CRDT
+
A NetworkAdapter which uses BroadcastChannel
+
A NetworkAdapter which uses BroadcastChannel
to communicate with other peers in the same browser tab. This is a bit of a
hack because NetworkAdapters are supposed to be used as point to
point communication channels. To get around this the BroadcastChannelNetworkAdapter
@@ -9,4 +9,4 @@
automerge-repo-network-messagechannel.
A NetworkAdapter which uses MessageChannel
+
A NetworkAdapter which uses MessageChannel
to communicate with other peers. This is useful for communicating between
browser tabs and web workers (including shared workers).
A NetworkAdapter which connects to a remote host via WebSockets
A NetworkAdapter which connects to a remote host via WebSockets
The websocket protocol requires a server to be listening and a client to
connect to the server. To that end the NodeWSServerAdapter does not
make outbound connections and instead listens on the provided socket for
@@ -15,4 +15,4 @@
Peer
These hooks are provided as helpers for using Automerge in your React project.
+These hooks are provided as helpers for using Automerge in your React project.
Use RepoContext to set up react context for an Automerge repo. Use useRepo to lookup the repo from context. Most hooks depend on RepoContext being available.
@@ -18,4 +18,4 @@ useThis module provides a storage adapter for IndexedDB.
+This module provides a storage adapter for IndexedDB.
A StorageAdapter which stores data in the local filesystem
A StorageAdapter which stores data in the local filesystem
For a working example, see the Svelte counter demo.
+// App.svelte
<script lang="ts">
import { Repo } from "@automerge/automerge-repo"
import Counter from './lib/Counter.svelte'
import { setContextRepo } from "@automerge/automerge-repo-svelte-store"
const repo = new Repo({storage: new SomeStorage() })
// Make the `Repo` available to child components (via Svelte's `setContext`).
setContextRepo(repo)
const docId = repo.create()
</script>
<main>
<div class="card">
<Counter {docId}/>
</div>
</main>
// Counter.svelte`
<script lang="ts">
import type { DocumentId } from "@automerge/automerge-repo"
import { document } from "@automerge/automerge-repo-svelte-store"
export let docId: DocumentId
// `document` calls `getContextRepo` internally to access the closest `Repo`.
// alternatively, you may pass in a specific repo as the second parameter
const doc = document<{count?: number}>(docId)
const increment = () => {
doc.change((d) => d.count = (d.count || 0) + 1)
}
</script>
<button on:click={increment}>
count is {$doc?.count || 0}
</button>
@@ -8,4 +8,4 @@
automerge-repo appThis generates a simple javascript project with the necessary dependencies for a repo which synchronises over websockets and stores data in the filesystem.
+automerge-repo appThis generates a simple javascript project with the necessary dependencies for a repo which synchronises over websockets and stores data in the filesystem.
npm create @automerge/repo-node-app <your project name>
yarn create @automerge/repo-node-app <your project name>
Now change into the directory and start editing index.js
Automerge Repo is a wrapper for the Automerge CRDT library +
Automerge Repo is a wrapper for the Automerge CRDT library which provides facilities to support working with many documents at once, as well as pluggable networking and storage.
After cloning this repo, run pnpm install and pnpm build.
Please note that a reference sync-server peer which demonstrates the use of automerge-repo-network-websocket is available at automerge-repo-sync-server (this is different from sync-server).
-A branded string representing a URL for a document, in the form automerge:<base58check encoded string>; for example, automerge:4NMNnkMhL8jXrdJ9jamS58PAVdXu.
A branded string representing a URL for a document, in the form automerge:<base58check encoded string>; for example, automerge:4NMNnkMhL8jXrdJ9jamS58PAVdXu.
The unencoded UUID of a document. Typically you should use a AutomergeUrl instead.
-The unencoded UUID of a document. Typically you should use a AutomergeUrl instead.
+Function which is called by change when making changes to a Doc<T>
A chunk is a snapshot or incremental change that is stored in a StorageAdapter.
-A chunk is a snapshot or incremental change that is stored in a StorageAdapter.
+Metadata about a chunk of data loaded from storage. This is stored on the StorageSubsystem so +
Metadata about a chunk of data loaded from storage. This is stored on the StorageSubsystem so when we are compacting we know what chunks we can safely delete.
-An automerge document.
+The base58check-encoded UUID of a document. This is the string following the automerge:
+
The base58check-encoded UUID of a document. This is the string following the automerge:
protocol prefix in an AutomergeUrl; for example, 4NMNnkMhL8jXrdJ9jamS58PAVdXu. When recording
links to an Automerge document in another Automerge document, you should store a
AutomergeUrl instead.
Sent by a Repo to indicate that it does not have the document and none of its connected +
Sent by a Repo to indicate that it does not have the document and none of its connected peers do either.
The document which the peer claims it doesn't have
-An ephemeral message.
+An ephemeral message.
A sequence number which must be incremented for each message sent by this peer.
The actual data of the message.
The document ID this message pertains to.
@@ -8,4 +8,4 @@In order to avoid infinite loops of ephemeral messages, every message has (a) a session ID, which is a random number generated by the sender at startup time; and (b) a sequence number. The combination of these two things allows us to discard messages we have already seen.
-A UUID encoded as a hex string. As of v1.0, a DocumentID is stored as a base58-encoded string with a checksum. +
A UUID encoded as a hex string. As of v1.0, a DocumentID is stored as a base58-encoded string with a checksum. Support for this format will be removed in a future version.
-Optional expand?: "before" | "after" | "both" | "none"Optional expand?: "before" | "after" | "both" | "none"Optional data?: Uint8ArrayOptional documentThe peer ID of the sender of this message
+Optional data?: Uint8ArrayOptional documentThe peer ID of the sender of this message
The peer ID of the recipient of this message
-Callback which is called by various methods in this library to notify the +
Callback which is called by various methods in this library to notify the user of what changes have been made.
A branded type for peer IDs
-A branded type for peer IDs
+These are message types that a NetworkAdapter surfaces to a Repo.
-These are message types that a NetworkAdapter surfaces to a Repo.
+Sent by a Repo to request a document from a peer.
+Sent by a Repo to request a document from a peer.
The automerge sync message
The document ID of the document this message is for
This is identical to a SyncMessage except that it is sent by a Repo as the initial sync message when asking the other peer if it has the document.
-A randomly generated string created when the Repo starts up
-A randomly generated string created when the Repo starts up
+A function that determines whether we should share a document with a peer
+A function that determines whether we should share a document with a peer
Optional documentId: DocumentIdA branded type for storage IDs
-A branded type for storage IDs
+A storage key is an array of strings that represents a path to a value in a +
A storage key is an array of strings that represents a path to a value in a StorageAdapter.
Storage keys are arrays because they are hierarchical and they allow the storage subsystem to do range queries for all keys that have a particular prefix. For example, incremental changes for a @@ -8,4 +8,4 @@
However, the storage adapter implementation should be agnostic to the meaning of the key and should not assume any particular structure.
-A sync message for a particular document
+A sync message for a particular document
The automerge sync message
The document ID of the document this message is for
-An error occurred. The other end will terminate the connection after sending this message
+An error occurred. The other end will terminate the connection after sending this message
A message from the client to the server
-A message from the client to the server
+A message from the server to the client
-A message from the server to the client
+Sent by the client to the server to tell the server the clients PeerID
+Sent by the client to the server to tell the server the clients PeerID
Metadata presented by the peer
The PeerID of the client
The protocol version the client supports
-Sent by the server in response to a "join" message to advertise the servers PeerID
+Sent by the server in response to a "join" message to advertise the servers PeerID
Metadata presented by the peer
The protocol version the server selected for this connection
The PeerID of the server
The PeerID of the client
-The versions of the websocket protocol
-The versions of the websocket protocol
+A map from peer ID to their last heartbeat timestamp
-A map from peer ID to their last heartbeat timestamp
+A map from peer ID to their state
-A map from peer ID to their state
+Const Possible internal states for a DocHandle
+Const Possible internal states for a DocHandle
Readonly DELETED: "deleted"The document has been deleted from the repo
Readonly IDLE: "idle"The handle has been created but not yet loaded or requested
Readonly LOADING: "loading"We are waiting for storage to finish loading
@@ -6,4 +6,4 @@Readonly REQUESTING: "requesting"We are waiting for someone in the network to respond to a sync request
Readonly UNAVAILABLE: "unavailable"The document was not available in storage or from any connected peers
Readonly UNLOADED: "unloaded"The document has been unloaded from the handle, to free memory usage
-Const Const Const A React context which provides access to an Automerge repo.
-Const A React context which provides access to an Automerge repo.
+
The most basic CRDT: an integer value that can be changed only by +
- Preparing search index...
- The search index is not available
Automerge Repo - v2.0.0-alpha.20Class Counter
The most basic CRDT: an integer value that can be changed only by incrementing and decrementing. Since addition of integers is commutative, the value trivially converges.
Index
Constructors
x + ''. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf -Returns number
Settings
Member Visibility
Theme
On This Page
Returns number
Settings
Member Visibility
Theme
On This Page