@novahelm/query

NovaQuery — a small, first-party React query cache. It's the NovaHelm replacement for @tanstack/react-query, providing the slice of the React Query surface the platform actually uses (no Suspense / infinite queries / optimistic mutations).

It's a leaf package (React-only dependency) so it can sit below @novahelm/rpc and @novahelm/client in the dependency graph — both build their RPC hooks on it.

Quick Start

pnpm add @novahelm/query

import {
  createQueryCache,
  NovaQueryProvider,
  useQuery,
  useMutation,
  useQueryCache,
} from "@novahelm/query";

const cache = createQueryCache({ defaultStaleTime: 30_000, defaultRetry: 1 });

function App() {
  return (
    <NovaQueryProvider client={cache}>
      <Profile />
    </NovaQueryProvider>
  );
}

function Profile() {
  const q = useQuery({
    queryKey: ["users.me", {}],
    queryFn: () => fetch("/api/me").then((r) => r.json()),
  });
  if (q.isPending) return <span>Loading…</span>;
  if (q.isError) return <span>Failed</span>;
  return <span>{q.data.name}</span>;
}

API

| Export | Description | |--------|-------------| | createQueryCache(config?) | Create a cache. config: defaultStaleTime (ms), defaultRetry, gcTime. | | NovaQueryProvider | Context provider — wrap your app, pass the cache as client. | | useQueryCache() | Access the cache (≈ TanStack's useQueryClient); exposes invalidateQueries({ predicate }) / refetchQueries({ predicate }). | | useQuery({ queryKey, queryFn, ...opts }) | Reactive query. Opts: enabled, staleTime, refetchInterval, initialData, select, keepPreviousData, retry. Returns { data, error, status, isPending, isLoading, isFetching, isSuccess, isError, refetch }. | | useMutation({ mutationFn, ...opts }) | Mutation. Opts: onSuccess, onError, retry. Returns { mutate, mutateAsync, data, error, status, isPending, isError, isSuccess, reset }. |

The cache uses immutable per-key snapshots (tear-free useSyncExternalStore reads), in-flight request dedup, staleTime-based freshness, predicate-based invalidation that refetches active queries, and gcTime garbage collection for unsubscribed entries.

Design: docs/superpowers/specs/2026-06-18-bns-2-novaquery-react-query-removal-design.md