experimental-a2 0.16.1 → 0.18.0

package/docs/guides/03-react.mdx

@@ -1,384 +0,0 @@
----
-title: Live UI with React
-description: "Synchronize one session from server to browser: render its state, stream new events, and push writes optimistically through one reducer."
----
-
-## The model
-
-A session can be read live from the browser. The server renders the first
-paint, a stream keeps it fresh, and writes apply instantly. One reducer
-produces every one of those views; server and client fold the same log
-with the same function, so they can't disagree.
-
-That's the trick, really. The client receives one state snapshot and its log
-position, then syncs later events and folds them locally. It does not keep
-synchronizing state. An append-only log with positions is simpler.
-
-This is session sync. The client follows one known session id; it does not
-subscribe to database tables or queries across many sessions. Keep those
-collection views in your [application database](/guides/application-data).
-
-The pieces: two route handlers (read and write), a factory that binds your
-reducer, and the provider + hook it returns.
-
-## The API route
-
-`server.fetch` exposes a session over HTTP. It is bound, so the route can
-export it directly: `GET` streams events and serves history slices;
-`POST` appends.
-
-```ts app/api/order-events/route.ts
-import { ordersServer } from '@/server/orders'
-
-export const GET = ordersServer.fetch
-export const POST = ordersServer.fetch
-```
-
-`GET` is the read path. A plain `GET` is the live stream: a server-sent
-events response of one session's events, resumed after the `index` query
-parameter, so clients pick up exactly where they left off after a first
-paint or a dropped connection. A `GET` carrying `gte`/`lte` query
-parameters is a history slice instead: the bounded log range as JSON,
-the cold read [`loadHistory`](#the-client-component) rides.
-
-`POST` is the write path. The push envelope is validated, then `append` does the
-rest. The response is the appended events: an ack, not a stream. Thrown
-[`A2Error`s](/reference/errors#over-the-wire) serialize onto the wire so
-the client can branch on the same codes.
-
-Wrap `server.fetch` when the route needs authentication, per-operation
-authorization, or response decoration. `authorize` receives the parsed
-A2 operation after envelope parsing and before schema validation or I/O.
-Return `false` to answer `FORBIDDEN`. A thrown error is treated as an
-infrastructure failure.
-
-```ts
-// app/api/order-events/route.ts, now with response decoration:
-import { ordersServer } from '@/server/orders'
-
-export async function GET(request: Request): Promise<Response> {
-  const response = await ordersServer.fetch(request)
-  if (response.headers.get('a2-history-covered') === 'true') {
-    response.headers.set('cache-control', 'private, max-age=31536000')
-  }
-  return response
-}
-
-export const POST = ordersServer.fetch
-```
-
-## The session module
-
-Bind your reducer once, in a `'use client'` file, and export the pair:
-
-```tsx app/orders/[orderId]/session.ts
-'use client'
-import { createClient } from 'experimental-a2/client'
-import { createReact } from 'experimental-a2/react'
-import { ordersReducer } from '@/reducer'
-
-export const ordersClient = createClient({
-  reducer: ordersReducer,
-  api: '/api/order-events',
-})
-export const { SessionProvider, useSession } = createReact({ client: ordersClient })
-```
-
-This is the whole client/server seam. `createReact` is a factory (like
-`createContext`): everything it returns is typed by the reducer value;
-the state from its fold, the pushable events from its vocabulary. No type
-arguments anywhere, and nothing in this file touches the server module.
-The client also gives every session a stable in-memory identity. Calling
-`ordersClient.session(orderId)` before navigation and mounting the provider
-after navigation reaches the same optimistic state, with no handoff store.
-
-## The server component
-
-The first paint costs no client JavaScript: fold on the server, pass the
-result down.
-
-```tsx app/orders/[orderId]/page.tsx
-import { ordersServer } from '@/server/orders'
-import { ordersReducer } from '@/reducer'
-import { SessionProvider } from './session'
-import { OrderClient } from './order-client'
-
-export default async function OrderPage({
-  params,
-}: {
-  params: Promise<{ orderId: string }>
-}) {
-  const { orderId } = await params
-  const session = ordersServer.session(orderId)
-  const { state, index } = await session.state(ordersReducer)
-
-  return (
-    <SessionProvider
-      sessionId={orderId}
-      initialState={state}
-      initialIndex={index}
-    >
-      <OrderClient />
-    </SessionProvider>
-  )
-}
-```
-
-Two props do the heavy lifting. `initialState` is the fold. `initialIndex` is
-its frontier, the log position the fold reflects. The client opens its stream
-after that position. The stream catches up any events appended after the server
-fold, then stays live. No history read is needed to hydrate state.
-(No `reducer` or `api` prop: the provider got both from the shared client.)
-
-## The client component
-
-```tsx app/orders/[orderId]/order-client.tsx
-'use client'
-import { useSession } from './session'
-
-export function OrderClient() {
-  const { state, push } = useSession()
-
-  return (
-    <button onClick={() => push({ type: 'shop.started', payload: {} })}>
-      Start
-    </button>
-  )
-}
-```
-
-What the hook gives you:
-
-- **`state`**: the live view, folded through the shared reducer. It
-  updates three ways: optimistically when you push, corrected when the
-  server acks, and continuously as the stream delivers events, yours and
-  everyone else's.
-- **`push`**: typed against the contract's vocabulary (via the reducer). Payloads are
-  validated locally before anything leaves the browser, apply instantly,
-  swap in the real event when the `POST` acks, and refold without it if
-  the server says no. Rejections carry the same
-  [`A2Error` codes](/reference/errors) the server throws, so both sides
-  branch on `code`. Awaiting `push(...)` gives the server ack; the
-  result also carries **`.confirmed`**, a promise for the moment the
-  live stream delivers the batch back and the view shows server truth.
-  `await push(...).confirmed` is "continue once this is real"; two
-  `performance.now()` calls around the two awaits are a complete
-  push→ack→stream latency meter. Overlapping calls on the same
-  session still apply immediately, then enter the transport in call
-  order. Controls do not need to wait or disable themselves to preserve
-  that order.
-- **`events`**: the raw events this client has observed or was explicitly
-  seeded with. With only the server snapshot, it begins after `initialIndex`.
-  Use it for UI that wants the log itself: an activity feed, a debug panel.
-  Earlier events are not needed to hydrate `state`. Later hydration can
-  advance state ahead of this feed; the stream keeps its own resume position
-  and adds delayed events without folding them again.
-- **`loadHistory`**: backscroll. `loadHistory({ before?, limit? })`
-  fetches a bounded slice of the log from below the frontier (the same
-  route, `gte`/`lte` query parameters) and merges it into `events`:
-  deduped, ordered, shared across every handle of the session. By
-  default each call walks backward 50 events at a time from the oldest
-  one loaded, including after a newer snapshot hydrates the session.
-  Pass an explicit `before` to read another range. It never touches `state`
-  or the optimistic overlay; backscrolled events are display data.
-  Calls serialize per session, so
-  a double-tap never fetches the same range twice. The `ws` api has no
-  history lane; `loadHistory` throws a `TypeError` there.
-- **`history`**: backscroll progress, `{ loading, complete,
-  oldestLoaded }`. `complete` means the feed reaches index 1 (or the
-  log is empty): nothing older is left, hide the "load older" button.
-- **`index`**: the latest server-confirmed state index, advanced by
-  snapshots and streamed events. This is the `lastSeenIndex` that makes
-  [cancellation](/guides/cancellation) exact.
-- **`connection`**: a discriminated union of `{ status: 'idle' }`,
-  `{ status: 'connecting', reconnects, error }`,
-  `{ status: 'paused', reconnects, error }`,
-  `{ status: 'live', reconnects }`, or `{ status: 'closed' }`. A status
-  dot is one ternary away; "reconnecting…" is
-  `status === 'connecting' && reconnects > 0`; `error` (why the last
-  connection ended) only exists while disconnected, so impossible
-  states don't compile. It's honest about silence, too: the server
-  heartbeats the stream (`: ping` every 15s), and a client that hears
-  nothing for two beats treats the connection as dead and reconnects, so
-  `live` means bytes are flowing, not "the socket hasn't errored yet".
-
-The provider opens the stream on mount, closes it on unmount, and
-reconnects with backoff, resuming from `index`, when the connection
-drops. Components that only write don't need the hook; `POST` to the
-route directly, or call `ordersClient.session(id).push(...)` so a later
-provider sees the same optimistic session.
-
-Polling streams start fast and back off to a two-second interval when idle.
-Idle is a polling state; the connection remains live and heartbeats continue.
-When you call `push()` on an idle SSE stream, the client refreshes that stream
-immediately, without reconnect backoff. It resumes from its existing `index`,
-so concurrent events before the write's acknowledged index are still read.
-Overlapping pushes share the refreshed stream. If a slow push is still pending
-when the stream idles again, or its acknowledged events have not arrived, the
-client refreshes again. WebSockets wake the session's attached read loop
-without replacing the socket. This is internal and requires no component
-configuration.
-
-Use `reconnect()` after a custom REST request commits a change outside
-`push()`. It is available on the session client and the `useSession()` result.
-It immediately restarts the live subscription from its current `index`, even
-when the stream is active. State, optimistic writes, and connection leases
-are preserved. Without an active lease it does nothing.
-
-`reconnect()` returns `void`; observe `connection` and `index` for progress.
-SSE opens a fresh GET. A single-session WebSocket opens a fresh socket; a
-multiplexed WebSocket re-subscribes only this session on its existing socket.
-Other subscribed sessions keep running. Any outstanding write interrupted by
-a socket replacement uses the normal idempotent retry path.
-
-The server stops the old session lane before authorizing its replacement.
-That lane stays closed if authorization denies access or fails. Successful
-authorization catches up from the cursor. Already accepted writes can finish,
-and failed subscription attempts follow the normal reconnect retry policy.
-
-Configure `createClient({ reconnect })` on a shared client to choose each
-retry's delay or return `false` to pause automatic reconnection. The callback
-receives `{ sessionId, error, attempt }`; `error` is an `A2ClientError`, or
-`null` when the stream ended cleanly. `attempt` starts at 1 and resets when
-the connection becomes live or you call `reconnect()` explicitly.
-
-A paused connection keeps the hydrated session, its writer, and its existing
-state. Observe `connection.status === 'paused'` and use the hook's
-`reconnect()` to resume when your application is ready. New consumers and
-pushes do not automatically resume it. Configure the policy where you create
-the client, without changing the hook's `hydrate` input.
-
-That identity is an in-memory L1, not another source of truth. Repeated
-`session(id)` calls reuse it while active and for five idle minutes by
-default. A newer server fold advances it, pending pushes stay overlaid,
-and a stale server render cannot rewind it. The optional IndexedDB cache
-is the L2: it survives reloads; the memory runtime does not. The
-stream is shared the same way: `connect()` takes a lease and returns
-its release, so however many hooks, providers, or plain calls hold one
-session open, the first lease connects and the last release closes
-(`close()` is the hard stop).
-
-One detail worth knowing: every push carries a client-generated event id.
-That id is how the ack finds its optimistic entry, and it makes retrying
-a failed `POST` idempotent. `push` retries `STORE_UNAVAILABLE` and client
-transport failures, with a three-attempt budget.
-
-Optimistic pushes are also what make [cancellation](/guides/cancellation)
-feel instant: the `cancelled` event folds locally before the server ever
-sees it.
-
-Sessions can outlive the tab, too: hand `createReact` a `cache` and
-revisits paint from the local copy, the stream resumes from the cached
-frontier, and offline pushes queue and replay. See
-[Local-first](/guides/local-first).
-
-## Client-first sessions
-
-Everything above assumes a server component hands the first fold down.
-A client-rendered app often has nothing to hand: a sidebar showing ten
-channel sessions, a user session read from deep inside a menu, panes
-that mount from client-side navigation. No server fold, and no natural
-provider boundary for components that reach sessions ad hoc.
-
-For that shape, `experimental-a2/react` exports a standalone hook. Any
-component can mount any session, no provider needed:
-
-```tsx app/orders/[orderId]/order-badge.tsx
-'use client'
-import { useSession } from 'experimental-a2/react'
-import { ordersClient } from './session'
-
-export function OrderBadge({ orderId }: { orderId: string }) {
-  // your fetch (SWR, a router loader, a parent's payload): anything
-  // that lands the { state, index } your route returns (below), e.g.
-  // const { data } = useSWR(`/api/orders/${orderId}/state`)
-  const data = undefined // still loading
-
-  const { state } = useSession(ordersClient, orderId, { hydrate: data })
-  if (!data) return <span>…</span> // your loading state IS the pending state
-  return <span>{state.status}</span>
-}
-```
-
-The fold comes from your own route, and the route is one line of A2:
-
-```ts app/api/orders/[orderId]/state/route.ts
-import { ordersServer } from '@/server/orders'
-import { ordersReducer } from '@/reducer'
-
-export async function GET(
-  _req: Request,
-  { params }: { params: Promise<{ orderId: string }> },
-) {
-  const { orderId } = await params
-  // here's where you'd do auth, or any other checks
-  return Response.json(
-    await ordersServer.session(orderId).state(ordersReducer),
-  )
-}
-```
-
-Note what is not on the wire: a reducer name. The route calls
-`session.state(reducer)` with the reducer by reference, the same
-module your client bundle folds with. That matters because renaming a
-reducer is the [snapshot invalidation knob](/concepts/state): if the
-name traveled on the wire, every rename would open a version-skew
-window between deployed clients and servers. By reference, the knob
-stays free. And unlike a history slice, which is immutable once read
-and earns a standard wire shape, a state read is a moving snapshot;
-there is nothing for the library to standardize, so the read stays
-behind your route, under your auth and caching policy.
-
-`hydrate` is one atomic option: the `{ state, index }` pair
-`session.state(reducer)` returns. State and its frontier travel
-together or not at all; a half-present handoff cannot compile. While
-it is `undefined` (your fetch has not landed), the hook holds the
-stream and `state` is the reducer's `initialState`. There is no
-pending flag on the result: whether the fold has been handed over is
-your own input, so your data layer's loading state is the pending
-state. When the value arrives, the session hydrates
-and the stream connects at that frontier. The hold is deliberate:
-connecting without a fold means replaying the whole log through the
-browser, and the library never picks the expensive path silently. When
-a full replay is what you want (a short log, a debug view), hand the
-fold's true starting point:
-`hydrate: { state: ordersReducer.initialState, index: 0 }`. State at
-index 0 is the reducer's seed by definition, so the explicit replay
-needs no special vocabulary; the stream then delivers every event
-live.
-
-The rest behaves like the provider. The handle is identity-mapped
-(every hook and provider mounting the same session shares one runtime)
-and each mount holds a lease on the shared stream (see
-[the client identity note](#the-client-component)). A later, further
-fold handed to the same session
-advances it and a stale one is ignored, the same never-move-backward
-rule as everywhere else. For presence, identity comes from the
-client's `participant` (set once on `createClient`) or the hook's
-`participant` option, which overrides it. The
-result is exactly the shape the bound hook returns. There is no
-loading or error member: the
-library performs no fetch here, so your data layer's states are the
-states, retried however your data layer retries.
-
-`SessionProvider` keeps its required `initialState`/`initialIndex`.
-The provider is the server-handoff tool; the hook is the client-first
-tool.
-
-## Keep the backend out of the bundle
-
-The split is structural, not disciplinary. Core `experimental-a2` (the contract,
-reducers, errors) imports no backend, ever; only `experimental-a2/server` can reach
-one, and its exports map resolves to a loud error under the browser
-condition. The layout above rides that:
-
-1. `contracts.ts` and `reducer.ts` import nothing but schemas and `experimental-a2`,
-   isomorphic by construction.
-2. The session module imports the reducer, never `experimental-a2/server`. Client
-   components don't need the server's *type*, even: the factory carries
-   all the typing.
-
-Belt and suspenders: put `import 'server-only'` at the top of your
-server module and enable `verbatimModuleSyntax` in your tsconfig; an
-accidental value import then fails your build too, with your own error
-message.

package/docs/guides/04-local-first.mdx

@@ -1,88 +0,0 @@
----
-title: Local-first
-description: "Cache one A2 session in the browser: instant revisits, stream resumption, and offline writes."
----
-
-## One option
-
-```tsx app/orders/[orderId]/session.ts
-'use client'
-import { createReact } from 'experimental-a2/react'
-import { indexedDb } from 'experimental-a2/cache-indexeddb'
-import { ordersReducer } from '@/reducer'
-
-export const { SessionProvider, useSession } = createReact({
-  reducer: ordersReducer,
-  cache: indexedDb(),
-})
-```
-
-This is the [session module](/guides/react#the-session-module) from Live
-UI with one addition. The cache is created here, in client code, where
-live objects belong; server components keep importing `SessionProvider`
-exactly as before; nothing crosses the server boundary.
-
-With `cache` set:
-
-- **Revisits paint instantly.** State folds from the local copy before the
-  network says a word. Works offline too.
-- **The stream resumes from the cached frontier.** Reconnects fetch only
-  what this browser hasn't seen, no matter how long it's been.
-- **Pushes queue while offline**, and replay, in order, when the
-  connection returns.
-
-Without it, nothing changes; the provider behaves exactly as before.
-
-## Why this is safe
-
-Local-first is usually hard because it means syncing state, and state
-needs merging. A2 caches an append-only log with server-assigned positions
-instead. A cached event can never be *wrong*; this browser can only be
-*behind*. Catching up is fetching events after an index, which is what
-`stream({ startAfter })` does anyway. There's no merge function because
-there's nothing to merge.
-
-## What gets stored
-
-Three things, in IndexedDB:
-
-| Stored                                        | Invalidated by                                          |
-| --------------------------------------------- | ------------------------------------------------------- |
-| the session's events                          | nothing; they're immutable                              |
-| a folded snapshot, keyed by reducer name | a reducer rename (or a `stateSchema` mismatch, when the reducer declares one): discarded, refolded from cached events |
-| pending pushes                                | the server's ack                                        |
-
-Note the middle row: the reducer's `name` does the same job here that it
-does for [server snapshots](/concepts/state#snapshots-are-a-cache). One
-string, both sides of the wire.
-
-Deleting the cache is always safe. It's a replica of what this browser
-already saw; the log on the server stays the only authority.
-
-## Offline writes
-
-`push` while offline persists the events, client ids and all, and
-applies them optimistically, same as always. On reconnect they replay in
-order. The replay is idempotent by construction: an identical batch is an
-idempotent success, so a flaky reconnect, or a second tab replaying the
-same queue, causes no duplicates. Rejections refold without the event,
-exactly like an online push the server refused.
-
-What this is *not*: local execution. Handlers run on the server, when the
-events arrive. An offline push is a queued intent, not a completed
-action. Design the UI accordingly ("sending…" is honest; "sent" is not).
-
-## Logout
-
-Cached events outlive the session cookie. If your app authenticates,
-clear the cache when the user leaves:
-
-```ts
-// in the browser, wherever your logout flow runs:
-await cache.clear() // everything, or cache.clear(sessionId) for one session
-```
-
-That's the one obligation `cache` puts on you. The cache never *grants*
-access (your routes still authorize every read and write) but it
-*retains* what was legitimately seen, and retained data belongs to the
-person who saw it.