event-sourced-collection 0.0.1 → 0.0.2

package/dist/index.d.mts

@@ -8,6 +8,18 @@ type CollectionDefConstraint = {
 };
 declare function createEventSourcedDB<const TDefs extends Record<string, CollectionDefConstraint>>(config: EventSourcedDBConfig<TDefs>): Promise<EventSourcedDB<TDefs>>;
 //#endregion
+//#region src/lazy-singleton.d.ts
+type LazySingletonOptions = {
+  guard?: () => void;
+  notInitializedMessage?: string;
+};
+type LazySingleton<T extends object> = {
+  ensure: () => Promise<T>;
+  proxy: T;
+  reset: () => void;
+};
+declare function createLazySingleton<T extends object>(factory: () => Promise<T>, options?: LazySingletonOptions): LazySingleton<T>;
+//#endregion
 //#region src/sync.d.ts
 declare function createHttpTransport(config: SyncUrlConfig): SyncTransport;
 declare class SyncPushError extends Error {
@@ -21,5 +33,5 @@ declare class SyncPullError extends Error {
   constructor(status: number, body: string);
 }
 //#endregion
-export { type CollectionDef, type CollectionMap, type CreateCollectionFn, type EventSourcedDB, type EventSourcedDBConfig, type EventSourcedLogger, type InboxEntry, type InferKey, type InferState, type ManualSyncResult, type MutationType, type OutboundEvent, type OutboxEntry, type OutboxSyncStatus, type PersistedCollectionOptionsFn, type PersistedCollectionPersistence, type PullEventsFn, type PullResponse, type PushConfirmation, type PushEventsFn, type PushFailure, type PushResponse, type ReservedCollections, type SQLiteDriver, type ServerEvent, type SyncHandlersConfig, SyncPullError, SyncPushError, type SyncResult, type SyncTransport, type SyncUrlConfig, createEventSourcedDB, createEventSourcedLogger, createHttpTransport, generateEventId };
+export { type CollectionDef, type CollectionMap, type CreateCollectionFn, type EventSourcedDB, type EventSourcedDBConfig, type EventSourcedLogger, type InboxEntry, type InferKey, type InferState, type LazySingleton, type LazySingletonOptions, type ManualSyncResult, type MutationType, type OutboundEvent, type OutboxEntry, type OutboxSyncStatus, type PersistedCollectionOptionsFn, type PersistedCollectionPersistence, type PullEventsFn, type PullResponse, type PushConfirmation, type PushEventsFn, type PushFailure, type PushResponse, type ReservedCollections, type SQLiteDriver, type ServerEvent, type SyncHandlersConfig, SyncPullError, SyncPushError, type SyncResult, type SyncTransport, type SyncUrlConfig, createEventSourcedDB, createEventSourcedLogger, createHttpTransport, createLazySingleton, generateEventId };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/create-event-sourced-db.ts","../src/sync.ts"],"mappings":";;;;KAuBK,uBAAA;EACH,MAAA,GAAS,KAAA;EACT,aAAA;AAAA;AAAA,iBAsCoB,oBAAA,qBACA,MAAA,SAAe,uBAAA,GACnC,MAAA,EAAQ,oBAAA,CAAqB,KAAA,IAAS,OAAA,CAAQ,cAAA,CAAe,KAAA;;;iBC9C/C,mBAAA,CAAoB,MAAA,EAAQ,aAAA,GAAgB,aAAa;AAAA,cAwI5D,aAAA,SAAsB,KAAK;EAAA,SAEpB,MAAA;EAAA,SACA,IAAA;cADA,MAAA,UACA,IAAA;AAAA;AAAA,cAOP,aAAA,SAAsB,KAAK;EAAA,SAEpB,MAAA;EAAA,SACA,IAAA;cADA,MAAA,UACA,IAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/create-event-sourced-db.ts","../src/lazy-singleton.ts","../src/sync.ts"],"mappings":";;;;KAuBK,uBAAA;EACH,MAAA,GAAS,KAAA;EACT,aAAA;AAAA;AAAA,iBAsCoB,oBAAA,qBACA,MAAA,SAAe,uBAAA,GACnC,MAAA,EAAQ,oBAAA,CAAqB,KAAA,IAAS,OAAA,CAAQ,cAAA,CAAe,KAAA;;;KCjEnD,oBAAA;EACV,KAAA;EACA,qBAAqB;AAAA;AAAA,KAGX,aAAA;EACV,MAAA,QAAc,OAAA,CAAQ,CAAA;EACtB,KAAA,EAAO,CAAA;EACP,KAAA;AAAA;AAAA,iBAGc,mBAAA,mBACd,OAAA,QAAe,OAAA,CAAQ,CAAA,GACvB,OAAA,GAAS,oBAAA,GACR,aAAA,CAAc,CAAA;;;iBCKD,mBAAA,CAAoB,MAAA,EAAQ,aAAA,GAAgB,aAAa;AAAA,cA8I5D,aAAA,SAAsB,KAAK;EAAA,SAEpB,MAAA;EAAA,SACA,IAAA;cADA,MAAA,UACA,IAAA;AAAA;AAAA,cAOP,aAAA,SAAsB,KAAK;EAAA,SAEpB,MAAA;EAAA,SACA,IAAA;cADA,MAAA,UACA,IAAA;AAAA"}

package/dist/index.mjs

@@ -1,584 +1,2 @@
-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 (Array.isArray(response)) return { confirmed: response };
-	return {
-		confirmed: response.confirmed,
-		failed: response.failed
-	};
-}
-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, 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, 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, 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, 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, transport, 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 transport.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, transport, targets, log) {
-	let pulled = 0;
-	let hasMore = true;
-	while (hasMore) {
-		const since = currentSince(inbox);
-		log.debug("pull inbox page", { since });
-		const response = await transport.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
-export { SyncPullError, SyncPushError, createEventSourcedDB, createEventSourcedLogger, createHttpTransport, generateEventId };
-
-//# sourceMappingURL=index.mjs.map
+import { a as SyncPullError, i as createEventSourcedLogger, n as createEventSourcedDB, o as SyncPushError, r as generateEventId, s as createHttpTransport, t as createLazySingleton } from "./lazy-singleton-DFrAsYTV.mjs";
+export { SyncPullError, SyncPushError, createEventSourcedDB, createEventSourcedLogger, createHttpTransport, createLazySingleton, generateEventId };