@questpie/tanstack-db 3.24.0 → 3.25.1

package/README.md

@@ -36,6 +36,16 @@ pagination, locale, stage, and soft-delete controls. Projections (`columns`),
 relation expansion (`with`), extras, and grouping are rejected because every
 TanStack DB row must retain the base collection shape and its canonical `id`.
 
+Snapshot mode narrows that set further, to what a live subscription can carry:
+`where`, `orderBy`, `limit`, `offset` and `locale`. `search`, `stage`,
+`includeDeleted` and `localeFallback` are rejected there, because the live
+snapshot would ignore them while the post-mutation repair read applied them —
+one collection describing two different row sets.
+
+A mutation that loses an optimistic-concurrency race rejects with
+`QuestpieDbConflictError`. The optimistic state is already rolled back, so
+refetch before retrying: the row still on screen carries the revision that lost.
+
 The package currently supports refetch and full-snapshot synchronization. Native
 row-delta synchronization is added independently without changing the collection
 factory API.

package/dist/index.d.mts

@@ -1,11 +1,36 @@
 import { Collection, and, eq, gt, inArray, lt, or } from "@tanstack/db";
 import { useLiveQuery } from "@tanstack/react-db";
 import { QueryClient, QueryKey } from "@tanstack/react-query";
-import { ApplyQuery, CollectionRelations, CollectionSelectFromApp, FindManyOptions, GetCollection, QuestpieApp, QuestpieClient, ResolveRelationsDeep } from "questpie/client";
+import { ApplyQuery, CollectionRelations, CollectionSelectFromApp, FindManyOptions, GetCollection, LiveQueryOptions, QuestpieApp, QuestpieClient, ResolveRelationsDeep } from "questpie/client";
 
 //#region src/sync.d.ts
 type QuestpieDbSyncMode = "refetch" | "snapshot";
 //#endregion
+//#region src/collection.d.ts
+
+/**
+ * A mutation lost an optimistic-concurrency race: QUESTPIE answered `409`
+ * (`CONFLICT`), or `412` when the request carried `If-Match`. TanStack DB has
+ * already rolled the optimistic state back, so the row on screen is the stale
+ * one that lost — refetch the collection before retrying, otherwise the retry
+ * carries the same stale revision and conflicts again.
+ *
+ * `ids` lists every row in the failed transaction. QUESTPIE validates all
+ * revisions before writing any row, so a conflict fails the whole batch without
+ * naming the individual loser.
+ */
+declare class QuestpieDbConflictError extends Error {
+  readonly collection: string;
+  readonly operation: "update" | "delete";
+  readonly ids: string[];
+  constructor(options: {
+    collection: string;
+    operation: "update" | "delete";
+    ids: string[];
+    cause: unknown;
+  });
+}
+//#endregion
 //#region src/types.d.ts
 type CollectionKeys<TApp extends QuestpieApp> = Extract<keyof QuestpieClient<TApp>["collections"], string>;
 type CollectionSelectOf<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = CollectionSelectFromApp<GetCollection<TApp["collections"], K$1>, {
@@ -13,6 +38,14 @@ type CollectionSelectOf<TApp extends QuestpieApp, K$1 extends CollectionKeys<TAp
 }>;
 type CollectionRelationsOf<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = ResolveRelationsDeep<CollectionRelations<GetCollection<TApp["collections"], K$1>>, TApp["collections"]>;
 type FindOptionsOf<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = Pick<FindManyOptions<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>>, "where" | "orderBy" | "limit" | "offset" | "search" | "locale" | "localeFallback" | "includeDeleted" | "stage">;
+/**
+ * The find options a `syncMode: "snapshot"` collection may use: the ones the
+ * realtime topic carries. `live()` re-runs the query server-side from those
+ * topic fields alone, so anything it drops would make the live snapshot and the
+ * `find()` repair describe different rows. Derived from `LiveQueryOptions` so
+ * the two cannot drift.
+ */
+type SnapshotFindOptionsOf<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = Pick<FindOptionsOf<TApp, K$1>, Extract<keyof FindOptionsOf<TApp, K$1>, keyof LiveQueryOptions<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>>>>;
 type CollectionRowOf<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = ApplyQuery<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>, undefined>;
 type IdOf<TRow> = TRow extends {
   id: infer TId;
@@ -24,13 +57,13 @@ type QuestpieDb<TApp extends QuestpieApp> = {
 };
 //#endregion
 //#region src/factory.d.ts
-type QuestpieFindOptions<TApp extends QuestpieApp> = Partial<{ [K in CollectionKeys<TApp>]: FindOptionsOf<TApp, K> }>;
-type CreateQuestpieCollectionsOptions<TApp extends QuestpieApp> = {
+type QuestpieFindOptions<TApp extends QuestpieApp, TMode extends QuestpieDbSyncMode = QuestpieDbSyncMode> = Partial<{ [K in CollectionKeys<TApp>]: TMode extends "snapshot" ? SnapshotFindOptionsOf<TApp, K> : FindOptionsOf<TApp, K> }>;
+type CreateQuestpieCollectionsOptions<TApp extends QuestpieApp, TMode extends QuestpieDbSyncMode = QuestpieDbSyncMode> = {
   queryClient: QueryClient;
-  syncMode?: QuestpieDbSyncMode;
-  find?: QuestpieFindOptions<TApp>;
+  syncMode?: TMode;
+  find?: QuestpieFindOptions<TApp, TMode>;
   keyPrefix?: QueryKey;
 };
-declare function createQuestpieCollections<TApp extends QuestpieApp>(client: QuestpieClient<TApp>, options: CreateQuestpieCollectionsOptions<TApp>): QuestpieDb<TApp>;
+declare function createQuestpieCollections<TApp extends QuestpieApp, TMode extends QuestpieDbSyncMode = QuestpieDbSyncMode>(client: QuestpieClient<TApp>, options: CreateQuestpieCollectionsOptions<TApp, TMode>): QuestpieDb<TApp>;
 //#endregion
-export { type CollectionKeys, type CollectionRelationsOf, type CollectionRowOf, type CollectionSelectOf, type CreateQuestpieCollectionsOptions, type FindOptionsOf, type IdOf, type QuestpieCollections, type QuestpieDb, type QuestpieDbSyncMode, type QuestpieFindOptions, and, createQuestpieCollections, eq, gt, inArray, lt, or, useLiveQuery };
+export { type CollectionKeys, type CollectionRelationsOf, type CollectionRowOf, type CollectionSelectOf, type CreateQuestpieCollectionsOptions, type FindOptionsOf, type IdOf, type QuestpieCollections, type QuestpieDb, QuestpieDbConflictError, type QuestpieDbSyncMode, type QuestpieFindOptions, type SnapshotFindOptionsOf, and, createQuestpieCollections, eq, gt, inArray, lt, or, useLiveQuery };

package/dist/index.mjs

@@ -72,6 +72,61 @@ function resolveSync(options) {
 
 //#endregion
 //#region src/collection.ts
+/**
+* A mutation lost an optimistic-concurrency race: QUESTPIE answered `409`
+* (`CONFLICT`), or `412` when the request carried `If-Match`. TanStack DB has
+* already rolled the optimistic state back, so the row on screen is the stale
+* one that lost — refetch the collection before retrying, otherwise the retry
+* carries the same stale revision and conflicts again.
+*
+* `ids` lists every row in the failed transaction. QUESTPIE validates all
+* revisions before writing any row, so a conflict fails the whole batch without
+* naming the individual loser.
+*/
+var QuestpieDbConflictError = class extends Error {
+	collection;
+	operation;
+	ids;
+	constructor(options) {
+		super(`QUESTPIE rejected a ${options.operation} on "${options.collection}" as a conflict: ${options.ids.join(", ")}`, { cause: options.cause });
+		this.name = "QuestpieDbConflictError";
+		this.collection = options.collection;
+		this.operation = options.operation;
+		this.ids = options.ids;
+	}
+};
+function isConflict(error) {
+	if (!error || typeof error !== "object") return false;
+	const { code, status } = error;
+	return status === 409 || status === 412 || code === "CONFLICT";
+}
+async function asConflict(options, run) {
+	try {
+		return await run();
+	} catch (error) {
+		if (!isConflict(error)) throw error;
+		throw new QuestpieDbConflictError({
+			...options,
+			cause: error
+		});
+	}
+}
+/**
+* QUESTPIE owns the `revision` column and only adds it when the collection
+* enables `optimisticConcurrency`, so its presence on the row TanStack DB read
+* is the feature detection. Collections without the feature must not send the
+* key at all: the server ignores it there, which would read as a precondition
+* that was checked when it never was.
+*/
+function revisionOf(original) {
+	const revision = original?.revision;
+	return typeof revision === "number" ? revision : void 0;
+}
+/** Spreadable form of {@link revisionOf}, so the key is absent when unset. */
+function expectedRevisionOf(original) {
+	const revision = revisionOf(original);
+	return revision === void 0 ? {} : { expectedRevision: revision };
+}
 function rowId(row) {
 	if (typeof row.id !== "string" || row.id.length === 0) throw new Error("QUESTPIE TanStack DB rows require a non-empty string id");
 	return row.id;
@@ -79,6 +134,12 @@ function rowId(row) {
 function persistedRow(result, fallback) {
 	return result && typeof result === "object" && "id" in result ? result : fallback;
 }
+function persistedRowsById(result) {
+	const rows = /* @__PURE__ */ new Map();
+	if (!Array.isArray(result)) return rows;
+	for (const row of result) if (row && typeof row === "object" && typeof row.id === "string") rows.set(row.id, row);
+	return rows;
+}
 function createQuestpieCollection(options) {
 	const { client, name, queryClient, queryKey, findOptions, syncMode, onDispose } = options;
 	const { getSnapshotRevision, queryFn, reconcileMutation } = resolveSync({
@@ -122,33 +183,36 @@ function createQuestpieCollection(options) {
 		},
 		onUpdate: async ({ transaction }) => {
 			const snapshotRevision = getSnapshotRevision();
-			const persisted = await Promise.all(transaction.mutations.map((mutation) => client.update({
+			const persisted = persistedRowsById(await asConflict({
+				collection: name,
+				operation: "update",
+				ids: transaction.mutations.map((mutation) => String(mutation.key))
+			}, () => client.updateBatch({ updates: transaction.mutations.map((mutation) => ({
 				id: String(mutation.key),
-				data: mutation.changes
-			})));
+				data: mutation.changes,
+				...expectedRevisionOf(mutation.original)
+			})) })));
 			await reconcileMutation(snapshotRevision, (rows) => {
 				const byId = new Map(rows.map((row) => [row.id, row]));
-				for (let index = 0; index < transaction.mutations.length; index++) {
-					const mutation = transaction.mutations[index];
+				for (const mutation of transaction.mutations) {
 					const current = byId.get(String(mutation.key));
 					if (!current) continue;
-					byId.set(String(mutation.key), persistedRow(persisted[index], {
+					byId.set(String(mutation.key), persisted.get(String(mutation.key)) ?? {
 						...current,
 						...mutation.changes
-					}));
+					});
 				}
 				return rows.map((row) => byId.get(row.id) ?? row);
 			}, (rows) => {
 				const byId = new Map(rows.map((row) => [row.id, row]));
-				for (let index = 0; index < transaction.mutations.length; index++) {
-					const mutation = transaction.mutations[index];
+				for (const mutation of transaction.mutations) {
 					const current = byId.get(String(mutation.key));
 					if (!current) continue;
 					const original = mutation.original;
-					const result = persistedRow(persisted[index], {
+					const result = persisted.get(String(mutation.key)) ?? {
 						...original,
 						...mutation.changes
-					});
+					};
 					const merged = { ...current };
 					for (const key of Object.keys(result)) if (deepEquals(current[key], original[key])) merged[key] = result[key];
 					byId.set(String(mutation.key), merged);
@@ -159,8 +223,23 @@ function createQuestpieCollection(options) {
 		},
 		onDelete: async ({ transaction }) => {
 			const snapshotRevision = getSnapshotRevision();
-			await Promise.all(transaction.mutations.map((mutation) => client.delete({ id: String(mutation.key) })));
-			const deleted = new Set(transaction.mutations.map((mutation) => String(mutation.key)));
+			const ids = transaction.mutations.map((mutation) => String(mutation.key));
+			const expectedRevisions = transaction.mutations.flatMap((mutation) => {
+				const revision = revisionOf(mutation.original);
+				return revision === void 0 ? [] : [{
+					id: String(mutation.key),
+					expectedRevision: revision
+				}];
+			});
+			await asConflict({
+				collection: name,
+				operation: "delete",
+				ids
+			}, () => client.deleteMany({
+				where: { id: { in: ids } },
+				...expectedRevisions.length === ids.length ? { expectedRevisions } : {}
+			}));
+			const deleted = new Set(ids);
 			await reconcileMutation(snapshotRevision, (rows) => rows.filter((row) => !deleted.has(row.id)), (rows) => {
 				const originals = new Map(transaction.mutations.map((mutation) => [String(mutation.key), mutation.original]));
 				return rows.filter((row) => {
@@ -181,10 +260,26 @@ const SHAPE_CHANGING_FIND_OPTIONS = [
 	"extras",
 	"groupBy"
 ];
+/**
+* Find options `find()` honours that the realtime topic cannot carry — the
+* complement of `SnapshotFindOptionsOf`. In snapshot mode the live subscription
+* would silently ignore them while the post-mutation repair read applied them,
+* so the two would describe different row sets.
+*/
+const SNAPSHOT_UNSUPPORTED_FIND_OPTIONS = [
+	"search",
+	"localeFallback",
+	"includeDeleted",
+	"stage"
+];
 function assertBaseRowFindOptions(options) {
 	if (!options || typeof options !== "object" || Array.isArray(options)) return;
 	for (const key of SHAPE_CHANGING_FIND_OPTIONS) if (key in options) throw new Error(`QUESTPIE TanStack DB find.${key} is not supported because collections require base rows with an id`);
 }
+function assertSnapshotFindOptions(options) {
+	if (!options || typeof options !== "object" || Array.isArray(options)) return;
+	for (const key of SNAPSHOT_UNSUPPORTED_FIND_OPTIONS) if (key in options) throw new Error(`QUESTPIE TanStack DB find.${key} is not supported in snapshot sync mode because live subscriptions cannot carry it, so snapshots and repair reads would describe different rows`);
+}
 function createQuestpieCollections(client, options) {
 	const cache = /* @__PURE__ */ new Map();
 	const disposers = /* @__PURE__ */ new Set();
@@ -200,6 +295,7 @@ function createQuestpieCollections(client, options) {
 			if (!collectionClient) return void 0;
 			const findOptions = options.find?.[property];
 			assertBaseRowFindOptions(findOptions);
+			if (syncMode === "snapshot") assertSnapshotFindOptions(findOptions);
 			const created = createQuestpieCollection({
 				client: collectionClient,
 				name: property,
@@ -230,4 +326,4 @@ function createQuestpieCollections(client, options) {
 }
 
 //#endregion
-export { and, createQuestpieCollections, eq, gt, inArray, lt, or, useLiveQuery };
+export { QuestpieDbConflictError, and, createQuestpieCollections, eq, gt, inArray, lt, or, useLiveQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@questpie/tanstack-db",
-	"version": "3.24.0",
+	"version": "3.25.1",
 	"description": "Typed TanStack DB collections backed by a QUESTPIE client",
 	"repository": {
 		"type": "git",
@@ -49,6 +49,6 @@
 		"@tanstack/query-db-collection": "1.1.0",
 		"@tanstack/react-db": "0.1.94",
 		"@tanstack/react-query": "^5.0.0",
-		"questpie": "^3.24.0"
+		"questpie": "^3.25.1"
 	}
 }