Guía de Migración

¿Vienes de Redux, Zustand o Jotai? Esta guía mapea los conceptos que ya conoces a Yoltra y muestra el antes/después de cada uno.

#El único cambio de mentalidad

Yoltra es event-sourced. No haces set del estado directamente: emites un evento (channel, type, payload), y un reducer puro calcula el siguiente estado. Las lecturas son suscripciones a rutas de grano fino: un componente se re-renderiza solo cuando cambia la hoja exacta que lee. El trabajo asíncrono vive en los effects.

emit("todos", "add", { title: "Comprar leche" }); // 1. emite un evento
// 2. un reducer calcula el siguiente estado (de forma síncrona)
const title = useAtomicProp({ reducer: "todos", property: "items.0.title" }); // 3. lee una ruta

Ese es todo el modelo. Todo lo de abajo es una traducción de tu librería actual a esos tres movimientos.

#Mapa de conceptos

#Desde Redux / Redux Toolkit

Mapeo: action → event, dispatch → emit, slice reducer → reducer, useSelector → useAtomicProp, thunk / RTK Query → effect, middleware → middleware (síncrono) o effect (async).

#Store + slice

// Redux Toolkit
const counter = createSlice({
  name: "counter",
  initialState: { value: 0 },
  reducers: {
    increment: (s, a: PayloadAction<number>) => { s.value += a.payload; },
    reset: (s) => { s.value = 0; },
  },
});
export const store = configureStore({ reducer: { counter: counter.reducer } });

// Yoltra
import { createYoltra } from "@yoltra/react";

export type AppEM = { counter: { increment: number; reset: null } };

export const { useAtomicProp, useEmit } = createYoltra({
  name: "App",
  reducer: {
    counter: {
      state: { value: 0 },
      when: { keys: [["counter", "increment"], ["counter", "reset"]] },
      reducer: (s, e) => {
        switch (e.type) {
          case "increment": return { value: s.value + e.payload };
          case "reset":     return { value: 0 };
          default:          return s;
        }
      },
    },
  },
});

#Dispatch → emit, useSelector → useAtomicProp

// Redux
const value = useSelector((s: RootState) => s.counter.value);
const dispatch = useDispatch();
dispatch(increment(1));

// Yoltra: se re-renderiza solo cuando counter.value cambia; sin memo, sin reselect
const value = useAtomicProp({ reducer: "counter", property: "value" });
const emit = useEmit();
emit("counter", "increment", 1);

#Thunks → effects

El trabajo asíncrono va en los effects, que corren después del reducer y pueden emitir eventos de seguimiento (tus acciones de éxito/fallo):

// Thunk de Redux
const fetchTodos = () => async (dispatch) => {
  dispatch(loading());
  const res = await api.getTodos();
  dispatch(loaded(res));
};

// Effect de Yoltra
effects: [
  {
    when: { keys: [["todos", "fetch"]] },
    effect: async (event, getState, emit) => {
      const res = await api.getTodos();
      await emit("todos", "loaded", res); // reduce el resultado como cualquier evento
    },
  },
],

#RTK Query → nada, y esa es la respuesta honesta

No hay equivalente, porque Yoltra es un contenedor de estado y RTK Query es una capa de fetching de datos. Te da caché de peticiones, deduplicación, invalidación por tags, refetch al recuperar el foco o la conexión, polling, updates optimistas y hooks generados. Nada de eso es gestión de estado, y reconstruirlo sobre effects es un proyecto, no una migración.

Lo normal es quedártelo. RTK Query necesita un store de Redux, así que conservarlo significa conservar ese store, lo cual está bien, y es justo de lo que trata la sección de abajo sobre adoptar Yoltra de forma incremental. Los datos del servidor se quedan donde están; el estado que es genuinamente tuyo se mueve.

Si prefieres no quedarte con Redux, TanStack Query hace el mismo trabajo sin él, y compone con Yoltra igual: él es dueño de la caché del servidor, Yoltra de todo lo demás.

Construirlo tú mismo es la última opción a la que recurrir. Las piezas están aquí (los effects hacen el fetch, createEntityAdapter te da una caché normalizada, y la ventana de dedup colapsa emisiones duplicadas), pero la deduplicación de peticiones, la invalidación de caché y la política de refetch son la parte difícil, y lo son en cualquier sitio donde las escribas:

const articles = createEntityAdapter<Article>();

effects: [
  {
    when: { keys: [["articles", "requested"]] },
    effect: async (event, getState, emit) => {
      // ¿Ya lo tenemos, y suficientemente fresco? Entonces esto no hace nada.
      if (articles.selectById(getState().articles, event.payload.id) !== undefined) return;
      await emit("articles", "loaded", await api.getArticle(event.payload.id));
    },
  },
],

Eso es una caché. No es invalidación, y no es una política de refetch. Escribe esas dos solo si sabes que las quieres.

#Middleware

El middleware de Redux envuelve dispatch. El de Yoltra es sincrono, y solo un false explicito rechaza un evento, que entonces se vuelve un evento "uncommitted" al que tu interfaz puede reaccionar. No devolver nada lo permite, asi que un middleware que solo registra o mide no necesita return. El trabajo asincrono del middleware se mueve a los efectos.

middleware: [
  {
    when: { channel: "admin" },
    middleware: (state, event) => state.auth.isAdmin, // false → rechazado
  },
],

#Desde Zustand

Mapeo: create(set => …) → createYoltra, set(...) → emit + reducer, useStore(selector) → useAtomicProp.

// Zustand
const useStore = create((set) => ({
  value: 0,
  increment: (n) => set((s) => ({ value: s.value + n })),
  reset: () => set({ value: 0 }),
}));

// Yoltra: estado y transiciones separados (emite un evento, redúcelo)
export const { useAtomicProp, useEmit } = createYoltra({
  name: "App",
  reducer: {
    counter: {
      state: { value: 0 },
      when: { keys: [["counter", "increment"], ["counter", "reset"]] },
      reducer: (s, e) =>
        e.type === "increment" ? { value: s.value + e.payload }
        : e.type === "reset"   ? { value: 0 }
        : s,
    },
  },
});

// Zustand: const value = useStore((s) => s.value); useStore.getState().increment(1);
// Yoltra:
const value = useAtomicProp({ reducer: "counter", property: "value" });
const emit = useEmit();
emit("counter", "increment", 1);

¿Por qué el paso extra? La separación acción/reducer es lo que te da el log de eventos, el time-travel y los DevTools; el set inline de Zustand no se puede reproducir ni inspeccionar. A cambio obtienes lecturas de grano fino gratis: useAtomicProp se re-renderiza por una hoja, sin ajustar igualdad de selectores.

#Desde Jotai

Mapeo: un atom ≈ una ruta en un slice; useAtomValue → useAtomicProp; átomos derivados → useAtomicProps(specs, selector); useSetAtom → useEmit.

// Jotai
const countAtom = atom(0);
const doubledAtom = atom((get) => get(countAtom) * 2);

// Lecturas/escrituras en Jotai
const count = useAtomValue(countAtom);
const doubled = useAtomValue(doubledAtom);
const setCount = useSetAtom(countAtom);
setCount((c) => c + 1);

// Yoltra: un slice, las rutas son tus "átomos", las derivaciones son selectores
const count = useAtomicProp({ reducer: "counter", property: "value" });
const doubled = useAtomicProp({ reducer: "counter", property: "value" }, (v) => v * 2);

const emit = useEmit();
emit("counter", "increment", 1);

Para un valor derivado de varias rutas, usa useAtomicProps; se recalcula solo cuando una de las rutas listadas cambia:

const filtered = useAtomicProps(
  [
    { reducer: "todos", property: "items.**" },
    { reducer: "filter", property: "q" },
  ],
  (s) => s.todos.items.filter((t) => t.title.includes(s.filter.q)),
  shallowEqual,
);

Jotai da reactividad de grano fino de abajo hacia arriba (muchos átomos); Yoltra da lo mismo de arriba hacia abajo (rutas en slices) más un log de eventos y DevTools con time-travel que el modelo de átomos no tiene.

#Adoptarlo junto a lo que ya tienes

No tienes que elegir. Dos stores pueden convivir en la misma aplicación sin saber el uno del otro, y así es como una migración se hace a plena luz en vez de en una rama enorme.

El ejemplo yoltra-in-react está construido exactamente así: la misma aplicación de todos implementada dos veces, src/state/redux junto a src/state/yoltra y src/components/redux junto a src/components/yoltra, corriendo lado a lado en una sola página. Existe para comparar ambas, pero la disposición es la misma que usa una adopción incremental.

Elige un slice acotado y muévelo entero. Una funcionalidad cuyo estado nadie más lee (un panel de filtros, un asistente, un cajón de ajustes) es un buen primer movimiento. Medio slice en cada librería es la única disposición que hay que evitar: dos dueños del mismo valor significa que ambos discrepan, y cuál tiene razón depende de cuál renderizó último.

// Redux conserva lo que ya es suyo.
<Provider store={reduxStore}>
  <App>
    <LegacyDashboard />         {/* useSelector, dispatch */}
    <StoreProvider store={yoltraStore}>
      <NewSettingsPanel />      {/* useAtomicProp, useEmit */}
    </StoreProvider>
  </App>
</Provider>

Mejor sin puente. Si los slices son realmente disjuntos, los dos stores nunca necesitan hablarse, y añadir un puente crea justo el acoplamiento que la separación buscaba evitar.

Cuando uno genuinamente deba reaccionar al otro, haz la dependencia unidireccional y ponla en un effect:

// Yoltra se entera de algo que pertenece a Redux. En una sola dirección.
effects: [
  {
    when: { keys: [["session", "endedElsewhere"]] },
    effect: async (_event, _getState, emit) => {
      await emit("settings", "cleared", null);
    },
  },
],

// En algún punto del lado de Redux, una sola vez:
reduxStore.subscribe(() => {
  if (!selectIsAuthenticated(reduxStore.getState())) {
    void yoltraStore.emit("session", "endedElsewhere", null);
  }
});

Dos puentes apuntándose entre sí son un ciclo, y un ciclo entre dos stores es un bug que se reproduce solo bajo un timing que no controlas. Si te descubres queriendo el segundo, mueve el estado compartido a un único store.

#Persistencia: reemplazar redux-persist

@yoltra/core incluye hydrate y persist. La forma difiere de redux-persist en un punto que conviene entender antes de portar nada.

El store nace hidratado. redux-persist rehidrata un store existente despachando una acción REHYDRATE, así que cada reducer tiene que tolerar que su estado sea reemplazado por debajo y la UI renderiza una vez con los valores por defecto antes de que lleguen los reales. Yoltra lee el payload primero y lo usa como estado inicial de los reducers: no hay parpadeo, ni acción sintética, ni una transición que los effects observen y que nunca ocurrió:

import {
  createStore, createWebStorageAdapter, hydrate, persist, withHydration,
} from "@yoltra/core";

const adapter = createWebStorageAdapter(localStorage);
const hydration = await hydrate({ key: "app", adapter, version: 3 });

const store = createStore({
  name: "App",
  reducer: withHydration({ todos: todosSpec, ui: uiSpec }, hydration),
});

// Persiste solo lo que vale la pena. Un cambio en un slice no vigilado no cuesta nada.
const stop = persist(store, { key: "app", adapter, version: 3, slices: ["todos"] });

Una versión que no coincide se rechaza, no se acepta a ciegas. Los reducers cambian, y un snapshot escrito contra una forma anterior puede no ser estado válido para este build. Aporta migrate para actualizarlo, o se descarta y arrancas desde tus valores por defecto.

Nada lanza al arrancar. Un payload ausente, ilegible o no migrable cae a esos valores por defecto y lo reporta por onError. Un store que no arranca porque localStorage guarda JSON viejo es peor que uno que arranca limpio, y un disco lleno no debería tumbar la página que está persistiendo.

Map, Set, Date, BigInt y las referencias cíclicas sobreviven el viaje de ida y vuelta. JSON.stringify no falla con un Map; lo convierte en {} en silencio, que es el tipo de pérdida de datos que descubres meses después.

Para render en servidor, dehydrate(store, { version }) produce el payload y hydrate({ source, version }) lo consume.

#Detalles y FAQ

• "¿Dónde está setState?" No existe, por diseño. Emite un evento; un reducer produce el siguiente estado. Esa indirección es lo que hace todo el historial inspeccionable y reproducible.
• Los reducers deben ser puros. Sin async, sin I/O, sin mutar el estado anterior; devuelve un valor nuevo. El async va en los effects.
• getState() es correcto justo después de emit(). La fase de reduce es síncrona. Usa await emit(...) solo cuando además quieras que los effects de ese evento hayan terminado.
• ¿Necesito un Provider? No. Los hooks de createYoltra usan el store que creó. Usa <StoreProvider> solo para acotar otra instancia a un subárbol (p. ej. un store nuevo por test).
• ¿Channels? La dimensión extra channel da namespace a los eventos ("auth"/"ui"/"todos") para que las apps grandes no colisionen en un espacio plano de tipos de acción. Elige channels por dominio.

#Siguientes pasos

• Guía de Inicio Rápido: de la instalación a una app funcionando en tres pasos
• Guía de Testing: prueba stores, effects y componentes
• yoltra-in-react: la misma app en Redux y en Yoltra, lado a lado
• API de @yoltra/core · API de @yoltra/react
• Comparación de Librerías: las compensaciones arquitectónicas honestas