experimental-a2 0.17.0 → 0.18.1

package/docs/client/01-react.mdx

@@ -0,0 +1,294 @@
+---
+title: React
+description: "Start from a snapshot, fold new events, and push optimistic writes through one shared session."
+---
+
+## Publish the state
+
+The reducer lives with the event vocabulary, in a shared module:
+
+```ts model.ts
+import { contract } from 'experimental-a2'
+import { z } from 'zod'
+
+export const counter = contract({
+  name: 'counter',
+  events: { added: z.number() },
+  reducer: {
+    name: 'count.v1',
+    initialState: 0,
+    fold: (state, event) => state + event.payload,
+  },
+})
+```
+
+A contract can publish one reducer. The client starts from a snapshot of its
+state and folds later events locally, for one known session ID. Queries across
+sessions belong in your [application database](/contract/sessions).
+
+The reducer name identifies its [snapshot format](/contract/state#snapshots-are-a-cache):
+change it when the fold's meaning or stored shape changes, and run the same
+version on server and client. An inline fold returning a discriminated union
+may need `as const` or an explicit return type; the
+[`reducer` builder](/contract/state#reducers) fixes the state type first.
+Other reducers read on the server with `session.state(reducer)` publish no
+client state.
+
+```ts server/counter.ts
+import { createServer } from 'experimental-a2/server'
+import { counter } from '../model'
+
+export const counterServer = createServer({ contract: counter })
+```
+
+```ts app/api/counter/route.ts
+import { counterServer } from '../../../server/counter'
+
+export const GET = counterServer.fetch
+export const POST = counterServer.fetch
+```
+
+`GET` serves the subscription and history reads; `POST` appends writes.
+Authentication and `authorize` live on [Routes](/server/routes). Bootstrap
+is authorized as a `stream` operation with `bootstrap: true` before A2 reads
+state.
+
+## Bind React once
+
+`createReact` binds the client's types into a Provider and hook. It creates
+no separate connection pool.
+
+```tsx app/counter/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { counter } from '../../model'
+
+export const counterClient = createClient({
+  contract: counter,
+  api: '/api/counter',
+})
+
+export const { SessionProvider, useSession } = createReact({
+  client: counterClient,
+})
+```
+
+```tsx app/counter/counter.tsx
+'use client'
+import { useSession } from './session'
+
+export function Counter() {
+  const { state, connection, push } = useSession()
+  const error = 'error' in connection ? connection.error : null
+
+  return (
+    <>
+      <button onClick={() => void push({ type: 'added', payload: 1 })}>
+        Count: {state}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+    </>
+  )
+}
+```
+
+`useSession()` returns `state`, `hydrated`, `events`, `index`, `connection`,
+`push`, `reconnect`, `loadHistory`, and `history`; presence contracts add
+`presence` and `setPresence`. The [reference](/reference/client) covers each.
+
+Without a [seed](#seed-the-first-render), `state` starts at
+`reducer.initialState` (through the reducer's client projection when present),
+which can look empty while an existing session loads. The subscription's first
+frame is a snapshot that replaces it atomically. Later events fold on top,
+including any appended while the snapshot was read. `connection` stays
+`connecting` until then; bootstrap failures retry like any stream failure, and
+a reconnect keeps the last state.
+
+A push during bootstrap is sent right away, and its optimistic update appears
+once the snapshot is applied. If it is still unacknowledged when the snapshot
+arrives, it stays hidden until its ack (the snapshot may already contain it),
+along with the pushes queued behind it, so the view never skips a write. The
+push promise resolves on the server ack; `.confirmed` waits for stream
+delivery, and the snapshot counts as delivery through its index.
+
+## Without server rendering
+
+A Provider needs only the session ID. It supplies scope and optional data;
+mounted hooks own connection leases.
+
+```tsx app/counter/page.tsx
+import { Counter } from './counter'
+import { SessionProvider } from './session'
+
+export default function Page() {
+  return (
+    <SessionProvider sessionId="shared">
+      <Counter />
+    </SessionProvider>
+  )
+}
+```
+
+Or skip the Provider. The bound hook already knows its client:
+
+```tsx app/counter/standalone.tsx
+'use client'
+import { useSession } from './session'
+
+export function StandaloneCounter({ sessionId }: { sessionId: string }) {
+  const { state, push } = useSession({ sessionId })
+  return (
+    <button onClick={() => void push({ type: 'added', payload: 1 })}>
+      {state}
+    </button>
+  )
+}
+```
+
+Without the factory, the direct `useSession(client, sessionId, options?)`
+export behaves the same.
+
+## Seed the first render
+
+Server rendering can skip the bootstrap read. Supply the state and its index
+together:
+
+```tsx app/seeded-counter/page.tsx
+import { counterServer } from '../../server/counter'
+import { Counter } from '../counter/counter'
+import { SessionProvider } from '../counter/session'
+
+export default async function Page() {
+  const initial = await counterServer.session('shared').state()
+  return (
+    <SessionProvider sessionId="shared" initial={initial}>
+      <Counter />
+    </SessionProvider>
+  )
+}
+```
+
+Index 10 means the state includes events through 10, so the stream starts
+after 10. Index 0 with the reducer's initial state requests replay from the
+beginning; an index alone cannot describe a state. The standalone hook takes
+the same `initial` option.
+
+Seeds are render-local: one request's seed never changes another's state, and
+hydration first renders the supplied snapshot even when the browser cache has
+advanced.
+
+`hydrated` turns `true` once a supplied snapshot or bootstrap initializes the
+session (index 0 counts) and stays `true` through disconnections, reconnects,
+and disabled readers while the session keeps its state. It is `false` while
+only the reducer seed shows, including during a pending or rejected cold
+preload. Use it to tell an empty queue from an unloaded one; it says nothing
+about freshness, connectivity, or permission to write. Imperative code reads
+`client.session(id).getSnapshot().hydrated`.
+
+## Start a preload on the server
+
+`initial` also accepts a Promise of a snapshot:
+
+```tsx app/preloaded-counter/page.tsx
+import { Suspense } from 'react'
+import { counterServer } from '../../server/counter'
+import { SessionProvider } from '../counter/session'
+import { PreloadedCounter } from './counter'
+
+export default function Page() {
+  const initial = counterServer.session('shared').state()
+  return (
+    <SessionProvider sessionId="shared" initial={initial}>
+      <h1>Counter</h1>
+      <Suspense fallback={<p>Loading counter…</p>}>
+        <PreloadedCounter />
+      </Suspense>
+    </SessionProvider>
+  )
+}
+```
+
+```tsx app/preloaded-counter/counter.tsx
+'use client'
+import { useSession } from '../counter/session'
+
+export function PreloadedCounter() {
+  const { state, push } = useSession({ suspend: true })
+  return (
+    <button onClick={() => void push({ type: 'added', payload: 1 })}>
+      {state}
+    </button>
+  )
+}
+```
+
+A cold session waits for the Promise before subscribing, showing
+`reducer.initialState` meanwhile. A snapshot result skips the bootstrap read;
+`null` or `undefined` falls back to it. A2 starts no extra request.
+
+`suspend: true` reads the Promise with React `use()`, so the nearest Suspense
+and Error boundaries handle pending and rejected states. Without it, the
+server response renders the reducer seed; to render the loaded session there,
+await the snapshot or suspend inside a boundary. The Provider and automatic
+bootstrap never suspend. Create the Promise outside the consuming component so
+its identity stays stable.
+
+A rejected cold preload pauses startup and reports through `connection`. A2
+cannot retry your Promise: supply a new Promise, a snapshot, or `null`. To
+fall back to bootstrap instead, catch the failure in your Promise and return
+`null`.
+
+A warm session keeps its state and connection while a new Promise is pending;
+a newer snapshot hydrates as usual, and a late rejection does not disrupt it.
+Replacing the source or calling the session's `close()` discards unapplied
+results. Unmounting releases the hook's lease but never cancels your fetch,
+and repeating the same Promise in a cached session does not restart cancelled
+work.
+
+## Connections and activation
+
+Hooks on the same client instance and session ID share one runtime,
+connection, state, and optimistic queue, under any Providers. Another client
+instance is isolated, even with the same URL. A reconnect resumes after the
+last delivered event, without another snapshot.
+
+`useSession({ enabled: false })` observes cached or initial data without
+taking a connection lease (default `true`). Disabling or unmounting a hook
+releases only its own lease. Explicit pushes still acquire a connection, so
+disabling is not an authorization boundary.
+
+The bound hook accepts `sessionId`, `client`, `participant`, `initial`,
+`enabled`, and `suspend`. It inherits the Provider's initial data and
+participant only when the resolved client and session ID match the
+Provider's.
+
+## Events and history
+
+`events` is the raw feed: supplied `initialEvents`, loaded history, live
+events, and pending optimistic events. A snapshot adds no historical rows, so
+without `initialEvents` the feed starts after the snapshot's index.
+
+`loadHistory({ before, limit })` loads older entries into `events`, by default
+up to 50 before the oldest loaded one, without touching state or the live
+cursor. `history` reports loading, the oldest loaded index, and whether the
+beginning is loaded. History reads need the HTTP
+[transport](/client/transports).
+
+`events` lives in memory, unpaginated, so long-lived sessions accumulate
+events. Snapshots bound replay work, not the size of state or retained events:
+choose reducer contents that fit.
+
+## Client lifetime
+
+Define the client once in a module, as `session.ts` does, so components
+share its sessions. `createClient({ gcTime })` keeps an idle session cached,
+five minutes by default; active connections, listeners, and pending work keep
+it alive.
+
+The cache is in memory, so a reload discards it. A2 ships no IndexedDB adapter
+(`experimental-a2/cache-indexeddb` has no implementation) and no persistent
+offline write queue. Pushes retry a bounded number of times and roll back when
+they fail. To persist state yourself, restore a state/index pair through
+`initial`, only for the same session and reducer version, and keep
+authentication and retention policy in your application.

package/docs/client/02-transports.mdx

@@ -0,0 +1,86 @@
+---
+title: Transports
+description: "One client, three wires: one HTTP route, split routes for per-verb timeouts, or one WebSocket."
+---
+
+## One wire seam, same client
+
+`api` picks the wire:
+
+```ts
+// in a 'use client' session module:
+api: '/api/order-events'
+api: (sessionId) => `/api/orders/${encodeURIComponent(sessionId)}/events`
+api: { type: 'http', push: '/api/order-push', stream: '/api/order-stream' }
+api: { type: 'ws', url: '/api/order-events' }
+```
+
+- **One route** is the default and the recommendation: a fixed URL or a
+  session URL function, serving GET (SSE stream and history) and POST (push).
+- **`http` split** serves the two verbs from separate routes, for platforms
+  whose duration limits differ per verb.
+- **`ws`** carries streams, pushes, and presence over one socket per session.
+  A socket is one connection in both directions, so it has no split form.
+
+The server side of each lives on [Routes](/server/routes). Everything above
+the wire is shared: `useSession`, push acks and `confirmed`, presence
+cadence, connection status, stall detection, and reconnection. SSE and
+WebSocket resume from the same durable frontier and treat presence as
+ephemeral, repaintable state.
+
+## Session URL functions
+
+Every session-scoped URL may be a `(sessionId) => string` function. A2
+resolves it for each request or reconnect, then adds its standard query
+parameters. Encode the ID when placing it in a path segment.
+
+The function chooses a route, not authority. If a path or connection token is
+scoped to one session, [`authorize`](/server/routes#the-http-route) must
+compare that scope to `operation.sessionId`. Bind URL tokens to the same
+session and keep them short-lived, because URLs can appear in infrastructure
+logs.
+
+## WebSocket
+
+```ts app/orders/[orderId]/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { orders } from '@/contracts'
+
+export const ordersClient = createClient({
+  contract: orders,
+  api: { type: 'ws', url: '/api/order-events' },
+})
+export const { SessionProvider, useSession } = createReact({
+  client: ordersClient,
+})
+```
+
+To share one socket across the client's sessions, set `multiplex: true` in
+`api` and `multiplexWebSocket: true` on the
+[route](/server/routes#the-websocket-route). A multiplexed URL is one plain
+string, since the connection carries more than one session.
+
+`ws` has no history lane. [`loadHistory`](/client/react#events-and-history)
+is a bounded cold read over plain HTTP; on a `ws` api it throws a
+`TypeError`.
+
+## Lifecycle
+
+When a socket closes, the client reconnects at its current frontier per its
+reconnection policy, receives a fresh presence snapshot, and re-sends its own
+latest presence. A multiplexed socket re-subscribes every active session at
+its own frontier. Pushes keep their client-generated ids, so retries stay
+idempotent.
+
+The `createClient({ reconnect })` policy returns a delay, or `false` to
+pause. The default reconnects with backoff indefinitely. A clean close also
+runs the policy, with `error: null`. A paused session keeps its state and
+leases; `session.reconnect()` resumes it.
+
+Upgrade authorization stays in the
+[HTTP route](/server/routes#the-websocket-route). Browser WebSockets hide a
+rejected upgrade's status and body, so it surfaces as an opaque
+`CONNECTION_FAILED` error. Structured subscription errors arrive once a
+multiplexed socket is open.

package/docs/client/03-presence.mdx

@@ -0,0 +1,224 @@
+---
+title: Presence
+description: "Ephemeral participant state on a durable session: cursors, typing, live progress. Presence repaints; the log replays."
+---
+
+## Two planes, one session
+
+Events are facts: stored, folded by reducers, replayed on demand. Presence is
+not. "Her cursor is at (312, 88)" is useful for about two seconds, has no
+replay value, and a lost update is repainted by the next one. The test:
+
+> Will anyone, human or reducer, care about this datum after the moment
+> passes? Yes: event, in the log. No: presence.
+
+Messages, document updates, cancellations: events. Cursors, selections,
+typing, "who's online", a handler's live progress: presence.
+
+Presence rides the session you already have: same contract, route, auth, and
+stream. A2 replicates each participant's latest field values to every
+subscriber and stores none of them in the log. Presence never appears in
+`history()`, `state()`, or a reducer's input type; never arms the scheduler,
+takes a claim, retries, or blocks an append; and never enters the browser
+cache.
+
+> **Presence repaints; the log replays.** Anything that decides (a fold,
+> a retry, an abort match) reads the log. Presence only hurries pixels.
+
+## Declare it in the contract
+
+`presence` is a second vocabulary next to `events`, one schema per field of a
+participant's state:
+
+```ts contracts.ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+
+export const canvas = a2.contract({
+  name: 'canvas',
+  events: {
+    'shape.created': z.object({
+      id: z.string(),
+      kind: z.enum(['rect', 'ellipse']),
+      x: z.number(),
+      y: z.number(),
+    }),
+    'shape.moved': z.object({ id: z.string(), x: z.number(), y: z.number() }),
+  },
+  reducer: { name: 'scene', initialState: {}, fold: (state) => state },
+  presence: {
+    cursor: z.object({ x: z.number(), y: z.number() }),
+    dragging: z.object({ shapeId: z.string(), x: z.number(), y: z.number() }),
+  },
+})
+```
+
+The field is the unit of replication: last writer wins per participant per
+field, so setting `cursor` leaves `dragging` alone. Fields are absent until
+set. They clear when set to `null` (pointer leaves the canvas, blur, unmount)
+or when their TTL lapses, so a closed tab disappears by silence, with no
+explicit leave. The TTL is 60 seconds by default; set
+`createServer({ presence: { ttlMs } })` to change it. Expiry counts on the
+backend's clock, not the sender's stamp.
+
+## The route
+
+```ts app/api/canvas-events/route.ts
+import { canvasServer } from '@/server/canvas'
+
+export const GET = canvasServer.fetch
+export const POST = canvasServer.fetch
+```
+
+This is the usual [`server.fetch` route](/server/routes). A contract with
+presence fields streams presence patches with events, starting with a snapshot
+of the current map, and its push body accepts an optional `presence` sibling
+to `events`, forwarded to `setPresence`. `authorize` sees the complete
+presence patch, including its caller-supplied participant id, over HTTP and
+WebSocket.
+
+`setPresence` validates each field against the contract, then broadcasts: no
+append, no dispatch, no log row. A bad field throws `INVALID_PAYLOAD` and an
+unknown one throws `UNKNOWN_PRESENCE_FIELD`, broadcasting nothing. A
+presence-only push acks `[]`.
+
+## The browser
+
+Presence needs a `participant` id, yours to mint: a user id, a tab nonce. Set
+it on `createClient({ participant })` when the app knows it at module scope,
+or on the Provider, whose `participant` prop overrides the client's. The
+session module is the usual [pair](/client/react#bind-react-once):
+
+```ts app/canvas/[canvasId]/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { canvas } from '@/contracts'
+
+export const canvasClient = createClient({
+  contract: canvas,
+  api: '/api/canvas-events',
+})
+export const { SessionProvider, useSession } = createReact({
+  client: canvasClient,
+})
+```
+
+```tsx app/canvas/[canvasId]/canvas-client.tsx
+'use client'
+import { useSession } from './session'
+
+export function CanvasClient() {
+  const { presence, setPresence } = useSession()
+
+  return (
+    <div
+      onPointerMove={(e) => setPresence({ cursor: { x: e.clientX, y: e.clientY } })}
+    >
+      {Object.entries(presence).map(([participant, fields]) =>
+        // render-time expiry: a cursor silent for a few seconds is gone
+        fields.cursor && Date.now() - fields.cursor.at.getTime() < 5_000 ? (
+          <Cursor key={participant} {...fields.cursor.value} />
+        ) : null,
+      )}
+    </div>
+  )
+}
+
+// your cursor sprite:
+// function Cursor({ x, y }: { x: number; y: number }) { ... }
+const Cursor = (props: { x: number; y: number }) => null
+```
+
+- **`setPresence(values)`** is fire-and-forget. It validates locally, merges
+  into the local map immediately, and coalesces on the wire: the first set
+  sends immediately, and later values within the interval merge per field
+  (latest wins, `null` included) into one trailing send. A 60Hz pointer
+  becomes about fifteen sends per second. No ack, no `confirmed`, no retry,
+  no rollback: nothing was ever true.
+- **`presence`** is the replicated map,
+  `Record<participantId, { [field]: { value, seen, at } }>`, including your
+  own participant. `at` is the sender's stamp for when the value was set and
+  the last-writer-wins comparator. The client stamps sends monotonically, so
+  overlapping sends never invert. How long to paint a value is view logic,
+  decided at render time.
+
+Both members are typed from the contract's `presence` map, with no type
+arguments. On a contract without `presence` they do not exist, so reaching
+for them is a compile error.
+
+## Reconciling the planes: `seen`
+
+Every presence value carries `seen`, the sender's stream frontier when it was
+set, stamped automatically. It orders the two planes without wall clocks.
+
+The classic race: a participant drags a shape (presence), drops it (event),
+and a stale `dragging` patch arrives after the durable `shape.moved`. Without
+a shared order, the shape flickers backward. With `seen`, superseding is one
+render-time rule:
+
+```ts
+// in render code: a ghost is dead once the log has moved past it.
+// show fields.dragging only if
+//   fields.dragging.seen >= state.shapes[fields.dragging.value.shapeId].movedAt
+// where movedAt is the index your reducer recorded for the last shape.moved
+```
+
+The durable event at index 214 beats any presence stamped 213 or lower. A2
+carries the stamp; the comparison is yours, in view code.
+
+## Handlers broadcast too
+
+`ctx.session.setPresence` is the same operation, so a handler can publish live
+progress without writing non-facts to the log:
+
+```ts server/canvas.ts
+import { createServer } from 'experimental-a2/server'
+import { canvas } from '@/contracts'
+
+export const canvasServer = createServer({
+  contract: canvas,
+  handlers: {
+    'shape.created': async (ctx) => {
+      // long work; broadcast progress as it goes:
+      // await ctx.session.setPresence({
+      //   participant: 'system:thumbnails',
+      //   values: { progress: { step: 2, of: 5 } },
+      // })
+    },
+  },
+})
+```
+
+The participant id is the handler's choice; a `system:` prefix keeps robots
+apart from humans in the map. When the work completes, append the outcome as
+an event: the progress was never a fact, the result is.
+
+## Backends
+
+Declaring `presence` requires a store with the presence capability;
+otherwise `createServer` throws `PRESENCE_NOT_SUPPORTED`. Every built-in
+store has it, at two tiers:
+
+| Backend | Delivery |
+| --- | --- |
+| `store-redis` | push: TTL'd hash plus pub/sub patches |
+| `store-redis-http` | push over HTTP subscriptions; adaptive polling when unsupported |
+| `store-memory` | in-process, immediate |
+| `store-postgres` | native notifications with `listenConnectionString`; adaptive polling by default |
+| `store-sqlite` | degraded: bounded TTL'd rows, read on the live feed's poll cadence |
+
+Degraded means later, not lost while watched. Presence-only traffic re-reads
+adaptively, from 25ms backing off to two seconds while unchanged; new patches
+or events restore the fast cadence. An idle remote viewer may wait up to two
+seconds plus query latency for the first change. Cursors want the push tier;
+typing indicators and progress read fine on either.
+
+Redis Pub/Sub does not broadcast TTL expiry: silent departures keep their
+last values in connected maps until a snapshot reconciles them, so expire at
+render time as above. Native Postgres subscriptions reconcile missing or
+expired fields on their ten-second safety reads.
+
+Presence rows are bounded per session and participant, so they are not log
+growth in disguise. On metered backends every patch is still a network
+operation.

package/docs/client/meta.ts

@@ -0,0 +1 @@
+export default { order: 4 }

package/docs/contract/01-events.mdx

@@ -0,0 +1,57 @@
+---
+title: Events
+description: "A contract names every event a session can hold, with a schema for each payload."
+---
+
+## Declare the events
+
+```ts contracts.ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+
+export const orders = a2.contract({
+  name: 'orders',
+  events: {
+    created: z.object({ shopId: z.string(), items: z.array(z.string()) }),
+    'shop.notified': z.object({}),
+    'shop.started': z.object({}),
+    'driver.notified': z.object({ driverId: z.string() }),
+    expired: z.object({}),
+  },
+})
+```
+
+A **contract** defines what can happen. A [session](/contract/sessions) is one
+instance of it.
+
+`name` identifies the contract everywhere: in storage, in queue messages, in
+logs. It keeps an app with several contracts unambiguous.
+
+`events` is the full vocabulary. Each key is an event name; each value is a
+schema for its payload. These docs use Zod, but any
+[Standard Schema](https://standardschema.dev) library works: Valibot, ArkType,
+your own.
+
+The contract is a plain, importable, **isomorphic** value. The server
+implements it with [handlers](/server/handlers), [reducers](/contract/state)
+derive the current view from it, and the browser types its pushes off it.
+
+## Validation
+
+Every append is validated against the contract. A bad payload throws
+`INVALID_PAYLOAD` before anything is written; an unknown type throws
+`UNKNOWN_EVENT_TYPE`. The log stores the validated output, with defaults
+applied and transforms run.
+
+## Presence
+
+A contract can also declare `presence`: ephemeral participant state (cursors,
+typing, live progress) that is replicated but never stored in the log. See
+[Presence](/client/presence).
+
+:::tip
+Events are facts, so name them in past tense: `created`, `expired`,
+`shop.notified`. A name that reads like a command (`notifyShop`) describes
+what a handler should do, not what happened. Dots are a naming convention, not
+a namespace.
+:::