experimental-a2 0.9.0 → 0.11.0

package/dist/client.d.ts

@@ -1,202 +1,2 @@
-import { a as ContractEvent, c as PresenceDefs, l as PresenceMap, p as WithPresence, r as AppendInput, s as EventDefs, t as Reducer, u as PresencePatch } from "./reducer-DJKWm3cp.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>[]>;
-};
-type LoadHistoryOptions = {
-  /**
-   * Exclusive upper bound for the fetch. Defaults to the oldest
-   * already-loaded index — successive calls page backward — or one
-   * past the hydration frontier while nothing is loaded yet.
-   */
-  before?: number;
-  /** Page size; defaults to 50. */
-  limit?: number;
-};
-/** Backscroll progress, derived from the raw event feed. */
-type HistoryState = {
-  /** A `loadHistory` fetch is in flight. */
-  loading: boolean;
-  /** The feed reaches index 1 — nothing older remains to fetch. */
-  complete: boolean;
-  /** The oldest loaded index; `null` while nothing is loaded. */
-  oldestLoaded: number | null;
-};
-/** 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 raw event feed: server truth — observed, seeded, or
-   * backscrolled via `loadHistory` — plus pending optimistic events
-   * (provisional indexes past the frontier). `state` never folds
-   * backscrolled events; they are display data below the frontier. */
-  events: ContractEvent<D>[];
-  /** The stream frontier: the last server-confirmed index. This is the
-   * `lastSeenIndex` cancellation wants. */
-  index: number;
-  /** Backscroll progress — `loadHistory` moves it. */
-  history: HistoryState;
-  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>;
-  /**
-   * Backscroll: fetch a bounded slice of events from below the
-   * frontier and merge it into `events` — deduped, ordered, shared by
-   * every handle of this session. Folded state and the optimistic
-   * overlay are never touched. Calls serialize per session and skip
-   * already-loaded ranges, so overlapping backscrolls never fetch the
-   * same range twice. Resolves with the events in the requested range.
-   * Requires an http api; the `ws` transport has no history lane and
-   * this throws a TypeError there.
-   */
-  loadHistory(options?: LoadHistoryOptions): Promise<ContractEvent<D>[]>;
-  /**
-   * Take a lease on the live stream and return its release. Leases
-   * refcount per handle — the first connects, releasing the last
-   * closes — so independent consumers of one identity-mapped handle
-   * (two hooks, a hook plus vanilla code) never fight over the
-   * stream. Releasing twice is a no-op. While any lease is held the
-   * stream reconnects with backoff and resumes from the frontier.
-   */
-  connect(): () => void;
-  /**
-   * The hard stop: drops every outstanding lease and closes the
-   * stream now. Not terminal — a later `connect()` starts fresh from
-   * the current frontier.
-   */
-  close(): void;
-};
-type SessionOptions<D extends EventDefs, S> = {
-  initialState?: S;
-  initialIndex?: number;
-  /** Server-rendered history through `initialIndex`. Seeds the event feed. */
-  initialEvents?: ContractEvent<D>[];
-  /** Overrides the client's `participant` for this session handle.
-   * Bound once per 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 — every session of this client — over one
- * multiplexed WebSocket, served by `sessionsSocket`.
- */
-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;
-  /**
-   * 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; the app states it once here. The
-   * default for every session handle this client creates;
-   * `session(id, { participant })` overrides it per handle.
-   */
-  participant?: string;
-};
-declare function createClient<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: CreateClientOptions<D, S, P>): A2Client<D, S, P>;
-//#endregion
-export { A2Client, ClientApi, ClientWebSocket, ClientWebSocketConstructor, Connection, ConnectionStatus, CreateClientOptions, HistoryState, LoadHistoryOptions, PushResult, SessionClient, SessionClientPresence, SessionOptions, SessionSnapshot, createClient };
-//# sourceMappingURL=client.d.ts.map
+import { _ as createClient, a as Connection, c as HistoryState, d as ReconnectPolicy, f as SessionClient, g as SessionUrl, h as SessionSnapshot, i as ClientWebSocketConstructor, l as LoadHistoryOptions, m as SessionOptions, n as ClientApi, o as ConnectionStatus, p as SessionClientPresence, r as ClientWebSocket, s as CreateClientOptions, t as A2Client, u as PushResult, v as A2ClientError, y as A2ClientErrorOptions } from "./client-P_NNNRM-.js";
+export { A2Client, A2ClientError, type A2ClientErrorOptions, ClientApi, ClientWebSocket, ClientWebSocketConstructor, Connection, ConnectionStatus, CreateClientOptions, HistoryState, LoadHistoryOptions, PushResult, ReconnectPolicy, SessionClient, SessionClientPresence, SessionOptions, SessionSnapshot, SessionUrl, createClient };