El modelo: el documento como raíz de todo

Los niveles anteriores han recorrido la teoría de los tipos replicados sin coordinación, sus relojes, sus costes y sus algoritmos de secuencia. Toca ahora la biblioteca que ganó: Yjs es, con diferencia, la opción dominante en producción, del orden de novecientas mil descargas semanales y más de veinte mil estrellas en su repositorio, y por debajo de los editores basados en Tiptap y BlockNote, de los cuadernos colaborativos de Jupyter y de una lista larga de productos que no anuncian que la usan. Aprender Yjs no es aprender una interfaz de programación más: es aprender un modelo de datos concreto con decisiones tomadas, y la primera de esas decisiones —la que condiciona todas las demás— es que existe un objeto raíz llamado documento del que cuelga absolutamente todo, y que ese objeto es la unidad atómica de casi todo lo que vas a querer hacer después. Esta lección disecciona esa raíz antes de tocar un solo tipo de dato.

Una raíz y tipos con nombre que cuelgan de ella

Un documento de Yjs se construye con new Y.Doc() y por sí solo no contiene nada. Lo que contiene son tipos compartidos de primer nivel, y a esos tipos no se llega construyéndolos sino pidiéndolos por su nombre. La distinción es más importante de lo que parece y conviene fijarla desde el principio: los métodos que empiezan por get no consultan, definen.

import * as Y from "yjs";

const doc = new Y.Doc();

// Definir tipos de primer nivel. Idempotente: siempre el mismo objeto.
const titulo = doc.getText("titulo");
const bloques = doc.getArray("bloques");
const meta = doc.getMap("meta");
const cuerpo = doc.getXmlFragment("cuerpo");

// Forma general equivalente
const otro = doc.get("titulo", Y.Text); // otro === titulo

La documentación oficial es explícita al respecto: getText es equivalente a get con la clase correspondiente, y su descripción literal es definir un tipo compartido. Llamar dos veces con el mismo nombre devuelve el mismo objeto, y llamarlo en dos réplicas distintas devuelve dos objetos que el algoritmo considera el mismo tipo. Esa equivalencia por nombre es lo que hace que dos clientes que nunca se han visto puedan sincronizar sin negociar un esquema: el nombre de la cadena de texto es el esquema.

De ahí salen dos consecuencias prácticas inmediatas. La primera es que no hay ninguna operación de creación que pueda entrar en conflicto: dos réplicas que definen a la vez el mapa llamado meta no crean dos mapas, definen el mismo. La segunda es que el nombre de primer nivel forma parte del contrato de datos de la aplicación para siempre, con la misma dureza que el nombre de una columna en una base de datos relacional, y renombrarlo es una migración con todas sus letras.

Hay una tercera consecuencia, más sutil, que solo se aprecia al depurar. Definir un tipo no produce ninguna actualización: mientras nadie escriba dentro, el nombre existe localmente y no viaja a ninguna parte. Eso significa que dos réplicas pueden estar perfectamente sincronizadas y tener conjuntos distintos de nombres definidos, sin que eso sea un error ni un síntoma de nada. Lo que se sincroniza es contenido, y un tipo vacío no tiene contenido que sincronizar.

El documento es la unidad de sincronización

La segunda decisión estructural es que los cambios no se emiten por tipo sino por documento. Cuando algo se modifica, el documento emite un evento update con un búfer binario, y ese búfer se aplica en otra réplica con Y.applyUpdate. No hay ningún canal por tipo, ninguna suscripción parcial y ninguna forma soportada de sincronizar solo el mapa de metadatos sin sincronizar el texto que vive al lado.

const doc1 = new Y.Doc();
const doc2 = new Y.Doc();

doc1.on("update", (update) => Y.applyUpdate(doc2, update));
doc2.on("update", (update) => Y.applyUpdate(doc1, update));

doc1.getArray("bloques").insert(0, ["hola"]);
doc2.getArray("bloques").get(0); // "hola"

Los búferes de actualización son conmutativos e idempotentes: se pueden aplicar en cualquier orden y varias veces sin cambiar el resultado. Esa propiedad es la que permite que el transporte sea tonto —puede duplicar mensajes, reordenarlos y reenviar los que dude— y es la razón de que escribir un proveedor propio sea sorprendentemente asequible, cosa que veremos en la última lección de este nivel.

flowchart TB
D[Y Doc raiz] --> T1[getText titulo]
D --> T2[getArray bloques]
D --> T3[getMap meta]
D --> T4[getXmlFragment cuerpo]
D --> U[evento update con buffer binario]
U --> N[transporte cualquiera]
N --> A[applyUpdate en la replica remota]
style D fill:#cba6f7,color:#11111b
style U fill:#f9e2af,color:#11111b
style A fill:#a6e3a1,color:#11111b

La misma atomicidad se hereda hacia arriba en toda la pila. Un proveedor de persistencia guarda documentos enteros; un servidor autoriza el acceso a documentos enteros; el historial de versiones, cuando se implementa, se toma sobre el documento entero. Cualquier requisito de producto que suene a que este usuario puede ver los comentarios pero no el texto se traduce inevitablemente en dos documentos distintos, nunca en dos tipos dentro del mismo.

Conviene además fijarse en lo que el búfer de actualización no contiene, porque la ausencia es informativa. No lleva una marca de tiempo de pared, no lleva la identidad del usuario, no lleva un número de secuencia global y no lleva ninguna referencia al canal por el que viaja. Todo eso son cosas que la aplicación puede querer y que tendrá que transportar por su cuenta, fuera del formato. La consecuencia es que el búfer es autosuficiente en el único sentido que le importa al algoritmo —contiene lo necesario para integrarse en cualquier réplica— y deliberadamente pobre en todo lo demás, que es lo que le permite ser tan pequeño y tan indiferente al transporte.

El identificador de cliente y el vector de estado

Para entender por qué la sincronización puede ser incremental hace falta mirar la contabilidad interna. Cada documento tiene un clientID numérico, aleatorio, generado en el momento de instanciarlo y de solo lectura. Cada estructura que ese documento crea recibe un identificador formado por ese cliente y un contador creciente, es decir, una marca de Lamport. El vector de estado es el mapa que asocia a cada cliente conocido el siguiente contador que se espera de él.

const sv2 = Y.encodeStateVector(doc2);        // que tiene ya doc2
const diff = Y.encodeStateAsUpdate(doc1, sv2); // solo lo que le falta
Y.applyUpdate(doc2, diff);

// Tambien se puede calcular sin cargar el documento en memoria
const sv = Y.encodeStateVectorFromUpdate(estadoBinario);
const parcial = Y.diffUpdate(otroEstadoBinario, sv);
const fusionado = Y.mergeUpdates([estadoBinario, parcial]);

La documentación es cuidadosa con un matiz que conviene no perder: el vector de estado se parece a un vector de versión de los que vimos en niveles anteriores, pero Yjs lo usa únicamente para describir el estado local y calcular lo que le falta al otro, no para rastrear causalidad. No es un reloj vectorial en el sentido pleno del término, y no responde a la pregunta de si dos operaciones fueron concurrentes; responde a la pregunta mucho más modesta de qué estructuras no has visto todavía.

Esa modestia deliberada es la que abre una capacidad muy útil en el servidor y que conviene conocer desde el principio: como el vector de estado se puede calcular directamente sobre un búfer binario, es posible sincronizar dos clientes y computar diferencias sin llegar a construir el documento en memoria. Un servidor que solo hace de intermediario puede así almacenar búferes, calcular lo que le falta a cada cliente y fusionar actualizaciones sin instanciar nada, con un consumo de memoria que no depende del tamaño del documento. Es la diferencia entre un servidor que escala con el número de conexiones y uno que escala con el volumen de datos, y está a una decisión de distancia.

Cuánto meter en un mismo documento

Como la atomicidad es total, la pregunta de diseño más consecuente de todo el nivel es dónde poner la frontera del documento. No hay una respuesta universal, pero sí hay ejes que hacen la decisión discutible en lugar de arbitraria.

El patrón que mejor envejece en aplicaciones reales es el de un documento por unidad que el usuario reconoce como una cosa —una nota, un tablero, un archivo— más un documento índice separado que solo contiene metadatos ligeros y que se sincroniza siempre. El índice permite listar sin cargar, y cada unidad se carga cuando alguien la abre. Es la misma arquitectura que tiene un sistema de archivos, y funciona por las mismas razones.

Ese patrón tiene un coste que conviene aceptar con los ojos abiertos: la coherencia entre el índice y las unidades deja de estar garantizada. Si alguien renombra una nota sin conexión mientras otro la borra desde otro dispositivo, el índice y el contenido pueden quedar diciendo cosas distintas, y ningún algoritmo lo va a reconciliar porque viven en documentos separados y no comparten noción de orden. La reconciliación pasa a ser responsabilidad de tu código, normalmente en forma de una rutina que se ejecuta al cargar y que trata el índice como una vista reconstruible en lugar de como una fuente de verdad. Es trabajo real, y es el precio exacto de haber elegido una granularidad más fina que el átomo del sistema.