What is Retomus?

Retomus is a lightweight, finite state machine-based state management library designed specifically for React and TypeScript applications.

It offers a predictable, declarative approach to managing component and application logic using event-driven, structured state models.

---

🧠 Why Retomus?

Modern React apps often suffer from:

• Sprawling state logic across multiple hooks
• Fragile transitions and UI state bugs
• Lack of clear separation between state and effect

Retomus solves these with:

• Declarative state machines that model UI behavior explicitly
• Type-safe transitions and event-driven updates
• Seamless React integration via hooks like useMachine and useService

---

🚀 Key Features

• 🔄 Finite State Logic: Clear state transitions and lifecycle boundaries
• 🧩 Composable Machines: Easily modularize complex logic
• 🛡️ TypeScript-First: Types as the source of truth
• 🧪 Testability: State logic is easy to test in isolation

---

🔍 Example: Counter Machine

const counterMachine = retomus.createMachine(
  createMachineConfig({
    id: 'counter',
    status: ['idle', 'active'],
    actions: ['increment', 'decrement', 'reset'],
    transitions: {
      idle: {
        increment: 'active',
        decrement: 'active',
      },
      active: {
        increment: 'active',
        decrement: 'active',
        reset: 'idle',
      },
    },
    actionHandlers: {
      increment: ({ ctx, done }) => {
        ctx.state.count++;
        done();
      },
      decrement: ({ ctx, done }) => {
        ctx.state.count--;
        done();
      },
      reset: ({ ctx, done }) => {
        ctx.state.count = 0;
        done();
      },
    },
    initialStatus: {
      status: 'idle',
    },
    ctx: {
      state: { count: 0 },
    },
  }),
);

const CounterComponent = ({ counterMachine }) => {
  const count = counterMachine.useState('count');
  const status = counterMachine.useStatus();
  const increment = counterMachine.useAction('increment');
  const decrement = counterMachine.useAction('decrement');
  const reset = counterMachine.useAction('reset');

  return (
    <div>
      <h2>Status: {status}</h2>
      <p>Count: {count}</p>
      <div>
        <button onClick={increment}>increment</button>
        <button onClick={decrement}>decrement</button>
        <button onClick={reset}>reset</button>
      </div>
    </div>
  );
};

This code declares a fully typed toggle state machine, ready to use in your components.

---