event-sourced-collection 0.0.13 → 0.0.14

package/dist/browser.d.mts

@@ -1,6 +1,36 @@
-import { a as BrowserPlatformConfig, c as BrowserWASQLiteDatabase, i as BrowserCoordinatorInstance, n as BrowserEventSourcedModules, o as BrowserPlatformDeps, r as createBrowserEventSourcedDB, s as BrowserPlatformResult, t as BrowserEventSourcedDBConfig } from "./browser-event-sourced-db-D3vSW3QV.mjs";
-import { t as EventSourcedDBHandle } from "./create-event-sourced-db-handle-DmHdplVr.mjs";
+import { I as SQLiteDriver, nt as InjectedModuleFn, p as EventSourcedSharedOptions, tt as InjectedCreateCollection, z as SyncLock } from "./types-Dc-_92xv.mjs";
+import { r as ModulesInput, t as EventSourcedDBHandle } from "./create-event-sourced-db-handle-DlUfot8-.mjs";
+import { PersistedCollectionPersistence } from "@tanstack/db-sqlite-persistence-core";
 
+//#region src/platforms/browser-wa-sqlite-driver.d.ts
+type BrowserWASQLiteDatabase = {
+  execute: <TRow = unknown>(sql: string, params?: ReadonlyArray<unknown>) => Promise<ReadonlyArray<TRow>>;
+  close?: () => Promise<void> | void;
+};
+//#endregion
+//#region src/platforms/browser-types.d.ts
+type BrowserCoordinatorInstance = {
+  dispose: () => void;
+};
+/**
+ * Injected TanStack browser persistence bindings. Parameters are `never` so
+ * version-skewed `@tanstack/browser-db-sqlite-persistence` exports stay assignable.
+ */
+type BrowserPlatformDeps = {
+  openBrowserWASQLiteOPFSDatabase: (options: never) => Promise<BrowserWASQLiteDatabase>;
+  createBrowserWASQLitePersistence: (options: never) => PersistedCollectionPersistence;
+  BrowserCollectionCoordinator: new (options: never) => BrowserCoordinatorInstance;
+};
+type BrowserPlatformConfig = {
+  databaseName: string;
+  coordinatorDbName?: string;
+};
+type BrowserPlatformResult = {
+  driver: SQLiteDriver;
+  persistence: PersistedCollectionPersistence;
+  close: () => Promise<void>;
+};
+//#endregion
 //#region src/platforms/browser.d.ts
 /**
  * Opens OPFS SQLite, a cross-tab coordinator, and TanStack persistence.
@@ -31,5 +61,91 @@ import { t as EventSourcedDBHandle } from "./create-event-sourced-db-handle-DmHd
  */
 declare function createBrowserPlatform(deps: BrowserPlatformDeps, config: BrowserPlatformConfig): Promise<BrowserPlatformResult>;
 //#endregion
+//#region src/platforms/browser-event-sourced-db.d.ts
+type CollectionDefConstraint = {
+  getKey: (state: never) => string | number;
+};
+type BrowserEventSourcedModules = BrowserPlatformDeps & {
+  createCollection: InjectedCreateCollection;
+  persistedCollectionOptions: InjectedModuleFn;
+};
+/**
+ * Browser entry-point config. Shared sync/lifecycle fields come from
+ * {@link EventSourcedSharedOptions} (hover those properties for docs).
+ * Deep guide: `docs/usage.md`.
+ */
+type BrowserEventSourcedDBConfig<TDefs extends Record<string, CollectionDefConstraint>> = Omit<EventSourcedSharedOptions, "lock" | "lockName"> & {
+  /**
+   * User collection registry. Object keys become `db.collections.<key>` and
+   * the wire `collectionId`. Must not collide with reserved names.
+   */
+  collections: TDefs;
+  /**
+   * OPFS SQLite database file name (e.g. `"my-app.sqlite"`). Also used as the
+   * default sync lock namespace so only one tab syncs for this DB at a time.
+   */
+  databaseName: string;
+  /**
+   * Name for the cross-tab collection coordinator database. Defaults to
+   * `databaseName` with a trailing `.sqlite` stripped.
+   */
+  coordinatorDbName?: string;
+  /**
+   * Browser OPFS persistence modules from
+   * `@tanstack/browser-db-sqlite-persistence` plus `createCollection`.
+   * Pass the imported bindings directly, or a function to keep WASM off the
+   * critical path.
+   */
+  modules: ModulesInput<BrowserEventSourcedModules>;
+  /**
+   * Defaults to a Web Locks–backed lock so only one tab syncs at a time.
+   * Pass `null` to opt out and let every tab sync independently.
+   */
+  lock?: SyncLock | null;
+};
+/**
+ * Browser-flavoured event-sourced DB: OPFS SQLite + optional Web Locks sync
+ * election, returned as a lazy singleton.
+ *
+ * @param config - See {@link BrowserEventSourcedDBConfig} for every option.
+ *
+ * @example
+ * ```ts
+ * import { createBrowserEventSourcedDB } from "event-sourced-collection/browser"
+ * import type { CollectionDef, EventSourcedDB } from "event-sourced-collection"
+ *
+ * type Todo = { id: string; title: string }
+ * type Defs = { todos: CollectionDef<Todo, string> }
+ *
+ * const { ensureDb, db } = createBrowserEventSourcedDB<Defs>({
+ *   databaseName: "app.sqlite",
+ *   collections: { todos: { getKey: (todo) => todo.id } },
+ *   sync: { push: "/api/sync/events", pull: "/api/sync/events" },
+ *   modules: async () => {
+ *     const { createCollection } = await import("@tanstack/db")
+ *     const {
+ *       BrowserCollectionCoordinator,
+ *       createBrowserWASQLitePersistence,
+ *       openBrowserWASQLiteOPFSDatabase,
+ *       persistedCollectionOptions,
+ *     } = await import("@tanstack/browser-db-sqlite-persistence")
+ *     return {
+ *       createCollection,
+ *       BrowserCollectionCoordinator,
+ *       createBrowserWASQLitePersistence,
+ *       openBrowserWASQLiteOPFSDatabase,
+ *       persistedCollectionOptions,
+ *     }
+ *   },
+ * })
+ *
+ * export async function start() {
+ *   await ensureDb()
+ * }
+ * export { db }
+ * ```
+ */
+declare function createBrowserEventSourcedDB<const TDefs extends Record<string, CollectionDefConstraint>>(config: BrowserEventSourcedDBConfig<TDefs>): EventSourcedDBHandle<TDefs>;
+//#endregion
 export { type BrowserCoordinatorInstance, type BrowserEventSourcedDBConfig, type EventSourcedDBHandle as BrowserEventSourcedDBHandle, type BrowserEventSourcedModules, type BrowserPlatformConfig, type BrowserPlatformDeps, type BrowserPlatformResult, type BrowserWASQLiteDatabase, createBrowserEventSourcedDB, createBrowserPlatform };
 //# sourceMappingURL=browser.d.mts.map

package/dist/browser.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.mts","names":[],"sources":["../src/platforms/browser.ts"],"mappings":";;;;;AA2CA;;;;;;;;;;;;;;;;AAGgC;;;;;;;;;;iBAHV,qBAAA,CACpB,IAAA,EAAM,mBAAA,EACN,MAAA,EAAQ,qBAAA,GACP,OAAA,CAAQ,qBAAA"}
+{"version":3,"file":"browser.d.mts","names":[],"sources":["../src/platforms/browser-wa-sqlite-driver.ts","../src/platforms/browser-types.ts","../src/platforms/browser.ts","../src/platforms/browser-event-sourced-db.ts"],"mappings":";;;;;KAEY,uBAAA;EACV,OAAA,mBACE,GAAA,UACA,MAAA,GAAS,aAAA,cACN,OAAA,CAAQ,aAAA,CAAc,IAAA;EAC3B,KAAA,SAAc,OAAA;AAAA;;;KCJJ,0BAAA;EACV,OAAO;AAAA;;ADFT;;;KCSY,mBAAA;EACV,+BAAA,GAAkC,OAAA,YAAmB,OAAA,CAAQ,uBAAA;EAC7D,gCAAA,GAAmC,OAAA,YAAmB,8BAAA;EACtD,4BAAA,OAAmC,OAAA,YAAmB,0BAAA;AAAA;AAAA,KAG5C,qBAAA;EACV,YAAA;EACA,iBAAiB;AAAA;AAAA,KAGP,qBAAA;EACV,MAAA,EAD+B,YAAA;EAE/B,WAAA,EAAa,8BAAA;EACb,KAAA,QAAa,OAAA;AAAA;;;;;;ADvBf;;;;;;;;;;;;;;;;;;;;;AAKuB;;;iBEoCD,qBAAA,CACpB,IAAA,EAAM,mBAAA,EACN,MAAA,EAAQ,qBAAA,GACP,OAAA,CAAQ,qBAAA;;;KC9BN,uBAAA;EACH,MAAA,GAAS,KAAY;AAAA;AAAA,KAGX,0BAAA,GAA6B,mBAAA;EACvC,gBAAA,EAAkB,wBAAA;EAClB,0BAAA,EAA4B,gBAAA;AAAA;;;;;;KAQlB,2BAAA,eAA0C,MAAA,SAAe,uBAAA,KACnE,IAAA,CAAK,yBAAA;EH5BK;;;;EGiCR,WAAA,EAAa,KAAA;EH9BF;;;;EGmCX,YAAA;EHlCmB;;;;EGuCnB,iBAAA;EF3CkC;;;AAC7B;AAOT;;EE0CI,OAAA,EAAS,YAAA,CAAa,0BAAA;EFzCqC;;;;EE8C3D,IAAA,GAAO,QAAA;AAAA;;;;;;;;;;;AF5CuE;AAGlF;;;;AAEmB;AAGnB;;;;;;;;;;;;;;;AAGsB;;;;ACkBtB;;;;;;;iBC8DgB,2BAAA,qBACM,MAAA,SAAe,uBAAA,GACnC,MAAA,EAAQ,2BAAA,CAA4B,KAAA,IAAM,oBAAA,CAAA,KAAA"}

package/dist/browser.mjs

@@ -1,4 +1,4 @@
-import { n as resolveModules, t as createEventSourcedDBHandle } from "./create-event-sourced-db-handle-BqV3vLjS.mjs";
+import { n as resolveModules, t as createEventSourcedDBHandle } from "./create-event-sourced-db-handle-BRSDLeq9.mjs";
 import { t as createWebLocksSyncLock } from "./web-locks-Bi2f732X.mjs";
 //#region src/platforms/browser-wa-sqlite-driver.ts
 function assertTransactionCallbackHasDriverArg(fn) {

package/dist/{create-event-sourced-db-handle-BqV3vLjS.mjs → create-event-sourced-db-handle-BRSDLeq9.mjs}

@@ -1380,6 +1380,18 @@ function generateEventId() {
 }
 //#endregion
 //#region src/core/create-event-sourced-db.ts
+/**
+* Thrown by `resetLocalReplica()` while the outbox still holds changes the
+* server has not accepted. Sync first, or pass `discardPending: true`.
+*/
+var UnsyncedChangesError = class extends Error {
+	pendingCount;
+	constructor(pendingCount) {
+		super(`${pendingCount} local change(s) have not been pushed yet`);
+		this.pendingCount = pendingCount;
+		this.name = "UnsyncedChangesError";
+	}
+};
 function emptyResult(overrides = {}) {
 	return {
 		pushed: 0,
@@ -1475,6 +1487,7 @@ async function createEventSourcedDB(config) {
 	};
 	const { outbox, inbox, deadletter, syncmeta, rowversions } = meta;
 	const userCollections = {};
+	const syncedCollections = [];
 	const localOnlyIds = new Set(Object.keys(config.collections).filter((id) => config.collections[id].localOnly === true));
 	for (const collectionId of Object.keys(config.collections)) {
 		const def = config.collections[collectionId];
@@ -1506,6 +1519,10 @@ async function createEventSourcedDB(config) {
 		});
 		const collection = config.createCollection(options);
 		applyCollectionIndexes(collection, collectionId, def.indexes, log);
+		if (!def.localOnly) syncedCollections.push({
+			collectionId,
+			collection
+		});
 		log.debug("registered collection", {
 			collectionId,
 			hasAcceptMutations: Boolean(collection.utils?.acceptMutations)
@@ -1870,6 +1887,59 @@ async function createEventSourcedDB(config) {
 			};
 		});
 	}
+	function resetLocalReplica(options = {}) {
+		const deferred = {
+			deferred: true,
+			removedRows: 0,
+			discardedPending: 0,
+			clientId: clientId.value
+		};
+		return runExclusive(() => withLock(async () => {
+			const pending = [...outbox.state.values()].filter((entry) => !entry.sync);
+			if (pending.length > 0 && options.discardPending !== true) throw new UnsyncedChangesError(pending.length);
+			let removedRows = 0;
+			for (const { collectionId, collection } of syncedCollections) {
+				const target = replayTargets[collectionId];
+				const rows = [...collection.state.entries()];
+				if (rows.length === 0 || !target?.utils.acceptMutations) continue;
+				await target.utils.acceptMutations({ mutations: rows.map(([key, row]) => ({
+					mutationId: generateEventId(),
+					type: "delete",
+					key,
+					modified: row,
+					original: row,
+					changes: row,
+					collection: target
+				})) });
+				removedRows += rows.length;
+			}
+			for (const meta of [
+				outbox,
+				inbox,
+				deadletter
+			]) for (const eventId of [...meta.state.keys()]) await meta.delete(eventId).isPersisted.promise;
+			for (const id of [...rowversions.state.keys()]) await rowversions.delete(id).isPersisted.promise;
+			clientId.value = generateEventId();
+			await ensureSyncMeta(syncmeta);
+			await syncmeta.update(SYNCMETA_KEY, (draft) => {
+				draft.clientId = clientId.value;
+				draft.pullCursor = 0;
+				draft.lastError = null;
+			}).isPersisted.promise;
+			log.warn("local replica reset", {
+				removedRows,
+				discardedPending: pending.length,
+				clientId: clientId.value
+			});
+			notifyStatus();
+			return {
+				deferred: false,
+				removedRows,
+				discardedPending: pending.length,
+				clientId: clientId.value
+			};
+		}, deferred));
+	}
 	function getSyncEnabled() {
 		return syncEnabled;
 	}
@@ -1902,6 +1972,7 @@ async function createEventSourcedDB(config) {
 			return pushLimits;
 		},
 		pruneSyncedEvents,
+		resetLocalReplica,
 		dispose
 	};
 }
@@ -2199,6 +2270,6 @@ async function resolveModules(modules) {
 	return typeof modules === "function" ? await modules() : modules;
 }
 //#endregion
-export { generateEventId as a, resolvePushLimits as c, createHttpTransport as d, BackendMismatchError as f, createEventSourcedDB as i, SyncPullError as l, resolveModules as n, createEventSourcedLogger as o, createLazySingleton as r, SYNC_PUSH_PRESETS as s, createEventSourcedDBHandle as t, SyncPushError as u };
+export { createEventSourcedDB as a, SYNC_PUSH_PRESETS as c, SyncPushError as d, createHttpTransport as f, UnsyncedChangesError as i, resolvePushLimits as l, resolveModules as n, generateEventId as o, BackendMismatchError as p, createLazySingleton as r, createEventSourcedLogger as s, createEventSourcedDBHandle as t, SyncPullError as u };
 
-//# sourceMappingURL=create-event-sourced-db-handle-BqV3vLjS.mjs.map
+//# sourceMappingURL=create-event-sourced-db-handle-BRSDLeq9.mjs.map