@prometheus-ags/entity-graph-solid 3.0.0-alpha.0

package/README.md

@@ -0,0 +1,192 @@
+# @prometheus-ags/entity-graph-solid
+
+SolidJS bindings for `@prometheus-ags/entity-graph-core` — fine-grained reactive entity and list primitives backed by the normalized entity graph.
+
+## Architecture
+
+```
+Component (SolidJS)
+  └─ createEntity / createEntityList  (this package, Layer 2)
+       └─ core engine fetchEntity / fetchList  (entity-graph-core, Layer 1)
+            └─ useGraphStore (Zustand, Layer 0)
+```
+
+Components access data only through `createEntity` / `createEntityList`. The store (Zustand) is the single source of truth; SolidJS signals mirror it for fine-grained reactivity.
+
+## Installation
+
+```bash
+pnpm add @prometheus-ags/entity-graph-solid @prometheus-ags/entity-graph-core solid-js
+```
+
+## Quick Start
+
+### 1. Configure the engine once at app boot
+
+```ts
+// src/index.tsx
+import { setupGraphProvider } from "@prometheus-ags/entity-graph-solid";
+import { registerEntityTransport, makeRestTransport } from "@prometheus-ags/entity-graph-core";
+
+// Register transports at startup — one per entity type.
+registerEntityTransport("Invoice", makeRestTransport({ baseUrl: "/api" }));
+
+// Wire focus/reconnect listeners and GC.
+const cleanup = setupGraphProvider({ staleTime: 60_000 });
+```
+
+### 2. Fetch a single entity
+
+```tsx
+import { createEntity } from "@prometheus-ags/entity-graph-solid";
+import { createSignal, Show } from "solid-js";
+
+interface Invoice {
+  id: string;
+  amount: number;
+  status: "draft" | "paid";
+}
+
+function InvoiceDetail(props: { id: string }) {
+  const invoice = createEntity<{ id: string; amount: number; status: string }, Invoice>({
+    type: "Invoice",
+    id: () => props.id,
+    fetch: (id) => fetch(`/api/invoices/${id}`).then((r) => r.json()),
+    normalize: (raw) => ({ id: raw.id, amount: raw.amount, status: raw.status as Invoice["status"] }),
+  });
+
+  return (
+    <Show when={!invoice.isLoading()} fallback={<p>Loading…</p>}>
+      <Show when={invoice.data()} fallback={<p>Not found</p>}>
+        {(inv) => (
+          <div>
+            <h1>Invoice #{inv().id}</h1>
+            <p>Amount: ${inv().amount}</p>
+            <p>Status: {inv().status}</p>
+          </div>
+        )}
+      </Show>
+    </Show>
+  );
+}
+```
+
+### 3. Fetch a reactive list
+
+```tsx
+import { createEntityList } from "@prometheus-ags/entity-graph-solid";
+import { createSignal, For, Show } from "solid-js";
+
+function InvoiceList() {
+  const [status, setStatus] = createSignal<string>("all");
+
+  const invoices = createEntityList<{ id: string; amount: number }, Invoice>({
+    type: "Invoice",
+    queryKey: () => ["invoices", { status: status() }],
+    fetch: ({ cursor, params }) =>
+      fetch(`/api/invoices?cursor=${cursor ?? ""}&status=${params?.status ?? "all"}`)
+        .then((r) => r.json()),
+    normalize: (raw) => ({
+      id: raw.id,
+      data: { id: raw.id, amount: raw.amount, status: "draft" },
+    }),
+  });
+
+  return (
+    <div>
+      <button onClick={() => setStatus("paid")}>Show paid</button>
+      <Show when={invoices.isLoading()}>
+        <p>Loading…</p>
+      </Show>
+      <For each={invoices.items()}>
+        {(inv) => <div>{inv.id} — ${inv.amount}</div>}
+      </For>
+      <Show when={invoices.hasNextPage()}>
+        <button
+          onClick={() => invoices.fetchNextPage()}
+          disabled={invoices.isLoadingMore()}
+        >
+          Load more
+        </button>
+      </Show>
+    </div>
+  );
+}
+```
+
+### 4. Ad-hoc graph slice
+
+```ts
+import { createGraphStore } from "@prometheus-ags/entity-graph-solid";
+
+// Fine-grained accessor for any graph slice.
+const invoiceCount = createGraphStore(
+  (s) => Object.keys(s.entities["Invoice"] ?? {}).length,
+);
+
+console.log(invoiceCount()); // reactive SolidJS signal
+```
+
+## API Reference
+
+### `createEntity(opts)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type` | `string` | Entity kind (graph partition key). |
+| `id` | `() => string \| null` | Reactive id accessor. |
+| `fetch` | `(id) => Promise<TRaw>` | Transport fetch function. |
+| `normalize` | `(raw) => TEntity` | Maps raw response to canonical shape. |
+| `idField` | `string` | Id field name in normalized entity (default `"id"`). |
+| `staleTime` | `number` | Cache freshness in ms. |
+| `enabled` | `() => boolean` | Gate fetching. |
+| `onSuccess` | `(entity) => void` | Called after successful graph write. |
+| `onError` | `(error) => void` | Called after all retries fail. |
+
+**Returns** `{ data, isLoading, isRefetching, error, typedError, refetch, entityState }`
+
+### `createEntityList(opts)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type` | `string` | Entity kind. |
+| `queryKey` | `() => unknown[]` | Reactive list cache key. |
+| `fetch` | `(params) => Promise<ListResult>` | Transport fetcher. |
+| `normalize` | `(raw) => { id, data }` | Per-row normalizer. |
+| `mode` | `"replace" \| "append"` | Replace list or append (infinite scroll). |
+| `staleTime` | `number` | Cache freshness in ms. |
+| `enabled` | `() => boolean` | Gate fetching. |
+
+**Returns** `{ items, isLoading, isLoadingMore, error, typedError, total, hasNextPage, hasPrevPage, fetchNextPage, refetch, listState }`
+
+### `createGraphStore(selector, equalityFn?)`
+
+Returns a fine-grained SolidJS accessor that updates when the selected graph slice changes.
+
+### `setupGraphProvider(opts?)`
+
+Configures the engine and attaches browser listeners. Call once at app startup. Returns a cleanup function.
+
+## Error Handling
+
+```tsx
+import { TerminalError, TransientError } from "@prometheus-ags/entity-graph-solid";
+
+const invoice = createEntity({ ... });
+
+// String error (always available):
+<Show when={invoice.error()}><p>Error: {invoice.error()}</p></Show>
+
+// Typed error (list variant):
+const list = createEntityList({ ... });
+const err = list.typedError();
+if (err instanceof TerminalError) {
+  // 4xx — do not offer a retry button
+} else if (err instanceof TransientError) {
+  // 5xx / network — show retry button
+}
+```
+
+## License
+
+MIT

package/dist/index.d.cts

@@ -0,0 +1,304 @@
+import { EntityType, EntityId, EntityError, ListState, EntityState, GraphState, EngineOptions } from '@prometheus-ags/entity-graph-core';
+export { EntityError, EntityId, EntityState, EntityType, FilterSpec, ListState, SortSpec, TerminalError, TransientError, ViewDescriptor, useGraphStore } from '@prometheus-ags/entity-graph-core';
+
+/**
+ * Shared option types for SolidJS entity-graph bindings.
+ *
+ * These mirror the engine option shapes from @prometheus-ags/entity-graph-core
+ * but are scoped to accessor patterns (no React-specific concepts).
+ */
+
+/**
+ * Options for `createEntity`. The `source` accessor is called reactively;
+ * changing either `type` or `id` inside it re-triggers the fetch.
+ *
+ * @template TRaw - Shape returned by the transport fetch function.
+ * @template TEntity - Normalized entity shape written to the graph.
+ */
+interface CreateEntityOptions<TRaw, TEntity extends object> {
+    /** Entity kind (e.g. `"Invoice"`). Drives the graph partition. */
+    type: EntityType;
+    /** Reactive accessor returning the entity id — return `null` / `undefined` to disable. */
+    id: () => EntityId | null | undefined;
+    /**
+     * Transport fetch function. Receives the resolved `id` and returns raw data.
+     * Called by the underlying `createResource`; deduplicated by the core engine.
+     */
+    fetch: (id: EntityId) => Promise<TRaw>;
+    /** Maps raw API response to the canonical shape upserted into the graph. */
+    normalize: (raw: TRaw) => TEntity;
+    /**
+     * Name of the id field inside the normalized entity (default `"id"`).
+     * Used when the server-returned id may differ from the request id.
+     */
+    idField?: string;
+    /**
+     * Milliseconds before a cached entity is considered stale and a background
+     * refetch is triggered (inherits from `configureEngine` when omitted).
+     */
+    staleTime?: number;
+    /** Set to `false` to skip fetching regardless of id presence (default `true`). */
+    enabled?: () => boolean;
+    /** Called after a successful fetch and graph write. */
+    onSuccess?: (entity: TEntity) => void;
+    /** Called after all retries are exhausted. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Options for `createEntityList`. The `queryKey` accessor is called reactively;
+ * changing the key triggers a new list fetch.
+ *
+ * @template TRaw - Shape of each raw row from the transport.
+ * @template TEntity - Normalized entity shape written to the graph.
+ */
+interface CreateEntityListOptions<TRaw, TEntity extends object> {
+    /** Entity kind for all items in this list. */
+    type: EntityType;
+    /**
+     * Reactive accessor returning the list query key array.
+     * Changing any element triggers a re-fetch. Use stable primitive values.
+     */
+    queryKey: () => unknown[];
+    /**
+     * Transport fetcher for the full list. Optional for graph-only (e.g. local-first
+     * PGlite) scenarios where the graph is hydrated out-of-band.
+     */
+    fetch?: (params: {
+        cursor?: string;
+        page?: number;
+        pageSize?: number;
+        params?: Record<string, unknown>;
+    }) => Promise<{
+        items: TRaw[];
+        total?: number | null;
+        nextCursor?: string | null;
+        prevCursor?: string;
+        hasNextPage?: boolean;
+        hasPrevPage?: boolean;
+        page?: number;
+        pageSize?: number;
+    }>;
+    /** Row normalizer: maps a raw row to `{ id, data }` for graph upsert. */
+    normalize?: (raw: TRaw) => {
+        id: EntityId;
+        data: TEntity;
+    };
+    /** Replace or append ids on re-fetch (default `"replace"`). */
+    mode?: "replace" | "append";
+    /** Milliseconds before the list is re-fetched in the background. */
+    staleTime?: number;
+    /** Reactive accessor; set to `false` to pause fetching (default `true`). */
+    enabled?: () => boolean;
+    /** Called after a successful list fetch. */
+    onSuccess?: (result: {
+        items: TRaw[];
+        total?: number | null;
+    }) => void;
+    /** Called after all retries are exhausted. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return value of `createEntity`.
+ * All fields are SolidJS signals (fine-grained, no re-render of unrelated parts).
+ */
+interface CreateEntityReturn<TEntity extends object> {
+    /** The merged entity (canonical + patch overlay) or `null` when not yet loaded. */
+    data: () => TEntity | null;
+    /** `true` while the initial or background fetch is in-flight. */
+    isLoading: () => boolean;
+    /** `true` only during background SWR refetch (data already present). */
+    isRefetching: () => boolean;
+    /** Per-entity fetch error string from the graph, or `null`. */
+    error: () => string | null;
+    /**
+     * Typed `EntityError` instance (`TerminalError` | `TransientError`) so
+     * consumers can `instanceof`-check the failure mode without string parsing.
+     */
+    typedError: () => EntityError | null;
+    /** Imperatively trigger a refetch, bypassing staleness checks. */
+    refetch: () => Promise<void>;
+    /** Raw `EntityState` slice for advanced use (isFetching, stale, lastFetched). */
+    entityState: () => EntityState;
+}
+/**
+ * Return value of `createEntityList`.
+ * Items are fine-grained: each row is individually reactive via SolidJS signals.
+ */
+interface CreateEntityListReturn<TEntity extends object> {
+    /** Resolved entity objects in list order (ids joined to graph at read time). */
+    items: () => TEntity[];
+    /** `true` while the initial list fetch is in-flight. */
+    isLoading: () => boolean;
+    /** `true` while a "load more" / pagination fetch is in-flight. */
+    isLoadingMore: () => boolean;
+    /** List fetch error string, or `null`. */
+    error: () => string | null;
+    /** Typed error instance for `instanceof` checks. */
+    typedError: () => EntityError | null;
+    /** Total entity count from the server (may be `null` before first fetch). */
+    total: () => number | null;
+    /** `true` when a next page is available. */
+    hasNextPage: () => boolean;
+    /** `true` when a previous page is available. */
+    hasPrevPage: () => boolean;
+    /** Fetch the next page (appends when `mode` is `"append"`). */
+    fetchNextPage: () => Promise<void>;
+    /** Refetch the list from scratch (replaces ids). */
+    refetch: () => Promise<void>;
+    /** Raw `ListState` slice for advanced pagination/meta access. */
+    listState: () => ListState;
+}
+
+/**
+ * createEntity — SolidJS primitive that bridges a single entity to the
+ * normalized entity graph via `createResource`.
+ *
+ * Architecture:
+ *   createEntity  (this file, Layer 2)
+ *     └─ core engine fetchEntity  (Layer 1 / transport)
+ *          └─ useGraphStore  (Layer 0 / Zustand graph)
+ *
+ * SolidJS `createResource` owns the async lifecycle; the graph is the
+ * single source of truth for the entity payload. Once fetchEntity writes to
+ * the graph, a Zustand subscription (via `createStore`) propagates the merged
+ * entity back to SolidJS as a fine-grained reactive signal.
+ */
+
+/**
+ * Creates a fine-grained SolidJS reactive primitive for a single entity.
+ *
+ * - Uses `createResource` as the async driver so Suspense and ErrorBoundary
+ *   boundaries work naturally.
+ * - Subscribes to the Zustand graph with `useGraphStore.subscribe` and mirrors
+ *   the merged entity into a `createStore`-backed signal for fine-grained
+ *   SolidJS reactivity (only the changed field triggers updates).
+ * - Registers / unregisters a subscriber token with the core engine so idle
+ *   entities stop background revalidation when no components are observing them.
+ *
+ * @example
+ * ```tsx
+ * const invoice = createEntity({
+ *   type: "Invoice",
+ *   id: () => props.invoiceId,
+ *   fetch: (id) => api.get(`/invoices/${id}`),
+ *   normalize: (raw) => ({ ...raw, id: raw.invoice_id }),
+ * });
+ *
+ * return (
+ *   <Show when={!invoice.isLoading()} fallback={<Spinner />}>
+ *     <p>{invoice.data()?.amount}</p>
+ *   </Show>
+ * );
+ * ```
+ */
+declare function createEntity<TRaw, TEntity extends object>(opts: CreateEntityOptions<TRaw, TEntity>): CreateEntityReturn<TEntity>;
+
+/**
+ * createEntityList — SolidJS primitive for reactive normalized entity lists.
+ *
+ * Architecture:
+ *   createEntityList  (this file, Layer 2)
+ *     └─ core engine fetchList  (Layer 1 / transport)
+ *          └─ useGraphStore  (Layer 0 / Zustand graph)
+ *
+ * A Zustand `subscribe` bridges the graph's `lists[key]` slot + entity rows
+ * into a SolidJS `createStore`, giving SolidJS fine-grained per-row reactivity.
+ * Changing `queryKey()` re-serializes to a new list slot, triggering a fresh
+ * fetch while keeping existing data visible (stale-while-revalidate).
+ */
+
+/**
+ * Creates a fine-grained SolidJS reactive primitive for an entity list.
+ *
+ * - Subscribes to `useGraphStore` to mirror list state (ids + pagination)
+ *   and resolves the entity rows by joining ids → graph entities on each read.
+ * - Changing `queryKey()` triggers a new fetch and subscribes to the new list
+ *   slot; the previous subscription is cleaned up automatically.
+ * - Supports pagination (`fetchNextPage`) and imperative refetch.
+ *
+ * @example
+ * ```tsx
+ * const invoices = createEntityList({
+ *   type: "Invoice",
+ *   queryKey: () => ["invoices", { status: filter() }],
+ *   fetch: (params) => api.getInvoices(params),
+ *   normalize: (raw) => ({ id: raw.invoice_id, data: { ...raw } }),
+ * });
+ *
+ * return (
+ *   <For each={invoices.items()}>
+ *     {(invoice) => <InvoiceRow invoice={invoice} />}
+ *   </For>
+ * );
+ * ```
+ */
+declare function createEntityList<TRaw, TEntity extends object>(opts: CreateEntityListOptions<TRaw, TEntity>): CreateEntityListReturn<TEntity>;
+
+/**
+ * createGraphStore — SolidJS fine-grained reactive bridge to the entire
+ * Zustand entity graph.
+ *
+ * Consumers that need ad-hoc access to the graph outside `createEntity` /
+ * `createEntityList` can use this to read any slice of `GraphState` as a
+ * SolidJS signal. The subscription is scoped to only the selected slice,
+ * so unrelated graph mutations do not trigger re-computations.
+ *
+ * @example
+ * ```ts
+ * // Read total entity count for a devtools panel.
+ * const entityCount = createGraphStore(
+ *   (s) => Object.keys(s.entities).reduce((n, t) => n + Object.keys(s.entities[t]).length, 0),
+ * );
+ * console.log(entityCount()); // reactive SolidJS accessor
+ * ```
+ */
+
+/**
+ * Subscribe to a selector over the entity graph.
+ * Returns a SolidJS accessor that updates whenever the selected slice changes.
+ *
+ * @param selector - Pure function that maps the full `GraphState` to a derived value.
+ * @param equalityFn - Optional equality check (default: strict reference equality `===`).
+ */
+declare function createGraphStore<T>(selector: (state: GraphState) => T, equalityFn?: (a: T, b: T) => boolean): () => T;
+
+/**
+ * GraphProvider utilities for SolidJS.
+ *
+ * Provides boot-time setup helpers for attaching global focus/reconnect
+ * listeners and configuring the engine from within a SolidJS application root.
+ *
+ * Usage in the application root (e.g. `src/index.tsx`):
+ *
+ * ```ts
+ * import { setupGraphProvider } from "@prometheus-ags/entity-graph-solid";
+ * import { configureEngine, attachGlobalListeners } from "@prometheus-ags/entity-graph-core";
+ *
+ * setupGraphProvider({
+ *   staleTime: 60_000,
+ *   revalidateOnFocus: true,
+ * });
+ * ```
+ */
+
+interface GraphProviderOptions extends EngineOptions {
+    /**
+     * Whether to attach window focus/online listeners for stale-while-revalidate.
+     * Defaults to `true` in browser environments.
+     */
+    attachListeners?: boolean;
+    /**
+     * Whether to start the periodic garbage collector.
+     * Defaults to `true`.
+     */
+    startGc?: boolean;
+}
+/**
+ * Configures the entity-graph engine and wires browser-level listeners.
+ * Call this once at application startup before mounting the root component.
+ *
+ * Returns a cleanup function that stops the GC interval (useful for tests).
+ */
+declare function setupGraphProvider(opts?: GraphProviderOptions): () => void;
+
+export { type CreateEntityListOptions, type CreateEntityListReturn, type CreateEntityOptions, type CreateEntityReturn, type GraphProviderOptions, createEntity, createEntityList, createGraphStore, setupGraphProvider };