Why StateMesh?

One store for everything. State, server cache, forms, URL parameters, routing, cross-tab sync, undo history — all live in one store with one set of types. No more wiring together 5 libraries with different mental models.

Every state change is a transaction. Validate, optimistic update, effect, commit, rollback — all automatic. Retry with exponential backoff, timeout, and cancellation.

Subscriptions that never waste renders. Path-scoped selectors with equality checking. Updating cart.items does not rerender components reading theme.

Zero runtime dependencies. React is the only peer dependency.

Quick Start

npm install statemesh-core

import { createMesh, StateMeshProvider, useMeshState } from "statemesh-core";

const mesh = createMesh({
  state: { count: 0 }
});

function Counter() {
  const [count, setCount] = useMeshState<number>("count");
  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

export function App() {
  return (
    <StateMeshProvider mesh={mesh}>
      <Counter />
    </StateMeshProvider>
  );
}

Features

| Feature | What it does | |---------|-------------| | State | External store with path-based subscriptions, useSyncExternalStore | | Actions | Named state mutations with payloads and handlers | | Selectors & Computed | Derived state, memoization, dependency tracking | | Transactions | Async lifecycle — validate, optimistic, effect, commit, rollback | | Undo / Redo | Automatic history tracking with configurable depth | | Time Travel | Replay to any point in time | | Middleware Pipelines | Intercept, transform, log, and guard state changes | | Resources | Cached API reads with deduplication, polling, pagination | | Mutations | Write operations with optimistic rollback and offline queue | | API Client | Built-in HTTP client with interceptors and retry | | Persistence | localStorage, sessionStorage, IndexedDB, cross-tab sync | | Forms | Async validation, schema adapters, field arrays, autosave | | URL State | Sync state with URL search params | | Router | Routing IS state management — transactions, loaders, guards | | DevTools | Timeline, profiler, diagnostics, state inspector | | Testing | Mock helpers, assertions, async utilities |

Example: Transaction with Optimistic UI

const checkout = mesh.transaction("cart.checkout", {
  optimistic(state) {
    state.cart.status = "processing";
  },
  async effect(state, payload, ctx) {
    return fetch("/api/checkout", { signal: ctx.signal });
  },
  commit(state, result) {
    state.order = result;
    state.cart.items = [];
  },
  rollback: true,
  retry: { attempts: 3, delay: backoff() }
});

function CheckoutButton() {
  const tx = useMeshTransaction(checkout);
  return (
    <button disabled={tx.pending} onClick={() => tx.run({ paymentMethodId: "card_1" })}>
      {tx.pending ? "Processing..." : "Pay now"}
    </button>
  );
}

Example: Router with Data Loading

const routes = defineRoutes([
  {
    path: "/products",
    component: () => import("./pages/Products"),
    loader: ({ mesh }) => mesh.resource("products.list").fetch(),
    children: [
      {
        path: ":id",
        component: () => import("./pages/ProductDetail"),
        loader: ({ params, mesh }) => mesh.resource("product.detail").fetch({ id: params.id })
      }
    ]
  }
]);

function Layout() {
  return (
    <div>
      <nav>
        <Link to="/products">Products</Link>
      </nav>
      <Outlet />
    </div>
  );
}

Documentation

Full documentation is available at react-statemesh.github.io/statemesh-docs

| Section | What's covered | |---------|---------------| | Guide | Installation, core concepts, TypeScript | | Core | State, actions, selectors, transactions, undo/redo | | Data | Resources, mutations, API client, persistence | | UI | Forms, URL state, error boundaries | | Router | Routes, navigation, guards, data loading, SEO | | Advanced | Middleware, guards, plugins, sync, devtools | | Testing | Test helpers and patterns | | Integration | Next.js, migration from other libraries | | API Reference | Error codes, events, changelog |

Test Coverage

603 tests across 19 test files covering every module, API surface, error path, and edge case.

pnpm test           # Full suite
pnpm test:types     # Type tests only
pnpm test:watch     # Watch mode

Production Notes

• Zero runtime dependencies — React is a peer dependency
• 100% TypeScript — type-safe paths, discriminated events, generic inference
• SSR-safe — all browser APIs guarded, dehydrate/hydrate for server rendering
• Tree-shakeable — router, devtools, and testing are separate entry points
• Bounded memory — LRU caches, ring buffers, snapshot limits

License

MIT