Explicit Automerge documents, changes and synchronization for JVM Clojure.
Explicit Automerge documents, changes and synchronization for JVM Clojure.
(actor-id doc)Return this replica's actor ID as hexadecimal.
Return this replica's actor ID as hexadecimal.
(apply-changes! doc changes)Decode and validate the complete batch, then apply it in place. Duplicate delivery is harmless; missing dependencies remain queued until received. Decode errors leave doc unchanged. Native application errors may change its internal state: discard and reload that working replica before retrying. Does not clone the document or roll back imported changes. Returns doc.
Decode and validate the complete batch, then apply it in place. Duplicate delivery is harmless; missing dependencies remain queued until received. Decode errors leave doc unchanged. Native application errors may change its internal state: discard and reload that working replica before retrying. Does not clone the document or roll back imported changes. Returns doc.
(author doc)Return this replica's author identifier as copied bytes, or nil. Author IDs provide application attribution; actor IDs identify sequential execution.
Return this replica's author identifier as copied bytes, or nil. Author IDs provide application attribution; actor IDs identify sequential execution.
(block-at context object i)Return the block map at an exact text index, or nil for a text character. Use spans to enumerate markers. The index must identify an existing element.
Return the block map at an exact text index, or nil for a text character. Use spans to enumerate markers. The index must identify an existing element.
(bytes value)Return a fresh byte array in Automerge's full-save format. For a SavedDocument, copy its encoding; for a live Document, save directly without a wrapper and advance its native incremental-save cursor.
Return a fresh byte array in Automerge's full-save format. For a SavedDocument, copy its encoding; for a live Document, save directly without a wrapper and advance its native incremental-save cursor.
(capture-delta doc acknowledged-heads)Atomically capture {:from heads :heads heads :changes [bytes ...]} since acknowledged-heads. Does not advance a cursor. Retain this batch until delivery is acknowledged, then use its :heads as the next checkpoint. Unknown heads fail. Causally incomplete input fails with :missing-deps rather than silently omitting queued changes. Retain incoming bytes or a full save until dependencies arrive.
Atomically capture {:from heads :heads heads :changes [bytes ...]} since
acknowledged-heads. Does not advance a cursor. Retain this batch until delivery
is acknowledged, then use its :heads as the next checkpoint. Unknown heads fail.
Causally incomplete input fails with :missing-deps rather than silently omitting
queued changes. Retain incoming bytes or a full save until dependencies arrive.(change! doc f)(change! doc {:keys [message time]} f)Run f with an exclusive change handle. Commit once on success, roll back on exception, and return f's result. The handle is valid only in this callback, on its invoking thread. Options: :message string and :time epoch seconds. Nested changes and cross-document calls in callbacks are rejected.
Run f with an exclusive change handle. Commit once on success, roll back on exception, and return f's result. The handle is valid only in this callback, on its invoking thread. Options: :message string and :time epoch seconds. Nested changes and cross-document calls in callbacks are rejected.
(change-by-hash doc hash)Return a copied encoded change by hash, or nil when unknown.
Return a copied encoded change by hash, or nil when unknown.
(change-info data)Decode an encoded change into copied metadata. :time is epoch seconds; :actor, :hash and :deps are hexadecimal. Does not retain native state.
Decode an encoded change into copied metadata. :time is epoch seconds; :actor, :hash and :deps are hexadecimal. Does not retain native state.
(changes-since doc have-heads)Return encoded changes missing from a set of heads. [] requests all changes.
Return encoded changes missing from a set of heads. [] requests all changes.
(conflicts context object key)Return concurrent values when more than one exists, otherwise [].
Return concurrent values when more than one exists, otherwise [].
(counter n)Construct a counter scalar. Use increment! to change its value collaboratively.
Construct a counter scalar. Use increment! to change its value collaboratively.
(create)Create an empty, mutable, GC-managed document with a fresh actor ID.
Create an empty, mutable, GC-managed document with a fresh actor ID.
(cursor context object position)(cursor context object position {:keys [move] :or {move :after}})Return a serializable, stable position token for a list or text object. Position is :start, :end, or an existing element index (UTF-16 for text). Options: :move :before/:after (default :after) when that element is deleted.
Return a serializable, stable position token for a list or text object. Position is :start, :end, or an existing element index (UTF-16 for text). Options: :move :before/:after (default :after) when that element is deleted.
(cursor-position context object token)Resolve a cursor token against the current object state.
Resolve a cursor token against the current object state.
(delete! tx object key)Delete a map property or list element. Does not delete the root object.
Delete a map property or list element. Does not delete the root object.
(diff doc before-heads)(diff doc before-heads after-heads)Copy native patches between two explicit sets of heads. The two-argument form compares before-heads to current heads under the document lock. [] denotes empty history. Patches describe visible edits; transport :changes from capture-delta to replicate history. Object references in patches are ID maps.
Copy native patches between two explicit sets of heads. The two-argument form compares before-heads to current heads under the document lock. [] denotes empty history. Patches describe visible edits; transport :changes from capture-delta to replicate history. Object references in patches are ID maps.
(document? x)True for a live Automerge document handle.
True for a live Automerge document handle.
(encode-sync-state state)Encode a peer's sync state for persistence.
Encode a peer's sync state for persistence.
(entries context object)Eager vector of [key value] pairs for a map or [index value] for a list. Uses one native range query. Nested objects remain handles.
Eager vector of [key value] pairs for a map or [index value] for a list. Uses one native range query. Nested objects remain handles.
(fork doc)(fork doc at-heads)Fork into an independent document with a fresh actor ID. Optionally fork at a vector of heads. An empty vector selects the empty document history.
Fork into an independent document with a fresh actor ID. Optionally fork at a vector of heads. An empty vector selects the empty document history.
(generate-sync-message! state)Generate the next message and advance peer state. Returns bytes, or nil if there is nothing to send. Deliver messages reliably and in order per peer.
Generate the next message and advance peer state. Returns bytes, or nil if there is nothing to send. Deliver messages reliably and in order per peer.
(get context object key)(get context object key not-found)Read one map property or list element. Nested objects remain handles. Missing map properties return not-found (nil by default); stored null is always nil. Invalid list indices raise native errors.
Read one map property or list element. Nested objects remain handles. Missing map properties return not-found (nil by default); stored null is always nil. Invalid list indices raise native errors.
(get-all context object key)Return all concurrent values as [{:id operation-id :value value} ...]. Includes the ordinary winning value. Missing entries return [].
Return all concurrent values as [{:id operation-id :value value} ...].
Includes the ordinary winning value. Missing entries return [].(get-in context path)(get-in context path not-found)Resolve a path from root. Each step performs a native lookup. For repeated access, keep the returned object handle. This does not materialize subtrees.
Resolve a path from root. Each step performs a native lookup. For repeated access, keep the returned object handle. This does not materialize subtrees.
(heads doc)Return the current change hashes as a vector of hexadecimal strings.
Return the current change hashes as a vector of hexadecimal strings.
(increment! tx object key delta)Add a signed integer delta to a counter in a map or list.
Add a signed integer delta to a counter in a map or list.
(insert! tx object i value)Insert a scalar at a list index (size appends). Requires an active change.
Insert a scalar at a list index (size appends). Requires an active change.
(insert-object! tx parent index kind)Insert a new :map, :list or :text into a list; return its handle.
Insert a new :map, :list or :text into a list; return its handle.
(join-block! tx object i)Remove the block marker at an exact text index, preserving surrounding text.
Remove the block marker at an exact text index, preserving surrounding text.
(keys context object)Eager vector of a map's string keys.
Eager vector of a map's string keys.
(load data)Load Automerge bytes or a SavedDocument into an independent live document with a fresh actor ID. Automerge validates the encoded contents when loading.
Load Automerge bytes or a SavedDocument into an independent live document with a fresh actor ID. Automerge validates the encoded contents when loading.
(load-incremental! doc data)Apply a SavedDocument, full-save bytes, incremental save, or concatenated change bytes. Returns doc. Follows upstream's permissive partial-load behavior; use apply-changes! for strict ingestion of individual encoded changes.
Apply a SavedDocument, full-save bytes, incremental save, or concatenated change bytes. Returns doc. Follows upstream's permissive partial-load behavior; use apply-changes! for strict ingestion of individual encoded changes.
(mark! tx object start end name value)(mark! tx object start end name value expand)Set a named scalar mark on [start,end) in a text object. Indices use UTF-16. Expansion controls adjacent insertions: :none (default), :before, :after, :both. Empty ranges are allowed, including empty text.
Set a named scalar mark on [start,end) in a text object. Indices use UTF-16. Expansion controls adjacent insertions: :none (default), :before, :after, :both. Empty ranges are allowed, including empty text.
(marks context object)Copy text annotations into [{:start n :end n :name string :value scalar} ...].
Copy text annotations into [{:start n :end n :name string :value scalar} ...].
(marks-at context object i)Read active marks as a name/value map at a text boundary, including its end.
Read active marks as a name/value map at a text boundary, including its end.
(materialize context)(materialize context object)Copy the visible subtree into persistent Clojure data. This walks and copies the entire subtree. History, object identity and hidden conflicts are omitted; Counter and UInt scalars retain their explicit types.
Copy the visible subtree into persistent Clojure data. This walks and copies the entire subtree. History, object identity and hidden conflicts are omitted; Counter and UInt scalars retain their explicit types.
(merge! destination source)Merge source into destination in place. Returns destination.
Merge source into destination in place. Returns destination.
(missing-deps doc)(missing-deps doc remote-heads)Hashes needed by queued changes or by the optional advertised remote heads.
Hashes needed by queued changes or by the optional advertised remote heads.
(object-id object)Return an object's Automerge identifier as a string.
Return an object's Automerge identifier as a string.
(object-type object)Return :map, :list or :text for an object handle.
Return :map, :list or :text for an object handle.
(object? x)True for a nested object handle. The root constant is not a handle.
True for a nested object handle. The root constant is not a handle.
(put! tx object key value)Set a scalar map property or replace an existing list element. Strings are immutable scalars; use a :text object and splice-text! for collaborative text. Setting a counter replaces it; increment! preserves concurrent increments.
Set a scalar map property or replace an existing list element. Strings are immutable scalars; use a :text object and splice-text! for collaborative text. Setting a counter replaces it; increment! preserves concurrent increments.
(put-object! tx parent key kind)Create a new :map, :list or :text at a map key or existing list position. Returns its handle. Replacing an object creates a new identity.
Create a new :map, :list or :text at a map key or existing list position. Returns its handle. Replacing an object creates a new identity.
(receive-sync-message! state message)Apply an incoming peer message and update its state. Returns the document.
Apply an incoming peer message and update its state. Returns the document.
(replace-block! tx object i)Replace the block marker at an exact text index with a new empty map. Returns its handle. To preserve identity, edit the existing block map instead.
Replace the block marker at an exact text index with a new empty map. Returns its handle. To preserve identity, edit the existing block map instead.
(resolve-object context id)Resolve a serialized object ID in this replica. This preserves identity even after an object moves or becomes unreachable from root. Unknown IDs fail.
Resolve a serialized object ID in this replica. This preserves identity even after an object moves or becomes unreachable from root. Unknown IDs fail.
The root map identifier, used with an explicit document or change.
The root map identifier, used with an explicit document or change.
(save doc)Capture a complete immutable SavedDocument, retaining history and queued changes. Advances the native incremental-save cursor.
Capture a complete immutable SavedDocument, retaining history and queued changes. Advances the native incremental-save cursor.
(save-incremental! doc)Serialize changes since the previous save, bytes or save-incremental! on this live document. Reading bytes from a SavedDocument does not advance any cursor. Advances its save cursor; use one persistence writer per document.
Serialize changes since the previous save, bytes or save-incremental! on this live document. Reading bytes from a SavedDocument does not advance any cursor. Advances its save cursor; use one persistence writer per document.
(saved-document data)Copy full-save bytes into an immutable SavedDocument. Checks the Automerge signature, initial snapshot chunk and all chunk lengths/boundaries. Does not check checksums, decompress or validate document contents; use load for that.
Copy full-save bytes into an immutable SavedDocument. Checks the Automerge signature, initial snapshot chunk and all chunk lengths/boundaries. Does not check checksums, decompress or validate document contents; use load for that.
(saved-document? x)True for an immutable saved Automerge document.
True for an immutable saved Automerge document.
(set-author! doc value)Set the author bytes for subsequent local changes, or nil to clear them. Automerge manages actor rotation when the author changes. Returns doc.
Set the author bytes for subsequent local changes, or nil to clear them. Automerge manages actor rotation when the author changes. Returns doc.
(size context object)Map property count, list length, or text length in UTF-16 units.
Map property count, list length, or text length in UTF-16 units.
(spans context object)Read rich text as text spans and block markers. Every span includes its UTF-16 :index. Text spans have :text and :marks; blocks have :object-id. Resolve a block ID to read/edit its map, including arbitrary nested attributes.
Read rich text as text spans and block markers. Every span includes its UTF-16 :index. Text spans have :text and :marks; blocks have :object-id. Resolve a block ID to read/edit its map, including arbitrary nested attributes.
(splice-text! tx object index-value delete-count value)Replace delete-count UTF-16 units at index with a string. Positions must fall on Unicode scalar boundaries; use cursors for positions that survive edits.
Replace delete-count UTF-16 units at index with a string. Positions must fall on Unicode scalar boundaries; use cursors for positions that survive edits.
(split-block! tx object i)Insert an empty block marker at a text boundary and return its map handle. Set its type, parents and attributes with ordinary map/list operations. The marker occupies one UTF-16 unit.
Insert an empty block marker at a text boundary and return its map handle. Set its type, parents and attributes with ordinary map/list operations. The marker occupies one UTF-16 unit.
(sync-state doc)(sync-state doc data)Create GC-managed sync state for one document/peer connection. Keep a separate state for each peer. Optionally restore bytes from encode-sync-state.
Create GC-managed sync state for one document/peer connection. Keep a separate state for each peer. Optionally restore bytes from encode-sync-state.
(text context object)Copy a collaborative text object's current content into a JVM string.
Copy a collaborative text object's current content into a JVM string.
(uint n)Construct an unsigned 64-bit scalar from a non-negative Clojure integer.
Construct an unsigned 64-bit scalar from a non-negative Clojure integer.
(unmark! tx object start end name)(unmark! tx object start end name expand)Remove a named mark from [start,end). Expansion defaults to :none.
Remove a named mark from [start,end). Expansion defaults to :none.
(update-text! tx object value)Diff the current plain text against value using Automerge's text diff and apply the edits. Cost depends on both texts. For rich text use block, mark and splice operations; this helper rejects text containing block markers.
Diff the current plain text against value using Automerge's text diff and apply the edits. Cost depends on both texts. For rich text use block, mark and splice operations; this helper rejects text containing block markers.
(with-change [tx doc options] & body)Evaluate body in a change. Binding is [tx doc] or [tx doc options].
Evaluate body in a change. Binding is [tx doc] or [tx doc options].
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |