El modelo: un JSON inmutable que solo se toca dentro de un cambio

El modelo de programación de Automerge es más raro de lo que su superficie sugiere, y esa rareza es deliberada. Aparentemente escribes código imperativo normal: asignas propiedades, insertas en arrays, incrementas contadores. En realidad no estás modificando nada, sino describiendo un conjunto de operaciones que la biblioteca graba mientras finges mutar, para después construir con ellas un documento nuevo y dejar el anterior intacto. El documento viejo sigue siendo válido, sigue siendo legible y sigue teniendo su propia identidad en la historia. Entender bien esta doble naturaleza —API imperativa por fuera, valor inmutable por dentro— es la diferencia entre usar la biblioteca con soltura y pelearse con ella durante semanas por errores que parecen aleatorios y no lo son. Esta lección desmonta el mecanismo, recorre los tipos que el modelo reconoce y fija las cuatro reglas cuya violación explica casi todos los fallos de los que empiezan.

El documento es un valor, no un contenedor

Un documento de Automerge se comporta como un número o como una cadena congelada, no como un objeto que guardas y modificas. La operación central lo deja claro en su firma: recibe un documento y devuelve otro. El que entró sigue existiendo, con el contenido que tenía, y puedes seguir leyéndolo indefinidamente.

import * as A from "@automerge/automerge";

const v0 = A.from({ titulo: "", tareas: [], hechas: new A.Counter(0) });

const v1 = A.change(v0, (d) => {
  A.splice(d, ["titulo"], 0, 0, "Compra");
  d.tareas.push({ texto: "pan", lista: false });
});

// v0 y v1 son dos documentos distintos y ambos siguen siendo validos.
console.log(v0.titulo); // ""
console.log(v1.titulo); // "Compra"

La consecuencia arquitectónica es que el estado de tu aplicación no es «el documento», sino «qué versión del documento estoy mostrando ahora mismo». Encaja de forma natural con cualquier almacén reactivo de los que vimos en los niveles de arquitectura del cliente: la función de cambio produce un valor nuevo, lo publicas, y quien esté suscrito vuelve a renderizar. No hay invalidación manual ni observadores sobre propiedades, porque no hay ninguna propiedad que cambie bajo tus pies.

flowchart LR
A[documento v0] --> B[funcion de cambio]
B --> C[el intermediario graba operaciones]
C --> D[documento v1]
A --> E[v0 sigue siendo legible y valido]
D --> F[v1 es el estado que publicas]
style D fill:#a6e3a1,color:#11111b
style E fill:#89b4fa,color:#11111b

Hay un matiz de rendimiento que conviene aclarar temprano porque genera desconfianza injustificada. Que se devuelva un documento nuevo no significa que se copie el contenido. La estructura comparte casi toda su representación interna con la anterior, igual que hace cualquier estructura persistente, así que el coste de un cambio es proporcional a lo que el cambio toca y no al tamaño del documento. Encadenar miles de cambios sobre un documento grande es una operación barata.

Dentro del cambio: el intermediario que graba

La segunda mitad del modelo es lo que ocurre dentro de la función. El objeto que recibe como argumento no es tu documento: es un intermediario, un objeto que intercepta cada lectura y cada escritura que haces sobre él. Cuando asignas una propiedad, el intermediario no guarda un valor sino que anota una operación con su ruta, su valor y su identidad. Cuando lees una propiedad anidada, te devuelve otro intermediario para que la intercepción siga funcionando en profundidad.

Al terminar la función, la biblioteca toma todas las operaciones anotadas y las empaqueta en un único cambio con su hash, sus dependencias causales, su marca de tiempo y, si se lo indicas, un mensaje descriptivo. Ese empaquetado es el motivo por el que la función de cambio es también una unidad de atomicidad: todo lo que ocurre dentro entra junto en la historia o no entra nada.

// Un cambio puede llevar metadatos, igual que un commit.
const v2 = A.change(v1, { message: "marcar la primera tarea" }, (d) => {
  d.tareas[0].lista = true;
  d.hechas.increment(1);
});

// Fusionar dos documentos con historias divergentes.
const fusionado = A.merge(v2, otroDocumento);

// Serializar y recuperar: el binario contiene el valor y la historia.
const bytes = A.save(fusionado);
const recuperado = A.load(bytes);

Agrupar operaciones relacionadas en un solo cambio no es solo higiene: es lo que hace legible la historia más adelante. Un cambio por pulsación de tecla es correcto pero produce un historial que nadie puede leer; un cambio por acción del usuario, con su mensaje, produce un historial que se parece a un registro de actividad y habilita todo lo que veremos en la lección siguiente.

Los tipos que el modelo reconoce

El modelo de datos es un JSON con la raíz siempre un mapa, más un puñado de tipos que JSON no tiene y que aquí hacen falta porque llevan semántica de fusión propia. Conocerlos importa mucho más de lo que parece, porque elegir el tipo equivocado no produce un error sino un comportamiento de fusión distinto del que esperabas.

La distinción entre los dos tipos de cadena es la que más problemas causa y la que la versión 3 dejó por fin en su sitio: el caso por defecto pasó a ser el texto colaborativo, representado con la cadena nativa del lenguaje, y el texto no colaborativo quedó relegado a una clase explícita. La regla mental es simple y vale casi siempre: si dos personas pueden estar escribiendo en ese campo a la vez y quieres que ambas contribuciones sobrevivan, es texto colaborativo; si el campo es un valor que se elige, no que se escribe —un estado, una categoría, una clave— es una cadena inmutable.

Hay una implicación operativa que se deriva de ahí y que conviene tener presente al modelar. El texto colaborativo se modifica con la función de empalme indicando la ruta, la posición, cuántos caracteres se borran y qué se inserta; nunca reasignando la propiedad entera. Reasignarla funciona, pero equivale a borrar todo el contenido e insertar el nuevo, lo cual destruye la posibilidad de fusionar con una edición concurrente y además infla la historia sin necesidad. Es la diferencia entre editar un párrafo y tirarlo para escribir otro.

// Correcto: se describe la edicion, y fusiona con ediciones concurrentes.
const bien = A.change(doc, (d) => {
  A.splice(d, ["cuerpo"], 12, 3, "nuevo");
});

// Incorrecto: equivale a borrar todo el texto e insertar otro distinto.
// Fusiona mal y ademas infla la historia sin necesidad.
const mal = A.change(doc, (d) => {
  d.cuerpo = "texto entero reescrito";
});

// Cuando ya tienes el texto final y no las posiciones,
// esta funcion calcula la diferencia minima por ti.
const tambienBien = A.change(doc, (d) => {
  A.updateText(d, ["cuerpo"], textoFinalDelEditor);
});

La última variante es la que suele hacer falta al integrar un editor de terceros, porque esos editores te entregan el texto resultante y no la operación que lo produjo. Calcular la diferencia mínima y aplicarla como empalmes preserva casi toda la capacidad de fusión, aunque no toda: si dos personas reordenan párrafos enteros a la vez, ninguna heurística de diferencias va a reconstruir la intención original. Cuando el editor sí te da las operaciones, pásalas directamente y no pases por aquí.

Los tipos restantes completan el cuadro sin sorpresas: enteros con y sin signo, coma flotante de doble precisión, booleanos, valores nulos, marcas de tiempo que se corresponden con el objeto de fecha nativo y secuencias de bytes. Este último merece una advertencia de dimensionamiento: técnicamente puedes guardar binario dentro del documento, pero cada byte que metas ahí se convierte en historia que viaja en cada sincronización y que nunca se podrá borrar. Los adjuntos pesados van fuera, referenciados por identificador.

Las cuatro reglas del contrato

Casi todos los fallos que aparecen al adoptar la biblioteca son violaciones de una de estas cuatro reglas, y todas se derivan de la inmutabilidad. Vale la pena memorizarlas junto con su síntoma, porque el síntoma rara vez apunta a la causa.

La primera: solo se escribe dentro de la función de cambio. Cualquier mutación sobre un documento fuera de ella lanza un error o se pierde, y el síntoma típico es un cambio que «no se guarda» sin que nada falle. La segunda: siempre hay que quedarse con el documento devuelto y descartar la referencia anterior como estado vivo. Si sigues renderizando desde la variable vieja, la interfaz se queda congelada aunque la historia avance, y es un fallo que puede tardar días en aparecer si la variable vieja se copió a algún sitio.

La tercera: las vistas históricas son de solo lectura. Un documento obtenido mirando un punto del pasado comparte memoria con el original, es baratísimo de crear precisamente por eso, y no se puede pasar a la función de cambio. La cuarta: no mezcles documentos de identidades distintas asumiendo que da igual cuál conservas. La operación de fusión toma dos documentos y produce uno con la unión de ambas historias, y aunque el resultado converge, el actor bajo el que quedan registrados los cambios posteriores depende del documento que uses como base.

Hay una quinta regla que no es del contrato sino de higiene, y que conviene adoptar desde el principio porque después cuesta reconvertir el código. Escribe siempre a través de una única función de tu aplicación que envuelva la operación de cambio, en lugar de invocarla dispersa por todos los componentes. Esa envoltura es el sitio natural donde poner el mensaje descriptivo, donde validar invariantes de dominio antes de grabar, donde publicar el documento nuevo en tu almacén reactivo y donde instrumentar la telemetría. Sin ella acabas con mensajes vacíos, con cambios de granularidad arbitraria y sin ningún punto donde comprobar que lo que se escribe cumple las reglas de tu dominio.