easy-peasy

Easy Peasy is one of several state management options for React. Before choosing Easy Peasy, consider if your requirements are better met by other specialized libraries:

• Server State Synchronization: If your primary goal is managing data synchronization with a server (e.g., handling GET/POST requests and CRUD operations), consider React Query. It is designed to reduce complexity and prevent bugs related to client/server data synchronization.
• Native React APIs: For many use cases, React's built-in Context and Hook APIs may be sufficient and offer long-term stability as they are part of the core library.
• Lightweight Global State: Zustand provides an elegant API for global state management and is designed to handle common pitfalls like the 'zombie child' problem and React concurrency.
• Redux Ecosystem: Redux Toolkit provides a simplified API for Redux to reduce boilerplate. Use this if you want to leverage the extensive Redux ecosystem and community support (requires react-redux to connect to your application).

When deciding whether to use easy-peasy, consider the following architectural tradeoffs:

• Redux Dependency: easy-peasy is built on top of Redux. While this provides access to battle-tested optimizations and the Redux DevTools ecosystem, you are bound to the capabilities and API of Redux.
• Leaky Abstraction: The abstraction is intentionally "leaky." Knowledge of Redux will help you understand easy-peasy more deeply. The library specifically exposes the ability to extend the underlying Redux store and uses Redux-specific concepts (like reducers) to allow for migration paths from traditional Redux implementations.
• Third-party Risk: As a third-party dependency, there is a risk regarding maintenance and alignment with evolving React architectures (e.g., React Concurrent Mode). However, the library is designed to evolve alongside React features like useSyncExternalStore (formerly useMutableSource).
• Bundle Size: Using easy-peasy increases your bundle size. The library, including its dependencies, is approximately 11kb gzipped.
• Onboarding: New developers will need to learn the easy-peasy API. While the API is designed to be intuitive, it does not have the same level of widespread community adoption as Redux or MobX.

To use Easy Peasy in your application, follow these three steps:

1. Create your store using createStore and define your state and actions using action.
2. Wrap your application with the StoreProvider component, passing in your created store.
3. Use the store in your components using hooks like useStoreState to access state and useStoreActions to access actions.

Note: The v7 Beta maintains the same public store/model API as v6.

// 1. Create your store
const store = createStore({
  todos: ['Create store', 'Wrap application', 'Use store'],

  addTodo: action((state, payload) => {
    state.todos.push(payload);
  }),
});

// 2. Wrap your application
function App() {
  return (
    <StoreProvider store={store}>
      <TodoList />
    </StoreProvider>
  );
}

// 3. Use the store
function TodoList() {
  const todos = useStoreState((state) => state.todos);
  const addTodo = useStoreActions((actions) => actions.addTodo);
  return (
    <div>
      {todos.map((todo, idx) => (
        <div key={idx}>{todo}</div>
      ))}
      <AddTodo onAdd={addTodo} />
    </div>
  );
}

This strategy prevents dispatched actions from executing and instead records them. Use this to verify that a thunk dispatches the correct actions with the correct payloads without triggering side effects from those actions.

To use this, set mockActions: true in the createStore configuration. You can then inspect the recorded actions using store.getMockedActions().

import { createStore } from 'easy-peasy';

// ... model definition ...

test('fetchById', async () => {
  // arrange
  const todo = { id: 1, text: 'Test my store' };
  const mockTodosService = {
    fetchById: jest.fn(() => Promise.resolve(todo)),
  };
  const store = createStore(todosModel, {
    injections: { todosService: mockTodosService },
    mockActions: true,
  });

  // act
  await store.getActions().fetchById(todo.id);

  // assert
  expect(mockTodosService.fetchById).toHaveBeenCalledWith(todo.id);
  expect(store.getMockedActions()).toEqual([
    { type: '@thunk.fetchById(start)', payload: todo.id },
    { type: '@action.fetchedTodo', payload: todo },
    { type: '@thunk.fetchById(success)', payload: todo.id },
    { type: '@thunk.fetchById', payload: todo.id },
  ]);
});

You can provide or update injections (external values used by your store) at runtime via the Provider.

• To override all previous injections: Pass an object to the injections prop.
• To update existing injections: Pass a function to the injections prop. This function receives the previousInjections as an argument, allowing you to spread them and overwrite specific keys.

import CounterStore from './stores/counter';

function MyApp({ language }) {
  const translator = useTranslator(language);

  return (
    <>
      <Header />
      {/* Option 1: Overwrite all injections */}
      <CounterStore.Provider injections={{ translator }}>
        <Main />
      </CounterStore.Provider>

      {/* Option 2: Update existing injections using a function */}
      <CounterStore.Provider
        injections={(previousInjections) => ({
          ...previousInjections,
          translator,
        })}
      >
        <Main />
      </CounterStore.Provider>
    </>
  );
}