event-sourced-collection 0.0.1 → 0.0.2

package/dist/lazy-singleton-DFrAsYTV.mjs

@@ -0,0 +1,629 @@
+import { uuidv7 as generateEventId } from "uuidv7";
+//#region src/sync.ts
+function createHttpTransport(config) {
+	return {
+		push: createHttpPushEvents(config.push, config.headers),
+		pull: createHttpPullEvents(config.pull, config.headers)
+	};
+}
+function createSyncTransport(config) {
+	if (!config) return null;
+	if (isTransport(config)) return {
+		push: config.push,
+		pull: config.pull
+	};
+	const pushUrl = getPushUrl(config);
+	const pullUrl = getPullUrl(config);
+	const push = "pushEvents" in config && config.pushEvents ? config.pushEvents : pushUrl ? createHttpPushEvents(pushUrl, config.headers) : void 0;
+	const pullEvents = "pullEvents" in config ? config.pullEvents : void 0;
+	const pull = pullEvents ? createPullFromHandler(pullEvents) : pullUrl ? createHttpPullEvents(pullUrl, config.headers) : void 0;
+	if (!push && !pull) return null;
+	return {
+		push,
+		pull
+	};
+}
+function normalizePushResponse(response) {
+	if (isConfirmationArray(response)) return { confirmed: response };
+	return {
+		confirmed: response.confirmed,
+		failed: response.failed
+	};
+}
+function isConfirmationArray(response) {
+	return Array.isArray(response);
+}
+function createHttpPushEvents(url, headers) {
+	return async (events) => {
+		if (events.length === 0) return { confirmed: [] };
+		const resolvedHeaders = await resolveHeaders(headers);
+		const response = await fetch(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...resolvedHeaders
+			},
+			body: JSON.stringify(events)
+		});
+		if (!response.ok) throw new SyncPushError(response.status, await response.text());
+		return response.json();
+	};
+}
+function createPullFromHandler(pullEvents) {
+	return (since) => pullEvents({ since });
+}
+function createHttpPullEvents(url, headers) {
+	return async (since) => {
+		const resolvedHeaders = await resolveHeaders(headers);
+		const pullUrl = appendSince(url, since);
+		const response = await fetch(pullUrl, { headers: {
+			Accept: "application/json",
+			...resolvedHeaders
+		} });
+		if (!response.ok) throw new SyncPullError(response.status, await response.text());
+		return response.json();
+	};
+}
+async function resolveHeaders(headers) {
+	if (!headers) return {};
+	if (typeof headers === "function") return headers();
+	return headers;
+}
+function appendSince(url, since) {
+	return `${url}${url.includes("?") ? "&" : "?"}since=${encodeURIComponent(String(since))}`;
+}
+function getPushUrl(config) {
+	if ("pushUrl" in config && config.pushUrl) return config.pushUrl;
+	if ("push" in config && typeof config.push === "string") return config.push;
+}
+function getPullUrl(config) {
+	if ("pullUrl" in config && config.pullUrl) return config.pullUrl;
+	if ("pull" in config && typeof config.pull === "string") return config.pull;
+}
+var SyncPushError = class extends Error {
+	status;
+	body;
+	constructor(status, body) {
+		super(`Event push failed: HTTP ${status}`);
+		this.status = status;
+		this.body = body;
+		this.name = "SyncPushError";
+	}
+};
+var SyncPullError = class extends Error {
+	status;
+	body;
+	constructor(status, body) {
+		super(`Event pull failed: HTTP ${status}`);
+		this.status = status;
+		this.body = body;
+		this.name = "SyncPullError";
+	}
+};
+function isTransport(value) {
+	return "push" in value && typeof value.push === "function";
+}
+//#endregion
+//#region src/utils/logger.ts
+const noopLogger = {
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+};
+const LOG_PREFIX = "[event-sourced]";
+function createEventSourcedLogger(debug) {
+	if (debug === void 0 || debug === false) return noopLogger;
+	if (typeof debug === "object") return debug;
+	return {
+		debug: (message, data) => {
+			if (data === void 0) {
+				console.debug(LOG_PREFIX, message);
+				return;
+			}
+			console.debug(LOG_PREFIX, message, data);
+		},
+		info: (message, data) => {
+			if (data === void 0) {
+				console.info(LOG_PREFIX, message);
+				return;
+			}
+			console.info(LOG_PREFIX, message, data);
+		},
+		warn: (message, data) => {
+			if (data === void 0) {
+				console.warn(LOG_PREFIX, message);
+				return;
+			}
+			console.warn(LOG_PREFIX, message, data);
+		},
+		error: (message, data) => {
+			if (data === void 0) {
+				console.error(LOG_PREFIX, message);
+				return;
+			}
+			console.error(LOG_PREFIX, message, data);
+		}
+	};
+}
+//#endregion
+//#region src/create-event-sourced-db.ts
+const OUTBOX_ID = "outbox";
+const INBOX_ID = "inbox";
+const RESERVED_IDS = /* @__PURE__ */ new Set([OUTBOX_ID, INBOX_ID]);
+async function createEventSourcedDB(config) {
+	assertReservedNamesAvailable(config.collections);
+	const log = createEventSourcedLogger(config.debug);
+	const transport = createSyncTransport(config.sync);
+	log.info("creating event-sourced db", {
+		collectionIds: Object.keys(config.collections),
+		hasTransport: transport !== null
+	});
+	const defaultSchemaVersion = config.schemaVersion ?? 1;
+	const seq = { value: 0 };
+	const outbox = createMetaCollection(config, OUTBOX_ID, (entry) => entry.eventId, defaultSchemaVersion);
+	const inbox = createMetaCollection(config, INBOX_ID, (entry) => entry.eventId, defaultSchemaVersion);
+	const userCollections = {};
+	for (const collectionId of Object.keys(config.collections)) {
+		const def = config.collections[collectionId];
+		const getKey = def.getKey;
+		const options = config.persistedCollectionOptions({
+			id: collectionId,
+			getKey,
+			persistence: config.persistence,
+			schemaVersion: def.schemaVersion ?? defaultSchemaVersion,
+			onInsert: createMutationHook(outbox, collectionId, "insert", seq, log),
+			onUpdate: createMutationHook(outbox, collectionId, "update", seq, log),
+			onDelete: createMutationHook(outbox, collectionId, "delete", seq, log)
+		});
+		const collection = config.createCollection(options);
+		const hasAcceptMutations = Boolean(collection.utils?.acceptMutations);
+		log.debug("registered collection", {
+			collectionId,
+			hasAcceptMutations
+		});
+		userCollections[collectionId] = collection;
+	}
+	const collections = {
+		...userCollections,
+		outbox,
+		inbox
+	};
+	const replayTargets = collections;
+	const subscriptions = [outbox.subscribeChanges(() => {}), inbox.subscribeChanges(() => {})];
+	await outbox.preload();
+	await inbox.preload();
+	seq.value = nextLocalSeq(outbox);
+	log.info("preloaded meta collections", {
+		outboxCount: outbox.state.size,
+		inboxCount: inbox.state.size,
+		nextLocalSeq: seq.value
+	});
+	await replayInbox(inbox, replayTargets, log);
+	async function sync() {
+		if (!transport) {
+			log.warn("sync skipped: no transport configured");
+			return {
+				pushed: 0,
+				pulled: 0,
+				errors: []
+			};
+		}
+		log.info("sync started");
+		await outbox.preload();
+		await inbox.preload();
+		const errors = [];
+		let pushed = 0;
+		let pulled = 0;
+		try {
+			if (transport.push) pushed = await pushOutbox(outbox, transport.push, log);
+			else log.debug("push skipped: no push transport configured");
+		} catch (err) {
+			const error = toError(err);
+			log.error("push outbox failed", { message: error.message });
+			errors.push(error);
+		}
+		try {
+			if (transport.pull) pulled = await pullInbox(outbox, inbox, transport.pull, replayTargets, log);
+			else log.debug("pull skipped: no pull transport configured");
+		} catch (err) {
+			const error = toError(err);
+			log.error("pull inbox failed", { message: error.message });
+			errors.push(error);
+		}
+		log.info("sync finished", {
+			pushed,
+			pulled,
+			errorCount: errors.length
+		});
+		return {
+			pushed,
+			pulled,
+			errors
+		};
+	}
+	async function manualSync() {
+		log.info("manual sync started");
+		await outbox.preload();
+		await inbox.preload();
+		const errors = [];
+		let pushed = 0;
+		let pulled = 0;
+		let replayed = 0;
+		if (transport) {
+			try {
+				if (transport.push) pushed = await pushOutbox(outbox, transport.push, log);
+				else log.debug("manual sync push skipped: no push transport configured");
+			} catch (err) {
+				const error = toError(err);
+				log.error("manual sync push failed", { message: error.message });
+				errors.push(error);
+			}
+			try {
+				if (transport.pull) pulled = await pullInbox(outbox, inbox, transport.pull, replayTargets, log);
+				else log.debug("manual sync pull skipped: no pull transport configured");
+			} catch (err) {
+				const error = toError(err);
+				log.error("manual sync pull failed", { message: error.message });
+				errors.push(error);
+			}
+		} else log.warn("manual sync: no transport configured, skipping push/pull");
+		try {
+			replayed = await replayInbox(inbox, replayTargets, log);
+		} catch (err) {
+			const error = toError(err);
+			log.error("manual sync replay failed", { message: error.message });
+			errors.push(error);
+		}
+		log.info("manual sync finished", {
+			pushed,
+			pulled,
+			replayed,
+			errorCount: errors.length
+		});
+		return {
+			pushed,
+			pulled,
+			replayed,
+			errors
+		};
+	}
+	function dispose() {
+		log.debug("disposing event-sourced db");
+		for (const subscription of subscriptions) subscription.unsubscribe();
+	}
+	return {
+		collections,
+		sync,
+		manualSync,
+		dispose
+	};
+}
+function createMetaCollection(config, id, getKey, schemaVersion) {
+	const options = config.persistedCollectionOptions({
+		id,
+		getKey,
+		persistence: config.persistence,
+		schemaVersion
+	});
+	return config.createCollection(options);
+}
+function createMutationHook(outbox, collectionId, type, seq, log) {
+	return async (params) => {
+		for (const mutation of params.transaction.mutations) {
+			const payload = type === "delete" ? mutation.original : mutation.modified;
+			const entry = {
+				eventId: generateEventId(),
+				collectionId,
+				type,
+				key: mutation.key,
+				payload,
+				timestamp: Date.now(),
+				localSeq: seq.value++,
+				globalSeq: null,
+				sync: false,
+				syncStatus: "pending",
+				attemptCount: 0,
+				lastAttemptAt: null,
+				lastError: null,
+				lastErrorCode: null,
+				retryable: null
+			};
+			await outbox.insert(entry).isPersisted.promise;
+			log.debug("outbox entry created", {
+				eventId: entry.eventId,
+				collectionId,
+				type,
+				key: entry.key,
+				localSeq: entry.localSeq
+			});
+		}
+		return {};
+	};
+}
+async function pushOutbox(outbox, push, log) {
+	const pending = [...outbox.state.values()].filter((entry) => !entry.sync && entry.syncStatus !== "failed").sort((a, b) => a.localSeq - b.localSeq);
+	log.debug("push outbox", { pendingCount: pending.length });
+	if (pending.length === 0) return 0;
+	const attemptAt = Date.now();
+	for (const entry of pending) await outbox.update(entry.eventId, (draft) => {
+		draft.syncStatus = "pending";
+		draft.attemptCount = (draft.attemptCount ?? 0) + 1;
+		draft.lastAttemptAt = attemptAt;
+		draft.lastError = null;
+		draft.lastErrorCode = null;
+		draft.retryable = null;
+	}).isPersisted.promise;
+	const outbound = pending.map((entry) => ({
+		eventId: entry.eventId,
+		collectionId: entry.collectionId,
+		type: entry.type,
+		key: entry.key,
+		payload: entry.payload,
+		timestamp: entry.timestamp
+	}));
+	const response = normalizePushResponse(await push(outbound));
+	log.info("push outbox confirmed", {
+		sent: outbound.length,
+		confirmed: response.confirmed.length,
+		failed: response.failed?.length ?? 0
+	});
+	for (const confirmation of response.confirmed) {
+		await outbox.update(confirmation.eventId, (draft) => {
+			draft.sync = true;
+			draft.syncStatus = "synced";
+			draft.globalSeq = confirmation.globalSeq;
+			draft.lastError = null;
+			draft.lastErrorCode = null;
+			draft.retryable = null;
+		}).isPersisted.promise;
+		log.debug("outbox entry marked pushed", {
+			eventId: confirmation.eventId,
+			globalSeq: confirmation.globalSeq
+		});
+	}
+	for (const failure of response.failed ?? []) {
+		await outbox.update(failure.eventId, (draft) => {
+			draft.sync = false;
+			draft.syncStatus = "failed";
+			draft.lastError = failure.message;
+			draft.lastErrorCode = failure.code ?? null;
+			draft.retryable = failure.retryable ?? null;
+		}).isPersisted.promise;
+		log.warn("outbox entry marked failed", {
+			eventId: failure.eventId,
+			message: failure.message,
+			code: failure.code,
+			retryable: failure.retryable
+		});
+	}
+	return response.confirmed.length;
+}
+async function pullInbox(outbox, inbox, pull, targets, log) {
+	let pulled = 0;
+	let hasMore = true;
+	while (hasMore) {
+		const since = currentSince(inbox);
+		log.debug("pull inbox page", { since });
+		const response = await pull(since);
+		log.debug("pull inbox response", {
+			since,
+			eventCount: response.events.length,
+			hasMore: response.hasMore,
+			cursor: response.cursor
+		});
+		if (response.events.length === 0) break;
+		const sorted = [...response.events].sort((a, b) => a.globalSeq - b.globalSeq);
+		for (const event of sorted) {
+			if (outbox.has(event.eventId)) {
+				await markInboxEventSynced(inbox, event);
+				log.debug("pull skipped: event originated locally", {
+					eventId: event.eventId,
+					globalSeq: event.globalSeq
+				});
+				continue;
+			}
+			const existing = inbox.get(event.eventId);
+			if (existing?.sync) {
+				log.debug("pull skipped: inbox already applied", {
+					eventId: event.eventId,
+					globalSeq: event.globalSeq
+				});
+				continue;
+			}
+			if (!existing) {
+				await inbox.insert(toInboxEntry(event, false)).isPersisted.promise;
+				log.debug("inbox entry inserted", {
+					eventId: event.eventId,
+					globalSeq: event.globalSeq,
+					collectionId: event.collectionId
+				});
+			}
+			if (!await replayEvent(targets, event.collectionId, event.eventId, event.type, event.key, event.payload, log)) return pulled;
+			await inbox.update(event.eventId, (draft) => {
+				draft.sync = true;
+			}).isPersisted.promise;
+			log.info("pull replay applied", {
+				eventId: event.eventId,
+				globalSeq: event.globalSeq,
+				collectionId: event.collectionId,
+				type: event.type,
+				key: event.key
+			});
+			pulled++;
+		}
+		hasMore = response.hasMore;
+	}
+	log.info("pull inbox finished", { pulled });
+	return pulled;
+}
+async function replayInbox(inbox, targets, log) {
+	const pending = [...inbox.state.values()].filter((entry) => !entry.sync).sort((a, b) => a.globalSeq - b.globalSeq);
+	log.info("pending inbox replay started", { pendingCount: pending.length });
+	let replayed = 0;
+	for (const entry of pending) {
+		if (!await replayEvent(targets, entry.collectionId, entry.eventId, entry.type, entry.key, entry.payload, log)) break;
+		await inbox.update(entry.eventId, (draft) => {
+			draft.sync = true;
+		}).isPersisted.promise;
+		replayed++;
+		log.info("pending inbox replay applied", {
+			eventId: entry.eventId,
+			globalSeq: entry.globalSeq,
+			collectionId: entry.collectionId
+		});
+	}
+	log.info("pending inbox replay finished", { replayed });
+	return replayed;
+}
+async function replayEvent(targets, collectionId, eventId, type, key, payload, log) {
+	if (RESERVED_IDS.has(collectionId)) {
+		log.warn("replay skipped: reserved collection", {
+			eventId,
+			collectionId,
+			type,
+			key
+		});
+		return false;
+	}
+	const target = targets[collectionId];
+	if (!target) {
+		log.warn("replay skipped: unknown collection", {
+			eventId,
+			collectionId,
+			type,
+			key,
+			knownCollections: Object.keys(targets).filter((id) => !RESERVED_IDS.has(id))
+		});
+		return false;
+	}
+	if (!target.utils.acceptMutations) {
+		log.warn("replay skipped: collection missing acceptMutations", {
+			eventId,
+			collectionId,
+			type,
+			key,
+			targetId: target.id
+		});
+		return false;
+	}
+	log.debug("replay applying mutation", {
+		eventId,
+		collectionId,
+		type,
+		key
+	});
+	try {
+		await target.utils.acceptMutations({ mutations: [{
+			mutationId: eventId,
+			type,
+			key,
+			modified: payload,
+			original: payload,
+			changes: payload,
+			collection: target
+		}] });
+		log.info("replay mutation accepted", {
+			eventId,
+			collectionId,
+			type,
+			key
+		});
+	} catch (err) {
+		const error = toError(err);
+		log.error("replay mutation failed", {
+			eventId,
+			collectionId,
+			type,
+			key,
+			message: error.message
+		});
+		throw error;
+	}
+	return true;
+}
+function currentSince(inbox) {
+	let max = 0;
+	for (const entry of inbox.state.values()) if (entry.sync && entry.globalSeq > max) max = entry.globalSeq;
+	return max;
+}
+function nextLocalSeq(outbox) {
+	let max = -1;
+	for (const entry of outbox.state.values()) if (entry.localSeq > max) max = entry.localSeq;
+	return max + 1;
+}
+async function markInboxEventSynced(inbox, event) {
+	const existing = inbox.get(event.eventId);
+	if (!existing) {
+		await inbox.insert(toInboxEntry(event, true)).isPersisted.promise;
+		return;
+	}
+	if (!existing.sync || existing.globalSeq !== event.globalSeq) await inbox.update(event.eventId, (draft) => {
+		draft.globalSeq = event.globalSeq;
+		draft.sync = true;
+	}).isPersisted.promise;
+}
+function toInboxEntry(event, sync) {
+	return {
+		eventId: event.eventId,
+		globalSeq: event.globalSeq,
+		collectionId: event.collectionId,
+		type: event.type,
+		key: event.key,
+		payload: event.payload,
+		timestamp: event.timestamp,
+		sync
+	};
+}
+function assertReservedNamesAvailable(collections) {
+	for (const id of Object.keys(collections)) if (RESERVED_IDS.has(id)) throw new Error(`Collection id "${id}" is reserved. "outbox" and "inbox" are built-in collections.`);
+}
+function toError(err) {
+	return err instanceof Error ? err : new Error(String(err));
+}
+//#endregion
+//#region src/lazy-singleton.ts
+function createLazySingleton(factory, options = {}) {
+	let instance = null;
+	let initPromise = null;
+	const ensure = async () => {
+		options.guard?.();
+		if (instance) return instance;
+		if (!initPromise) initPromise = factory().then((resolved) => {
+			instance = resolved;
+			return resolved;
+		}).catch((error) => {
+			initPromise = null;
+			throw error;
+		});
+		return initPromise;
+	};
+	const message = options.notInitializedMessage ?? "Instance is not initialized. Call ensure() first.";
+	const proxy = new Proxy({}, {
+		get(_target, prop, receiver) {
+			if (!instance) throw new Error(message);
+			return Reflect.get(instance, prop, receiver);
+		},
+		has(_target, prop) {
+			if (!instance) throw new Error(message);
+			return Reflect.has(instance, prop);
+		},
+		getPrototypeOf() {
+			if (!instance) throw new Error(message);
+			return Reflect.getPrototypeOf(instance);
+		}
+	});
+	const reset = () => {
+		instance = null;
+		initPromise = null;
+	};
+	return {
+		ensure,
+		proxy,
+		reset
+	};
+}
+//#endregion
+export { SyncPullError as a, createEventSourcedLogger as i, createEventSourcedDB as n, SyncPushError as o, generateEventId as r, createHttpTransport as s, createLazySingleton as t };
+
+//# sourceMappingURL=lazy-singleton-DFrAsYTV.mjs.map