@prometheus-ags/prometheus-entity-management 1.2.3 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,269 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [2.0.0] — 2026-05-25 — BREAKING
+
+### Overview
+
+2.0 eliminates the **"transport leak"** — the 1.x pattern where every
+`useEntityView` / `useEntityList` call accepted its own `remoteFetch`,
+`normalize`, `queryKey`, `enabled`, and error-handling strategy. Each
+call site reinvented the same retry-loop bug in subtly different ways.
+
+The new model: register ONE transport per entity type at app boot.
+Every hook thereafter looks it up by name. Error handling, retry policy,
+AbortController threading, and SWR staleness are enforced once, in the
+library, not at every call site.
+
+### BREAKING CHANGES
+
+#### Removed (runtime-warning shims remain — they log a migration message and continue working)
+
+- `useEntityList(opts)` — inline `fetch`/`normalize` closure form
+- `useEntityView(opts)` — inline `remoteFetch`/`normalize` closure form
+
+Both names still export. Calling them logs:
+```
+[entity-management] useEntityView("Foo") is deprecated in 2.0.
+Register a transport: registerEntityTransport("Foo", makeRestTransport(...))
+Then replace this call with: useEntityQuery<T>("Foo", { view })
+```
+
+TypeScript types remain unchanged — existing consumers compile without
+modification. Runtime behavior is identical. The warning is the only
+observable change for existing call sites.
+
+#### Migration guide
+
+**Step 1 — Register transports at app boot (once per entity type):**
+
+```ts
+import { registerEntityTransport, makeRestTransport } from "@prometheus-ags/prometheus-entity-management";
+import { supabase } from "@/shared/db/supabase";
+
+registerEntityTransport("Invoice", makeRestTransport({
+  supabase,
+  table: "invoice",
+  authoritative: false,
+}));
+```
+
+**Step 2a — Simple lists: replace `useEntityList` with `useEntities`:**
+
+```ts
+// BEFORE
+const { items, isLoading, error } = useEntityList({
+  type: "Invoice",
+  queryKey: ["Invoice", companyId],
+  fetch: () => supabase.from("invoice").select("*"),
+  normalize: (raw) => ({ id: String(raw.id), data: raw }),
+  enabled: !!companyId,
+});
+
+// AFTER
+const { items, isLoading, error } = useEntities<Invoice>("Invoice", {
+  filter: { field: "company_id", op: "eq", value: companyId },
+  enabled: !!companyId,
+});
+// error is now TerminalError | TransientError | null (instanceof-checkable)
+```
+
+**Step 2b — Rich views with toolbars: replace `useEntityView` with `useEntityQuery`:**
+
+```ts
+// BEFORE
+const { items, setFilter, setSort } = useEntityView({
+  type: "Client",
+  baseQueryKey: ["clients", workspaceId],
+  view: { filter, sort },
+  remoteFetch: (params) => api.clients(params.rest),
+  normalize: (raw) => ({ id: raw.id, data: raw }),
+});
+
+// AFTER
+const { items, setFilter, setSort } = useEntityQuery<Client>("Client", { view: { filter, sort } });
+```
+
+### Added
+
+- **`TerminalError`** — 4xx / permanent failures. `instanceof`-checkable.
+  `kind: "terminal"`, optional `status: number`.
+  Engine does NOT retry on TerminalError.
+
+- **`TransientError`** — 5xx / network failures. `instanceof`-checkable.
+  `kind: "transient"`, optional `status: number`.
+  Engine retries with exponential backoff (up to `maxRetries`, default 3).
+
+- **`toEntityError(err)`** — Converts unknown thrown values to
+  `TerminalError | TransientError`:
+  - 4xx status → TerminalError
+  - AbortError → TerminalError
+  - 5xx / network → TransientError
+  - Plain Error → TransientError
+
+- **`EntityTransport<T>` interface** — One implementation per entity type:
+  ```ts
+  interface EntityTransport<T extends object> {
+    identify: (row: T) => string;
+    authoritative: boolean;
+    staleTime?: number;
+    list: (q: ListQuery) => Promise<ListResult<T>>;
+    get?: (id: string, signal?: AbortSignal) => Promise<T | null>;
+    subscribe?: (onChange: (ev: ChangeEvent<T>) => void) => () => void;
+  }
+  ```
+
+- **`registerEntityTransport(type, transport)`** — Register at app boot.
+  Re-registering replaces (useful in tests).
+
+- **`getEntityTransport<T>(type)`** — Look up registered transport.
+  Throws `TerminalError` if not found.
+
+- **`makeRestTransport(opts)`** — PostgREST/Supabase transport builder.
+  Maps `ListQuery` → query params, parses `Content-Range` for total,
+  maps 4xx → TerminalError, 5xx/network → TransientError, threads signal.
+
+- **`useEntities<T>(type, opts)`** — Thin replacement for `useEntityList`.
+  5-field return: `{ items, isLoading, isError, error, refetch }`.
+  - `error` is typed `TerminalError | TransientError | null`.
+  - `isLoading` is `lastFetched === null && isFetching` — never stuck at true.
+  - AbortController per fetch; aborts on unmount/key-change/refetch.
+  - 4xx → TerminalError, no retry.
+  - 5xx → TransientError, retry with exponential backoff.
+
+- **`useEntityQuery<T>(type, opts)`** — Rich replacement for `useEntityView`.
+  Full toolbar API: `setFilter`, `setSort`, `setSearch`, `fetchNextPage`,
+  `setView`, `clearView`, `refetch`. Transport looked up from registry
+  (no inline closure). `error` is typed.
+
+### Fixed (preserved from 1.3.2)
+
+- `setListError` stamps `lastFetched` — terminal failures no longer cause
+  infinite retry loops.
+- `useEntityView` writes errors to the base key — closes the Quick Stats
+  staleness trap.
+
+---
+
+## [1.3.2] — 2026-05-25
+
+### Fixed
+
+- **`setListError` now stamps `lastFetched` and clears `stale`.**
+  Previously, a failed list fetch only set `error` + cleared
+  `isFetching` — leaving `lastFetched: null`. Every consumer hook's
+  SWR staleness check
+  (`Date.now() - (lastFetched ?? 0) > staleTime`) then returned
+  `true` on the very next render, refiring the fetcher in an
+  infinite loop. A 404 on a missing table (e.g. against a schema
+  that hasn't been migrated yet) became a perpetual retry storm.
+  After this fix, a terminal failure is treated as a completed
+  attempt: consumers see a stable `error` and `isFetching: false`,
+  and the fetcher runs once. Manual `refetch()` is still available
+  for explicit retries.
+- **`useEntityView` writes errors to the BASE key**, not just to
+  the remote-result key. The base key is the one
+  `isLoading` / `isStale` read from — without this, the staleness
+  check kept refiring even after the catch. Combined with the
+  `setListError` fix, this closes the terminal-error trap for
+  `useEntityView` consumers (Quick Stats, Active Trial Performance,
+  Revenue Trend, Recent Activity, etc.).
+- **`useEntityView`'s `isLoading` no longer defaults to `true` when
+  there is no list state.** The previous `listState?.isFetching ??
+  true` was the actual symptom of the trap: when no list state
+  existed (because the failed fetch never seeded the base key), the
+  `?? true` kept `isLoading` at `true` forever. Changed to `?? false`
+  to match `useEntityList`'s symmetric behaviour (it reads
+  `EMPTY_LIST_STATE` which has `isFetching: false` by default).
+
+### Added
+
+- **`isError: boolean`** added to both `UseEntityViewResult` and
+  `UseEntityListResult`. Convenience for `error !== null`,
+  matching TanStack Query's hook ergonomics. Purely additive on
+  the return — no breaking API change.
+
+### Notes
+
+- This release does NOT add an `onError` callback option to either
+  hook. The decision is deliberate: TanStack Query deprecated
+  per-query `onError` callbacks in v5 because they fire per
+  observer (calling the same hook from N components produces N
+  notifications on a single failure). Consumers should read
+  `error` / `isError` from the hook return and decide their own
+  display strategy. See
+  https://tkdodo.eu/blog/react-query-error-handling for the
+  research that drove this decision.
+
+---
+
+## [1.3.1] — 2026-05-25
+
+### Fixed
+
+- **`useEntityList` no longer triggers React 19's "The result of
+  getSnapshot should be cached to avoid an infinite loop" warning.**
+  The hook's return shape was a fresh object literal on every render,
+  which `useSyncExternalStore` (via Zustand's `useStore`) interpreted
+  as a changed snapshot. Wrapping the return in `useMemo` keyed on
+  `[items, listState, fetchNextPage, doFetch]` stabilises the
+  identity. `items` was already identity-stable via the
+  `useShallow(itemsSelector)` call on the `useStore` read; this fix
+  closes the gap for the outer shape consumers depend on (e.g. hook
+  composition chains like `useTeam` → `useQuickStats` → widget).
+  See [pmndrs/zustand discussion #1936](https://github.com/pmndrs/zustand/discussions/1936)
+  and [React's `useSyncExternalStore` docs](https://react.dev/reference/react/useSyncExternalStore)
+  for the contract being honoured.
+- Downstream effect: consumers stuck at first commit because of the
+  warning-loop guard now hydrate normally, so Tier-A and hybrid list
+  views render data on first paint instead of showing perpetual
+  loading skeletons.
+
+---
+
+## [1.3.0] — 2026-05-23
+
+Upstream features driven by the `hotseaters-pglite-port` phase — every
+consumer of the library benefits from these primitives, but the focal use
+case is a tenant-scoped, PGlite-backed local-first React app talking to a
+self-hosted Supabase + ElectricSQL stack.
+
+### Added
+
+- **`createPGlitePersistenceAdapter(pglite, options?)`** in
+  `src/adapters/pglite-persistence.ts` — a `GraphPersistenceAdapter` that
+  stores the local-first runtime's graph snapshot in a PGlite table
+  (`_graph_snapshot` by default), instead of `localStorage`/`IndexedDB`.
+- **`createTenantScopedElectricAdapter(opts)`** in
+  `src/adapters/electricsql-tenant.ts` — Electric adapter wrapper that
+  refuses to attach a shape unless it declares a `tenantColumn` (string or
+  explicit `null` for the tenant root). Builds the `WHERE` clause from a
+  validated `{ companyId }` claim so shape predicates can never widen past
+  RLS by accident. Implements RULE 5 (shape predicates ⊆ RLS) and the
+  auth-claim-aware shape registration helper (Change 13 item 11).
+- **`registerEntityFromSql({ entityType, createTableSql, overrides })`** in
+  `src/schema-from-sql.ts` — generates and registers a JSON Schema directly
+  from a Postgres `CREATE TABLE` block, removing the need to hand-maintain
+  TypeScript schema duplicates.
+- **`useEntityListAsTable(opts)`** in `src/table/use-entity-list-as-table.ts`
+  — wraps `useEntityList` and returns a referentially-stable `data` array
+  suitable for TanStack Table's `data` prop. Does not pull
+  `@tanstack/react-table` as a dep.
+- **Retry-with-backoff replay** for pending offline actions in
+  `startLocalFirstGraph(...)` via a new `retryPolicy` option
+  (`{ maxAttempts, initialDelayMs, maxDelayMs, backoffFactor, jitter, poisonHandler }`).
+  Exhausted actions go to a poison handler instead of looping forever.
+
+### Notes
+
+- No new runtime dependencies. PGlite and ElectricSQL are still consumed
+  through minimal structural types, exactly like the existing
+  `adapters/electricsql.ts`.
+- Backward compatible: every existing export remains. Consumers can adopt
+  the new APIs incrementally.
+
+---
+
 ## [1.2.0] — 2026-04-05
 
 PWA/local-first and schema-driven entity release focused on dynamic JSON-column UI, markdown-aware rendering, and IPC-safe graph persistence.

package/README.md

@@ -99,6 +99,45 @@ Data flows **up** into the graph; UI reads **down** through hooks (see [Architec
 
 ---
 
+## 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
+
+| API | File | Purpose |
+|-----|------|---------|
+| `createPGlitePersistenceAdapter(pglite, options?)` | `src/adapters/pglite-persistence.ts` | `GraphPersistenceAdapter` that stores the snapshot in a PGlite table (`_graph_snapshot` by default) |
+| `createTenantScopedElectricAdapter(opts)` | `src/adapters/electricsql-tenant.ts` | Refuses to attach Electric shapes that lack a `tenantColumn`; builds the `WHERE` from a validated `{ companyId }` claim so shape predicates can never widen past RLS |
+| `registerEntityFromSql({ entityType, createTableSql, overrides })` | `src/schema-from-sql.ts` | Generates and registers a JSON Schema directly from a Postgres `CREATE TABLE` block — no hand-maintained TypeScript schema duplicates |
+| `useEntityListAsTable(opts)` | `src/table/use-entity-list-as-table.ts` | Wraps `useEntityList` for TanStack Table — returns a referentially-stable `data` array and `rowCount`; no TanStack Table dep required |
+| `startLocalFirstGraph({ ..., retryPolicy })` | `src/local-first-runtime.ts` | Retry-with-backoff for pending offline action replay; exhausted actions go to an opt-in `poisonHandler` instead of looping forever |
+
+### 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:
@@ -183,6 +222,7 @@ Compare against peers only when measurement methodology matches (minified vs unm
 | Export | Description |
 |--------|-------------|
 | `registerEntityJsonSchema` / `registerRuntimeSchema` | Register static or runtime-generated JSON Schemas for an entity type or JSON column. |
+| `registerEntityFromSql` | Generate and register a JSON Schema from a Postgres `CREATE TABLE` block — eliminates hand-maintained TypeScript schema duplicates. |
 | `getEntityJsonSchema` | Resolve the active schema by entity type, schema id, or field. |
 | `buildEntityFieldsFromSchema` | Generate entity field descriptors from JSON Schema for dynamic forms and detail views. |
 | `useSchemaEntityFields` | Hook that resolves a registered schema and returns generated field descriptors. |
@@ -193,19 +233,23 @@ Compare against peers only when measurement methodology matches (minified vs unm
 
 | Export | Description |
 |--------|-------------|
-| `startLocalFirstGraph` | Starts a higher-level local-first runtime for graph hydration, persistence, action replay, and sync status. |
+| `startLocalFirstGraph` | Starts a higher-level local-first runtime for graph hydration, persistence, action replay, and sync status. Accepts optional `retryPolicy` for offline action replay. |
 | `hydrateGraphFromStorage` | Restore graph state from a storage adapter using a JSON-serializable snapshot payload. |
 | `persistGraphToStorage` | Persist graph state and pending action metadata through a storage adapter. |
 | `useGraphSyncStatus` | Hook exposing online/offline/hydrating/syncing/ready state for PWAs and IPC-safe hosts. |
+| `replayActionWithRetry` | Replay a single pending action with configurable exponential-backoff retry. |
+| `createPGlitePersistenceAdapter` | PGlite-backed `GraphPersistenceAdapter`; stores the snapshot in a PGlite table alongside synced data. |
 
 ### Hooks (REST-oriented)
 
 | Export | Description |
 |--------|-------------|
-| `useEntity` | Subscribe to one entity; fetch/normalize into graph; SWR + subscriber-aware refetch. |
-| `useEntityList` | Subscribe to a list query key; stores IDs; merges row data from graph. |
+| `useEntity` | Subscribe to one entity; fetch/normalize into graph; SWR + subscriber-aware refetch. Returns `{ data, isLoading, isError, error, refetch }`. |
+| `useEntityList` | Subscribe to a list query key; stores IDs; merges row data from graph. Returns `{ items, isLoading, isError, error, isFetching, fetchNextPage, refetch }`. |
+| `useEntityView` | Filter/sort/search with local/remote/hybrid completeness modes. Returns `{ items, isLoading, isError, error, setFilter, setSort, setSearch }`. |
 | `useEntityMutation` | Mutate with optional optimistic updates and list invalidation hooks. |
 | `useEntityAugment` | Patch UI-only fields merged at read time across all subscribers. |
+| `useEntityListAsTable` | Wraps `useEntityList` with a referentially-stable `data` array + `rowCount` for TanStack Table. |
 | `useSuspenseEntity` | Suspense variant of `useEntity` (non-null `id` required). |
 | `useSuspenseEntityList` | Suspense variant of `useEntityList`. |
 
@@ -213,7 +257,6 @@ Compare against peers only when measurement methodology matches (minified vs unm
 
 | Export | Description |
 |--------|-------------|
-| `useEntityView` | Filter/sort/search with `local` / `remote` / `hybrid` completeness modes. |
 | `FilterSpec`, `SortSpec` | Transport-agnostic filter and sort AST types. |
 | `toRestParams` | Compile view → REST query params. |
 | `toSQLClauses` | Compile view → SQL-style WHERE / ORDER BY fragments. |
@@ -259,11 +302,12 @@ Compare against peers only when measurement methodology matches (minified vs unm
 | `prismaRelationsToSchema` | Convert Prisma-style relation map → `EntitySchema` for `registerSchema`. |
 | `toPrismaInclude` | Build an `include` map from relation descriptors. |
 
-### Local-first
+### Local-first adapters
 
 | Export | Description |
 |--------|-------------|
-| `createElectricAdapter` | ElectricSQL / PGlite changes → graph. |
+| `createElectricAdapter` | ElectricSQL / PGlite shape changes → graph. |
+| `createTenantScopedElectricAdapter` | Safety wrapper: refuses to attach a shape unless it declares a `tenantColumn`; builds the `WHERE` clause from a validated `{ companyId }` claim. |
 | `useLocalFirst` | Hook for local-first workflows with the adapter. |
 | `usePGliteQuery` | Run queries against PGlite in sync with the graph story. |
 
@@ -337,6 +381,41 @@ const { items, isLoading } = useEntityList<Post, Post>({
 
 **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**
+
+```tsx
+const { data = [] } = useQuery<Post[]>({
+  queryKey: ["posts"],
+  queryFn: () => api.posts.list(),
+});
+const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+```
+
+**After**
+
+```tsx
+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() });
+```
+
+**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**