Advanced State Management in 2026: Balancing Signals, Server State, and React Context

// features/cart/cart-store.ts
import { signal, computed, batch } from '@preact/signals-react';

export interface CartLine {
  readonly sku: string;
  readonly unitPriceCents: number;
  quantity: number;
}

export class CartStore {
  private readonly _lines = signal<ReadonlyMap<string, CartLine>>(new Map());
  private readonly _coupon = signal<string | null>(null);

  // Pull-based derivations: recompute lazily, only when read after invalidation.
  readonly lines = computed(() => [...this._lines.value.values()]);
  readonly itemCount = computed(() =>
    this.lines.value.reduce((n, l) => n + l.quantity, 0),
  );
  readonly subtotalCents = computed(() =>
    this.lines.value.reduce((sum, l) => sum + l.unitPriceCents * l.quantity, 0),
  );

  addLine(line: Omit<CartLine, 'quantity'>, qty = 1): void {
    if (!Number.isInteger(qty) || qty <= 0) {
      throw new RangeError(`addLine: qty must be a positive integer, got ${qty}`);
    }
    const next = new Map(this._lines.value);
    const existing = next.get(line.sku);
    next.set(
      line.sku,
      existing
        ? { ...existing, quantity: existing.quantity + qty }
        : { ...line, quantity: qty },
    );
    this._lines.value = next;
  }

  clear(): void {
    // batch() collapses N writes into a single notification flush.
    batch(() => {
      this._lines.value = new Map();
      this._coupon.value = null;
    });
  }
}

// features/cart/CartBadge.tsx
import { useSyncExternalStore } from 'react';
import type { CartStore } from './cart-store';

export function CartBadge({ store }: { store: CartStore }) {
  // Only re-renders when itemCount changes — not when the coupon changes.
  const count = useSyncExternalStore(
    (notify) => {
      // signals-react exposes subscription via effect(); for a bridge you can
      // also use the store's own pub/sub. Keep the callback stable.
      const dispose = store.itemCount.subscribe?.(notify) ?? (() => {});
      return dispose;
    },
    () => store.itemCount.value,
    () => store.itemCount.value, // getServerSnapshot: required for SSR
  );

  return <span aria-live="polite">{count}</span>;
}

// features/todos/queries.ts
import { queryOptions } from '@tanstack/react-query';

export class ApiError extends Error {
  constructor(
    message: string,
    readonly status: number,
    readonly requestId?: string,
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

async function apiFetch<T>(path: string, init: RequestInit = {}): Promise<T> {
  const res = await fetch(path, {
    ...init,
    headers: { accept: 'application/json', ...init.headers },
  });
  if (!res.ok) {
    throw new ApiError(
      await res.text(),
      res.status,
      res.headers.get('x-request-id') ?? undefined,
    );
  }
  return (await res.json()) as T;
}

export type TodoFilter = 'all' | 'open' | 'done';

export const todoKeys = {
  all: ['todos'] as const,
  list: (filter: TodoFilter) => [...todoKeys.all, 'list', filter] as const,
  detail: (id: string) => [...todoKeys.all, 'detail', id] as const,
};

export const todoListQuery = (filter: TodoFilter) =>
  queryOptions({
    queryKey: todoKeys.list(filter),
    // The context signal is an AbortSignal — wire it into fetch for real cancellation.
    queryFn: ({ signal }) =>
      apiFetch<Todo[]>(`/api/todos?filter=${filter}`, { signal }),
    staleTime: 30_000,
    gcTime: 5 * 60_000,
    retry: (attempt, error) =>
      attempt < 2 && !(error instanceof ApiError && error.status < 500),
  });

// features/todos/use-update-todo.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';

export interface TodoPatch {
  id: string;
  title?: string;
  done?: boolean;
}

export function useUpdateTodo() {
  const qc = useQueryClient();

  return useMutation({
    mutationFn: (patch: TodoPatch) =>
      apiFetch<Todo>(`/api/todos/${patch.id}`, {
        method: 'PATCH',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(patch),
      }),

    onMutate: async (patch) => {
      // 1. Cancel in-flight reads so they cannot clobber the optimistic write.
      await qc.cancelQueries({ queryKey: todoKeys.detail(patch.id) });
      // 2. Snapshot for rollback.
      const previous = qc.getQueryData<Todo>(todoKeys.detail(patch.id));
      // 3. Apply optimistically.
      qc.setQueryData<Todo>(todoKeys.detail(patch.id), (old) =>
        old ? { ...old, ...patch } : old,
      );
      return { previous };
    },

    onError: (_err, patch, ctx) => {
      if (ctx?.previous) {
        qc.setQueryData(todoKeys.detail(patch.id), ctx.previous);
      }
    },

    onSettled: () => {
      // Reconcile with server truth regardless of outcome.
      void qc.invalidateQueries({ queryKey: todoKeys.all });
    },
  });
}

// app/todos/page.tsx — Server Component
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
import { todoListQuery } from '@/features/todos/queries';

export default async function TodosPage() {
  const qc = new QueryClient();
  // Fire-and-forget prefetch: streamed to the client via HydrationBoundary.
  void qc.prefetchQuery(todoListQuery('open'));

  return (
    <HydrationBoundary state={dehydrate(qc)}>
      <TodoList filter="open" />
    </HydrationBoundary>
  );
}

// ❌ New object identity on every render → every consumer re-renders.
<AuthContext.Provider value={{ user, signOut }}>

// ✅ Stable identity, so consumers only re-render when user or signOut change.
const authValue = useMemo(() => ({ user, signOut }), [user, signOut]);
<AuthContext.Provider value={authValue}>

// shared/create-store-context.tsx
import {
  createContext,
  useCallback,
  useContext,
  useRef,
  useSyncExternalStore,
  type ReactNode,
} from 'react';

export interface ObservableStore<T> {
  getState: () => T;
  subscribe: (listener: () => void) => () => void;
}

export function createStoreContext<T>(name: string) {
  const StoreContext = createContext<ObservableStore<T> | null>(null);
  StoreContext.displayName = `${name}Context`;

  function StoreProvider({
    store,
    children,
  }: {
    store: ObservableStore<T>;
    children: ReactNode;
  }) {
    return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
  }

  function useStore<U>(
    selector: (state: T) => U,
    isEqual: (a: U, b: U) => boolean = Object.is,
  ): U {
    const store = useContext(StoreContext);
    if (store === null) {
      throw new Error(`use${name}Store must be used within <${name}Provider>`);
    }

    const cache = useRef<{ value: U } | null>(null);

    // Snapshot must be referentially stable when the selected slice is unchanged,
    // otherwise useSyncExternalStore loops. Cache the last value.
    const getSnapshot = useCallback(() => {
      const next = selector(store.getState());
      if (cache.current !== null && isEqual(cache.current.value, next)) {
        return cache.current.value;
      }
      cache.current = { value: next };
      return next;
    }, [store, selector, isEqual]);

    return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
  }

  return { StoreProvider, useStore, StoreContext };
}