experimental-a2 0.17.0 → 0.18.0

package/docs/guides/03-react.mdx

@@ -1,324 +0,0 @@
----
-title: Live UI with React
-description: "Start from a snapshot, fold new events, and push optimistic writes through one shared session."
----
-
-## One session, one state
-
-A contract can publish one reducer. The client starts from a snapshot of
-that state and folds subsequent events locally. Initial data from a server
-component is optional. Without it, the server sends a snapshot as the first
-data frame of the subscription, then streams events after its index.
-
-The same connection carries bootstrap and live events, over SSE or WebSocket.
-Events appended while the snapshot is read remain in the durable log and
-are delivered after its index. Reconnecting resumes after the last delivered
-position without fetching another snapshot.
-
-This is session sync. A client follows a known session ID. Keep collection
-queries across sessions in your [application database](/guides/application-data).
-
-## 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,
-  },
-})
-```
-
-The reducer name identifies its snapshot format. Change it when the fold's
-meaning or stored shape changes. The server and client must use the same
-version. A fold returning a discriminated union may need `as const` on a
-returned literal or an explicit return type. The standalone `reducer`
-builder fixes the state type before its `.fold()` call.
-
-Additional server-side reducers can be read with `session.state(reducer)`;
-those reads do not publish another 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 bounded history reads. `POST` appends
-writes. Wrap `server.fetch` with its `authorize` option for application
-checks. Bootstrap is authorized as a stream operation with `bootstrap: true`
-before reading state.
-
-## Bind React once
-
-The factory binds the client's types into the Provider and hook. It does
-not create a 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>}
-    </>
-  )
-}
-```
-
-`state` has the reducer's client state type. A supplied snapshot seeds the
-first render; otherwise the client displays `reducer.initialState` (through
-the reducer's client projection when present). The connection snapshot
-replaces that seed atomically, then new events update it. The seed can look
-empty while an existing session loads. Supply a server snapshot to render
-its current state immediately.
-
-`connection` stays `connecting` until bootstrap completes. Failures use its
-existing error and retry policy. A slow snapshot can keep loading while the
-connection sends heartbeats. The ordinary stream stall watchdog handles a
-silent connection. A reconnect preserves the last state.
-
-A push made during bootstrap is sent right away; it does not wait for the
-snapshot. Its optimistic update appears once the snapshot is applied. If
-the push was already sent when the snapshot arrives and has no
-acknowledgement yet, it stays hidden until the acknowledgement arrives,
-because the snapshot may already contain it. Pushes queued behind it stay
-hidden with it, so the view never skips a write. As usual, the push promise
-resolves on the server acknowledgement; `.confirmed` waits for delivery
-through the stream, and the bootstrap snapshot counts as delivery through
-its index.
-
-## Without server rendering
-
-A Provider only needs 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>
-  )
-}
-```
-
-You can also omit 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>
-  )
-}
-```
-
-The direct `useSession(client, sessionId, options?)` export is available
-when you do not use the factory. It has the same bootstrap and connection
-ownership behavior.
-
-## 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 this state already includes events through 10. The stream
-starts after 10. Index 0 is valid when paired with the reducer's initial
-state; that explicitly requests replay from the beginning. An index by
-itself cannot describe a reducer state.
-
-A standalone hook can receive the same pair as `initial`. Omitting
-it enables automatic bootstrap. For an asynchronous server read, pass its
-Promise as described below.
-
-SSR uses render-local snapshots. One request's seed does not modify another
-request's state, and browser hydration first renders the supplied snapshot
-even when the shared browser cache has already advanced.
-
-`hydrated` distinguishes the reducer seed from a known state/index snapshot.
-It is `false` until a supplied snapshot or subscription bootstrap initializes
-the session, including while a cold preload is pending or rejected. A snapshot
-at index 0 counts. Once initialized, it stays `true` through disconnections,
-reconnects, and disabled readers while the session retains its state. A new
-session without a seed starts at `false` again.
-
-Use `hydrated` when a decision needs initialized state, such as distinguishing
-an empty queue from one that has not loaded. `connection` describes the
-transport independently. A hydrated snapshot may be stale and does not imply
-permission to write. Imperative code reads the same flag from
-`client.session(id).getSnapshot().hydrated`.
-
-## Start a preload on the server
-
-`initial` also accepts a stable Promise of a snapshot. A pending preload
-blocks only cold startup: A2 waits before opening its subscription, displaying
-`reducer.initialState` without suspending the UI by default. A snapshot result
-replaces that seed and skips the
-bootstrap read. A `null` or `undefined` result uses ordinary subscription
-bootstrap. No additional request is started to resolve the Promise.
-
-```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 rejected cold preload pauses startup and reports its error through
-`connection`. A2 cannot retry an externally created Promise: supply a new
-Promise, a snapshot, or `null` to continue. The caller can catch a preload
-failure and return `null` when bootstrap fallback is appropriate.
-
-A warm session keeps its state and connection while another initial Promise
-is pending. A newer successful snapshot follows the normal hydration rules;
-a rejected late preload does not disrupt a working session. Replaced sources
-and hard close invalidate pending results, including deferred hydration.
-Unmounting releases that hook's connection lease; it does not cancel the
-caller's fetch. Within a cached session, repeating the same Promise does not
-restart cancelled work.
-
-Each hook can opt into React Suspense with `useSession({ suspend: true })`.
-It reads the supplied Promise with React `use()`. The nearest Suspense and
-Error boundaries handle its pending and rejected states. The Provider itself
-does not suspend. Without a Promise, or when it resolves to no snapshot,
-ordinary subscription bootstrap displays the reducer seed without suspending.
-`enabled` continues to control connection ownership separately.
-
-A non-suspending preload renders the reducer seed on the server. Await the
-snapshot upstream or use the suspending hook within an appropriate boundary
-to render the loaded session in the server response. Keep
-Promise identity stable across client renders; do not create it inside the
-component that consumes it.
-
-## Connections and activation
-
-Hooks using the same client instance and session ID share one runtime,
-connection, state, and optimistic queue. Providers do not determine deduplication.
-Another client instance is isolated, even when its URL matches.
-
-`useSession({ enabled: false })` observes cached or initial data without
-acquiring an automatic connection lease. The default is `true`. Disabling
-or unmounting a hook releases only its own lease. Another enabled consumer
-continues normally. Explicit pushes still work and acquire a connection
-when needed; disabling is not an authorization boundary.
-
-The bound hook accepts `sessionId`, `client`, `participant`, `initial`,
-`enabled`, and `suspend` options. Initial data and participant defaults are inherited
-only when the resolved client and session ID match the Provider's scope.
-
-## Events and history
-
-`useSession()` returns `state`, `events`, `index`, `connection`, `push`,
-`reconnect`, `loadHistory`, and `history`. Presence contracts also return
-`presence` and `setPresence`.
-
-`events` contains supplied history, loaded history, received events, and
-pending optimistic events. A bootstrap snapshot does not invent historical
-rows. Without `initialEvents`, the array starts empty and receives events
-after the snapshot's index.
-
-`loadHistory({ before, limit })` reads older log entries into that array.
-Omit the options to load up to 50 events before the oldest loaded event.
-History reads do not change state or rewind the live cursor. `history`
-reports loading, the oldest loaded index, and whether the beginning is
-loaded. History reads currently require the HTTP transport.
-
-The array is an in-memory collection, not a paginated projection. Long-lived
-sessions can accumulate many events; a state snapshot bounds replay work,
-not the size of state or retained history.

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

@@ -1,47 +0,0 @@
----
-title: Client lifetime
-description: "Share an in-memory session, control idle eviction, and resume its event stream."
----
-
-## Reuse a client
-
-Keep the client in a module so components share session identity, state,
-raw events, pending writes, and connection ownership:
-
-```ts app/session-client.ts
-'use client'
-import { createClient } from 'experimental-a2/client'
-import { orders } from '@/contracts'
-
-export const ordersClient = createClient({
-  contract: orders,
-  api: '/api/order-events',
-  gcTime: 5 * 60 * 1_000,
-})
-```
-
-`gcTime` is the idle eviction delay, five minutes by default. Active
-connections, listeners, and pending work keep the runtime alive. Another
-client instance has a separate cache even when it uses the same URL.
-
-## Startup and reconnect
-
-A new unseeded session receives a snapshot on its event subscription.
-A supplied state/index pair skips that read. A cached session keeps its
-state and resumes after its delivered event position. See
-[Live UI](/guides/react).
-
-State snapshots bound replay work, not the size of the reducer state or
-raw event collection. Choose reducer contents that fit the application.
-
-## Persistence
-
-This cache is in memory. Reloading the page discards it. A2 does not ship
-an IndexedDB adapter or a persistent offline write queue. The
-`experimental-a2/cache-indexeddb` entry point currently has no implementation.
-
-Pushes have bounded retries and optimistic rollback when they fail.
-Application-owned persistence can restore a state/index pair through the
-normal hydration options. Only restore data belonging to the same session
-and reducer version, and keep authentication and retained-data policy in
-the application.