Los tipos: texto, array, mapa y la familia XML

Una vez establecido que el documento es la raíz, lo siguiente que hay que entender es qué se le puede colgar. Yjs expone cuatro familias de tipos compartidos —texto, array, mapa y un pequeño conjunto orientado a árboles de marcado— y la tentación natural del recién llegado es leerlas como si fueran las estructuras equivalentes del lenguaje anfitrión con la magia de la sincronización añadida por encima. Esa lectura es cómoda y es falsa en el punto que más importa: cada familia lleva debajo un tipo replicado distinto, con una regla de convergencia distinta y con un comportamiento distinto ante la edición concurrente. Elegir entre un array y un mapa para guardar una lista de tareas no es una elección de estilo, es una elección sobre qué ocurre exactamente cuando dos personas tocan la misma tarea a la vez. Esta lección recorre las cuatro familias por dentro, con las operaciones verificadas contra la interfaz publicada, y con el algoritmo que cada una implementa.

El texto y el algoritmo YATA

Y.Text es el tipo optimizado para edición compartida de texto y el único que además permite asignar atributos de formato a rangos, que es lo que hace posible construir editores de texto enriquecido sobre él. Su interfaz es pequeña y deliberadamente indexada por posición, aunque por debajo no haya posiciones.

const texto = doc.getText("cuerpo");

texto.insert(0, "hola mundo");
texto.insert(0, "negrita", { bold: true }); // atributos de formato
texto.format(0, 7, { italic: true });
texto.delete(0, 5);

texto.length;      // numero de caracteres visibles
texto.toString();  // cadena sin formato
texto.toDelta();   // representacion en formato delta de Quill
texto.applyDelta(delta);

El algoritmo que hay debajo es YATA, siglas de la propuesta original de Kevin Jahns sobre edición compartida entre pares en tipos de datos extensibles. Yjs implementa una versión modificada de ese algoritmo, y su corrección ha sido objeto de verificación formal reciente: el proyecto lean-yjs ha demostrado con el asistente de pruebas Lean propiedades de preservación y conmutatividad del algoritmo, y de paso ha revelado que el pseudocódigo del artículo original contenía errores que la implementación real no tiene.

Lo relevante para el uso diario es que YATA es un tipo de secuencia con identidad por elemento, con las mismas propiedades que estudiamos en niveles anteriores: cada carácter insertado recibe un identificador formado por cliente y contador, cada borrado deja una lápida, y el orden entre inserciones concurrentes se decide de forma determinista sin consultar a nadie. Yjs añade tres optimizaciones que la documentación describe con precisión y que explican por qué el coste en la práctica es tolerable: fusiona estructuras contiguas del mismo cliente en una sola, vacía el contenido de las estructuras borradas conservando solo su marca, y recoge lápidas convertidas en estructuras de recolección cuando el padre entero ha sido eliminado y el orden ya no importa.

El array: la misma secuencia con contenido arbitrario

Y.Array es, según la propia documentación, un tipo similar a un array que soporta inserción y borrado eficientes en cualquier posición y que internamente usa una lista enlazada de arrays que se parte cuando hace falta. Es decir, es el mismo mecanismo de secuencia que el texto, con la diferencia de que cada elemento no es un carácter sino un valor.

const lista = doc.getArray("tareas");

lista.insert(0, [{ id: "a", hecho: false }]); // ojo: el contenido es un array
lista.push([1, 2, 3]);
lista.unshift(["primero"]);
lista.delete(1, 2);

lista.get(0);
lista.slice(0, 5);
lista.length;
lista.toArray();  // copia superficial
lista.toJSON();   // convierte tambien los tipos hijos
lista.map((v, i) => v);

El detalle de interfaz que más errores causa en los primeros días es que insert y push reciben un array de elementos, no un elemento: lista.insert(0, [1]) inserta el número uno en la posición cero, mientras que lista.insert(0, 1) no hace lo que parece. La razón es que la operación es un empalme, no una asignación, y esa forma es coherente con el hecho de que por debajo se está insertando un tramo en una secuencia.

Lo que hay que interiorizar es el comportamiento concurrente. Como es una secuencia con identidad, dos inserciones simultáneas en la misma posición conservan las dos, en un orden que todas las réplicas acuerdan. No hay pérdida. Pero eso mismo significa que un array no sirve para representar un conjunto ni para representar un valor único: si modelas un campo de estado como un array de un solo elemento, dos ediciones concurrentes te dejarán un array de dos.

flowchart TB
S[secuencia con identidad y YATA] --> TX[Y Text con atributos de formato]
S --> AR[Y Array con valores cualesquiera]
S --> XF[Y XmlFragment y Y XmlElement]
M[registro por clave] --> MP[Y Map]
TX --> R1[dos inserciones concurrentes se conservan las dos]
AR --> R1
MP --> R2[dos escrituras en la misma clave gana una sola]
style S fill:#89b4fa,color:#11111b
style M fill:#f9e2af,color:#11111b
style R1 fill:#a6e3a1,color:#11111b
style R2 fill:#f38ba8,color:#11111b

El mapa: un registro por clave sin fusión del valor

Y.Map es un tipo de mapa compartido con la interfaz que cabe esperar, y su semántica de conflicto es radicalmente distinta de la de los tres tipos de secuencia. Aquí no hay identidad por elemento ni acumulación: hay claves, y cada clave guarda un valor.

const meta = doc.getMap("meta");

meta.set("titulo", "Borrador");
meta.set("etiquetas", new Y.Array()); // anidar tipos si quieres fusion dentro
meta.get("titulo");
meta.has("titulo");
meta.delete("titulo");
meta.clear();

meta.size;
meta.toJSON();
for (const [clave, valor] of meta) { /* ... */ }

Ante dos escrituras concurrentes sobre la misma clave, el resultado es que sobrevive una de las dos, elegida de forma determinista e idéntica en todas las réplicas, y la otra desaparece de la vista. No hay fusión del valor, no hay excepción y no hay aviso. Es la semántica de última escritura gana que estudiamos en el bloque de conflictos, con la ventaja de que el desempate no depende de relojes de pared sino de la identidad de las estructuras, y por tanto no se rompe cuando los relojes de dos máquinas discrepan.

La consecuencia de diseño es la regla más útil de toda la lección y merece enunciarse sola: si el valor que guardas en una clave es un objeto plano de JavaScript, ese objeto es opaco para el algoritmo y se sustituye entero. Si quieres que dos personas puedan editar campos distintos del mismo objeto sin pisarse, el objeto tiene que ser un tipo compartido anidado, no un objeto plano.

La familia XML y para qué existe realmente

La cuarta familia la componen Y.XmlFragment, Y.XmlElement y Y.XmlText. La documentación es franca sobre lo que son: Y.XmlElement representa un elemento con un nombre de nodo, atributos y una lista de hijos, pero no hace ningún esfuerzo por validar su contenido ni por ser realmente conforme a XML. Y.XmlFragment es un contenedor que guarda una secuencia de esos elementos.

const cuerpo = doc.getXmlFragment("cuerpo");

const parrafo = new Y.XmlElement("paragraph");
parrafo.setAttribute("align", "center");
parrafo.insert(0, [new Y.XmlText("texto del parrafo")]);

cuerpo.insert(0, [parrafo]);
cuerpo.firstChild;
cuerpo.toString();               // serializacion de todos los descendientes
cuerpo.createTreeWalker((t) => true); // recorrido iterable de los hijos

El nombre despista y conviene decir para qué se usan en la práctica: no para intercambiar XML, sino para representar árboles de documento de editores de texto enriquecido. Los enlaces con ProseMirror —y por tanto Tiptap, BlockNote y Milkdown, que lo usan por debajo— apoyan el árbol del editor sobre esta familia, porque la correspondencia entre un nodo con nombre, atributos e hijos y un nodo de un esquema de editor es directa. Si no estás integrando un editor de este tipo, casi con seguridad no necesitas estos tipos y una combinación de mapas y arrays anidados expresará mejor tu modelo.