experimental-a2 0.0.0

package/dist/log-memory.js

@@ -0,0 +1,345 @@
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { n as SYSTEM_CLOCK, t as RANDOM_IDS } from "./log-yJbXUf72.js";
+//#region src/log-memory.ts
+/**
+* a2/log-memory — in-memory log backend (the test default).
+*
+* Implements the A2Log interface with zero dependencies. See
+* specs/a2-implementation.md §3 for the contract; the conformance suite
+* in test/conformance is the executable version of it.
+*/
+const toStored = (row) => ({
+	id: row.id,
+	type: row.type,
+	payload: structuredClone(row.payload),
+	index: row.index,
+	sessionId: row.sessionId,
+	createdAt: new Date(row.createdAt),
+	cause: row.cause ? { ...row.cause } : null,
+	processedAt: row.processedAt ? new Date(row.processedAt) : null,
+	processedByAttempt: row.processedByAttempt,
+	firstClaimedAt: row.firstClaimedAt ? new Date(row.firstClaimedAt) : null,
+	lastClaimedAt: row.lastClaimedAt ? new Date(row.lastClaimedAt) : null,
+	attemptCount: row.attemptCount,
+	failureCount: row.failureCount,
+	lastFailedAt: row.lastFailedAt ? new Date(row.lastFailedAt) : null,
+	lastFailedAttempt: row.lastFailedAttempt,
+	lastError: row.lastError,
+	failedAt: row.failedAt ? new Date(row.failedAt) : null
+});
+const toEvent = (row) => ({
+	id: row.id,
+	type: row.type,
+	payload: structuredClone(row.payload),
+	index: row.index,
+	sessionId: row.sessionId,
+	createdAt: new Date(row.createdAt)
+});
+function memory(options = {}) {
+	const clock = options.clock ?? SYSTEM_CLOCK;
+	const generateId = options.ids ?? RANDOM_IDS;
+	const sessions = /* @__PURE__ */ new Map();
+	/** Global unique index on event ids, like the SQL schema's. */
+	const byEventId = /* @__PURE__ */ new Map();
+	const leases = /* @__PURE__ */ new Map();
+	/** Array offset of the first row not known to be processed. */
+	const pendingHeads = /* @__PURE__ */ new Map();
+	/** Keyed by `${sessionId}\u0000${reducerName}` — a pure cache. */
+	const snapshots = /* @__PURE__ */ new Map();
+	const streamSubscribers = /* @__PURE__ */ new Map();
+	const notifyStreams = (sessionId, rows) => {
+		const subs = streamSubscribers.get(sessionId);
+		if (!subs) return;
+		for (const listener of subs) for (const row of rows) listener(row);
+	};
+	const rowsOf = (sessionId) => {
+		let rows = sessions.get(sessionId);
+		if (!rows) {
+			rows = [];
+			sessions.set(sessionId, rows);
+		}
+		return rows;
+	};
+	const find = (sessionId, index) => {
+		const row = sessions.get(sessionId)?.find((candidate) => candidate.index === index);
+		if (!row) throw new TypeError(`no event at index ${index} in session '${sessionId}'`);
+		return row;
+	};
+	const pendingHead = (sessionId) => {
+		const rows = sessions.get(sessionId) ?? [];
+		let offset = pendingHeads.get(sessionId) ?? 0;
+		while (offset < rows.length && rows[offset]?.processedAt !== null) offset += 1;
+		pendingHeads.set(sessionId, offset);
+		return rows[offset];
+	};
+	const claim = (row, now) => {
+		row.attemptCount += 1;
+		row.firstClaimedAt ??= new Date(now);
+		row.lastClaimedAt = new Date(now);
+		return toStored(row);
+	};
+	return {
+		async append(sessionId, events) {
+			if (events.length === 0) return [];
+			const supplied = events.filter((e) => e.id !== void 0);
+			if (new Set(supplied.map((e) => e.id)).size !== supplied.length) throw new A2Error("PARTIAL_DUPLICATE_BATCH", "batch contains the same event id more than once");
+			const existing = supplied.map((e) => byEventId.get(e.id)).filter((row) => row !== void 0);
+			if (existing.length > 0) {
+				const foreign = existing.find((row) => row.sessionId !== sessionId);
+				if (foreign) throw new A2Error("PARTIAL_DUPLICATE_BATCH", `event id '${foreign.id}' already exists in another session`);
+				if (existing.length === events.length) return existing.toSorted((a, b) => a.index - b.index).map(toStored);
+				throw new A2Error("PARTIAL_DUPLICATE_BATCH", `batch mixes ${existing.length} already-appended and ${events.length - existing.length} fresh events`);
+			}
+			const rows = rowsOf(sessionId);
+			const now = clock.now();
+			const base = rows.length === 0 ? 0 : rows[rows.length - 1].index;
+			const inserted = events.map((e, i) => {
+				return {
+					id: e.id ?? generateId(),
+					type: e.type,
+					payload: structuredClone(e.payload),
+					index: base + 1 + i,
+					sessionId,
+					createdAt: new Date(now),
+					cause: e.cause ? { ...e.cause } : null,
+					processedAt: null,
+					processedByAttempt: null,
+					firstClaimedAt: null,
+					lastClaimedAt: null,
+					attemptCount: 0,
+					failureCount: 0,
+					lastFailedAt: null,
+					lastFailedAttempt: null,
+					lastError: null,
+					failedAt: null
+				};
+			});
+			for (const row of inserted) if (byEventId.has(row.id)) throw new A2Error("PARTIAL_DUPLICATE_BATCH", `event id '${row.id}' already exists`);
+			for (const row of inserted) {
+				rows.push(row);
+				byEventId.set(row.id, row);
+			}
+			notifyStreams(sessionId, inserted);
+			return inserted.map(toStored);
+		},
+		async read(sessionId, opts) {
+			return (sessions.get(sessionId) ?? []).filter((row) => {
+				if (opts?.afterIndex !== void 0 && row.index <= opts.afterIndex) return false;
+				if (opts?.unprocessedOnly && row.processedAt !== null) return false;
+				return true;
+			}).map(toStored);
+		},
+		async claimNext({ sessionId, holder, ttlMs, expiresAtMs, maxIndex }) {
+			const next = pendingHead(sessionId);
+			if (!next || next.failedAt || maxIndex !== void 0 && next.index > maxIndex) return { outcome: "settled" };
+			const claimedAt = clock.now();
+			const now = claimedAt.getTime();
+			const current = leases.get(sessionId);
+			if (current && current.expiresAt > now && current.holder !== holder) return { outcome: "busy" };
+			leases.set(sessionId, {
+				holder,
+				expiresAt: expiresAtMs ?? now + ttlMs
+			});
+			return {
+				outcome: "claimed",
+				event: claim(next, claimedAt)
+			};
+		},
+		async completeAndClaimNext({ sessionId, holder, completedIndex, attempt, maxIndex }) {
+			const claimedAt = clock.now();
+			const completed = find(sessionId, completedIndex);
+			if (completed.processedAt || completed.attemptCount !== attempt) return { outcome: "superseded" };
+			completed.processedAt = new Date(claimedAt);
+			completed.processedByAttempt = attempt;
+			const next = pendingHead(sessionId);
+			if (!next || next.failedAt || maxIndex !== void 0 && next.index > maxIndex) return { outcome: "settled" };
+			const now = claimedAt.getTime();
+			const current = leases.get(sessionId);
+			if (!current || current.holder !== holder || current.expiresAt <= now) return { outcome: "busy" };
+			return {
+				outcome: "claimed",
+				event: claim(next, claimedAt)
+			};
+		},
+		async markProcessed(sessionId, index) {
+			const row = find(sessionId, index);
+			row.processedAt ??= clock.now();
+		},
+		async failAttempt({ sessionId, index, attempt, error, maxFailures }) {
+			const row = find(sessionId, index);
+			if (row.processedAt || row.attemptCount !== attempt) return {
+				outcome: "superseded",
+				failureCount: row.failureCount
+			};
+			if (row.failedAt) return {
+				outcome: "dead_lettered",
+				failureCount: row.failureCount
+			};
+			row.failureCount += 1;
+			row.lastError = error;
+			const failedAt = clock.now();
+			row.lastFailedAt = new Date(failedAt);
+			row.lastFailedAttempt = attempt;
+			if (row.failureCount >= maxFailures) {
+				row.failedAt = new Date(failedAt);
+				return {
+					outcome: "dead_lettered",
+					failureCount: row.failureCount
+				};
+			}
+			return {
+				outcome: "failed",
+				failureCount: row.failureCount
+			};
+		},
+		async markFailed(sessionId, index) {
+			find(sessionId, index).failedAt = clock.now();
+		},
+		async readState(sessionId, reducerName) {
+			const snap = snapshots.get(`${sessionId}\u0000${reducerName}`);
+			const snapshot = snap ? {
+				index: snap.index,
+				state: structuredClone(snap.state)
+			} : null;
+			const afterIndex = snapshot?.index ?? 0;
+			return {
+				snapshot,
+				events: (sessions.get(sessionId) ?? []).filter((row) => row.index > afterIndex).map(toEvent)
+			};
+		},
+		async putSnapshot(sessionId, reducerName, index, state) {
+			const key = `${sessionId}\u0000${reducerName}`;
+			const existing = snapshots.get(key);
+			if (existing && existing.index >= index) return;
+			snapshots.set(key, {
+				index,
+				state: structuredClone(state),
+				updatedAt: clock.now()
+			});
+		},
+		inspect: {
+			async listSessions(inspectionOptions) {
+				const ids = [...sessions.keys()].filter((sessionId) => sessionId.startsWith(inspectionOptions.prefix) && (inspectionOptions.cursor === void 0 || sessionId > inspectionOptions.cursor)).toSorted();
+				const visible = ids.slice(0, inspectionOptions.limit);
+				return {
+					sessions: visible.map((sessionId) => {
+						const rows = sessions.get(sessionId);
+						const first = rows[0];
+						let updatedAt = first.createdAt;
+						let pendingCount = 0;
+						let failedCount = 0;
+						let attemptCount = 0;
+						let failureCount = 0;
+						for (const row of rows) {
+							attemptCount += row.attemptCount;
+							failureCount += row.failureCount;
+							if (row.processedAt === null && row.failedAt === null) pendingCount += 1;
+							if (row.failedAt !== null) failedCount += 1;
+							for (const timestamp of [
+								row.createdAt,
+								row.firstClaimedAt,
+								row.lastClaimedAt,
+								row.lastFailedAt,
+								row.processedAt,
+								row.failedAt
+							]) if (timestamp && timestamp > updatedAt) updatedAt = timestamp;
+						}
+						return {
+							sessionId,
+							eventCount: rows.length,
+							pendingCount,
+							failedCount,
+							attemptCount,
+							failureCount,
+							firstEventAt: new Date(first.createdAt),
+							updatedAt: new Date(updatedAt)
+						};
+					}),
+					cursor: ids.length > visible.length ? visible.at(-1) ?? null : null
+				};
+			},
+			async listSnapshots(sessionId) {
+				const prefix = `${sessionId}\u0000`;
+				return [...snapshots.entries()].filter(([key]) => key.startsWith(prefix)).map(([key, snapshot]) => ({
+					reducerName: key.slice(prefix.length),
+					index: snapshot.index,
+					updatedAt: new Date(snapshot.updatedAt)
+				})).toSorted((a, b) => a.reducerName.localeCompare(b.reducerName));
+			}
+		},
+		stream(sessionId, opts) {
+			const startAt = opts?.startAt ?? 0;
+			return { [Symbol.asyncIterator]() {
+				let last = startAt;
+				const buffer = [];
+				let wake = null;
+				let closed = false;
+				const onRow = (row) => {
+					buffer.push(row);
+					wake?.();
+				};
+				let subs = streamSubscribers.get(sessionId);
+				if (!subs) {
+					subs = /* @__PURE__ */ new Set();
+					streamSubscribers.set(sessionId, subs);
+				}
+				subs.add(onRow);
+				const existing = sessions.get(sessionId) ?? [];
+				buffer.unshift(...existing.filter((row) => row.index > startAt));
+				const unsubscribe = () => {
+					subs.delete(onRow);
+					if (subs.size === 0) streamSubscribers.delete(sessionId);
+				};
+				return {
+					async next() {
+						for (;;) {
+							while (buffer.length > 0) {
+								const row = buffer.shift();
+								if (row.index <= last) continue;
+								last = row.index;
+								return {
+									value: toStored(row),
+									done: false
+								};
+							}
+							if (closed) return {
+								value: void 0,
+								done: true
+							};
+							await new Promise((resolve) => {
+								wake = resolve;
+							});
+							wake = null;
+						}
+					},
+					async return() {
+						closed = true;
+						unsubscribe();
+						wake?.();
+						return {
+							value: void 0,
+							done: true
+						};
+					}
+				};
+			} };
+		},
+		lease: {
+			async acquire({ sessionId, holder, ttlMs, expiresAtMs }) {
+				const now = clock.now().getTime();
+				const current = leases.get(sessionId);
+				if (current && current.expiresAt > now && current.holder !== holder) return false;
+				leases.set(sessionId, {
+					holder,
+					expiresAt: expiresAtMs ?? now + ttlMs
+				});
+				return true;
+			},
+			async release({ sessionId, holder }) {
+				if (leases.get(sessionId)?.holder === holder) leases.delete(sessionId);
+			}
+		}
+	};
+}
+//#endregion
+export { memory };

package/dist/log-polling-RO7kclzR.js

@@ -0,0 +1,83 @@
+import { n as POLL_TIMINGS } from "./internal-Dm8Ejnud.js";
+//#region src/log-polling.ts
+/**
+* The shared polling stream — how poll-based backends (sqlite,
+* postgres) implement `A2Log.stream`.
+*
+* The cadence is activity-adaptive: while events are flowing, polls
+* run at a tight floor (25ms) so streams feel pushed — a token
+* generation reads smoothly instead of clumping at the idle interval;
+* every empty poll doubles the gap until the idle ceiling. The cadence
+* is owned (POLL_TIMINGS in internal.ts), not a public option: the
+* floor already keeps active streams smooth, so tuning it is a cost
+* decision a2 makes, not one it delegates. Correctness never depends
+* on the cadence — each poll is a catch-up read (`index > last`, in
+* order), so nothing can be missed, only arrive a beat later.
+*/
+const defaultSleep = (ms) => {
+	let timer;
+	let wake;
+	return {
+		promise: new Promise((resolve) => {
+			wake = resolve;
+			timer = setTimeout(resolve, ms);
+			timer.unref?.();
+		}),
+		cancel: () => {
+			clearTimeout(timer);
+			wake?.();
+		}
+	};
+};
+const ceiling = () => POLL_TIMINGS.idleCeilingMs;
+const floor = () => Math.min(POLL_TIMINGS.activeFloorMs, POLL_TIMINGS.idleCeilingMs);
+/**
+* Build the `stream()` iterable from a backend's catch-up read. The
+* iterable ends when the consumer calls `return()` (a disconnecting
+* SSE client), waking any pending sleep immediately.
+*/
+function pollingStream(readAfter, options) {
+	const startAt = options.startAt ?? 0;
+	const sleep = options.sleep ?? defaultSleep;
+	return { [Symbol.asyncIterator]() {
+		let last = startAt;
+		let buffer = [];
+		let closed = false;
+		let pending = null;
+		let interval = floor();
+		return {
+			async next() {
+				for (;;) {
+					if (closed) return {
+						value: void 0,
+						done: true
+					};
+					if (buffer.length === 0) buffer = await readAfter(last);
+					const row = buffer.shift();
+					if (row) {
+						interval = floor();
+						last = row.index;
+						return {
+							value: row,
+							done: false
+						};
+					}
+					pending = sleep(interval);
+					await pending.promise;
+					pending = null;
+					interval = Math.min(interval * 2, ceiling());
+				}
+			},
+			async return() {
+				closed = true;
+				pending?.cancel();
+				return {
+					value: void 0,
+					done: true
+				};
+			}
+		};
+	} };
+}
+//#endregion
+export { pollingStream as t };

package/dist/log-postgres.d.ts

@@ -0,0 +1,40 @@
+import { c as IdSource, i as Clock, t as A2Log } from "./log-Dg1I8NRr.js";
+//#region src/log-postgres.d.ts
+/** The result shape this backend reads: just rows. */
+type PostgresQueryResult = {
+  rows: Record<string, unknown>[];
+};
+/** One checked-out connection — what transactions run on. */
+type PostgresConnection = {
+  query(text: string, values?: unknown[]): Promise<PostgresQueryResult>;
+  release(): void;
+};
+/**
+ * The minimal client this backend needs. `pg.Pool` matches it
+ * structurally; so does PGlite (which has no `connect` — transactions
+ * then serialize on an internal mutex, fine for a single-connection
+ * client).
+ */
+type PostgresClient = {
+  query(text: string, values?: unknown[]): Promise<PostgresQueryResult>;
+  connect?(): Promise<PostgresConnection>;
+  end?(): Promise<void>;
+};
+type PostgresLogOptions = {
+  /** Creates a `pg` Pool lazily (requires the optional peer dep `pg`). */
+  connectionString?: string | undefined;
+  /** Bring your own client — a `pg` Pool, PGlite, a pooler wrapper. */
+  client?: PostgresClient;
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+type PostgresLog = A2Log & {
+  /** End the underlying pool/client (when this backend created it, or
+   * the injected client has `end`). */
+  close(): Promise<void>;
+};
+declare function postgres(options?: PostgresLogOptions): PostgresLog;
+//#endregion
+export { PostgresClient, PostgresConnection, PostgresLog, PostgresLogOptions, PostgresQueryResult, postgres };