1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
//! # Automerge
//!
//! Automerge is a library of data structures for building collaborative,
//! [local-first](https://www.inkandswitch.com/local-first/) applications. The
//! idea of automerge is to provide a data structure which is quite general,
//! \- consisting of nested key/value maps and/or lists - which can be modified
//! entirely locally but which can at any time be merged with other instances of
//! the same data structure.
//!
//! In addition to the core data structure (which we generally refer to as a
//! "document"), we also provide an implementation of a sync protocol (in
//! [`crate::sync`]) which can be used over any reliable in-order transport; and
//! an efficient binary storage format.
//!
//! This crate is organised around two representations of a document -
//! [`Automerge`] and [`AutoCommit`]. The difference between the two is that
//! [`AutoCommit`] manages transactions for you. Both of these representations
//! implement [`ReadDoc`] for reading values from a document and
//! [`sync::SyncDoc`] for taking part in the sync protocol. [`AutoCommit`]
//! directly implements [`transaction::Transactable`] for making changes to a
//! document, whilst [`Automerge`] requires you to explicitly create a
//! [`transaction::Transaction`].
//!
//! NOTE: The API this library provides for modifying data is quite low level
//! (somewhat analogous to directly creating JSON values rather than using
//! `serde` derive macros or equivalent). If you're writing a Rust application which uses automerge
//! you may want to look at [autosurgeon](https://github.com/automerge/autosurgeon).
//!
//! ## Data Model
//!
//! An automerge document is a map from strings to values
//! ([`Value`]) where values can be either
//!
//! * A nested composite value which is either
//!   * A map from strings to values ([`ObjType::Map`])
//!   * A list of values ([`ObjType::List`])
//!   * A text object (a sequence of unicode characters) ([`ObjType::Text`])
//! * A primitive value ([`ScalarValue`]) which is one of
//!   * A string
//!   * A 64 bit floating point number
//!   * A signed 64 bit integer
//!   * An unsigned 64 bit integer
//!   * A boolean
//!   * A counter object (a 64 bit integer which merges by addition)
//!     ([`ScalarValue::Counter`])
//!   * A timestamp (a 64 bit integer which is milliseconds since the unix epoch)
//!
//! All composite values have an ID ([`ObjId`]) which is created when the value
//! is inserted into the document or is the root object ID [`ROOT`]. Values in
//! the document are then referred to by the pair (`object ID`, `key`). The
//! `key` is represented by the [`Prop`] type and is either a string for a maps,
//! or an index for sequences.
//!
//! ### Conflicts
//!
//! There are some things automerge cannot merge sensibly. For example, two
//! actors concurrently setting the key "name" to different values. In this case
//! automerge will pick a winning value in a random but deterministic way, but
//! the conflicting value is still available via the [`ReadDoc::get_all`] method.
//!
//! ### Change hashes and historical values
//!
//! Like git, points in the history of a document are identified by hash. Unlike
//! git there can be multiple hashes representing a particular point (because
//! automerge supports concurrent changes). These hashes can be obtained using
//! either [`Automerge::get_heads`] or [`AutoCommit::get_heads`] (note these
//! methods are not part of [`ReadDoc`] because in the case of [`AutoCommit`] it
//! requires a mutable reference to the document).
//!
//! These hashes can be used to read values from the document at a particular
//! point in history using the various `*_at` methods on [`ReadDoc`] which take a
//! slice of [`ChangeHash`] as an argument.
//!
//! ### Actor IDs
//!
//! Any change to an automerge document is made by an actor, represented by an
//! [`ActorId`]. An actor ID is any random sequence of bytes but each change by
//! the same actor ID must be sequential. This often means you will want to
//! maintain at least one actor ID per device. It is fine to generate a new
//! actor ID for each change, but be aware that each actor ID takes up space in
//! a document so if you expect a document to be long lived and/or to have many
//! changes then you should try to reuse actor IDs where possible.
//!
//! ### Text Encoding
//!
//! Both [`Automerge`] and [`AutoCommit`] provide a `with_encoding` method which
//! allows you to specify the [`crate::TextEncoding`] which is used for
//! interpreting the indexes passed to methods like [`ReadDoc::list_range`] or
//! [`transaction::Transactable::splice`]. The default encoding is UTF-8, but
//! you can switch to UTF-16.
//!
//! ## Sync Protocol
//!
//! See the [`sync`] module.
//!
//! ## Serde serialization
//!
//! Sometimes you just want to get the JSON value of an automerge document. For
//! this you can use [`AutoSerde`], which implements `serde::Serialize` for an
//! automerge document.
//!
//! ## Example
//!
//! Let's create a document representing an address book.
//!
//! ```
//! use automerge::{ObjType, AutoCommit, transaction::Transactable, ReadDoc};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let mut doc = AutoCommit::new();
//!
//! // `put_object` creates a nested object in the root key/value map and
//! // returns the ID of the new object, in this case a list.
//! let contacts = doc.put_object(automerge::ROOT, "contacts", ObjType::List)?;
//!
//! // Now we can insert objects into the list
//! let alice = doc.insert_object(&contacts, 0, ObjType::Map)?;
//!
//! // Finally we can set keys in the "alice" map
//! doc.put(&alice, "name", "Alice")?;
//! doc.put(&alice, "email", "[email protected]")?;
//!
//! // Create another contact
//! let bob = doc.insert_object(&contacts, 1, ObjType::Map)?;
//! doc.put(&bob, "name", "Bob")?;
//! doc.put(&bob, "email", "[email protected]")?;
//!
//! // Now we save the address book, we can put this in a file
//! let data: Vec<u8> = doc.save();
//! # Ok(())
//! # }
//! ```
//!
//! Now modify this document on two separate devices and merge the modifications.
//!
//! ```
//! use std::borrow::Cow;
//! use automerge::{ObjType, AutoCommit, transaction::Transactable, ReadDoc};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # let mut doc = AutoCommit::new();
//! # let contacts = doc.put_object(automerge::ROOT, "contacts", ObjType::List)?;
//! # let alice = doc.insert_object(&contacts, 0, ObjType::Map)?;
//! # doc.put(&alice, "name", "Alice")?;
//! # doc.put(&alice, "email", "[email protected]")?;
//! # let bob = doc.insert_object(&contacts, 1, ObjType::Map)?;
//! # doc.put(&bob, "name", "Bob")?;
//! # doc.put(&bob, "email", "[email protected]")?;
//! # let saved: Vec<u8> = doc.save();
//!
//! // Load the document on the first device and change alices email
//! let mut doc1 = AutoCommit::load(&saved)?;
//! let contacts = match doc1.get(automerge::ROOT, "contacts")? {
//!     Some((automerge::Value::Object(ObjType::List), contacts)) => contacts,
//!     _ => panic!("contacts should be a list"),
//! };
//! let alice = match doc1.get(&contacts, 0)? {
//!    Some((automerge::Value::Object(ObjType::Map), alice)) => alice,
//!    _ => panic!("alice should be a map"),
//! };
//! doc1.put(&alice, "email", "[email protected]")?;
//!
//!
//! // Load the document on the second device and change bobs name
//! let mut doc2 = AutoCommit::load(&saved)?;
//! let contacts = match doc2.get(automerge::ROOT, "contacts")? {
//!    Some((automerge::Value::Object(ObjType::List), contacts)) => contacts,
//!    _ => panic!("contacts should be a list"),
//! };
//! let bob = match doc2.get(&contacts, 1)? {
//!   Some((automerge::Value::Object(ObjType::Map), bob)) => bob,
//!   _ => panic!("bob should be a map"),
//! };
//! doc2.put(&bob, "name", "Robert")?;
//!
//! // Finally, we can merge the changes from the two devices
//! doc1.merge(&mut doc2)?;
//! let bobsname: Option<automerge::Value> = doc1.get(&bob, "name")?.map(|(v, _)| v);
//! assert_eq!(bobsname, Some(automerge::Value::Scalar(Cow::Owned("Robert".into()))));
//!
//! let alices_email: Option<automerge::Value> = doc1.get(&alice, "email")?.map(|(v, _)| v);
//! assert_eq!(alices_email, Some(automerge::Value::Scalar(Cow::Owned("[email protected]".into()))));
//! # Ok(())
//! # }
//! ```
//!

#![doc(
    html_logo_url = "https://raw.githubusercontent.com/automerge/automerge-rs/main/img/brandmark.svg",
    html_favicon_url = "https:///raw.githubusercontent.com/automerge/automerge-rs/main/img/favicon.ico"
)]
#![warn(
    missing_debug_implementations,
    // missing_docs, // TODO: add documentation!
    rust_2018_idioms,
    unreachable_pub,
    bad_style,
    dead_code,
    improper_ctypes,
    non_shorthand_field_patterns,
    no_mangle_generic_items,
    overflowing_literals,
    path_statements,
    patterns_in_fns_without_body,
    private_in_public,
    unconditional_recursion,
    unused,
    unused_allocation,
    unused_comparisons,
    unused_parens,
    while_true
)]

#[doc(hidden)]
#[macro_export]
macro_rules! log {
     ( $( $t:tt )* ) => {
          {
            use $crate::__log;
            __log!( $( $t )* );
          }
     }
 }

#[cfg(all(feature = "wasm", target_family = "wasm"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __log {
     ( $( $t:tt )* ) => {
         web_sys::console::log_1(&format!( $( $t )* ).into());
     }
 }

#[cfg(not(all(feature = "wasm", target_family = "wasm")))]
#[doc(hidden)]
#[macro_export]
macro_rules! __log {
     ( $( $t:tt )* ) => {
         println!( $( $t )* );
     }
 }

mod autocommit;
mod automerge;
mod autoserde;
mod change;
mod change_graph;
mod clock;
mod columnar;
mod convert;
mod error;
mod exid;
mod indexed_cache;
mod keys;
mod keys_at;
mod legacy;
mod list_range;
mod list_range_at;
mod map_range;
mod map_range_at;
pub mod op_observer;
mod op_set;
mod op_tree;
mod parents;
mod query;
mod read;
mod storage;
pub mod sync;
pub mod transaction;
mod types;
mod value;
mod values;
#[cfg(feature = "optree-visualisation")]
mod visualisation;

pub use crate::automerge::{Automerge, OnPartialLoad};
pub use autocommit::{AutoCommit, AutoCommitWithObs};
pub use autoserde::AutoSerde;
pub use change::{Change, LoadError as LoadChangeError};
pub use error::AutomergeError;
pub use error::InvalidActorId;
pub use error::InvalidChangeHashSlice;
pub use exid::{ExId as ObjId, ObjIdFromBytesError};
pub use keys::Keys;
pub use keys_at::KeysAt;
pub use legacy::Change as ExpandedChange;
pub use list_range::ListRange;
pub use list_range_at::ListRangeAt;
pub use map_range::MapRange;
pub use map_range_at::MapRangeAt;
pub use op_observer::OpObserver;
pub use op_observer::Patch;
pub use op_observer::VecOpObserver;
pub use parents::{Parent, Parents};
pub use read::ReadDoc;
pub use types::{ActorId, ChangeHash, ObjType, OpType, ParseChangeHashError, Prop, TextEncoding};
pub use value::{ScalarValue, Value};
pub use values::Values;

/// The object ID for the root map of a document
pub const ROOT: ObjId = ObjId::Root;