experimental-a2 0.3.0 → 0.5.0

package/src/react.ts

@@ -0,0 +1,284 @@
+'use client'
+/**
+ * experimental-a2/react — React bindings over experimental-a2/client.
+ *
+ * `createReact({ client })` is a factory (like createContext): call it
+ * once in a `'use client'` module with a shared A2 client and export the
+ * bound pair. Server components import `SessionProvider` from that module
+ * as a client reference; client components import `useSession` from the
+ * same file. The shared client also makes imperative pushes and provider
+ * renders resolve the same live session. Everything is typed by the
+ * reducer value — no type arguments, and nothing here ever touches the
+ * machine module.
+ */
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+import {
+  createClient,
+  type A2Client,
+  type Connection,
+  type HistoryState,
+  type LoadHistoryOptions,
+  type PushResult,
+  type SessionClient,
+  type SessionClientPresence,
+  type SessionSnapshot,
+} from './client.ts'
+import type {
+  AppendInput,
+  ContractEvent,
+  EventDefs,
+  PresenceDefs,
+  PresenceMap,
+  PresencePatch,
+  WithPresence,
+} from './contract.ts'
+import type { Reducer } from './reducer.ts'
+
+export type SessionProviderProps<D extends EventDefs, S> = {
+  /** Which session to subscribe to. */
+  sessionId: string
+  /** Base path of the route exposing GET (stream) and POST (push). */
+  api: string
+  /** The server-rendered fold — the first paint, no client JS needed. */
+  initialState: S
+  /** The fold's frontier — the stream resumes exactly there. */
+  initialIndex: number
+  /** Server-rendered event history through `initialIndex`. */
+  initialEvents?: ContractEvent<D>[]
+  /**
+   * This client's presence identity — required to call `setPresence`.
+   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
+   * not invent an identity story.
+   */
+  participant?: string
+  children?: ReactNode
+}
+
+export type BoundSessionProviderProps<D extends EventDefs, S> = Omit<
+  SessionProviderProps<D, S>,
+  'api'
+>
+
+/**
+ * The presence members of the hook result — intersected in via
+ * `WithPresence`, so they exist exactly when the contract declares
+ * presence fields (the reducer is the client's typed handle on it).
+ */
+export type UseSessionPresence<P extends PresenceDefs> = {
+  /** The replicated presence map, this client included (local echo). */
+  presence: PresenceMap<P>
+  /**
+   * Fire-and-forget: validated locally, echoed into the map
+   * immediately, coalesced on the wire to a fixed cadence (a leading
+   * send immediately, then at most one merged send per interval;
+   * later values win per field), stamped with the frontier at send
+   * time as `seen`. Requires the provider's `participant`.
+   */
+  setPresence: (values: PresencePatch<P>['values']) => void
+}
+
+export type UseSessionResult<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = WithPresence<P, UseSessionPresence<P>> & {
+  /** The live view, folded through the shared reducer. */
+  state: S
+  /** The raw event feed — observed, seeded, or backscrolled. */
+  events: ContractEvent<D>[]
+  /** The stream frontier — `lastSeenIndex` for cancellation. */
+  index: number
+  /**
+   * The connection, as a discriminated union — `error` exists only
+   * while disconnected; "reconnecting…" is
+   * `status === 'connecting' && reconnects > 0`.
+   */
+  connection: Connection
+  /**
+   * Typed optimistic append. Awaiting it gives the server ack;
+   * `.confirmed` resolves when the live stream has delivered the batch
+   * back. Rejects with the server's A2Error codes.
+   */
+  push: (...events: AppendInput<D>[]) => PushResult<D>
+  /**
+   * Backscroll: fetch a bounded slice of older events into `events`.
+   * Defaults page backward 50 at a time from the oldest loaded event.
+   * Display data only — `state` and the optimistic overlay never move.
+   */
+  loadHistory: (options?: LoadHistoryOptions) => Promise<ContractEvent<D>[]>
+  /** Backscroll progress: `complete` means the feed reaches index 1. */
+  history: HistoryState
+}
+
+export type A2React<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement
+  useSession: () => UseSessionResult<D, S, P>
+}
+
+export type BoundA2React<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement
+  useSession: () => UseSessionResult<D, S, P>
+}
+
+export function createReact<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+>(options: { client: A2Client<D, S, P> }): BoundA2React<D, S, P>
+export function createReact<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+>(options: { reducer: Reducer<D, S, P> }): A2React<D, S, P>
+export function createReact<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+>(
+  options: { client: A2Client<D, S, P> } | { reducer: Reducer<D, S, P> },
+): BoundA2React<D, S, P> | A2React<D, S, P> {
+  const Context = createContext<SessionClient<D, S, P> | null>(null)
+  const providerMounts = new WeakMap<SessionClient<D, S, P> & object, number>()
+  const resolveSession: (
+    sessionId: string,
+    api: string | undefined,
+    initialState: S,
+    initialIndex: number,
+    initialEvents: ContractEvent<D>[] | undefined,
+    participant: string | undefined,
+  ) => SessionClient<D, S, P> =
+    'client' in options
+      ? (
+          sessionId,
+          _api,
+          initialState,
+          initialIndex,
+          initialEvents,
+          participant,
+        ) =>
+          options.client.session(sessionId, {
+            initialState,
+            initialIndex,
+            ...(initialEvents === undefined ? {} : { initialEvents }),
+            ...(participant === undefined ? {} : { participant }),
+          })
+      : (() => {
+          const clients = new Map<string, A2Client<D, S, P>>()
+          return (
+            sessionId: string,
+            api: string | undefined,
+            initialState: S,
+            initialIndex: number,
+            initialEvents: ContractEvent<D>[] | undefined,
+            participant: string | undefined,
+          ) => {
+            if (api === undefined) {
+              throw new TypeError(
+                'SessionProvider requires api when createReact binds a reducer',
+              )
+            }
+            let client = clients.get(api)
+            if (!client) {
+              client = createClient({ reducer: options.reducer, api })
+              clients.set(api, client)
+            }
+            return client.session(sessionId, {
+              initialState,
+              initialIndex,
+              ...(initialEvents === undefined ? {} : { initialEvents }),
+              ...(participant === undefined ? {} : { participant }),
+            })
+          }
+        })()
+
+  function SessionProvider(
+    props: SessionProviderProps<D, S> | BoundSessionProviderProps<D, S>,
+  ): ReactElement {
+    const {
+      sessionId,
+      initialState,
+      initialIndex,
+      initialEvents,
+      participant,
+    } = props
+    const api = 'api' in props ? props.api : undefined
+    const client = useMemo(
+      () =>
+        resolveSession(
+          sessionId,
+          api,
+          initialState,
+          initialIndex,
+          initialEvents,
+          participant,
+        ),
+      [sessionId, api, initialState, initialIndex, initialEvents, participant],
+    )
+    useEffect(() => {
+      const mounts = providerMounts.get(client) ?? 0
+      providerMounts.set(client, mounts + 1)
+      if (mounts === 0) client.connect()
+      return () => {
+        const remaining = (providerMounts.get(client) ?? 1) - 1
+        if (remaining === 0) {
+          providerMounts.delete(client)
+          client.close()
+        } else {
+          providerMounts.set(client, remaining)
+        }
+      }
+    }, [client])
+    return createElement(Context.Provider, { value: client }, props.children)
+  }
+
+  function useSession(): UseSessionResult<D, S, P> {
+    const client = useContext(Context)
+    if (!client) {
+      throw new Error(
+        'useSession must be rendered inside its matching SessionProvider',
+      )
+    }
+    const snapshot: SessionSnapshot<D, S, P> = useSyncExternalStore(
+      client.subscribe,
+      client.getSnapshot,
+      client.getSnapshot,
+    )
+    return useMemo(() => {
+      // Runtime mirror of the WithPresence surface: the client attaches
+      // setPresence (and the snapshot carries presence) exactly when the
+      // reducer declares presence fields — no runtime-inert members.
+      const { setPresence } = client as Partial<SessionClientPresence<P>>
+      const { presence } = snapshot as Partial<{ presence: PresenceMap<P> }>
+      return {
+        state: snapshot.state,
+        events: snapshot.events,
+        index: snapshot.index,
+        connection: snapshot.connection,
+        push: client.push,
+        loadHistory: client.loadHistory,
+        history: snapshot.history,
+        ...(setPresence && presence ? { presence, setPresence } : {}),
+      } as UseSessionResult<D, S, P>
+    }, [snapshot, client])
+  }
+
+  return { SessionProvider, useSession }
+}

package/src/reducer.ts

@@ -0,0 +1,108 @@
+import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'
+import type { StandardSchemaV1 } from './standard-schema.ts'
+import { validateSync } from './validate.ts'
+
+/**
+ * A pure fold over a session's events — `(state, event) => state` —
+ * derived from a contract via `contract.reducer(options).fold(fn)`.
+ *
+ * The name is the reducer's identity. Cached folds (server snapshots,
+ * the browser cache) are keyed by it, which makes it the invalidation
+ * knob too: changed the fold's logic? Change the name. Snapshots under
+ * the old name are ignored and the next read refolds from raw events.
+ * See docs/concepts/04-state.mdx.
+ */
+export type Reducer<
+  D extends EventDefs = EventDefs,
+  S = unknown,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  /** Identity and cache key. Rename when the fold's logic changes. */
+  readonly name: string
+  /** The contract's vocabulary — types every event in the fold. */
+  readonly events: Readonly<D>
+  /**
+   * The contract's presence vocabulary — carried because the reducer
+   * is the client's typed handle on the contract. The fold never sees
+   * presence.
+   */
+  readonly presence: Readonly<P>
+  readonly fold: (state: S, event: ContractEvent<D>) => S
+  readonly initialState: S
+  /**
+   * When present: `initialState` was validated against it at
+   * definition, and any cached fold a2 rehydrates (server snapshots,
+   * the browser cache) is checked against it — failing snapshots are
+   * discarded and refolded, catching shape drift a stale name can't.
+   */
+  readonly stateSchema: StandardSchemaV1<unknown, S> | undefined
+}
+
+/** The second step of `contract.reducer` — see the method's doc. */
+export type ReducerBuilder<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  fold(fold: (state: S, event: ContractEvent<D>) => S): Reducer<D, S, P>
+}
+
+/** Internal — reducers are created through `contract.reducer(...).fold(...)`. */
+export function makeReducerBuilder<
+  D extends EventDefs,
+  P extends PresenceDefs,
+  Seed,
+  S,
+>(
+  events: Readonly<D>,
+  presence: Readonly<P>,
+  options: {
+    name: string
+    initialState: Seed
+    stateSchema?: StandardSchemaV1<Seed, S>
+  },
+): ReducerBuilder<D, S, P> {
+  const { name } = options
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new TypeError(
+      'reducer name must be a non-empty string — it identifies the reducer and keys cached snapshots',
+    )
+  }
+
+  // Without a schema, S = Seed (the type parameter default), so the
+  // seed is the state. With one, the seed is the schema's input and the
+  // validated output (defaults applied) becomes the fold's actual seed.
+  let initialState = options.initialState as unknown as S
+  if (options.stateSchema) {
+    const result = validateSync(
+      options.stateSchema,
+      options.initialState,
+      'the stateSchema',
+    )
+    if (result.issues) {
+      throw new TypeError(
+        `reducer initialState does not match its stateSchema: ${result.issues
+          .map((issue) => issue.message)
+          .join('; ')}`,
+      )
+    }
+    initialState = result.value as S
+  }
+
+  return {
+    fold(fold) {
+      if (typeof fold !== 'function') {
+        throw new TypeError('reducer fold must be a function')
+      }
+      return {
+        name,
+        events,
+        presence,
+        fold,
+        initialState,
+        stateSchema: options.stateSchema as
+          StandardSchemaV1<unknown, S> | undefined,
+      }
+    },
+  }
+}

package/src/retryable-lazy.ts

@@ -0,0 +1,27 @@
+/**
+ * One lazy in-flight attempt: concurrent callers share it, fulfilled values
+ * stay cached, and rejected attempts are evicted so a later call can retry.
+ */
+export type RetryableLazy<T> = {
+  get(): Promise<T>
+  peek(): Promise<T> | null
+}
+
+export const retryableLazy = <T>(
+  initialize: () => Promise<T>,
+): RetryableLazy<T> => {
+  let current: Promise<T> | null = null
+
+  const get = (): Promise<T> => {
+    if (current) return current
+
+    const attempt = Promise.resolve().then(initialize)
+    current = attempt
+    void attempt.catch(() => {
+      if (current === attempt) current = null
+    })
+    return attempt
+  }
+
+  return { get, peek: () => current }
+}