@prometheus-ags/prometheus-entity-management

Normalized, globally-reactive entity graph store for React

Update a post in one screen and every list row, detail panel, and badge that reads that entity updates automatically—without hand-maintained query keys. Normalization is built around your type + id + normalize function, not a separate cache product. The same graph holds data from REST, GraphQL, WebSocket / Supabase / Convex, Prisma-shaped APIs, and ElectricSQL + PGlite local-first sync.

3.0 React release

The 3.2.0 package line and its React 19/Vite 8 source-workspace showcase is implemented. The production-browser gate covers normalized cross-view updates, optimistic confirm/rollback, relationships, view completeness modes, REST/GraphQL seams, realtime coalescing, PGlite/Loro, Suspense/error containment, DevTools, and accessibility.

See the React 19/Vite 8 release guide for the assembled example evidence. Install the matching stable core and React pair with:

pnpm add @prometheus-ags/entity-graph-core@3.2.0 \
  @prometheus-ags/prometheus-entity-management@3.2.0 \
  react@^19 react-dom@^19
Copy

Release boundary: npm 3.2.0 includes the optional ./devtools and development-only ./devtools/auto inspector entries documented below. The ordinary package root remains inspector-free.

Documentation map

Quick start

1. Install

pnpm add @prometheus-ags/entity-graph-core @prometheus-ags/prometheus-entity-management react react-dom
Copy

(npm install works for consumers too; this repository itself is pnpm-only.)

@prometheus-ags/entity-graph-core is a required peer: install it explicitly so the application owns the one compatible graph instance. The React package must not install a private core copy. See the binding singleton contract.

2. Define an entity type

type Post = { id: string; title: string; status: string };
Copy

3. Fetch and render

import { useEntity } from "@prometheus-ags/prometheus-entity-management";

export function PostCard({ postId }: { postId: string }) {
  const { data, isLoading, error } = useEntity<Post, Post>({
    type: "Post",
    id: postId,
    fetch: async (id) => {
      const res = await fetch(`/api/posts/${id}`);
      if (!res.ok) throw new Error(String(res.status));
      return res.json() as Post;
    },
    normalize: (raw) => raw,
  });

  if (isLoading) return <p>Loading…</p>;
  if (error) return <p>{error}</p>;
  if (!data) return null;
  return <article>{data.title}</article>;
}
Copy

Any other component that calls useEntity with the same type and id reads the same normalized record from the graph.

Core concepts

Entities live exactly once

Each (entityType, id) maps to a single canonical object in the Zustand graph (entities[type][id]). Lists and detail views never keep their own full copies; they resolve through that node.

Queries are instructions, not containers

useEntity, useEntityList, and GraphQL hooks describe how to load data and how to normalize it into the graph. They do not own isolated cache entries the way query-key–scoped caches do.

Lists store IDs, not data

List state keeps ordered IDs plus pagination metadata. Rows are items joined from entities at render time, so when Post:123 changes, every list that includes that ID re-renders consistently.

Three-layer model

Data flows up into the graph; UI reads down through hooks (see Architecture).

┌─────────────────────────────────────────────────────────────┐
│ Layer 3: UI Components (optional, users can build their own)│
│ src/ui/                                                      │
│ EntityTable · EntityDetailSheet · EntityFormSheet · columns │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Access Patterns (hooks - how components read data) │
│ src/hooks.ts, src/graphql/hooks.ts, src/crud/               │
│ useEntity · useEntityList · useEntityView · useEntityCRUD   │
│ useGQLEntity · useEntityMutation · useEntityAugment         │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: Entity Graph (Zustand store - canonical data)      │
│ src/graph.ts                                                 │
│ entities[type][id] · patches[type][id] · lists[queryKey]     │
└─────────────────────────────────────────────────────────────┘
              ▲           ▲           ▲           ▲
         REST fetch   GraphQL    WebSocket    ElectricSQL
Copy

v1.3 additions

Eight focused additions across three patch releases for tenant-scoped, PGlite-backed local-first apps. All backward compatible; no new runtime dependencies.

v1.3.0 — new APIs

v1.3.1 — stability fix

• useEntityList return shape is now useMemo-stabilised. React 19's useSyncExternalStore was detecting a fresh object on every render and emitting an infinite-loop warning. Identity-stable items + stable pagination state means no more perpetual loading skeletons from hook composition chains.

v1.3.2 — error handling

• isError: boolean added to both UseEntityListResult and UseEntityViewResult as a convenience alias for error !== null, matching TanStack Query's hook ergonomics.
• setListError now stamps lastFetched and clears stale, closing a terminal-error retry loop where a 404 on a missing table triggered an infinite refetch storm.
• useEntityView writes errors to the base key (the one isLoading reads from) and defaults isLoading to false when no list state exists, so a failed first fetch no longer leaves consumers stuck in a perpetual loading state.

New in v1.2

The graph runtime now exposes a focused set of non-hook helpers for loaders, workflows, and orchestration:

• queryOnce(...) / selectGraph(...) for one-shot graph snapshots without a live subscription
• nested include projections over normalized graph data
• createGraphTransaction(...) / createGraphAction(...) for explicit optimistic graph writes with rollback
• sync-aware snapshot metadata: $synced, $origin, $updatedAt
• createGraphEffect(...) for enter/update/exit reactions over graph query results
• createGraphTool(...) / exportGraphSnapshot(...) for AI interoperability without bundling an AI runtime
• startLocalFirstGraph(...), hydrateGraphFromStorage(...), and persistGraphToStorage(...) for PWA/PGlite-friendly graph persistence and replay
• schema-driven entity rendering via registerEntityJsonSchema(...), buildEntityFieldsFromSchema(...), and useSchemaEntityFields(...)
• built-in markdown-aware schema fields plus schema-aware graph export helpers for A2UI/runtime-generated entity models

These additions are intentionally graph-native. They extend the entity graph for orchestration use cases without changing the core Components → Hooks → Stores → APIs/Realtime architecture.

Feature comparison

Peer dependencies (react and react-dom) are not included in any column. The package installs @tanstack/react-table because the root entry exports the built-in table components that use it at runtime. Published dist sizes change with each release—measure before quoting numbers in docs or talks.

Bundle size

The npm package ships a single large entry (dist/index.mjs) that re-exports the full surface (hooks, GraphQL, CRUD, view, UI, adapters). Your app’s gzipped cost depends on tree-shaking, minification, and which imports you use.

Maintainers: after pnpm run build, a rough gzip size of the ESM bundle is:

gzip -c dist/index.mjs | wc -c
Copy

Compare against peers only when measurement methodology matches (minified vs unminified, gzip vs brotli, ESM vs CJS).

API reference (brief)

Core

useGraphStore's imperative surface (getState / setState / subscribe / getInitialState) resolves the active graph on every call, so store actions, module-level helpers, and mutation callbacks honour a mounted GraphStoreProvider without being rewritten as hooks. Resolution order is:

1. the request scope opened by runWithGraphStore(store, fn),
2. the module-level store published by a mounted GraphStoreProvider,
3. the package singleton.

With no provider and no request scope this is exactly the pre-3.0.5 behaviour, so existing imperative callers are unaffected.

Server code must open a request scope. GraphStoreProvider is React context and cannot scope Server Components or module-level functions, and a module-level store would leak across concurrent requests. Wrap each request:

import { createGraphStore, runWithGraphStore, prepareGraphStoreScope } from "@prometheus-ags/entity-graph-core";

// Once at startup — REQUIRED under pure ESM, where there is no synchronous
// `require` to load node:async_hooks. Without it request scoping degrades to
// the module-level store and warns.
await prepareGraphStoreScope();

// Per request
runWithGraphStore(createGraphStore(), () => renderThisRequest());
Copy

Capturing useGraphStoreApi() during render is still the most explicit option inside React, and injecting a GraphStore parameter remains available for code that wants no ambient resolution at all.

Graph runtime

Schema-driven entities

Local-first runtime

Hooks (REST-oriented)

View

CRUD

Realtime

GraphQL

Prisma

Local-first adapters

DevTools

The ordinary package root keeps the lightweight legacy useGraphDevTools hook and does not import or mount the inspector. The full inspector ships in 3.2.0 behind two optional subpaths:

For Vite, add one debug-only dynamic import near the client entry:

if (import.meta.env.DEV) {
  void import("@prometheus-ags/prometheus-entity-management/devtools/auto");
}
Copy

For Next.js, mount the explicit host from a client component after hydration and pass the same provider-owned graph used by the application:

"use client";

import { useEffect, useState } from "react";
import type { GraphStore } from "@prometheus-ags/entity-graph-core";

type Host = typeof import(
  "@prometheus-ags/prometheus-entity-management/devtools"
)["EntityGraphDevtools"];

export function DevelopmentGraphTools({ store }: { store: GraphStore }) {
  const [Host, setHost] = useState<Host | null>(null);
  useEffect(() => {
    if (process.env.NODE_ENV === "production") return;
    let active = true;
    void import("@prometheus-ags/prometheus-entity-management/devtools")
      .then((module) => {
        if (active) setHost(() => module.EntityGraphDevtools);
      });
    return () => {
      active = false;
    };
  }, []);
  return Host ? <Host mode="auto" store={store} /> : null;
}
Copy

After opt-in, development mode shows a floating Graph launcher. Open it to inspect Overview, Entities, Views, Activity, Graph Pulse causality, canonical originals, local patches, merged live values, registered rendered-view membership, retained entity history, and controller-owned time travel. The display menu can move or compact the launcher, dock the inspector, hide it until reload, or hide it for the browser. Restore/toggle it with Ctrl/Cmd+Shift+G.

Serialized/remote inspection remains metadata-only unless the host explicitly enables an include/redact value policy. The same-origin embedded inspector can read the selected local store without sending values over a transport. The optional Loro adapter is loaded only when a consumer uses that integration.

UI (optional)

Types (high level)

GraphState, EntityState, ListState, EntityType, EntityId, EntitySyncMetadata, EntitySnapshot, EngineOptions, EntityQueryOptions, ListQueryOptions, ViewDescriptor, EntitySchema, RelationDescriptor, realtime adapter types, GraphQL types, CRUD types, and column meta types are all exported from the package entry.

Migration from TanStack Query

Single record: useQuery → useEntity

Before (TanStack Query)

const { data, isLoading } = useQuery({
  queryKey: ["post", id],
  queryFn: () => fetch(`/api/posts/${id}`).then((r) => r.json()),
});
Copy

After (entity graph)

const { data, isLoading } = useEntity<Post, Post>({
  type: "Post",
  id,
  fetch: (postId) => fetch(`/api/posts/${postId}`).then((r) => r.json()),
  normalize: (raw) => raw,
});
Copy

Difference: the graph key is (type, id), not an opaque query key. Anything else that uses the same type/id shares that record—no setQueryData across keys.

Lists: useQuery + key → useEntityList

Before

const { data } = useQuery({
  queryKey: ["posts", { status }],
  queryFn: () => api.posts.list({ status }),
});
Copy

After

const { items, isLoading } = useEntityList<Post, Post>({
  type: "Post",
  queryKey: ["posts", { status }],
  fetch: (p) => api.posts.list({ status, page: p.page, pageSize: p.pageSize, cursor: p.cursor }),
  normalize: (row) => ({ id: row.id, data: row }),
});
Copy

Difference: the list stores IDs; row objects are always read through the normalized Post map, so updates propagate everywhere.

TanStack Table: useQuery data prop → useEntityListAsTable

If you wire useEntityList directly into TanStack Table's data prop, the table treats a new array reference as new data on every render. Use useEntityListAsTable instead—it returns a referentially-stable data array that only changes when the underlying items actually change.

Before

const { data = [] } = useQuery<Post[]>({
  queryKey: ["posts"],
  queryFn: () => api.posts.list(),
});
const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
Copy

After

import { useEntityListAsTable } from "@prometheus-ags/prometheus-entity-management";

const { data, rowCount, isLoading, isError, error } = useEntityListAsTable<Post, Post>({
  type: "Post",
  fetch: (p) => api.posts.list(p),
  normalize: (row) => ({ id: row.id, data: row }),
});

const table = useReactTable({ data, rowCount, columns, getCoreRowModel: getCoreRowModel() });
Copy

Difference: data identity is stable across renders where items haven't changed, so TanStack Table's memoization works correctly and row state (selection, expansion) is preserved between refetches.

Mutations: useMutation → useEntityMutation

Before

const qc = useQueryClient();
const mutation = useMutation({
  mutationFn: (id: string) => api.posts.archive(id),
  onSuccess: () => {
    qc.invalidateQueries({ queryKey: ["posts"] });
    qc.invalidateQueries({ queryKey: ["post"] });
  },
});
Copy

After

import { serializeKey, useEntityMutation } from "@prometheus-ags/prometheus-entity-management";

const { mutate } = useEntityMutation<string, Post, Post>({
  type: "Post",
  mutate: (id) => api.posts.archive(id),
  normalize: (raw) => ({ id: raw.id, data: raw }),
  optimistic: (id) => ({ id, patch: { status: "archived" } }),
  invalidateLists: [serializeKey(["posts"])],
});
Copy

Difference: optimistic updates target the entity; optional list invalidation is declarative. Cross-view consistency comes from normalization, not from remembering every query key.

Migration from Apollo Client

Query: useQuery → useGQLEntity / useGQLList

Before (Apollo)

const { data } = useQuery(GET_POST, { variables: { id } });
Copy

After

const { data } = useGQLEntity({
  client: gqlClient,
  document: GET_POST,
  variables: {},
  type: "Post",
  id,
  descriptor: postDescriptor,
});
Copy

Use useGQLList with document, queryKey, descriptor, and getItems to map the response into rows.

Difference: you describe entities with descriptors (how to normalize IDs and nested types) once; you do not maintain a parallel universe of type policies and merge functions for every edge case.

Mutation: useMutation → useGQLMutation

Before

const [mutate] = useMutation(UPDATE_POST);
Copy

After

const { mutate } = useGQLMutation({
  client: gqlClient,
  document: UPDATE_POST,
  type: "Post",
  descriptors: [postDescriptor],
});
Copy

Descriptors tell the client how to write normalized entities from the mutation payload—no Apollo-style type policies.

Subscriptions: useSubscription → useGQLSubscription

Before

useSubscription(POST_UPDATED, { variables: { id } });
Copy

After

useGQLSubscription({
  client: gqlClient,
  wsClient: gqlWsClient,
  document: POST_UPDATED_SUB,
  variables: { id },
  descriptors: [postDescriptor],
});
Copy

Difference: GraphQL, REST, and realtime adapters can all write the same entity graph, so mixed stacks do not need two caches.

Prisma integration

createPrismaEntityConfig targets REST APIs that accept Prisma-style where and orderBy as JSON query parameters (typical for Prisma-backed route handlers).

import {
  createPrismaEntityConfig,
  registerSchema,
  useEntity,
  useEntityList,
} from "@prometheus-ags/prometheus-entity-management";

type Post = { id: string; title: string; authorId: string };

const Posts = createPrismaEntityConfig<Post>({
  type: "Post",
  endpoint: "/api/posts",
  relations: {
    author: { type: "User", foreignKey: "authorId", relation: "belongsTo" },
    comments: { type: "Comment", foreignKey: "postId", relation: "hasMany" },
  },
});

// Register cascade rules once (e.g. app init)
Posts.schemas().forEach(registerSchema);
Copy

function PostDetail({ postId }: { postId: string }) {
  const { data } = useEntity(Posts.entity(postId));
  return data ? <h1>{data.title}</h1> : null;
}

function PostList() {
  const { items } = useEntityList(
    Posts.list({
      filter: [{ field: "status", op: "eq", value: "published" }],
      sort: [{ field: "createdAt", direction: "desc" }],
    })
  );
  return (
    <ul>
      {items.map((p) => (
        <li key={p.id}>{p.title}</li>
      ))}
    </ul>
  );
}
Copy

Use Posts.crud() with useEntityCRUD when you want the full list + detail + forms pipeline against the same endpoints.

Examples

From the repo root (this monorepo uses pnpm):

pnpm install
pnpm run dev:vite   # http://localhost:5173
pnpm run dev:next   # http://localhost:3000
Copy

Architecture

Data flow rules

• Components → Hooks → Stores → APIs / realtime — UI uses hooks only; hooks orchestrate; network and adapters update the graph.
• Up into the graph: fetches, mutations, and realtime events call into the Zustand store.
• Down from hooks: useEntity, useEntityList, useEntityView, GraphQL hooks, and CRUD read merged entities + patches.

Graph structures (src/graph.ts)

1. entities — Canonical server-shaped records per (type, id).
2. patches — Local-only overlays (_selected, _loading, …) merged at read time.
3. lists — Ordered ids[], pagination, and fetch flags — not duplicated row payloads.
4. syncMetadata — Per-entity sync/provenance state layered into snapshot reads as $synced, $origin, and $updatedAt.

Engine (src/engine.ts)

In-flight deduplication, retries, subscriber ref-counting, stale-while-revalidate, optional periodic garbage collection for entities without subscribers.

Realtime (src/adapters/realtime-manager.ts)

Adapters emit a shared change shape; the manager batches updates per animation frame to avoid UI thrash.

View layer (src/view/)

One FilterSpec / SortSpec can compile to REST, SQL, GraphQL variables, or Prisma shapes, and can run locally when the graph already holds enough data.

CRUD (src/crud/)

useEntityCRUD keeps the edit buffer in React state so other views stay on committed data until save; registerSchema drives relation-aware cascade invalidation.

Development (this repository)

pnpm install

# Examples
pnpm run dev:vite
pnpm run dev:next

# Typecheck
pnpm run typecheck
pnpm run typecheck:vite
pnpm run typecheck:next

# Production builds of examples
pnpm run build:vite
pnpm run build:next

# Clean artifacts
pnpm run clean
Copy

The library is consumed from source via path aliases in examples during development (no separate build step required for local hacking).

License

MIT © Prometheus AGS / KnowMe LLC