experimental-a2 0.9.0 → 0.11.0

package/src/actor-react.ts

@@ -41,6 +41,7 @@ import type { A2Client, Connection } from './client.ts'
 import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'
 import type { Reducer } from './reducer.ts'
 import { useSession } from './react.ts'
+import { useMemo } from 'react'
 
 /** The server-to-client handoff: `await def.actor(id).state()`. */
 export type ActorSnapshot<S> = { state: S; index: number }
@@ -66,13 +67,14 @@ type PresenceOf<D extends AnyActorDefinition> = D extends {
   : never
 
 export type UseActorResult<D extends AnyActorDefinition, View> = {
-  /** The actor's state, live: every commit streams in and replaces it. */
+  /** The live view, advanced by call answers, refreshes, and stream commits. */
   state: View
-  /** The stream frontier. */
+  /** The latest adopted state index. */
   index: number
   connection: Connection
   /** Typed calls over POST — the response is the answer. */
   call: ActorClientCall<D, View>
+  refresh: () => Promise<ActorSnapshot<View>>
   /** The state-commit feed this browser has observed. */
   events: ContractEvent<EventDefs>[]
   /**
@@ -128,12 +130,25 @@ export function useActor<D extends AnyActorDefinition, View = ActorStateOf<D>>(
       ? {}
       : { participant: options.participant }),
   })
-  const { call } = createActorClient<D, View>({ api })
+  const { call, state: refresh } = useMemo(
+    () =>
+      createActorClient<D, View>({
+        api,
+        onSnapshot: ({ state, index }) => {
+          client.session(options.id, {
+            initialState: state,
+            initialIndex: index,
+          })
+        },
+      }),
+    [api, client, options.id],
+  )
   return {
     state: session.state as View,
     index: session.index,
     connection: session.connection,
     call,
+    refresh,
     events: session.events,
     presence: session.presence as ActorPresenceMap<PresenceOf<D>>,
     setPresence: session.setPresence as (

package/src/actor.ts

@@ -169,9 +169,10 @@ export type ActorOptions<D extends ActorProtocol> = {
 /**
  * One HTTP operation `handle.fetch` is about to serve — the actor
  * mirror of core's `A2Operation`. `authorize` sees it before any
- * write or subscription; returning `false` answers 403.
+ * read, write, or subscription; returning `false` answers 403.
  */
 export type ActorOperation =
+  | { readonly type: 'state'; readonly id: string }
   | {
       readonly type: 'stream'
       readonly id: string
@@ -736,6 +737,19 @@ export function actor<D extends ActorProtocol>(
 
       if (request.method === 'GET') {
         const url = new URL(request.url)
+        if (url.searchParams.has('snapshot')) {
+          if (!(await authorized({ type: 'state', id }))) return forbidden()
+          const result = await readState()
+          return Response.json(
+            {
+              state: fetchOptions?.view
+                ? applyView(fetchOptions.view, result.state)
+                : result.state,
+              index: result.index,
+            },
+            { headers: { 'cache-control': 'private, no-store' } },
+          )
+        }
         const raw = Number(url.searchParams.get('index'))
         const startAfter = Number.isSafeInteger(raw) && raw >= 0 ? raw : 0
         if (!(await authorized({ type: 'stream', id, startAfter }))) {
@@ -851,6 +865,7 @@ export function actor<D extends ActorProtocol>(
                 index: result.index,
               }
             : result,
+          { headers: { 'cache-control': 'private, no-store' } },
         )
       } catch (error) {
         if (error instanceof ActorRefusedError) {

package/src/client-errors.ts

@@ -0,0 +1,51 @@
+import { A2Error, type A2ErrorCode } from './errors.ts'
+
+export type A2ClientErrorOptions = {
+  details?: unknown
+  cause?: unknown
+  status?: number
+  closeCode?: number
+  closeReason?: string
+  phase?: 'stream' | 'subscribe'
+  timeoutMs?: number
+}
+
+export class A2ClientError extends A2Error {
+  readonly status: number | undefined
+  readonly closeCode: number | undefined
+  readonly closeReason: string | undefined
+  readonly phase: 'stream' | 'subscribe' | undefined
+  readonly timeoutMs: number | undefined
+
+  constructor(
+    code: A2ErrorCode,
+    message: string,
+    options?: A2ClientErrorOptions,
+  ) {
+    super(code, message, options)
+    this.name = 'A2ClientError'
+    this.status = options?.status
+    this.closeCode = options?.closeCode
+    this.closeReason = options?.closeReason
+    this.phase = options?.phase
+    this.timeoutMs = options?.timeoutMs
+  }
+}
+
+export function asClientError(
+  error: unknown,
+  options?: { code?: A2ErrorCode },
+): A2ClientError {
+  if (error instanceof A2ClientError) return error
+  if (error instanceof A2Error) {
+    return new A2ClientError(error.code, error.message, {
+      details: error.details,
+      cause: error,
+    })
+  }
+  return new A2ClientError(
+    options?.code ?? 'UNKNOWN',
+    error instanceof Error ? error.message : 'client operation failed',
+    { cause: error },
+  )
+}