rxfy-react 0.2.0 → 1.0.0

package/README.md

@@ -1,36 +1,406 @@
 # rxfy-react
 
-`rxfy-react` — official bindings of `rxfy` for `react`
+`rxfy-react` is the official React bindings for [`rxfy`](../rxfy/README.md). Subscribe React components to normalized entities; each renders the one shared copy and updates live.
 
-# install
+## Install
 
-`pnpm install rxfy-react`
+```bash
+npm install rxfy rxfy-react
+# or: pnpm add rxfy rxfy-react
+```
+
+## Peer dependencies
+
+```json
+{
+  "@types/react": "^18.0.0 || ^19.0.0",
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0",
+  "rxfy": "*",
+  "lodash": "^4.0.0",
+  "next": ">=14"
+}
+```
+
+`next` is **optional**; only needed for the `rxfy-react/next` subpath (Next.js App Router streaming).
+
+---
+
+## Setup
+
+Wrap your app (or the relevant subtree) with `StoreProvider`. This creates the model registry that `useStateData` and `useModelStore` write to and read from.
+
+```tsx
+import { StoreProvider } from "rxfy-react";
+import { createRoot } from "react-dom/client";
+
+createRoot(document.getElementById("root")!).render(
+  <StoreProvider>
+    <App />
+  </StoreProvider>,
+);
+```
+
+**Signature:**
+
+```ts
+function StoreProvider(props: PropsWithChildren<{
+  ssr?: boolean;                    // enables server-side fetch-and-suspend in useStateData
+  registry?: IModelRegistry;        // per-request registry created by server code (for dehydrate)
+  dehydratedState?: DehydratedState; // snapshot for custom transports; usually unnecessary, see below
+}>): JSX.Element
+```
+
+All three props exist for [SSR](#server-side-rendering); a plain client-only app uses none of them. On the client the provider automatically ingests `window.__RXFY_SSR__` chunks: both the snapshot injected by `hydrationScript` and the streamed pushes from `<HydrationStream />`, including chunks arriving after hydration starts. `dehydratedState` is only needed when the snapshot travels by some other channel (a framework loader, tests).
+
+---
+
+## High-level hooks
+
+### `useStateData`
+
+Fetches data, normalizes entities into model stores, and returns a `StateHandle`. **`data$` emits the normalized query shape: entity ids, not entities** (`array` fields → `string[]`, `single` fields → `string`). Render lists by id and read entity data through [`useModelStore`](#usemodelstore); that's the only place entity values live, so a stale read is impossible by construction.
+
+`fetchFn` returns the full fetch shape (entities) and receives an `AbortSignal` that fires on cleanup. `mutations` and `set` also operate on full entities: rxfy denormalizes the current ids into the freshest store values, runs your reducer, and normalizes the result back, so one call updates both membership and entity data.
+
+```tsx
+import { useMemo, useState } from "react";
+import { useStateData, useModelStore, Pending } from "rxfy-react";
+import { todosState, fetchTodos, TodoModel } from "./todos";
+
+function TodoApp() {
+  const [filter, setFilter] = useState<"all" | "active" | "done">("all");
+  const params = useMemo(() => ({ filter }), [filter]);
+
+  const { data$, mutations, reload } = useStateData(todosState, fetchTodos, params);
+
+  return (
+    <Pending value$={data$} pending={<p>Loading...</p>}>
+      {({ todos }) => (
+        <>
+          <ul>{todos.map((id) => <TodoItem key={id} id={id} />)}</ul>
+          <button onClick={() => mutations.addTodo({ id: crypto.randomUUID(), title: "new", done: false })}>
+            Add
+          </button>
+          <button onClick={reload}>Reload</button>
+        </>
+      )}
+    </Pending>
+  );
+}
+
+function TodoItem({ id }: { id: string }) {
+  const store = useModelStore(TodoModel);
+  const todo$ = useMemo(() => store.get(id), [store, id]);
+  return <Pending value$={todo$}>{(todo) => <li>{todo.title}</li>}</Pending>;
+}
+```
+
+**Signature:**
+
+```ts
+function useStateData<TParams, TShape, TMutations>(
+  state: StateDescriptor<TParams, TShape, TMutations>,
+  fetchFn: (params: TParams, signal: AbortSignal) => Promise<TShape>,
+  params: TParams,
+): StateHandle<TShape, TMutations>
 
-# api
+// StateHandle<TShape, TMutations>: {
+//   data$: Observable<QueryShapeOf<TShape>>;  // ids only
+//   set: (value: TShape | ((prev: TShape) => TShape)) => void;  // full entities
+//   reload: () => void;
+//   mutations: BoundMutations<TShape, TMutations>;  // full entities
+// }
+```
+
+**Caching semantics** (states with a `key`): results, mutations, and `set` write through to the registry's query cache, so a remount with the same params starts from the cached ids without re-fetching, while entity values always come live from model stores (a websocket-style `store.set` between mounts is never clobbered). `reload()` deletes the cache entry and re-fetches. Keyless states skip the cache entirely and fetch per mount.
+
+**During SSR** (inside `<StoreProvider ssr>` on the server): a cache miss calls `fetchFn` and suspends until it settles; concurrent components with the same key share one fetch. Rejections are captured and hydrate as rejected state; `<Pending rejected>` renders them with a working retry. See [Server-side rendering](#server-side-rendering).
+
+### `useModelStore`
+
+Returns the `ModelStore` for a model descriptor. Lets a component subscribe to a single normalized entity that was populated by `useStateData` or a direct `store.set` call, without re-fetching the full list.
+
+```tsx
+import { useMemo } from "react";
+import { useModelStore, Pending } from "rxfy-react";
+import { TodoModel } from "./models";
+
+function TodoItem({ id }: { id: string }) {
+  const store = useModelStore(TodoModel);
+  const todo$ = useMemo(() => store.get(id), [store, id]);
+
+  return (
+    <Pending value$={todo$}>
+      {(todo) => <li>{todo.title}</li>}
+    </Pending>
+  );
+}
+```
+
+**Signature:**
+
+```ts
+function useModelStore<T>(descriptor: ModelDescriptor<T>): ModelStore<T>
+// ModelStore<T>: {
+//   get(key: string): Observable<T>;        // reactive read; emits on every change
+//   set(key, val): void;
+//   setMany(items): void;
+//   getValue(key: string): T | undefined;   // synchronous read
+//   entity(key: string): IAtom<T>;          // writable handle over one entity's cell
+//   valueEntries(): [string, T][];
+//   added$: Observable<string>;             // a key, the first time its entity appears
+// }
+```
+
+> **Note:** `store.get(id)` returns an Observable that never emits until `set` or `setMany` is called for that key. It stays in pending state until data arrives, typically populated by a `useStateData` call that includes this model in its `model` field.
 
-- useEdge — use edge state
-- <Edge /> — useEdge wrapped with render props pattern
+### `useAtom`
 
-# example
+Binds any `IAtom<T>` (a plain `Atom`, a field `Lens`, or a `ModelStore.entity(id)` handle) to React as `[value, setValue]`. Paired with `store.entity(id)` and `keyLens`, it gives two-way form binding that stays in sync across every component subscribed to that entity: typing writes through the field `Lens` into the entity cell, so the edit reaches the list row, the detail header, and any other subscriber with no re-fetch.
 
 ```tsx
-import PQueue from "p-queue";
 import { useMemo } from "react";
-import { of } from "rxjs";
-import { createAtom, createState, createStore } from "rxfy";
-import { Edge } from "rxfy-react";
+import { createLens, keyLens } from "rxfy";
+import { useAtom, useModelStore } from "rxfy-react";
+import { TodoModel } from "./models";
+
+function EditTitle({ id }: { id: string }) {
+  const store = useModelStore(TodoModel);
+  const todo$ = useMemo(() => store.entity(id), [store, id]); // IAtom<Todo>
+  const title$ = useMemo(() => createLens(todo$, keyLens("title")), [todo$]);
+  const [title, setTitle] = useAtom(title$);
+
+  return <input value={title} onChange={(e) => setTitle(e.target.value)} />;
+}
+```
+
+**Signature:**
+
+```ts
+function useAtom<T>(atom$: IAtom<T>): [T, (value: T) => void]
+```
+
+> `atom$` must be referentially stable across renders; wrap `store.entity(id)` and the `Lens` in `useMemo` as above. `store.entity(id)` assumes the entity is already loaded.
+
+---
+
+## Rendering helpers
+
+### `Pending`
+
+Subscribes to any `ObservableLike<T>` and renders the appropriate UI for pending, rejected, or fulfilled state. The `rejected` render prop receives the rejected `IWrapped` (`{ type, error }`). If `rejected` is not provided, it defaults to rendering nothing and logging the error to `console.error`.
+
+Reload is not carried on the status object: get it from the `useStateData` handle's `reload()` (or `getAttachedReload(source$)` from `rxfy` for a standalone observable).
+
+```tsx
+import { Pending, useStateData } from "rxfy-react";
+
+const { data$, reload } = useStateData(todosState, fetchTodos, params);
+
+<Pending
+  value$={data$}
+  pending={<p>Loading...</p>}
+  rejected={({ error }) => (
+    <p>
+      Error: {String(error)} <button onClick={reload}>Retry</button>
+    </p>
+  )}
+>
+  {(value) => <div>{JSON.stringify(value)}</div>}
+</Pending>
+```
+
+**Signature:**
+
+```tsx
+function Pending<T>(props: {
+  value$: ObservableLike<T>;
+  pending?: IRenderable<void>;
+  rejected?: IRenderable<IWrapped<T, StatusEnum.REJECTED>>;  // { type, error }
+  children: IRenderable<T>;
+  getDefaultValue?: () => T;
+}): JSX.Element
+
+// IRenderable<T> = React.ReactNode | ((data: T) => React.ReactNode)
+// ObservableLike<T> = Observable<T> | T
+```
+
+---
+
+## Low-level hooks
+
+### `usePending`
+
+Tracks any `ObservableLike<T>` and returns the current [`IWrapped<T>`](../rxfy/README.md), narrowed to `PENDING` / `FULFILLED` / `REJECTED` (never `IDLE`). This is the hook powering `<Pending>`. Narrow on `type` to read `value` (only on `FULFILLED`) or `error` (only on `REJECTED`). Pass `getDefaultValue` to start `FULFILLED` instead of `PENDING`.
+
+```ts
+import { usePending } from "rxfy-react";
+import { StatusEnum } from "rxfy";
+
+const wrapped = usePending(data$);
+if (wrapped.type === StatusEnum.PENDING) return <span>…</span>;
+if (wrapped.type === StatusEnum.REJECTED) return <span>error</span>;
+return <span>{JSON.stringify(wrapped.value)}</span>;
+```
+
+**Signature:**
+
+```ts
+function usePending<T>(
+  source$: ObservableLike<T>,
+  getDefaultValue?: () => T,
+): IWrapped<T, StatusEnum.PENDING | StatusEnum.FULFILLED | StatusEnum.REJECTED>
+```
+
+> **Reload** is not part of the status object; trigger it via the `useStateData` handle's `reload()` or `getAttachedReload(source$)` from `rxfy`.
+>
+> **Contract:** `source$` must be referentially stable across renders (memoize it; `data$` from `useStateData` already is). A new identity restarts the pipeline from `PENDING`; an observable created inline in render restarts every render and never settles.
+
+### `useObservable`
+
+Low-level hook that subscribes to any `Observable<T>` via `useSyncExternalStore`.
+
+```ts
+import { useObservable } from "rxfy-react";
+
+const value = useObservable(observable$, defaultValue);
+const maybeValue = useObservable(observable$); // T | undefined
+```
+
+**Signature:**
+
+```ts
+function useObservable<T>(observable: Observable<T>, initialValue: T): T
+function useObservable<T>(observable: Observable<T>): T | undefined
+```
+
+Emissions that are deep-equal (`lodash.isEqual`) to the current value are skipped; re-emitting an identical value does not re-render.
+
+---
+
+## Context / registry internals
+
+`ModelRegistryContext` and `useModelRegistry` expose the underlying React context. Use them directly only when building a custom provider or accessing the registry outside `StoreProvider`.
+
+```tsx
+import { ModelRegistryContext, useModelRegistry } from "rxfy-react";
+import { createModelRegistry } from "rxfy";
+
+// custom provider
+const registry = createModelRegistry();
+<ModelRegistryContext.Provider value={registry}>
+  <App />
+</ModelRegistryContext.Provider>
+
+// inside any child; throws if no provider is found above
+const registry = useModelRegistry();
+```
+
+**Signatures:**
 
-const queue = new PQueue({ concurrency: 5 });
-const state = createAtom(createState({}));
-const store = createStore(queue, state);
-const userStore = store.factory("users", (id) => of({ id }));
+```ts
+const ModelRegistryContext: React.Context<IModelRegistry | null>
+function useModelRegistry(): IModelRegistry
+```
+
+---
+
+## Server-side rendering
+
+SSR is on-demand: there is no prefetch API. Components declare their data with `useStateData` exactly as on the client; on the server (`<StoreProvider ssr>`) a cache miss suspends until the fetch settles. Results (fulfilled or rejected) are captured in the registry, serialized into the HTML, and ingested on the client so the first paint is already fulfilled: no loading flash, no re-fetch, no hydration mismatch.
+
+Requirements: give models a `name` and states a `key` (stable string identities), and write `fetchFn` to work in both environments (it runs on the server during SSR and on the client for reloads).
+
+### Buffered mode (any Node server)
+
+Wait for every Suspense boundary with `onAllReady`, then send the complete document. This is the recommended non-Next mode; [examples/vite-todo](../../examples/vite-todo) runs it end to end.
+
+```tsx
+// server
+import { renderToPipeableStream } from "react-dom/server";
+import { createModelRegistry, dehydrate, hydrationScript } from "rxfy";
+import { StoreProvider } from "rxfy-react";
+
+function render(): Promise<{ html: string; state: string }> {
+  const registry = createModelRegistry(); // one per request
+  return new Promise((resolve, reject) => {
+    const { pipe } = renderToPipeableStream(
+      <StoreProvider registry={registry} ssr><App /></StoreProvider>,
+      {
+        onAllReady() {
+          // collect the stream into a string, then:
+          // resolve({ html, state: hydrationScript(dehydrate(registry)) });
+        },
+        onError: reject,
+      },
+    );
+  });
+}
+
+// template: <div id="root"><!--app-html--></div><!--app-state-->
+// inject:   template.replace("<!--app-state-->", state)
+```
+
+```tsx
+// client: StoreProvider picks the snapshot up from the injected script automatically
+import { hydrateRoot } from "react-dom/client";
+
+hydrateRoot(
+  document.getElementById("root")!,
+  <StoreProvider ssr><App /></StoreProvider>,
+);
+```
+
+### Streaming mode (Next.js App Router)
 
-export function User({ userId }: { userId: string }) {
-  const user = useMemo(() => userStore.get(userId), [userId]);
+`rxfy-react/next` ships `<HydrationStream />`: on each stream flush it emits newly settled queries and newly written entities as `window.__RXFY_SSR__.push(...)` script tags; the client `StoreProvider` ingests them, including chunks arriving after hydration starts.
+
+```tsx
+// app/providers.tsx
+"use client";
+import { StoreProvider } from "rxfy-react";
+import { HydrationStream } from "rxfy-react/next";
+
+export function Providers({ children }: { children: React.ReactNode }) {
   return (
-    <Edge edge={user} pending={<span>Loading..</span>} rejected={(err) => <span>{JSON.stringify(err)}</span>}>
-      {(user) => <div key={user.id}>{user.id}</div>}
-    </Edge>
+    <StoreProvider ssr>
+      <HydrationStream />
+      {children}
+    </StoreProvider>
   );
 }
 ```
+
+`next` is an optional peer dependency; only this subpath needs it.
+
+### Two-pass mode (strict `renderToString`)
+
+For environments without React stream APIs, `collectStateData` loops render passes until nothing suspends (the `getDataFromTree` pattern; each fetch waterfall level costs one extra pass):
+
+```ts
+import { renderToString } from "react-dom/server";
+import { collectStateData } from "rxfy-react";
+
+const html = await collectStateData(registry, () =>
+  renderToString(<StoreProvider registry={registry} ssr><App /></StoreProvider>),
+);
+const state = hydrationScript(dehydrate(registry));
+```
+
+**Signature:**
+
+```ts
+function collectStateData(registry: IModelRegistry, render: () => string): Promise<string>
+```
+
+### Error handling
+
+A `fetchFn` rejection on the server is captured as a serialized rejected entry (`{ name, message }`, stack stripped) and hydrates as rejected state: the server HTML shows your `<Pending rejected>` UI, and the handle's `reload()` retries client-side with a real fetch.
+
+---
+
+## See also
+
+- [rxfy: Core API](../rxfy/README.md)
+- [examples/vite-todo](../../examples/vite-todo): full working example with buffered SSR and URL-driven state

package/dist/chunk-BO3M5NLW.js

@@ -0,0 +1,42 @@
+"use client";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/registry-context.ts
+import { createContext, useContext } from "react";
+var ModelRegistryContext = createContext(null);
+function useModelRegistry() {
+  const ctx = useContext(ModelRegistryContext);
+  if (!ctx) throw new Error("StoreProvider not found");
+  return ctx;
+}
+
+export {
+  __commonJS,
+  __toESM,
+  ModelRegistryContext,
+  useModelRegistry
+};