experimental-a2 0.2.0 → 0.4.0

package/dist/client-BrfDXQ8A.d.ts

@@ -0,0 +1,155 @@
+import { a as EventDefs, c as PresencePatch, d as WithPresence, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
+//#region src/client.d.ts
+type ConnectionStatus = "idle" | "connecting" | "live" | "closed";
+/**
+ * The connection, as a discriminated union — impossible states are
+ * unrepresentable: an error only exists while disconnected,
+ * `reconnects` only once a connection has been attempted.
+ * "Reconnecting…" is `status === 'connecting' && reconnects > 0`.
+ */
+type Connection = {
+  status: "idle";
+} | {
+  status: "connecting";
+  /** Drops of an established stream so far. `0` = first connect. */
+  reconnects: number;
+  /** Why the last connection ended; `null` on the first connect. */
+  error: Error | null;
+} | {
+  status: "live";
+  reconnects: number;
+} | {
+  status: "closed";
+};
+/**
+ * What `push` returns: resolves at the server ack (exactly like a
+ * plain promise — `await push(...)` gives the acked events), and
+ * carries `confirmed` for the later moment when the live stream has
+ * delivered the whole batch back and the optimistic overlay entry
+ * retired — the view now shows server truth. `confirmed` is lazy:
+ * never accessed, never created. A rejected push rejects both.
+ */
+type PushResult<D extends EventDefs> = Promise<ContractEvent<D>[]> & {
+  readonly confirmed: Promise<ContractEvent<D>[]>;
+};
+/** One immutable view of the session — stable identity between changes. */
+type SessionSnapshot<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, {
+  /** The replicated presence map, this client included (local echo). */
+  presence: PresenceMap<P>;
+}> & {
+  /** The live view: server events folded, optimistic pushes applied. */
+  state: S;
+  /** The observed feed `state` is folded from — server truth plus
+   * pending optimistic events (provisional indexes past the frontier). */
+  events: ContractEvent<D>[];
+  /** The stream frontier: the last server-confirmed index. This is the
+   * `lastSeenIndex` cancellation wants. */
+  index: number;
+  connection: Connection;
+};
+/**
+ * The presence member of a client session — intersected in via
+ * `WithPresence`, so it exists exactly when the contract declares
+ * presence fields.
+ */
+type SessionClientPresence<P extends PresenceDefs> = {
+  /**
+   * Fire-and-forget presence: validates locally against the reducer's
+   * presence schemas, merges into the local map immediately (the
+   * echo), and coalesces on the wire to a fixed cadence — a leading
+   * send immediately, then at most one merged send per interval,
+   * later values winning field-wise. `null` clears a field. No ack,
+   * no retry, no rollback: a lost patch is repainted by the next one.
+   * Requires the session's `participant`.
+   */
+  setPresence(values: PresencePatch<P>["values"]): void;
+};
+type SessionClient<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, SessionClientPresence<P>> & {
+  readonly sessionId: string;
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): SessionSnapshot<D, S, P>;
+  /**
+   * Optimistic append: validates locally against the reducer's event
+   * schemas (instant `INVALID_PAYLOAD`, no flicker), applies to the
+   * local fold, POSTs, swaps in the ack, rolls back on rejection.
+   * Auto-retries only `STORE_UNAVAILABLE`. Resolves with the appended
+   * events as the server recorded them. Overlapping calls on this
+   * handle enter the transport in invocation order without delaying
+   * their optimistic folds.
+   */
+  push(...events: AppendInput<D>[]): PushResult<D>;
+  /** Open the live stream (idempotent while open). Reconnects with
+   * backoff and resumes from the frontier until `close()`. */
+  connect(): void;
+  /**
+   * Stop the live stream. Not terminal: `connect()` starts it again
+   * from the current frontier — which is what makes the React
+   * StrictMode mount dance (setup → cleanup → setup) work.
+   */
+  close(): void;
+};
+type SessionOptions<D extends EventDefs, S> = {
+  initialState?: S;
+  initialIndex?: number;
+  /** Server-rendered history through `initialIndex`. Seeds the event feed. */
+  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. Bound once per session handle.
+   */
+  participant?: string;
+};
+type A2Client<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
+  session(sessionId: string, options?: SessionOptions<D, S>): SessionClient<D, S, P>;
+};
+/**
+ * The wire the client rides. The string form is one route serving GET
+ * (SSE stream) + POST (push). `http` splits the verbs across two
+ * routes, for when platform duration limits differ per verb. `ws`
+ * rides everything over one WebSocket.
+ */
+type ClientApi = string | {
+  type: "http";
+  push: string;
+  stream: string;
+} | {
+  type: "ws";
+  url: string;
+};
+/**
+ * The socket surface the `ws` transport drives — satisfied structurally
+ * by the DOM `WebSocket` and Node's alike, and small enough to fake in
+ * tests.
+ */
+type ClientWebSocket = {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: "open", listener: () => void): void;
+  addEventListener(type: "message", listener: (event: {
+    data: unknown;
+  }) => void): void;
+  addEventListener(type: "close", listener: (event: {
+    code: number;
+    reason: string;
+  }) => void): void;
+  addEventListener(type: "error", listener: () => void): void;
+};
+type ClientWebSocketConstructor = new (url: string) => ClientWebSocket;
+type CreateClientOptions<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
+  reducer: Reducer<D, S, P>;
+  /** The route (or routes) the client speaks — see `ClientApi`. */
+  api: ClientApi;
+  /** Injectable fetch — defaults to the global. */
+  fetch?: typeof globalThis.fetch;
+  /** Injectable WebSocket constructor for the `ws` api — defaults to
+   * the global. The http transports never touch it. */
+  webSocket?: ClientWebSocketConstructor;
+  /** How long an idle session keeps its in-memory identity, in
+   * milliseconds. Defaults to five minutes; `Infinity` disables GC. */
+  gcTime?: number;
+};
+declare function createClient<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: CreateClientOptions<D, S, P>): A2Client<D, S, P>;
+//#endregion
+export { Connection as a, PushResult as c, SessionOptions as d, SessionSnapshot as f, ClientWebSocketConstructor as i, SessionClient as l, ClientApi as n, ConnectionStatus as o, createClient as p, ClientWebSocket as r, CreateClientOptions as s, A2Client as t, SessionClientPresence as u };