@braine/statemanagement

The "God Particle" of State Management.

A unified architecture that merges Store, Actions, and API Logic into single, high-performance "Smart Models".

Why This Exists?

Existing libraries force you to split your brain:

• Redux/Zustand: Great for Client state, bad for Server state.
• React Query: Great for Server state, explicitly ignores Client state.

We solved this. With defineModel, you define Smart Models that own both their data (server + client) and their logic (optimistic updates, fetching).

Installation

npm install @braine/statemanagement
# or
yarn add @braine/statemanagement

The "Smart Model" Pattern

This is all you need to know. One function: defineModel.

1. Define It

import { defineModel } from '@braine/statemanagement';

export const Todos = defineModel({
  // 1. Unified State (Server + Client mixed!)
  state: {
    items: [] as string[],
    filter: 'all',
    isLoading: false
  },

  // 2. Computed Properties (Auto-Memoized)
  computed: {
    activeCount() {
      return this.items.length;
    },
    isEmpty() {
      return this.items.length === 0;
    }
  },

  // 3. Actions (Sync + Async + Optimistic)
  // 'this' is automatically bound to the reactive proxy.
  actions: {
    setFilter(filter: string) {
      this.filter = filter;
    },

    async add(text: string) {
      // A. Optimistic Update (Instant UI)
      this.items.push(text);
      
      try {
        // B. Network Call
        await fetch('/api/todos', { method: 'POST', body: text });
      } catch (err) {
        // C. Auto-Rollback (Manual for now, easy to do)
        this.items.pop();
        alert('Failed to save!');
      }
    }
  }
});

2. Use It

No selectors. No context. No providers. Just use it.

import { useStore } from '@braine/statemanagement';
import { Todos } from './models/Todos';

function TodoApp() {
  const model = useStore(Todos); // Auto-subscribes to properties you access

  if (model.isEmpty) return <div>No tasks!</div>;

  return (
    <div>
      <h1>Active: {model.activeCount}</h1>
      <button onClick={() => model.add("New Task")}>
        Add Task
      </button>
    </div>
  );
}

Comparison

| Feature | Redux Toolkit | TanStack Query | @braine/statemanagement | | :--- | :--- | :--- | :--- | | Philosophy | Reducers + Thunks | Server Cache Only | Unified Smart Models | | Boilerplate | High (Slices, Types) | Medium (Keys, Fetchers) | Zero | | Client State | Yes | No (Need Zustand) | Yes (Integrated) | | Optimistic UI| Complex (onQueryStarted) | Complex (onMutate) | Simple (this.push) | | Performance | Good | Excellent | Excellent (Proxy) |

Advanced Features

Direct Promise Binding

If you don't want a full model, you can still use the raw proxy power:

import { createState } from '@braine/statemanagement';

// Assign a promise, and the UI suspends automatically!
const store = createState({
  data: fetch('/api/data').then(r => r.json())
});

DevTools

Full Redux DevTools support is built-in.

import { enableDevTools } from '@braine/statemanagement';
enableDevTools(Todos, 'TodoModel');

License

MIT