Migraciones: versionar el estado guardado y al usuario que vuelve

Hay un momento en la vida de toda aplicación con persistencia en el que alguien renombra un campo del store, la prueba en su máquina, la ve funcionar perfectamente y despliega. La prueba funcionó porque su navegador tenía el estado guardado por la misma versión que acababa de escribir. Los usuarios, en cambio, abren la aplicación nueva con el estado que dejó la vieja, y en su store entra un objeto con la clave antigua, sin la nueva, que el código de hoy leerá como indefinida. Ese es el bug característico de este nivel: no se reproduce en desarrollo, no aparece en las pruebas, no lo detecta el compilador porque los tipos describen lo que el código produce y no lo que el almacén contiene, y llega como un informe confuso de un usuario que dice que algo dejó de funcionar sin saber explicar qué. La migración es la disciplina que convierte ese cambio silencioso en un cambio declarado.

El estado guardado tiene un esquema, lo hayas escrito o no

Cada vez que serializas una rebanada del store al almacén, estás publicando un formato. No hay archivo de esquema, no hay declaración, pero el contrato existe con la misma fuerza que el de una base de datos: hay unas claves con unos nombres, unos tipos y unos rangos, y hay un código que asumirá todo eso al leerlo. La diferencia con una base de datos es que ahí nadie puede modificar la tabla sin escribir una migración, y aquí cualquier persona del equipo puede cambiar el esquema sin darse cuenta, simplemente editando el objeto inicial de una rebanada.

Los cambios que rompen son más variados de lo que parece, y el primer paso de la disciplina es saber reconocerlos. Renombrar una clave rompe. Cambiar el tipo de un identificador de número a texto rompe. Anidar un campo suelto dentro de un objeto rompe. Cambiar la unidad de un valor —de minutos a segundos, de porcentaje a fracción— es el peor de todos, porque no produce ningún error: produce datos plausibles y equivocados. Añadir un campo nuevo con valor por defecto es el único que suele sobrevivir, y solo si vive en el primer nivel y la fusión lo respeta.

version y migrate: la mecánica

Ambas herramientas resuelven esto igual: un número de versión que viaja junto a los datos guardados y una función que recibe lo guardado y la versión con la que se guardó, y devuelve algo con la forma que el código de hoy espera. Si la versión guardada coincide con la actual, la función no se llama. Si es menor, se llama. Si el almacén no tiene versión porque lo escribió una época anterior a esta disciplina, se trata como la versión más baja posible.

// Zustand: migrate recibe lo guardado y la version con la que se escribio.
persist(inicializador, {
  name: 'preferencias',
  version: 3,
  migrate: (guardado, version) => {
    let s = guardado as Record<string, unknown>
    if (version < 1) s = { ...s, idioma: 'es' }                       // campo nuevo
    if (version < 2) s = { ...s, densidad: s.compacto ? 'alta' : 'media' }
    if (version < 3) s = { ...s, duracionMs: Number(s.duracionSeg) * 1000 }
    return s
  },
})

// redux-persist: los pasos se declaran por numero y la libreria los encadena.
import { createMigrate } from 'redux-persist'

const migraciones = {
  1: (s) => ({ ...s, idioma: 'es' }),
  2: (s) => ({ ...s, densidad: s.compacto ? 'alta' : 'media' }),
  3: (s) => ({ ...s, duracionMs: Number(s.duracionSeg) * 1000 }),
}

const config = { key: 'raiz', version: 3, storage, migrate: createMigrate(migraciones) }

La forma encadenada es la única correcta y merece una explicación, porque la alternativa tentadora —un solo bloque condicional que convierte cualquier versión vieja directamente a la actual— parece más corta y es insostenible. Con la cadena, cada paso solo necesita conocer dos formas consecutivas, la anterior y la siguiente, y por tanto se escribe una vez y no vuelve a tocarse nunca. Con el bloque único, cada versión nueva obliga a revisar todas las ramas anteriores, y el número de combinaciones que hay que tener en la cabeza crece hasta que alguien se rinde y borra el soporte de las versiones antiguas.

flowchart LR
V0[guardado version 0] --> P1[paso 1 anade idioma]
P1 --> P2[paso 2 traduce compacto a densidad]
P2 --> P3[paso 3 convierte segundos a milisegundos]
P3 --> OK[forma actual validada]
V2[guardado version 2] --> P3
OK --> ST[entra en el store]
style OK fill:#a6e3a1,color:#11111b

Migraciones que no mienten

Una migración es una función que se ejecutará en el arranque de la aplicación, en el navegador de un usuario, sin nadie mirando y sin posibilidad de reintento manual. Esa situación impone tres restricciones que no son estilísticas. La primera es que debe ser pura y síncrona: nada de red, nada de peticiones al servidor para completar campos que faltan, nada de leer otras partes del almacén. Si la información necesaria para reparar el estado no está en el propio estado guardado, la respuesta correcta no es ir a buscarla, es descartar el dato y dejar que el flujo normal de la aplicación lo recupere.

La segunda es que debe ser total: tiene que producir un resultado válido para cualquier entrada, incluidas las que no esperabas, porque el almacén de un usuario puede contener basura escrita por una extensión, una escritura interrumpida a medias o el resultado de una migración anterior que falló. La tercera es que debe ser idempotente en la práctica: si por cualquier motivo un paso se ejecuta dos veces sobre el mismo dato, el resultado no debe empeorar. Duplicar una conversión de unidades es el ejemplo canónico de lo que ocurre cuando no se respeta.

// La migracion propone y el validador dispone.
const Esquema = z.object({
  idioma: z.enum(['es', 'en']),
  densidad: z.enum(['alta', 'media', 'baja']),
  duracionMs: z.number().int().nonnegative(),
})

const migrarSeguro = (guardado: unknown, version: number) => {
  try {
    const migrado = migrar(guardado, version)
    return Esquema.parse(migrado)         // lanza si la forma no cumple
  } catch {
    return undefined                      // descartar y usar el estado inicial
  }
}

El usuario que vuelve después de un año

Toda esta disciplina existe por una persona concreta: la que instaló la aplicación, la usó una temporada, la dejó y vuelve mucho después. Su navegador guarda un estado de la versión cuatro y tu código va por la once. Si conservaste los siete pasos intermedios, su estado se repara y no nota nada. Si alguien los borró porque parecían código muerto, su estado no se puede interpretar y, con suerte, se descarta.

Su caso tiene además una particularidad que rompe la intuición de quien nunca la ha vivido: los saltos de versión no son de uno en uno. La cadena tiene que soportar entradas en cualquier versión histórica, incluida la ausencia de versión, y tiene que producir un resultado válido para todas ellas. Por eso los pasos se escriben con condiciones de menor que y no de igualdad: una comparación por igualdad solo repara al usuario que estaba exactamente una versión atrás, que es precisamente el único que no necesitaba reparación.

Ese es el criterio para decidir cuánto tiempo se conservan los pasos antiguos, y la respuesta honesta es que más de lo que resulta cómodo. Un paso de migración es una decena de líneas que no se vuelven a tocar y cuya única obligación es seguir existiendo. Borrarlo ahorra una cantidad de mantenimiento indistinguible de cero y arriesga la experiencia de una cola de usuarios que no aparece en ninguna métrica porque, precisamente, no estaban usando el producto. Cuando llegue el momento de recortar, la retirada correcta no es eliminar el paso sino sustituirlo por un descarte explícito de las versiones anteriores a un umbral, para que el caso quede documentado y el estado se limpie en vez de interpretarse mal.

// Retirada documentada: por debajo del umbral no se interpreta, se descarta.
const VERSION_MINIMA_SOPORTADA = 5

const migrar = (guardado: unknown, version: number) => {
  if (version < VERSION_MINIMA_SOPORTADA) return undefined   // arranque limpio
  let s = guardado as Record<string, unknown>
  if (version < 6) s = { ...s, moneda: 'EUR' }
  if (version < 7) s = { ...s, importeCent: Math.round(Number(s.importe) * 100) }
  return s
}