experimental-a2 0.8.1 → 0.9.0

package/docs/actors/04-routes.mdx

@@ -0,0 +1,352 @@
+---
+title: Routes, clients, and React
+description: "One route serves an instance: GET streams live state, POST answers calls. Authorize per operation, project per mount, and mount it in React with one hook."
+---
+
+## The actor for this page
+
+A vault with one internal field, so the projection section below has
+something to hide:
+
+```ts vault.ts
+import { NonRetriableError } from 'experimental-a2'
+import { actor } from 'experimental-a2/actor'
+
+interface Vault {
+  state: {
+    balance: number
+    /** Internal bookkeeping; not for subscribers. */
+    audit: string[]
+  }
+  events: {
+    deposit: { amount: number }
+    withdraw: { amount: number }
+  }
+}
+
+export type VaultState = Vault['state']
+
+export const vault = actor<Vault>({
+  name: 'vault',
+  state: { balance: 0, audit: [] },
+  handlers: {
+    deposit: (ctx, input) => {
+      ctx.state.balance += input.amount
+      ctx.state.audit.push(`deposit ${input.amount}`)
+    },
+    withdraw: (ctx, input) => {
+      if (ctx.state.balance < input.amount) {
+        throw new NonRetriableError('insufficient funds')
+      }
+      ctx.state.balance -= input.amount
+      ctx.state.audit.push(`withdraw ${input.amount}`)
+    },
+  },
+})
+```
+
+## The route
+
+`handle.fetch` serves one instance over HTTP. Your route authenticates
+and picks the instance; the library serves the rest.
+
+```ts app/vault/[vaultId]/route.ts
+import { vault } from '@/vault'
+
+async function respond(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  // here's where you'd do auth, or any other checks
+  return vault.actor(vaultId).fetch(request)
+}
+
+export const GET = respond
+export const POST = respond
+```
+
+`GET` is the live stream: a server-sent events response of the
+instance's state commits, resumed after the `index` query parameter,
+with heartbeats. The stream carries state and nothing else: subscribers
+see what the actor is, never other callers' inputs, and a refusal
+answers only its caller. The full mailbox stays server-side.
+
+`POST` is the call lane. The body names a declared event:
+
+```json
+{ "event": "deposit", "input": { "amount": 100 }, "messageId": "m-1" }
+```
+
+The response is the answer: `{ state, index }` on success, `409` with
+the refusal's message when the handler says no, `400` for an undeclared
+event. `messageId` is optional; send one to make retrying the request
+idempotent.
+
+## Authorize
+
+`authorize` is per-operation policy, checked before any write or
+subscription. Authentication (who is asking) stays in your route;
+`authorize` decides whether this operation is allowed.
+
+```ts
+// app/vault/[vaultId]/route.ts, now with per-operation policy:
+import { vault } from '@/vault'
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  return vault.actor(vaultId).fetch(request, {
+    authorize: (operation) =>
+      operation.type === 'call' && operation.event !== 'withdraw',
+  })
+}
+```
+
+The operation is a discriminated union: `{ type: 'stream', id,
+startAfter }` for subscriptions, `{ type: 'call', id, event, input,
+messageId? }` for calls. Returning `false` answers `403`.
+
+## Views: what each mount shows
+
+State can be mixed-audience: internal bookkeeping next to public
+fields. The definition stays audience-blind; audiences are a route
+concern, like auth. A `view` is a request-time projection applied to
+everything that mount serves: every state frame on the stream and
+every call answer (the two must agree, or the call lane would leak
+what the stream hides).
+
+```ts
+// app/vault/[vaultId]/public/route.ts, a projected mount of the same actor:
+import { vault } from '@/vault'
+
+export async function GET(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  return vault.actor(vaultId).fetch(request, {
+    view: (state) => ({ balance: state.balance }),
+  })
+}
+```
+
+Different routes project the same actor differently: an admin mount
+with no view sees everything, the public mount above hides `audit`.
+Per-viewer views need no extra machinery, because the route already
+holds the identity; a closure does it
+(`view: (state) => ({ ...visible, mine: state.perUser[user.id] })`).
+View output holds to the same plain-JSON floor as state itself.
+
+Views are for internal-but-not-secret fields. Secrets do not belong in
+state at all: state commits are log rows, and the log is forever. Keep
+secrets outside, pass references, resolve them inside handlers.
+
+## Any client
+
+`createActorClient` is the typed call surface over that route's `POST`
+lane. It works anywhere: browsers, other frameworks, other servers.
+
+```ts
+// in the browser, or any client at all:
+import {
+  ActorRefusedError,
+  createActorClient,
+} from 'experimental-a2/actor/client'
+import type { vault } from '@/vault'
+
+const savings = createActorClient<typeof vault>({ api: '/vault/savings' })
+
+try {
+  const { state } = await savings.call.deposit({ amount: 100 })
+  // state is the answer: the fold after this deposit
+} catch (error) {
+  if (error instanceof ActorRefusedError) {
+    // the server's refusal, revived with its message
+  }
+}
+```
+
+The import of `vault` is type-only, so it is erased at build time: the
+server module never enters a client bundle. On a view-projected mount,
+pass the projected shape as the second type argument
+(`createActorClient<typeof vault, PublicVault>`) so answers carry it.
+
+## React
+
+One hook. The server component hands down the first fold, the hook
+keeps it live and exposes the same typed calls.
+
+```tsx app/vault/[vaultId]/page.tsx
+import { vault } from '@/vault'
+import { VaultClient } from './vault-client'
+
+export default async function VaultPage({
+  params,
+}: {
+  params: Promise<{ vaultId: string }>
+}) {
+  const { vaultId } = await params
+  const initial = await vault.actor(vaultId).state()
+  return <VaultClient vaultId={vaultId} initial={initial} />
+}
+```
+
+```tsx app/vault/[vaultId]/vault-client.tsx
+'use client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { vault, VaultState } from '@/vault'
+
+export function VaultClient({
+  vaultId,
+  initial,
+}: {
+  vaultId: string
+  initial: ActorSnapshot<VaultState>
+}) {
+  const { state, call, connection } = useActor<typeof vault>({
+    api: `/vault/${vaultId}`,
+    id: vaultId,
+    initial,
+  })
+
+  return (
+    <div>
+      <p>
+        Balance: {state.balance}
+        {connection.status === 'live' ? '' : ' (reconnecting)'}
+      </p>
+      <button onClick={() => void call.deposit({ amount: 25 })}>
+        Deposit $25
+      </button>
+    </div>
+  )
+}
+```
+
+What the hook gives you:
+
+- **`state`**: the live view. Every commit streams in and replaces it;
+  the fold is library code, so no reducers, schemas, or contracts
+  appear in browser code.
+- **`call`**: the same typed surface as `createActorClient`, because it
+  is one; `useActor` is a thin React wrapper over the client primitive
+  and the stream.
+- **`index`**: the stream frontier, and **`events`**: the state-commit
+  feed this browser has observed, for activity-feed UI.
+- **`connection`**: the same discriminated union as
+  [`useSession`](/guides/react#the-client-component), heartbeat
+  watchdog included.
+
+Live, not optimistic. Handlers are server code deciding against
+serialized fresh state, so there is nothing correct for the browser to
+apply early; a local guess would be wrong exactly when the actor
+matters. If a control needs pending UI, `await call.deposit(...)` is a
+promise like any other.
+
+On a view-projected mount, pass the projected shape as the second type
+argument (`useActor<typeof vault, PublicVault>`); `initial`, `state`,
+and the call answers all carry it.
+
+## Presence
+
+Who is here, live: cursors, names, viewer counts. Presence is
+ephemeral audience state. It replicates to the instance's subscribers
+and expires; it never enters the log, and handlers cannot see it (an
+actor decides from its log, never from who is watching).
+
+Declare the vocabulary in the protocol as types, and arm the wire with
+`presence: true`:
+
+```ts board.ts
+import { actor } from 'experimental-a2/actor'
+
+interface Board {
+  state: { strokes: number }
+  events: { draw: { path: string } }
+  presence: { cursor: { x: number; y: number }; name: string }
+}
+
+export const board = actor<Board>({
+  name: 'board',
+  state: { strokes: 0 },
+  presence: true,
+  handlers: {
+    draw: (ctx) => {
+      ctx.state.strokes += 1
+    },
+  },
+})
+```
+
+The route does not change: the same `GET` stream interleaves presence
+updates between state commits, and the same `POST` lane accepts
+presence announcements. In React, pass a `participant` identity and
+use the map:
+
+```tsx app/board/[boardId]/board-client.tsx
+'use client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { board } from '@/board'
+
+export function BoardClient({
+  boardId,
+  initial,
+  user,
+}: {
+  boardId: string
+  initial: ActorSnapshot<{ strokes: number }>
+  user: string
+}) {
+  const { presence, setPresence } = useActor<typeof board>({
+    api: `/board/${boardId}`,
+    id: boardId,
+    initial,
+    participant: user,
+  })
+
+  return (
+    <div
+      onPointerMove={(event) =>
+        setPresence({ cursor: { x: event.clientX, y: event.clientY } })
+      }
+    >
+      {Object.keys(presence).length} here
+    </div>
+  )
+}
+```
+
+`setPresence` is fire-and-forget: throttled on the way out, resent
+after a reconnect, `null` clears a field. The map holds each
+participant's latest fields with their stamps; how long a value stays
+painted is render logic, decided against `at`.
+
+Three guards stand where presence enters, and none of them is a
+schema:
+
+- **Types**: the protocol types `setPresence` and the map, so honest
+  clients cannot send the wrong shape.
+- **The floor**: the library rejects values that are not plain JSON
+  trees, values over 8 KB, and object-plumbing field names.
+- **`authorize`**: every announcement arrives as
+  `{ type: 'presence', id, participant, values }` before it is
+  accepted. Clamp, verify the participant matches the authenticated
+  user, or rate-limit here.
+
+What no guard does is make peer values trustworthy. Presence is
+authored by whoever holds a connection: render it like user input.
+
+## The session wire underneath
+
+`handle.fetch` serves the actor's two lanes and nothing else. When you
+want the raw session protocol instead (the full event feed, pushes,
+presence, the `ws` transport), the definition exposes the underlying
+server: mount `def.server.fetch` and use the core
+[client](/guides/react) against it. That wire shows the whole mailbox
+to its subscribers, inputs included, so reserve it for trusted
+audiences.

package/docs/actors/meta.ts

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

package/docs/concepts/meta.ts

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

package/docs/guides/meta.ts

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

package/docs/index.mdx

@@ -281,6 +281,9 @@ public package entry points. See [Complete examples](/guides/examples).
   <Card title="A2 and your database" href="/guides/application-data" icon="database">
     Decide what belongs in a session and what belongs in ordinary tables.
   </Card>
+  <Card title="Actors" href="/actors/introduction" icon="boxes">
+    Durable objects on the log: typed state, one message at a time.
+  </Card>
   <Card title="Complete examples" href="/guides/examples" icon="code">
     Read or copy the standalone Next.js playground included with the package.
   </Card>

package/docs/reference/02-errors.mdx

@@ -58,6 +58,39 @@ contains the same id twice, and an id that was already used in a
 *different* session (event ids are globally unique). In every case,
 nothing is written.
 
+## NonRetriableError
+
+The second exported error class. Throw it (or a subclass, matched by
+`instanceof`) from a handler when the failure is deterministic: the
+event dead-letters immediately instead of consuming the ten-failure
+retry budget, because a guard that refuses this attempt will refuse
+every retry identically. Any other thrown error keeps the ordinary
+retry contract.
+
+```ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+import { NonRetriableError } from 'experimental-a2'
+import { createServer } from 'experimental-a2/server'
+
+const orders = a2.contract({
+  name: 'orders',
+  events: { created: z.object({ chargeable: z.boolean() }) },
+})
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event }) => {
+      if (!event.payload.chargeable) {
+        throw new NonRetriableError('this order cannot be charged')
+      }
+      // transient failures below retry as usual
+    },
+  },
+})
+```
+
 ## What append never throws for
 
 - **A failing handler.** Appends always land; handler failures are retried

package/docs/reference/meta.ts

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

package/examples/playground/app/page.tsx

@@ -6,7 +6,7 @@ export default function HomePage(): ReactNode {
     <article>
       <h1>A durable event log, live in your browser</h1>
       <p className="lede">
-        Seven small demos, one model: append an event, let a handler react, fold
+        Eight small demos, one model: append an event, let a handler react, fold
         the log into a view — on the server for the first paint, in the browser
         for every moment after.
       </p>
@@ -64,6 +64,15 @@ export default function HomePage(): ReactNode {
             under a fresh claim.
           </p>
         </Link>
+        <Link className="card" href="/vault">
+          <h2>Vault (actor)</h2>
+          <p>
+            A durable actor: send messages to one vault's mailbox, watch it
+            process them one at a time against its state — serialized
+            read-modify-write, refusals as answers, and the whole transcript in
+            the log. Built on <code>experimental-a2/actor</code>.
+          </p>
+        </Link>
         <Link className="card" href="/counter">
           <h2>Counter</h2>
           <p>

package/examples/playground/app/vault/[vaultId]/route.ts

@@ -0,0 +1,19 @@
+/**
+ * The vault's ingress — the actor mirror of `server.fetch`: your route
+ * authenticates and picks the instance, `handle.fetch` serves the rest
+ * (GET → the state-plane SSE, POST → the call lane).
+ */
+import { vault } from '../server'
+
+async function respond(
+  request: Request,
+  context: { params: Promise<{ vaultId: string }> },
+): Promise<Response> {
+  const { vaultId } = await context.params
+  // here's where you'd authenticate; per-operation policy goes in
+  // fetch's { authorize } option
+  return vault.actor(vaultId).fetch(request)
+}
+
+export const GET = respond
+export const POST = respond

package/examples/playground/app/vault/page.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react'
+import { vault } from './server'
+import { VaultClient } from './vault-client'
+
+export const dynamic = 'force-dynamic'
+
+const VAULT_ID = 'shared'
+
+export default async function VaultPage(): Promise<ReactNode> {
+  const initial = await vault.actor(VAULT_ID).state()
+  return <VaultClient vaultId={VAULT_ID} initial={initial} />
+}

package/examples/playground/app/vault/server.ts

@@ -0,0 +1,9 @@
+import 'server-only'
+import { store } from '@/lib/store'
+import { createVault } from './vault'
+
+export type { VaultState } from './vault'
+
+export const vault: ReturnType<typeof createVault> = createVault(
+  store ? { store } : {},
+)

package/examples/playground/app/vault/vault-client.tsx

@@ -0,0 +1,124 @@
+'use client'
+import type { ReactNode } from 'react'
+import { useEffect, useState } from 'react'
+import { ActorRefusedError } from 'experimental-a2/actor/client'
+import { useActor } from 'experimental-a2/actor/react'
+import type { ActorSnapshot } from 'experimental-a2/actor/react'
+import type { vault, VaultState } from '@/app/vault/server'
+import { ActivityFeed } from '@/app/components/activity-feed'
+import { ConnectionPill } from '@/app/components/connection-pill'
+
+const ACTIVITY_LIMIT = 50
+
+export function VaultClient({
+  vaultId,
+  initial,
+}: {
+  vaultId: string
+  initial: ActorSnapshot<VaultState>
+}): ReactNode {
+  const [participant] = useState(
+    () => `guest-${Math.random().toString(36).slice(2, 8)}`,
+  )
+  const { state, call, events, index, connection, presence, setPresence } =
+    useActor<typeof vault>({
+      api: `/vault/${vaultId}`,
+      id: vaultId,
+      initial,
+      participant,
+    })
+  const [answer, setAnswer] = useState<string | null>(null)
+
+  useEffect(() => {
+    setPresence({ viewing: true })
+  }, [setPresence])
+  const here = Object.keys(presence).length
+
+  const run = async (invoke: () => Promise<unknown>): Promise<void> => {
+    try {
+      await invoke()
+      setAnswer(null)
+    } catch (err) {
+      setAnswer(
+        err instanceof ActorRefusedError
+          ? err.message
+          : err instanceof Error
+            ? err.message
+            : String(err),
+      )
+    }
+  }
+
+  // deployed state may predate the `pending` field
+  const pending = Object.entries(state.pending ?? {})
+  const visibleEvents = events.slice(-ACTIVITY_LIMIT)
+
+  return (
+    <article>
+      <header className="session-header">
+        <h1>Vault</h1>
+        <ConnectionPill connection={connection} />
+        <span className="badge live">shared</span>
+        {here > 1 ? <span className="badge">{here} viewing</span> : null}
+      </header>
+      <p className="lede">
+        One durable actor per vault id — serial brain, concurrent muscle. A
+        withdrawal is a saga: the action <em>reserves</em> instantly (balance
+        drops, a pending transfer appears), a <em>task</em> runs the slow
+        2-second transfer off the lane, and its result comes back as a message
+        that <em>settles</em> or <em>refunds</em>. The lane is never blocked:
+        keep depositing while transfers are in flight.
+      </p>
+
+      <section className="counter-panel" aria-label="Vault controls">
+        <output className="counter-value" aria-live="polite">
+          ${state.balance}
+        </output>
+        <div className="counter-actions">
+          <button
+            type="button"
+            onClick={() => void run(() => call.deposit({ amount: 25 }))}
+          >
+            Deposit $25
+          </button>
+          <button
+            type="button"
+            className="secondary"
+            onClick={() => void run(() => call.withdraw({ amount: 60 }))}
+          >
+            Withdraw $60
+          </button>
+          <button
+            type="button"
+            className="secondary"
+            onClick={() => void run(() => call.withdraw({ amount: 19 }))}
+          >
+            Withdraw $19 (bounces)
+          </button>
+        </div>
+        <p className="hint" aria-live="polite">
+          {pending.length > 0
+            ? `${pending.length} transfer${pending.length === 1 ? '' : 's'} in flight: ${pending
+                .map(([, amount]) => `$${amount}`)
+                .join(', ')}`
+            : `${state.deposits} deposits, ${state.withdrawals} settled withdrawals`}
+        </p>
+      </section>
+
+      {answer ? <p className="error">refused: {answer}</p> : null}
+      <p className="hint">
+        Watch the state plane below narrate the saga: <code>withdraw</code> (the
+        reserve commits with the transfer trigger, atomically), then two seconds
+        later <code>settle</code> — or <code>refund</code> for amounts ending in
+        9, the demo bank&apos;s bounce policy. Withdrawing more than the balance
+        is refused instantly by the guard; the reserve means in-flight transfers
+        can never oversell the balance, from any number of tabs.
+      </p>
+
+      <ActivityFeed events={visibleEvents} index={index} />
+      {events.length > ACTIVITY_LIMIT ? (
+        <p className="hint">Showing the latest {ACTIVITY_LIMIT} events.</p>
+      ) : null}
+    </article>
+  )
+}