experimental-a2 0.0.0

package/dist/cache-indexeddb.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+import { i as EventDefs, r as ContractEvent, s as Reducer, t as AppendInput } from "./contract-DL8btVd9.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> = {
+  /** 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;
+};
+type SessionClient<D extends EventDefs, S> = {
+  readonly sessionId: string;
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): SessionSnapshot<D, S>;
+  /**
+   * 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 `LOG_UNAVAILABLE`. Resolves with the appended
+   * events as the server recorded them.
+   */
+  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>[];
+};
+type A2Client<D extends EventDefs, S> = {
+  session(sessionId: string, options?: SessionOptions<D, S>): SessionClient<D, S>;
+};
+type CreateClientOptions<D extends EventDefs, S> = {
+  reducer: Reducer<D, S>;
+  /** Base path (or absolute URL) of the route exposing GET/POST. */
+  api: string;
+  /** Injectable fetch — defaults to the global. */
+  fetch?: typeof globalThis.fetch;
+  /** 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>(options: CreateClientOptions<D, S>): A2Client<D, S>;
+//#endregion
+export { A2Client, Connection, ConnectionStatus, CreateClientOptions, PushResult, SessionClient, SessionOptions, SessionSnapshot, createClient };

package/dist/client.js

@@ -0,0 +1,410 @@
+import { n as validateSync } from "./validate-XKT4FSNn.js";
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { r as STREAM_TIMINGS } from "./internal-Dm8Ejnud.js";
+import { i as eventFromWire, o as isWireEvent, t as errorFromWire } from "./wire-2QpU1EtJ.js";
+//#region src/client.ts
+/**
+* a2/client — the framework-agnostic session client.
+*
+* Everything the browser needs to read a session live and push
+* optimistically, with no framework attached: the SSE subscription with
+* frontier resume and reconnection, the optimistic push queue with
+* ack/rollback, and the local fold through the same reducer the server
+* uses. `a2/react`'s `createReact` is a thin binding over it, and the
+* store contract (`subscribe`/`getSnapshot`) is exactly what
+* `useSyncExternalStore` wants.
+*
+* The client is a replica, never an access path — the routes it talks
+* to authorize every read and write.
+*/
+const PUSH_ATTEMPTS = 3;
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 5e3;
+const DEFAULT_GC_TIME_MS = 3e5;
+function createClient(options) {
+	const { reducer, api } = options;
+	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const gcTime = options.gcTime ?? DEFAULT_GC_TIME_MS;
+	if (Number.isNaN(gcTime) || gcTime < 0) throw new RangeError("gcTime must be a non-negative number or Infinity");
+	const sessions = /* @__PURE__ */ new Map();
+	const scheduleGc = (sessionId, delay = gcTime) => {
+		const entry = sessions.get(sessionId);
+		if (!entry) return;
+		clearTimeout(entry.timer);
+		if (gcTime === Infinity) return;
+		entry.timer = setTimeout(() => {
+			if (sessions.get(sessionId) !== entry) return;
+			if (entry.runtime.canEvict()) {
+				sessions.delete(sessionId);
+				return;
+			}
+			scheduleGc(sessionId, Math.max(gcTime, 1e3));
+		}, delay);
+		entry.timer.unref?.();
+	};
+	const touch = (sessionId) => {
+		scheduleGc(sessionId);
+	};
+	const makeSession = (sessionId, sessionOptions) => {
+		let frontier = sessionOptions?.initialIndex ?? 0;
+		let foldedState = sessionOptions?.initialState !== void 0 ? sessionOptions.initialState : reducer.initialState;
+		const serverEvents = (sessionOptions?.initialEvents ?? []).filter((event) => event.index <= frontier).toSorted((a, b) => a.index - b.index);
+		let pending = [];
+		const listeners = /* @__PURE__ */ new Set();
+		let snapshot = null;
+		let status = "idle";
+		let reconnects = 0;
+		let lastError = null;
+		let inFlightPushes = 0;
+		let deferredHydration;
+		let hydrationNotification;
+		const emit = () => {
+			for (const listener of [...listeners]) listener();
+		};
+		const notify = () => {
+			snapshot = null;
+			emit();
+		};
+		const notifyHydrated = () => {
+			snapshot = null;
+			clearTimeout(hydrationNotification);
+			hydrationNotification = setTimeout(emit, 0);
+			hydrationNotification.unref?.();
+		};
+		const mergeServerEvents = (events, throughIndex) => {
+			if (!events || events.length === 0) return false;
+			const byIndex = new Map(serverEvents.map((event) => [event.index, event]));
+			let changed = false;
+			for (const event of events) {
+				if (event.index > throughIndex) continue;
+				if (byIndex.get(event.index)?.id === event.id) continue;
+				byIndex.set(event.index, event);
+				changed = true;
+			}
+			if (!changed) return false;
+			serverEvents.splice(0, serverEvents.length, ...[...byIndex.values()].toSorted((a, b) => a.index - b.index));
+			return true;
+		};
+		const overlayEvents = () => {
+			const acked = pending.filter((p) => p.acked).map((p) => p.acked).toSorted((a, b) => a.index - b.index);
+			const maxKnown = acked.at(-1)?.index ?? frontier;
+			const unacked = pending.filter((p) => !p.acked).map((p, i) => ({
+				id: p.id,
+				type: p.type,
+				payload: p.payload,
+				index: maxKnown + 1 + i,
+				sessionId,
+				createdAt: p.createdAt
+			}));
+			return [...acked, ...unacked];
+		};
+		const connection = () => {
+			switch (status) {
+				case "idle": return { status: "idle" };
+				case "closed": return { status: "closed" };
+				case "live": return {
+					status: "live",
+					reconnects
+				};
+				case "connecting": return {
+					status: "connecting",
+					reconnects,
+					error: lastError
+				};
+			}
+		};
+		const buildSnapshot = () => {
+			const overlay = overlayEvents();
+			let state = foldedState;
+			for (const event of overlay) state = reducer.fold(state, event);
+			return {
+				state,
+				events: [...serverEvents, ...overlay],
+				index: frontier,
+				connection: connection()
+			};
+		};
+		/** Pushes awaiting stream confirmation — resolved by `ingest` the
+		* moment the frontier passes their batch. */
+		let confirmWatchers = [];
+		/** The single ingest point: every server-confirmed event, in log
+		* order, from the stream. */
+		const ingest = (event) => {
+			if (event.index <= frontier) return;
+			frontier = event.index;
+			serverEvents.push(event);
+			foldedState = reducer.fold(foldedState, event);
+			pending = pending.filter((p) => p.id !== event.id);
+			if (confirmWatchers.some((w) => w.index <= frontier)) {
+				const due = confirmWatchers.filter((w) => w.index <= frontier);
+				confirmWatchers = confirmWatchers.filter((w) => w.index > frontier);
+				for (const watcher of due) watcher.resolve();
+			}
+			notify();
+			touch(sessionId);
+		};
+		const validated = (events) => events.map((event) => {
+			const schema = Object.hasOwn(reducer.events, event.type) ? reducer.events[event.type] : void 0;
+			if (!schema) throw new A2Error("UNKNOWN_EVENT_TYPE", `no event type '${String(event.type)}' in the reducer's vocabulary`);
+			const result = validateSync(schema, event.payload, `event '${String(event.type)}'`);
+			if (result.issues) throw new A2Error("INVALID_PAYLOAD", `invalid payload for event '${String(event.type)}'`, { details: result.issues });
+			return {
+				id: event.id ?? crypto.randomUUID(),
+				type: event.type,
+				payload: result.value
+			};
+		});
+		const post = async (body) => {
+			let lastPushError = new A2Error("LOG_UNAVAILABLE", "push failed");
+			for (let attempt = 1; attempt <= PUSH_ATTEMPTS; attempt += 1) {
+				try {
+					const res = await fetchImpl(api, {
+						method: "POST",
+						headers: { "content-type": "application/json" },
+						body: JSON.stringify(body)
+					});
+					if (res.ok) {
+						const rows = await res.json();
+						if (!Array.isArray(rows) || !rows.every(isWireEvent)) throw new A2Error("LOG_UNAVAILABLE", "push ack was not a list of events");
+						return rows.map((row) => eventFromWire(row));
+					}
+					lastPushError = errorFromWire(await res.json().catch(() => null)) ?? new A2Error("LOG_UNAVAILABLE", `push failed with ${res.status}`);
+				} catch (err) {
+					lastPushError = err instanceof A2Error ? err : new A2Error("LOG_UNAVAILABLE", "push request failed", { cause: err });
+				}
+				if (lastPushError.code !== "LOG_UNAVAILABLE") throw lastPushError;
+				if (attempt < PUSH_ATTEMPTS) await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
+			}
+			throw lastPushError;
+		};
+		/**
+		* Decorate the ack promise into a PushResult. `confirmed` is a
+		* lazy getter — materialized on first access, so callers that
+		* ignore it can't leak an unhandled rejection.
+		*/
+		const withConfirmed = (ack) => {
+			let confirmed;
+			return Object.defineProperty(ack, "confirmed", { get() {
+				confirmed ??= ack.then((acked) => new Promise((resolve) => {
+					const last = acked.at(-1)?.index ?? 0;
+					if (frontier >= last) {
+						resolve(acked);
+						return;
+					}
+					confirmWatchers.push({
+						index: last,
+						resolve: () => resolve(acked)
+					});
+				}));
+				return confirmed;
+			} });
+		};
+		const push = (...events) => {
+			touch(sessionId);
+			return withConfirmed((async () => {
+				if (events.length === 0) throw new TypeError("push requires at least one event");
+				const entries = validated(events).map((e) => ({
+					id: e.id,
+					type: e.type,
+					payload: e.payload,
+					createdAt: /* @__PURE__ */ new Date()
+				}));
+				pending.push(...entries);
+				inFlightPushes += 1;
+				notify();
+				try {
+					const acked = await post({
+						sessionId,
+						events: entries.map(({ id, type, payload }) => ({
+							id,
+							type,
+							payload
+						}))
+					});
+					for (const event of acked) {
+						const entry = pending.find((p) => p.id === event.id);
+						if (entry) entry.acked = event;
+					}
+					notify();
+					return acked;
+				} catch (err) {
+					const ids = new Set(entries.map((e) => e.id));
+					pending = pending.filter((p) => !ids.has(p.id));
+					notify();
+					throw err;
+				} finally {
+					inFlightPushes -= 1;
+					if (inFlightPushes === 0 && deferredHydration) {
+						const next = deferredHydration;
+						deferredHydration = void 0;
+						runtime.hydrate(next);
+					}
+					touch(sessionId);
+				}
+			})());
+		};
+		let generation = 0;
+		let active = false;
+		let abort = null;
+		const streamUrl = () => {
+			const sep = api.includes("?") ? "&" : "?";
+			return `${api}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${frontier}`;
+		};
+		const consume = async (body, onActivity) => {
+			const decoder = new TextDecoder();
+			const reader = body.getReader();
+			let buffer = "";
+			try {
+				for (;;) {
+					const { done, value } = await reader.read();
+					if (done) return;
+					onActivity();
+					buffer += decoder.decode(value, { stream: true });
+					for (;;) {
+						const boundary = buffer.indexOf("\n\n");
+						if (boundary === -1) break;
+						const frame = buffer.slice(0, boundary);
+						buffer = buffer.slice(boundary + 2);
+						const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+						if (!data) continue;
+						const parsed = JSON.parse(data);
+						if (isWireEvent(parsed)) ingest(eventFromWire(parsed));
+					}
+				}
+			} finally {
+				reader.cancel().catch(() => {});
+			}
+		};
+		const runStream = async (run) => {
+			let backoff = RECONNECT_BASE_MS;
+			while (generation === run) {
+				const controller = new AbortController();
+				abort = controller;
+				let stall;
+				let stalled = false;
+				const armStall = () => {
+					clearTimeout(stall);
+					stall = setTimeout(() => {
+						stalled = true;
+						controller.abort();
+					}, STREAM_TIMINGS.stallTimeoutMs);
+					stall.unref?.();
+				};
+				let wasLive = false;
+				try {
+					const res = await fetchImpl(streamUrl(), {
+						headers: { accept: "text/event-stream" },
+						signal: controller.signal
+					});
+					if (!res.ok || !res.body) throw new Error(`stream failed with ${res.status}`);
+					if (generation !== run) break;
+					backoff = RECONNECT_BASE_MS;
+					wasLive = true;
+					status = "live";
+					lastError = null;
+					notify();
+					armStall();
+					await consume(res.body, armStall);
+					if (generation === run) lastError = null;
+				} catch (err) {
+					if (generation === run) lastError = stalled ? /* @__PURE__ */ new Error(`stream stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`) : err instanceof Error ? err : new Error(String(err));
+				} finally {
+					clearTimeout(stall);
+				}
+				if (generation !== run) break;
+				if (wasLive) reconnects += 1;
+				status = "connecting";
+				notify();
+				await new Promise((resolve) => {
+					let settled = false;
+					const finish = () => {
+						if (settled) return;
+						settled = true;
+						clearTimeout(timer);
+						resolve();
+					};
+					const timer = setTimeout(finish, backoff);
+					timer.unref?.();
+					abort?.signal.addEventListener("abort", finish);
+				});
+				backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
+			}
+		};
+		const runtime = {
+			sessionId,
+			subscribe(listener) {
+				touch(sessionId);
+				listeners.add(listener);
+				return () => {
+					listeners.delete(listener);
+					touch(sessionId);
+				};
+			},
+			getSnapshot() {
+				snapshot ??= buildSnapshot();
+				return snapshot;
+			},
+			push,
+			connect() {
+				touch(sessionId);
+				if (active) return;
+				active = true;
+				status = "connecting";
+				notify();
+				runStream(generation);
+			},
+			close() {
+				touch(sessionId);
+				if (!active) return;
+				active = false;
+				generation += 1;
+				abort?.abort();
+				abort = null;
+				status = "closed";
+				notify();
+			},
+			hydrate(next) {
+				touch(sessionId);
+				if (!next) return;
+				const nextIndex = next.initialIndex ?? 0;
+				if (nextIndex > frontier && inFlightPushes > 0) {
+					if (!deferredHydration || nextIndex > (deferredHydration.initialIndex ?? 0)) deferredHydration = next;
+					return;
+				}
+				const historyChanged = mergeServerEvents(next.initialEvents, Math.min(nextIndex, frontier));
+				if (next.initialState === void 0 || nextIndex <= frontier) {
+					if (historyChanged) notifyHydrated();
+					return;
+				}
+				frontier = nextIndex;
+				foldedState = next.initialState;
+				mergeServerEvents(next.initialEvents, frontier);
+				pending = pending.filter((entry) => !entry.acked || entry.acked.index > frontier);
+				if (confirmWatchers.some((watcher) => watcher.index <= frontier)) {
+					const due = confirmWatchers.filter((watcher) => watcher.index <= frontier);
+					confirmWatchers = confirmWatchers.filter((watcher) => watcher.index > frontier);
+					for (const watcher of due) watcher.resolve();
+				}
+				notifyHydrated();
+			},
+			canEvict() {
+				return listeners.size === 0 && !active && inFlightPushes === 0 && confirmWatchers.length === 0;
+			}
+		};
+		return runtime;
+	};
+	return { session(sessionId, sessionOptions) {
+		const existing = sessions.get(sessionId);
+		if (existing) {
+			existing.runtime.hydrate(sessionOptions);
+			touch(sessionId);
+			return existing.runtime;
+		}
+		const runtime = makeSession(sessionId, sessionOptions);
+		sessions.set(sessionId, { runtime });
+		touch(sessionId);
+		return runtime;
+	} };
+}
+//#endregion
+export { createClient };

package/dist/contract-B0kAXoaL.js

@@ -0,0 +1,60 @@
+import { n as validateSync, t as assertSyncSchema } from "./validate-XKT4FSNn.js";
+//#region src/reducer.ts
+/** Internal — reducers are created through `contract.reducer(...).fold(...)`. */
+function makeReducerBuilder(events, options) {
+	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");
+	let initialState = options.initialState;
+	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;
+	}
+	return { fold(fold) {
+		if (typeof fold !== "function") throw new TypeError("reducer fold must be a function");
+		return {
+			name,
+			events,
+			fold,
+			initialState,
+			stateSchema: options.stateSchema
+		};
+	} };
+}
+//#endregion
+//#region src/contract.ts
+/**
+* The contract — a2's primary noun. A named event vocabulary, shared by
+* everything: the server implements it (a2/server's `createServer`),
+* reducers derive from it (`contract.reducer`), the browser types its
+* pushes off it. Isomorphic by construction: this module imports
+* nothing but schema plumbing.
+*
+* The contract says what can be *said*; the server says how it's
+* *reacted to*; a reducer says how it's *seen*.
+*/
+/**
+* Define a contract: a name plus the events it understands. Validators
+* must be synchronous — async ones are rejected here, at definition
+* time. The result is a plain, importable, isomorphic value.
+*/
+function contract(options) {
+	const { name } = options;
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("contract name must be a non-empty string");
+	if (name.includes("")) throw new TypeError("contract name contains a reserved control character");
+	const defs = options.events;
+	for (const [type, schema] of Object.entries(defs)) {
+		if (typeof schema?.["~standard"]?.validate !== "function") throw new TypeError(`contract '${name}': the value for '${type}' is not a Standard Schema (expected an object with '~standard')`);
+		assertSyncSchema(schema, `event '${type}'`);
+	}
+	const events = Object.freeze({ ...defs });
+	return {
+		name,
+		events,
+		reducer(reducerOptions) {
+			return makeReducerBuilder(events, reducerOptions);
+		}
+	};
+}
+//#endregion
+export { contract as t };