Skip to main content

Counters

If you have a numeric value that is only ever changed by adding or subtracting (e.g. counting how many times the user has done a particular thing), you should use the Automerge.Counter datatype instead of a plain number, because it deals with concurrent changes correctly.

Note: Using the Automerge.Counter datatype is safer than changing a number value yourself using the ++ or += 1 operators. For example, suppose the value is currently 3:

  • 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 of 8 (3 + 2 + 3).

To set up a Counter:

state = Automerge.change(state, (doc) => {
  // The counter is initialized to 0 by default. You can pass a number to the
  // Automerge.Counter constructor if you want a different initial value.
  doc.buttonClicks = new Automerge.Counter();
});

To get the current counter value, use doc.buttonClicks.value. Whenever you want to increase or decrease the counter value, you can use the .increment() or .decrement() method:

state = Automerge.change(state, (doc) => {
  doc.buttonClicks.increment(); // Add 1 to counter value
  doc.buttonClicks.increment(4); // Add 4 to counter value
  doc.buttonClicks.decrement(3); // Subtract 3 from counter value
});

Note: In relational databases it is common to use an auto-incrementing counter to generate primary keys for rows in a table, but this is not safe in Automerge, since several users may end up generating the same counter value! Instead it is best to use UUIDs to identify entities.