@spfn/core 0.3.0-beta.27 → 0.3.0-beta.28

package/src/state/README.md

@@ -23,7 +23,7 @@ import { Type } from '@sinclair/typebox';   // for .key() / .value() / .data() /
 
 // browser — the router by type only
 import { createStateClient } from '@spfn/core/state/client';
-import { useServerState } from '@spfn/core/state/react';
+import { useConnectionStatus, useServerState } from '@spfn/core/state/react';
 import type { states } from '@/server/states';
 ```
 
@@ -191,7 +191,7 @@ With the default `path` `/state`:
 | `getConsentState` | `GET /state/consent` → `{ at, value, data }`. Keyed: key fields in the query, validated by the route (missing → 400) |
 | `putConsentState` | `PUT /state/consent`, only when `.write()` exists. Body = the input schema, keyed: key fields in the query. → `{ at, value, data }` |
 | `getStates` | `GET /state` → `{ at, states: { consent: { value, data }, … } }` in declaration order — one for all states of the router |
-| `states.events['state.consent.changed']` | the SSE event, payload `{ at, value, data, key?, subject? }` — `key` on a keyed state, `subject` unless shared |
+| `states.events['state.consent.changed']` | the SSE event, payload `{ at, value, data, key?, subject? }` — `key` on a keyed state, `subject` unless shared. It declares `.canSubscribe` and `.filter` from `canRead` and the key, and `.initial`: a connection it allows receives the state's current frame — one `read()` for its subject and the key in its connect query — right after `connected` |
 | `consent.changed` | the change signal, payload keyless `{ subject }`, keyed `{ ...keyFields, subject }`, shared `{ ...keyFields }` |
 
 `data` is present exactly when `.data()` is declared, in every response and frame.
@@ -240,7 +240,11 @@ Every `read()` result is checked against `{ value, data }` as declared — `data
 `.data()` is, no other field — with a schema built once per state when the router is built.
 A result that does not match fails the read, write and snapshot routes with an `Error` (500)
 naming the state and the first validation message, never the value; on the change signal it
-is logged at warn and sends nothing; `grant` rejects with the same error and sends nothing.
+is logged at warn and sends nothing; `grant` rejects with the same error and sends nothing. On
+the stream's connect it is logged at warn naming the state's event (never the error), the state
+is left out of `connected.initial` and sends no initial frame. The client's snapshot read then
+fails too — the snapshot route reads every state — so the entry keeps its last value, `onError`
+is called, and the state recovers with its next frame or the next connect.
 
 A write whose `read()` then fails — it threw or returned an undeclared result — answers 500
 and sends no frame. Without a transaction the write has already committed: there is no value
@@ -314,17 +318,15 @@ Every frame — of the write route, of the change signal and of `grant` — is s
 | Where the read ran | Frame |
 | --- | --- |
 | outside a transaction | emitted at once and awaited; an emit that throws fails the write or `grant`; on the change signal it is logged at warn and `changed.emit` resolves |
-| inside a transaction | queued with `onAfterCommit` and published after the root transaction commits; never when the root rolls back |
+| inside a transaction | queued with `onAfterCommit` and published after the root transaction commits; never when the transaction that read it, or any transaction around it, rolls back |
 
 - The frame carries the value read inside the transaction, with that read's `at`; nothing is
   read again after the commit. The response is the same snapshot.
 - So a `changed.emit` or a `grant` made inside a transaction is deferred to its commit, like a
   write.
-- The queue belongs to the root transaction: a `Transactional()` nested in an outer
-  `runInTransaction` publishes at the outer commit.
-- A nested transaction (a savepoint) that rolls back while the root commits still publishes
-  the frame read inside it, because after-commit callbacks belong to the root; emit the signal
-  from the outer transaction, or after it, when an inner one may roll back.
+- A `Transactional()` nested in an outer `runInTransaction` is a savepoint: its frame is
+  handed to the outer transaction and published at the outer commit, or dropped if the
+  handler throws.
 - A deferred emit runs outside the transaction context; an error it throws is logged by the
   transaction runner and reaches nobody.
 
@@ -430,6 +432,10 @@ write and snapshot routes, keeps one SSE stream open for every state, and decide
 only** — `import type { states }` — so no server code reaches the browser bundle;
 `@spfn/core/state/client` imports nothing from `@spfn/core/state` at runtime.
 
+A page load costs one snapshot read, and the server makes it: the server component's render,
+handed to the client as `initial`. The browser makes no snapshot `GET` of its own — the stream
+serves each allowed state's current frame on connect ([The stream](#the-stream)).
+
 ```typescript
 // src/client/state.ts
 import { createStateClient } from '@spfn/core/state/client';
@@ -480,28 +486,70 @@ of fields, goes to `onError`, and the subscription is dropped without reopening
 `write` on a state the manifest marks `write: false` rejects naming the state, before any
 request. A first snapshot that fails goes to `onError` (or rejects the call that needed it).
 While subscriptions wait on it, it is read again every `retryDelay` (default 3000 ms, the SSE
-client's `reconnectDelay`), each failure to `onError`, until it succeeds, `close()` runs, or
-nothing is subscribed; a `get`, `write` or `snapshot` that reads it first serves the waiting
-subscriptions too — whichever call brings the manifest opens the stream. `close()` while it is
+client's `reconnectDelay`), each failure to `onError`, until it succeeds, `close()` runs,
+nothing is subscribed, or `maxRetries` retries failed too (default `0`: no limit) — then the
+status is `'failed'` and no retry is set ([Connection status](#connection-status)); a `get`,
+`write` or `snapshot` that reads it first serves the waiting subscriptions too — whichever
+call brings the manifest opens the stream. `close()` while it is
 in flight discards its answer, and a `get` or `write` waiting on it rejects: the client was
 closed.
 
-### `createStateClient<typeof states>({ sse, api?, onError?, retryDelay? })`
+The manifest may also come from `initial` — the snapshot the server rendered with (below). Such a
+client knows it from construction: nothing above waits, a refused `subscribe` goes to `onError` at
+once, and the first `subscribe` opens the stream without reading the snapshot first.
+
+### `createStateClient<typeof states>({ sse, api?, onError?, retryDelay?, maxRetries?, initial? })`
+
+`initial: { snapshot, query? }` is the snapshot a server render read — `api.getStates`'s answer —
+and the query it was read with (default `{}`). The client installs its manifest and applies each
+state it holds at construction, keyed states under the query's key, so `current()` answers at once
+and the first `subscribe` opens the stream without reading the snapshot first. Nothing is marked
+`'revoked'` from it: an omission in the render's snapshot is not a denial by the stream. The
+snapshot type is the router's own — another router's does not compile — and comes from the router
+type parameter: without `<typeof states>` the client is untyped, as before. Pass what
+`api.getStates` answered, not a hand-built snapshot: one whose manifest names a state the server
+does not serve keeps the stream from opening, as the SSE handler refuses that event. A server component reads
+the snapshot and passes it, with its query, as a prop to the client component that builds the
+client:
+
+```tsx
+// app/[workspaceId]/page.tsx — a server component
+const query = { workspaceId };
+const snapshot = await api.getStates.call({ query });
+
+return <Shell initial={{ snapshot, query }} workspaceId={workspaceId} />;
+```
+
+```tsx
+'use client';
+import type { StateClientInitial } from '@spfn/core/state/client';
+
+export function Shell({ initial, workspaceId }: { initial: StateClientInitial<typeof states>; workspaceId: string })
+{
+    const [state] = useState(() => createStateClient<typeof states>({ sse: createAuthSSEClient(), initial }));
+    useEffect(() => () => state.close(), [state]);
+    // useServerState(state, 'runtime', { workspaceId }) is 'ready' on the first render
+}
+```
 
 | Member | Behaviour |
 | --- | --- |
 | `get(id, key?)` | `GET` `get<Id>State`, key fields in the query. The answer is applied under the ordering rule and returned |
 | `snapshot(query?)` | `GET getStates`, by default with the stream's query. Each state in the answer is applied, and each subscribed state it omits is marked `'revoked'` (below); the snapshot is returned. A rejected fetch rejects and changes nothing |
-| `subscribe(id, key?, listener)` | Registers the listener for `(id, key)` and returns its unsubscribe (idempotent). The client's first subscriber reads the snapshot, then opens the stream (below) |
+| `subscribe(id, key?, listener)` | Registers the listener for `(id, key)` and returns its unsubscribe (idempotent). The listener is called when the entry's `status`, `value` or `data` changes — never for an arrival that differs only by a newer `at` (Ordering, below). The client's first subscriber reads the snapshot, then opens the stream (below) |
 | `write(id, input, key?)` | `put<Id>State` with the input as the body, key fields in the query. The answer is applied at once — before the frame the write also sends — and returned. Typed only for a state with a write, and requires the key on a keyed one |
 | `current(id, key?)` | Synchronous: `{ at, value, data?, status }`, `{ status: 'revoked' }` for a state revoked before any value arrived, or `undefined`. The same frozen object until a change is applied |
-| `close()` | Closes the stream, drops every listener. Idempotent |
+| `connection()` | Synchronous: the connection status ([Connection status](#connection-status)), a frozen object, the same reference until it changes |
+| `subscribeConnection(listener)` | Registers `listener(status)`, called with the new status on every change, after `connection()` returns it; returns its unsubscribe (idempotent). The same function subscribed twice is two subscriptions |
+| `retry()` | When `'failed'` or `'reconnecting'`: reads the first snapshot now (its retry count reset), or, once the manifest is known, reopens the stream now. A no-op when `'connected'`, while the first snapshot is in flight, and with nothing subscribed — after `close()` too, until a new `subscribe` |
+| `close()` | Closes the stream, drops every listener — connection listeners too — and stops listening to `online`; the status is back to `'reconnecting'` 0. Idempotent. A `subscribe` after it starts the client again, without `online`: `retry()` restarts it as before |
 
 `onError` receives a failure of something the client ran on its own — the first snapshot, the
 snapshot after the stream opened, the read after a grant — and a refused `subscribe` (default
 `console.error`). Calls the app makes reject.
 
-A listener that throws is logged at warn with the state id and does not stop the others.
+A listener that throws is logged at warn with the state id and does not stop the others; so is
+a connection listener.
 
 Give the state client an `SSEClient` of its own: an `SSEClient` holds one subscription, and
 the state client's supersedes any other made on it.
@@ -510,16 +558,24 @@ the state client's supersedes any other made on it.
 
 Per `(id, key)`, every arrival — a snapshot entry, a frame, a read or a write answer — goes
 through one rule. `at` is the time the server's read started, so a larger `at` is a later value.
+The client keeps, per `(id, key)`, an ordering stamp — the newest `at` seen — apart from the
+entry, and compares each arrival against it.
 
 | Arrival | Result |
 | --- | --- |
-| no current entry, or `at` newer than the current | applied, listeners notified |
-| `at` equal to the current | one read stamps one `at`, so this is the same value: applied and notified only when `value` or `data` differ (deep-equal) or the entry is `'revoked'` |
-| `at` older than the current | dropped |
-| a snapshot older than one state's entry | that state keeps its entry; the others take the snapshot |
+| no current entry, or `at` newer than the stamp | the ordering stamp advances; applied and notified only when `status`, `value` or `data` differ (deep-equal) |
+| `at` equal to the stamp | one read stamps one `at`, so this is the same value: applied and notified only when `value` or `data` differ (deep-equal), or its status differs from the entry's |
+| `at` older than the stamp | dropped |
+| a snapshot older than one state's stamp | that state keeps its entry; the others take the snapshot |
 | a write answer | applied like a frame — its own frame, arriving later with the same `at` and value, changes nothing |
 | a frame for a key not subscribed here | dropped (the server already filters by the connect query; this is the second guard) |
 
+Every stream open — the first, a reconnect, a reopen on a key change — brings each state's
+current value with a newer `at`: the stream's initial frame, or the snapshot re-read when the
+stream did not serve it. A listener hears it only when `status`, `value` or `data` changed. The
+`at` of `current()` is the `at` of the read that last changed the value; a later read that repeats
+it advances only the stamp, so an older arrival after it is still dropped.
+
 The ordering rule decides the value; the status is decided apart (next section): an arrival
 on a revoked `(id, key)` supplies its value and leaves it `'revoked'`.
 
@@ -532,23 +588,79 @@ changed.
 - **One stream per client**, opened when the first subscriber arrives and closed when the last
   leaves. Subscriptions made in the same task (components mounting together, a StrictMode
   unmount-remount) are batched into one change.
-- **Snapshot first**: the first stream opens after the first snapshot, whose manifest it needs.
+- **Snapshot first**: the first stream opens after the first snapshot, whose manifest it needs —
+  at once on a client built with `initial`, which already holds it.
 - **Every event requested**: `events=` lists `state.<id>.changed` for every state of the
   manifest, in its order, never only the subscribed ones. The server's `grant` activates only an event the
   connection requested, so a state subscribed later would otherwise be ungrantable.
 - **Keys in the query**: the connect query is the union of the subscribed keys' fields (SSE
   `subscribe({ query })`). A new key value, or the last subscriber of one leaving, closes the
   stream and opens it with the new query.
-- **Snapshot on every open** — the first, a reconnect, a reopen on a key change. A frame sent
-  while no stream was open is lost, whether its key changed or not; the snapshot read after
-  the open covers that gap. (It runs on the stream's `open`, not at `onReconnect`: a snapshot
-  read before the new stream is live would leave the same gap.)
+- **Current frames on every open** — the first, a reconnect, a reopen on a key change. A frame
+  sent while no stream was open is lost, whether its key changed or not. The server covers that
+  gap: right after the `connected` frame it writes each allowed state's current frame — one
+  `read()` for the subject and the carried key, its `at` the read's start — before any live
+  frame, and `connected.initial` names the states it served. They are ordinary frames under the
+  ordering rule, so whatever changed between the render and the open arrives as a newer `at`.
+  The client reads the snapshot only when a state it requested is neither in `initial` nor in
+  `deniedEvents` — a state whose read threw on the server — or when `initial` is absent (a
+  server before it); a state in `deniedEvents` it watches on the carried key is `'revoked'`.
+  (It all runs on the stream's `connected`, not at `onReconnect`: a read before the new stream
+  is live would leave the same gap.)
 - **One value per key field per connection.** A connect query carries one `workspaceId`; when
   two subscribed keys disagree on a field, the most recently subscribed key is carried. A key
   the stream does not carry is read once (`get`) when the stream opens and receives no frames
   until it is carried again. A screen that must follow two workspaces live uses a second
   state client.
 
+### Connection status
+
+The client decides the retries — the SSE client's reconnects of the stream, its own of the
+first snapshot — so it says where they stand. `connection()` is one of:
+
+| Status | Holds |
+| --- | --- |
+| `{ status: 'connected' }` | a stream is open (the SSE `onOpen`) |
+| `{ status: 'reconnecting', attempt }` | no stream open — not yet, or nothing subscribed — or the SSE client retrying a dropped one: `attempt` is its count (`onReconnect`), reset when a stream opens; `0` before the first stream opens, while the first snapshot is read or retried, and after `retry()` |
+| `{ status: 'failed' }` | the retries are exhausted: the SSE client's `maxReconnectAttempts` (its `onClose`, the attempts spent), or `maxRetries` for the first snapshot. Nothing more is tried until a restart (below) or, with the manifest unknown, a `get`, `write` or `snapshot` that brings it |
+
+- **Start value** `{ status: 'reconnecting', attempt: 0 }`, a client built with `initial` too:
+  its entries are ready, its stream is not.
+- A stream error alone changes nothing — a reconnect or the end of the attempts follows. A
+  stream the client closes itself — a key change, `close()` — is no failure; a reopen on a
+  key change while connected stays `'connected'`.
+- **Restarts.** `retry()` and the browser's `online` event — listened to from construction
+  where `addEventListener` exists — restart when `'failed'` or `'reconnecting'`; a `subscribe`
+  restarts when `'failed'`, reopening a failed stream even when the query is unchanged. An
+  unsubscribe that leaves subscribers never does: the status stays `'failed'` (the last one:
+  below). With the manifest unknown, any call that brings it — `get`, `write`, `snapshot` —
+  opens the stream; with the manifest known, those calls reopen nothing while `'failed'`. The
+  first snapshot is read now with its count reset (one in flight is not doubled), or the stream
+  is reopened now as a new SSE subscription, whose attempts start from 0 — a pending reconnect
+  timer is superseded. The status is `'reconnecting'` 0 until it opens.
+- **The last unsubscribe** closes the stream: `'reconnecting'` 0, the start value, and the
+  first snapshot's retry count starts over for the next wait.
+- **`close()`** sets `'reconnecting'` 0, drops the connection listeners and removes the
+  `online` listener; its own teardown is not `'failed'`. A `subscribe` after it starts the
+  client again, and `retry()` restarts it; `online` is not listened to again.
+
+```tsx
+const connection = useConnectionStatus(state);
+
+if (connection.status === 'failed')
+{
+    return <Banner action={() => state.retry()}>The server has a problem.</Banner>;
+}
+if (connection.status === 'reconnecting' && connection.attempt > 0)
+{
+    return <Banner>The server is not answering, retrying…</Banner>;
+}
+```
+
+`maxRetries` bounds the first snapshot only; bound the stream's reconnects with the SSE
+client's `maxReconnectAttempts` (`createAuthSSEClient({ maxReconnectAttempts: 5 })`). Both
+default to `0`, retrying forever: the status never turns `'failed'`.
+
 ### `'revoked'` — the server does not serve this to you
 
 One status says the server stopped serving a `(id, key)` to this subject, however the client
@@ -558,12 +670,13 @@ value has arrived yet.
 | Arrival | Client |
 | --- | --- |
 | `subscription.revoked` for `state.<id>.changed` | the entry of `id` for **the key the connection carries** (keyless: its one entry) gets `status: 'revoked'`, value kept, listeners notified. The server scopes a revoke by the connect query, so a shadowed key of the same state is untouched |
+| `connected.deniedEvents` names a subscribed state — keyless, or keyed on the key the connection carries | `'revoked'`, value kept, listeners notified: the connect check (`canRead` false, or the key absent) denied it. A shadowed key of the same state is untouched |
 | a snapshot that omits a subscribed state — keyless, or keyed with its key in the query | `'revoked'`, value kept if one exists, listeners notified. This is also a state denied at connect (`canRead` false, absent from the snapshot), and a reconnect after access was lost while the stream was down, when no revoke could arrive. A keyed state whose key the query did not carry is not marked |
 | a frame, a read or a snapshot started before the revoke | supplies its value under the ordering rule; the status stays `'revoked'` |
 | `subscription.granted` for it | clears the mark for the carried key and reads it once (`get`); the server also sends a frame, before or after the control frame. Both arrive `'ready'`, and either order ends at the latest value |
-| the snapshot of a connection opened after the revoke, holding the state | clears the mark: that connection's own connect check served it |
+| a frame — the initial one included — or the snapshot of a connection opened after the revoke, holding the state | clears the mark: that connection's own connect check served it |
 | the read of a shadowed key when a connection opened after the revoke, answered | clears the mark the same way: the read route served it |
-| an answer of such a read older than the entry — a frame or a `write()` answer of the new connection landed first | its value is dropped under the ordering rule, while the mark is still lifted: the lift goes by the connection, not by `at` |
+| an answer of such a read older than the stamp — a frame or a `write()` answer of the new connection landed first | its value is dropped under the ordering rule, while the mark is still lifted: the lift goes by the connection, not by `at` |
 
 Every automatic read is tagged with the connection it was started for, which is how a
 snapshot in flight across a revoke is told from one read after it.
@@ -575,29 +688,42 @@ snapshot in flight across a revoke is told from one read after it.
 ```
 
 - Built on `useSyncExternalStore`: `subscribe` is `client.subscribe(id, key, cb)`,
-  `getSnapshot` is `client.current(id, key)`, and the server snapshot is `undefined` — a
-  server render is `'loading'` and opens nothing.
+  `getSnapshot` is `client.current(id, key)`, and so is the server snapshot. A server render
+  opens nothing; it shows the value when the client was built with `initial`, `'loading'`
+  otherwise. Hydration matches when the server and the browser build their clients from the
+  same `initial`.
 - The key is compared by its fields (stable-stringified), so `{ workspaceId }` written inline
   does not resubscribe on every render; another `workspaceId` unsubscribes and subscribes. A
   key never seen is `'loading'` until it has an entry; a key seen before shows its cached
-  entry as `'ready'` until the reopen snapshot lands (entries are not evicted).
+  entry as `'ready'` until the reopen's frame or snapshot lands (entries are not evicted).
 - `write` is typed only for a state with a write, bound to the hook's key. At runtime it is on
   every result — the type decides, so no render waits on the manifest — and on a state
   without a write it rejects naming the state.
 - `react` (`^18 || ^19`) is an **optional peer** of `@spfn/core`: only `@spfn/core/state/react`
   imports it. `@spfn/core/state/client` is framework-neutral.
 
-A page's first paint still comes from a server component reading the state's route with the
-app's `api.` client; the hook takes over in the browser.
+A page's first paint still comes from a server component reading the snapshot with the app's
+`api.` client; handed to the client as `initial`, the same read serves the hook's first render
+and the client's first subscribe, the stream's initial frames bring anything newer, and the
+hook takes over in the browser.
+
+### `useConnectionStatus(client)`
+
+`connection()` in a component, on `useSyncExternalStore`: `subscribe` is
+`client.subscribeConnection(cb)`, `getSnapshot` is `client.connection()`, both stable per
+client, so a render does not resubscribe. The server snapshot is `{ status: 'reconnecting',
+attempt: 0 }` — what every client starts with, so hydration matches.
 
 ### Types
 
 From `@spfn/core/state/client`: `createStateClient`, `StateClient<TStates>`,
-`StateClientConfig`, `StateFrame<V, D>`, `StateEntry<V, D>` (a frame plus `status`, or
-`{ status: 'revoked' }` alone), `StateListener`, `StateId`, `StateKeyArgs`, `WritableStateId`,
+`StateClientConfig<TStates>` (`sse`, `api?`, `onError?`, `retryDelay?`, `maxRetries?`, `initial?`),
+`ConnectionStatus`, `ConnectionListener`,
+`StateClientInitial<TStates>` (`{ snapshot, query? }`), `StateFrame<V, D>`, `StateEntry<V, D>`
+(a frame plus `status`, or `{ status: 'revoked' }` alone), `StateListener`, `StateId`, `StateKeyArgs`, `WritableStateId`,
 `StateCatalog`, `StateFrameOf`, `InferStateData`, and — re-exported type-only from the server
 module — `InferStateValue`, `InferStateKey`, `InferStateInput`. From `@spfn/core/state/react`:
-`useServerState`, `ServerState<TStates, Id>`.
+`useServerState`, `ServerState<TStates, Id>`, `useConnectionStatus`.
 
 ---