Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions content/blog/automerge-2.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Of course, even the most productive authors struggle to type an entire paper qui
| automerge 2.0 | 129,062 |
| automerge 0.14 | 146,406,415 |

The binary format works wonders in this example, encoding a full history for the document with only 30% overhead. That's less than one additional byte per character! The naive JSON encoding often used circa automerge 0.14 could exceed 1,300 bytes _per character_. If you'd like to learn more about the file format, we have a [specification](https://automerge.org/automerge-binary-format-spec/) document.
The binary format works wonders in this example, encoding a full history for the document with only 30% overhead. That's less than one additional byte per character! The naive JSON encoding often used circa Automerge 0.14 could exceed 1,300 bytes _per character_. If you'd like to learn more about the file format, we have a [specification](https://automerge.org/automerge-binary-format-spec/) document.

| Load ~260k operations | Timing (ms) |
| ------------------------ | ----------- |
Expand All @@ -86,7 +86,7 @@ While we are proud of these results, we will continue to invest in improved perf

A few notes about methodology before we move on. The particular implementation we used to run the benchmarks can be found [here](https://github.com/alexjg/automerge-perf-comparisons). These numbers were produced on Ryzen 9 7900X. The "timing" column is how long it takes to apply every single edit in the trace, whilst the "memory" common is the peak memory usage during this process.

The improvements found in "2.0.2-unstable" mostly result from an upcoming improved API for text. Also note that the "automerge 1.0.1" here is actually the `automerge@1.0.1-preview-7` release. Automerge 1.0.1 was a significant rewrite from 0.14 and has a similar architecture to the Rust implementation. Improvements between 1.0.1 and 2.0.1 are a result of both optimization and adopting WebAssembly rather than an architectural change.
The improvements found in "2.0.2-unstable" mostly result from an upcoming improved API for text. Also note that the "Automerge 1.0.1" here is actually the `automerge@1.0.1-preview-7` release. Automerge 1.0.1 was a significant rewrite from 0.14 and has a similar architecture to the Rust implementation. Improvements between 1.0.1 and 2.0.1 are a result of both optimization and adopting WebAssembly rather than an architectural change.

## Portability & Mobile Devices

Expand Down Expand Up @@ -114,7 +114,7 @@ It's under active development, and available in beta right now. We'll talk more

## Rust Developer Experience Improvements

We've seen tremendous enthusiasm for the native Rust experience of Automerge, and the current Rust API is powerful and fast. Unfortunately, it's also low-level and can be difficult to work with directly. To make building Rust applications against automerge easier, Alex built [Autosurgeon](https://github.com/automerge/autosurgeon), a library that helps bind Rust data structures to Automerge documents, and we'll continue to listen to our Rust users and improve on that experience.
We've seen tremendous enthusiasm for the native Rust experience of Automerge, and the current Rust API is powerful and fast. Unfortunately, it's also low-level and can be difficult to work with directly. To make building Rust applications against Automerge easier, Alex built [Autosurgeon](https://github.com/automerge/autosurgeon), a library that helps bind Rust data structures to Automerge documents, and we'll continue to listen to our Rust users and improve on that experience.

## Improved Synchronization

Expand Down
2 changes: 1 addition & 1 deletion content/blog/automerge-3.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ In Automerge 3.0, we're fully committing to the new API—we've removed the `Tex

## Try it out

Automerge 3.0 is used by default when installing the latest version (`2.1.0`) of `@automerge/automerge-repo` or `@automerge/react`. If you're new to automerge take a look at the [tutorial](/docs/tutorial/) to get started.
Automerge 3.0 is used by default when installing the latest version (`2.1.0`) of `@automerge/automerge-repo` or `@automerge/react`. If you're new to Automerge take a look at the [tutorial](/docs/tutorial/) to get started.

If you already have an Automerge codebase take a look at the [migration guide](/docs/guides/migrating-from-automerge-2-to-automerge-3) to see if you need to change anything other than the version number of Automerge you depend on. If you just depend on `@automerge/automerge-repo` you'll need to run `npm update @automerge/automerge` (or your package manager's equivalent) to pull in the new version.

Expand Down
8 changes: 4 additions & 4 deletions content/blog/automerge-anywhere.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ This means you should be able to conveniently use Automerge in vanilla JS applic
If you find a place where none of our approaches work for you then please let us know by inquring [in our Discord](https://discord.gg/TrgN9FkYSa) or by filing a (GitHub issue)[https://github.com/automerge/automerge].

## How to use it
We've collected of examples showing how to initialize automerge in specific environments in [a new documentation page](/docs/reference/library-initialization/). If you had trouble with Automerge in your environment before, try again without changing anything first. This new release improved support for a few edge cases within the old API, so you might find everything just starts working on its own.
We've collected of examples showing how to initialize Automerge in specific environments in [a new documentation page](/docs/reference/library-initialization/). If you had trouble with Automerge in your environment before, try again without changing anything first. This new release improved support for a few edge cases within the old API, so you might find everything just starts working on its own.

If you do need to use the new manual initialization code you'll need to to make a couple of small changes:
1. Import the `/slim` variant of automerge and separately, the WebAssembly blob.
1. Import the `/slim` variant of Automerge and separately, the WebAssembly blob.
2. Await the result of calling `Automerge.initializeWasm(wasm)`.

For example, here's how to perform initialization in a Vite app without importing WebAssembly modules:
Expand Down Expand Up @@ -69,5 +69,5 @@ await next.initializeBase64Wasm(automergeWasmBase64)
const repo = new Repo({..})
```

### For libraries which depend on automerge
If you are writing a library which depends on automerge that other applications might use, please be sure to only import the `@automerge/automerge/slim` package. Doing so will ensure other users retain the option of
### For libraries which depend on Automerge
If you are writing a library which depends on Automerge that other applications might use, please be sure to only import the `@automerge/automerge/slim` package. Doing so will ensure other users retain the option of
8 changes: 4 additions & 4 deletions content/blog/automerge-repo.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,8 +159,8 @@ Note that when `Repo` receives changes over the network or registers local chang

export let documentUrl: AutomergeUrl

// Doc is an automerge store with a `change` method which accepts
// a standard automerge change function
// Doc is an Automerge store with a `change` method which accepts
// a standard Automerge change function
const doc = document<HasCount>(documentUrl)
const increment = () => {
doc.change((d: HasCount) => (d.count = (d.count || 0) + 1))
Expand All @@ -174,7 +174,7 @@ Note that when `Repo` receives changes over the network or registers local chang

## What about &lt;X&gt;?

We'd love to help you make automerge work in your favorite development environment! Please reach out to us on GitHub or via [our Slack](https://join.slack.com/t/automerge/shared_invite/zt-e4p3760n-kKh7r3KRH1YwwNfiZM8ktw).
We'd love to help you make Automerge work in your favorite development environment! Please reach out to us on GitHub or via [our Slack](https://join.slack.com/t/automerge/shared_invite/zt-e4p3760n-kKh7r3KRH1YwwNfiZM8ktw).

## Extending `automerge-repo`

Expand All @@ -194,7 +194,7 @@ The `automerge-repo` library provides network adapters for WebSocket, MessageCha

### Other languages/platforms

This release of `automerge-repo` is just for javascript. Automerge is a multi-language library though and there are efforts under way to implement `automerge-repo` on other platforms. The most mature of these is [`automerge-repo-rs`](https://github.com/automerge/automerge-repo-rs). We welcome contributions and please reach out if you're starting to develop `automerge-repo` for a new platform.
This release of `automerge-repo` is just for JavaScript. Automerge is a multi-language library though and there are efforts under way to implement `automerge-repo` on other platforms. The most mature of these is [`automerge-repo-rs`](https://github.com/automerge/automerge-repo-rs). We welcome contributions and please reach out if you're starting to develop `automerge-repo` for a new platform.

## Beta Quality

Expand Down
2 changes: 1 addition & 1 deletion content/blog/rich-text.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Block markers have a type - such as "ordered list item" - and parents - such as

These elements map quite closely to user actions whilst editing. Typically a text editor allows you to highlight a sequence of characters and format them - regardless of whether they are in different regions of the document (try highlighting and bolding half of a list item and preceding paragraph in Google Docs for example). On the other hand, inserting a new list item is usually achieved by pressing Enter at the end of the current list item - inserting a block marker; and indenting a list item is done by pressing a button in the toolbar - inserting a new parent into the block parents.

Choosing operations on the underlying data structure which map well to typical actions performed while editing text means we can provide accurate representations of the difference between two versions of the text. Here's the same structure change example in automerge
Choosing operations on the underlying data structure which map well to typical actions performed while editing text means we can provide accurate representations of the difference between two versions of the text. Here's the same structure change example in Automerge

<video controls playsinline autoplay muted loop>
<source src="automerge-structure-change.webm" type="video/webm" />
Expand Down
2 changes: 1 addition & 1 deletion content/docs/cookbook/modeling-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ In this section, we will discuss how to model data within a particular document,

## How many documents?

You can decide which things to group together as one Automerge document (more fine grained or more coarse grained) based on what makes sense in your app. Having hundreds of docs should be fine — we've built prototypes of that scale. One major automerge project, [PushPin](https://github.com/automerge/pushpin), was built around very granular documents. This had a lot of benefits, but the overhead of syncing many thousands of documents was high.
You can decide which things to group together as one Automerge document (more fine grained or more coarse grained) based on what makes sense in your app. Having hundreds of docs should be fine — we've built prototypes of that scale. One major Automerge project, [PushPin](https://github.com/automerge/pushpin), was built around very granular documents. This had a lot of benefits, but the overhead of syncing many thousands of documents was high.

We believe on the whole there's an art to the granularity of data that is universal. When should you have two JSON documents or two SQLite databases or two rows? We suspect that an Automerge document is best suited to being a unit of collaboration between two people or a small group.

Expand Down
2 changes: 1 addition & 1 deletion content/docs/cookbook/rich-text-prosemirror-react.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ function App({ docUrl }: { docUrl: AutomergeUrl }) {
const [view, setView] = useState<EditorView | null>(null)
useEffect(() => {
if (editorRoot.current != null && loaded) {
// This is the integration with automerge
// This is the integration with Automerge
const { pmDoc: doc, schema, plugin } = init(handle!, ["text"])
const plugins = exampleSetup({schema})
plugins.push(plugin)
Expand Down
6 changes: 3 additions & 3 deletions content/docs/cookbook/rich-text-prosemirror-vanilla.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ const repo = new Repo({
})
```

Now, we'll store the automerge URL for the document we are editing in the browsers URL hash. This way, we can share the URL with others to collaborate on the document.
Now, we'll store the Automerge URL for the document we are editing in the browsers URL hash. This way, we can share the URL with others to collaborate on the document.

```js title="main.js"
// Get the document ID from the URL fragment if it's there. Otherwise, create
Expand All @@ -51,10 +51,10 @@ if (docUrl && isValidAutomergeUrl(docUrl)) {
}
```

At this point we have a document handle with a fully loaded automerge document, now we need to wire up a prosemirror editor.
At this point we have a document handle with a fully loaded Automerge document, now we need to wire up a prosemirror editor.

```js title="main.js"
// This is the integration with automerge.
// This is the integration with Automerge.
const { schema, doc, plugin } = init(handle, ["text"])

const editorConfig = {
Expand Down
16 changes: 8 additions & 8 deletions content/docs/reference/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,23 @@ template: docs

<div class="note">

This documentation is mostly focused on the javascript implementation of automerge. Some things will translate to other languages but some things — in particular the "repository" concept and `automerge-repo` library — will not.
This documentation is mostly focused on the JavaScript implementation of Automerge. Some things will translate to other languages but some things — in particular the "repository" concept and `automerge-repo` library — will not.

</div>

## Core concepts

Using automerge means storing your data in automerge [documents](#documents). Documents have [URL](#document-urls)s which you can use to share or request documents with/from other peers using a [repository](#repositories). Repositories give you [`DocHandle`](#dochandles)s which you use to make changes to the document and listen for changes from other peers.
Using Automerge means storing your data in Automerge [documents](#documents). Documents have [URL](#document-urls)s which you can use to share or request documents with/from other peers using a [repository](#repositories). Repositories give you [`DocHandle`](#dochandles)s which you use to make changes to the document and listen for changes from other peers.

Automerge as used in javascript applications is actually a composition of two libraries. [`automerge-repo`](https://www.npmjs.com/package/@automerge/automerge-repo) which provides the networking and storage plumbing, and [`automerge`](https://www.npmjs.com/package/@automerge/automerge) which provides the CRDT implementation, a transport agnostic [sync protocol](#sync-protocol), and a compressed [storage format](#storage-format) which `automerge-repo` uses to implement various networking and storage plugins.
Automerge as used in JavaScript applications is actually a composition of two libraries. [`automerge-repo`](https://www.npmjs.com/package/@automerge/automerge-repo) which provides the networking and storage plumbing, and [`automerge`](https://www.npmjs.com/package/@automerge/automerge) which provides the CRDT implementation, a transport agnostic [sync protocol](#sync-protocol), and a compressed [storage format](#storage-format) which `automerge-repo` uses to implement various networking and storage plugins.

### Documents

A document is the "unit of change" in automerge. It's like a combination of a JSON object and a git repository. What does that mean?
A document is the "unit of change" in Automerge. It's like a combination of a JSON object and a git repository. What does that mean?

Like a JSON object, an automerge document is a map from strings to values, where the values can be maps, arrays, or simple types like strings or numbers. See the [data model](/docs/reference/documents/) section for more details.
Like a JSON object, an Automerge document is a map from strings to values, where the values can be maps, arrays, or simple types like strings or numbers. See the [data model](/docs/reference/documents/) section for more details.

Like a git repository, an automerge document has a history made up of commits. Every time you make a change to a document you are adding to the history of the document. The combination of this history and some rules about how to handle conflicts means that any two automerge documents can always be merged. See [merging](/docs/reference/under-the-hood/merge-rules) for the gory details.
Like a git repository, an Automerge document has a history made up of commits. Every time you make a change to a document you are adding to the history of the document. The combination of this history and some rules about how to handle conflicts means that any two Automerge documents can always be merged. See [merging](/docs/reference/under-the-hood/merge-rules) for the gory details.

### Repositories

Expand All @@ -31,15 +31,15 @@ Networking and storage for a repository are pluggable. There are various ready-m

### DocHandles

A `DocHandle` is an object returned from the various methods on a repository which create or request a document. The `DocHandle` has methods on it to access the underlying automerge document and to create new changes which are stored locally and transmitted to connected peers.
A `DocHandle` is an object returned from the various methods on a repository which create or request a document. The `DocHandle` has methods on it to access the underlying Automerge document and to create new changes which are stored locally and transmitted to connected peers.

### Document Refs

A `Ref` is an object referencing a specific subsection of a document. It can be obtained from a `DocHandle` or looked up through its URL from a Repository. The ref has methods to read and update the current value of the referenced subsection in its parent document.

### Document URLs

Documents in a repository have a URL. An automerge URL looks like this:
Documents in a repository have a URL. An Automerge URL looks like this:

```
automerge:2akvofn6L1o4RMUEMQi7qzwRjKWZ
Expand Down
2 changes: 1 addition & 1 deletion content/docs/reference/documents/counters.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ instead of a plain number, because it deals with concurrent changes correctly.
> - If two users increment it concurrently, they will both register **4** as the new value, whereas
> the two increments should result in a value of **5**.
> - If one user increments twice and the other user increments three times before the documents are
> merged, we will now have conflicting changes (**5** vs. **6**), rather > than the desired value
> merged, we will now have conflicting changes (**5** vs. **6**), rather than the desired value
> of **8** (3 + 2 + 3).

To set up a `Counter`:
Expand Down
Loading