@questpie/tanstack-db 3.17.0

package/README.md

@@ -0,0 +1,41 @@
+# @questpie/tanstack-db
+
+Typed TanStack DB collections backed by a QUESTPIE client.
+
+## Per-request setup
+
+TanStack Start and other SSR applications must create both the QueryClient and
+the QUESTPIE collections once per request:
+
+```ts
+import { createQuestpieCollections } from "@questpie/tanstack-db";
+import { QueryClient } from "@tanstack/react-query";
+import type { QuestpieClient } from "questpie/client";
+
+import type { AppConfig } from "#questpie";
+
+export function createRequestDb(client: QuestpieClient<AppConfig>) {
+	const queryClient = new QueryClient();
+	const db = createQuestpieCollections(client, { queryClient });
+
+	return { db, queryClient };
+}
+```
+
+Call `db.destroy()` when the request or browser application is torn down. A
+module-scope registry is safe only in the browser; on the server it would leak
+one request's optimistic overlay into another request.
+
+Use `syncMode: "snapshot"` to keep the store replaced from QUESTPIE `.live()`
+snapshots. The default is `"refetch"` and uses TanStack Query's authoritative
+refetch after a successful mutation. Successful optimistic mutations are folded
+into the current authoritative snapshot until the next live snapshot arrives.
+
+The `find` registry option accepts only row-shape-preserving filters, ordering,
+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`.
+
+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

@@ -0,0 +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";
+
+//#region src/sync.d.ts
+type QuestpieDbSyncMode = "refetch" | "snapshot";
+//#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>, {
+  collections: TApp["collections"];
+}>;
+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">;
+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;
+} ? Extract<TId, string> : never;
+type QuestpieCollections<TApp extends QuestpieApp> = { [K in CollectionKeys<TApp>]: Collection<CollectionRowOf<TApp, K>, IdOf<CollectionRowOf<TApp, K>>> };
+type QuestpieDb<TApp extends QuestpieApp> = {
+  collections: QuestpieCollections<TApp>;
+  destroy: () => void;
+};
+//#endregion
+//#region src/factory.d.ts
+type QuestpieFindOptions<TApp extends QuestpieApp> = Partial<{ [K in CollectionKeys<TApp>]: FindOptionsOf<TApp, K> }>;
+type CreateQuestpieCollectionsOptions<TApp extends QuestpieApp> = {
+  queryClient: QueryClient;
+  syncMode?: QuestpieDbSyncMode;
+  find?: QuestpieFindOptions<TApp>;
+  keyPrefix?: QueryKey;
+};
+declare function createQuestpieCollections<TApp extends QuestpieApp>(client: QuestpieClient<TApp>, options: CreateQuestpieCollectionsOptions<TApp>): 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 };

package/dist/index.mjs

@@ -0,0 +1,233 @@
+import { and, createCollection, deepEquals, eq, gt, inArray, lt, or } from "@tanstack/db";
+import { queryCollectionOptions } from "@tanstack/query-db-collection";
+import { useLiveQuery } from "@tanstack/react-db";
+
+//#region src/sync.ts
+function resolveSync(options) {
+	const { client, findOptions, mode, queryClient, queryKey, onDispose } = options;
+	if (mode === "refetch") return {
+		queryFn: async () => (await client.find(findOptions)).docs,
+		getSnapshotRevision: () => 0,
+		reconcileMutation: async () => {}
+	};
+	let latest;
+	let initial;
+	let snapshotRevision = 0;
+	const setLatest = (rows) => {
+		latest = rows;
+		queryClient.setQueryData(queryKey, latest);
+	};
+	const acceptSnapshot = (rows) => {
+		snapshotRevision += 1;
+		setLatest(rows);
+	};
+	return {
+		getSnapshotRevision: () => snapshotRevision,
+		reconcileMutation: async (revision, update, fallback) => {
+			if (revision === snapshotRevision) {
+				setLatest(update(latest ?? queryClient.getQueryData(queryKey) ?? []));
+				return;
+			}
+			const refreshRevision = snapshotRevision;
+			try {
+				const refreshed = await client.find(findOptions);
+				if (refreshRevision === snapshotRevision) acceptSnapshot(refreshed.docs);
+			} catch {
+				if (refreshRevision === snapshotRevision) setLatest(fallback(latest ?? queryClient.getQueryData(queryKey) ?? []));
+			}
+		},
+		queryFn: () => {
+			if (latest) return Promise.resolve(latest);
+			if (initial) return initial;
+			initial = new Promise((resolve, reject) => {
+				let settled = false;
+				let dispose = () => {};
+				let unregisterDispose = () => {};
+				let failedSynchronously = false;
+				dispose = client.live(findOptions, (snapshot) => {
+					acceptSnapshot(snapshot.docs);
+					if (!settled) {
+						settled = true;
+						resolve(snapshot.docs);
+					}
+				}, { onError: (error) => {
+					if (!settled) {
+						settled = true;
+						failedSynchronously = true;
+						dispose();
+						unregisterDispose();
+						reject(error);
+					}
+				} });
+				if (failedSynchronously) dispose();
+				else unregisterDispose = onDispose(dispose) ?? (() => {});
+			}).catch((error) => {
+				initial = void 0;
+				throw error;
+			});
+			return initial;
+		}
+	};
+}
+
+//#endregion
+//#region src/collection.ts
+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;
+}
+function persistedRow(result, fallback) {
+	return result && typeof result === "object" && "id" in result ? result : fallback;
+}
+function createQuestpieCollection(options) {
+	const { client, name, queryClient, queryKey, findOptions, syncMode, onDispose } = options;
+	const { getSnapshotRevision, queryFn, reconcileMutation } = resolveSync({
+		client,
+		findOptions,
+		mode: syncMode,
+		queryClient,
+		queryKey,
+		onDispose
+	});
+	const skipRefetch = syncMode === "snapshot" ? { refetch: false } : void 0;
+	return createCollection(queryCollectionOptions({
+		id: `questpie:${name}`,
+		queryClient,
+		queryKey,
+		queryFn,
+		getKey: rowId,
+		onInsert: async ({ transaction }) => {
+			const snapshotRevision = getSnapshotRevision();
+			const persisted = await Promise.all(transaction.mutations.map((mutation) => client.create(mutation.modified)));
+			await reconcileMutation(snapshotRevision, (rows) => {
+				const next = [...rows];
+				for (let index = 0; index < transaction.mutations.length; index++) {
+					const optimistic = transaction.mutations[index].modified;
+					const row = persistedRow(persisted[index], optimistic);
+					const existing = next.findIndex((item) => item.id === row.id);
+					if (existing === -1) next.push(row);
+					else next[existing] = row;
+				}
+				return next;
+			}, (rows) => {
+				const next = [...rows];
+				for (let index = 0; index < transaction.mutations.length; index++) {
+					const optimistic = transaction.mutations[index].modified;
+					const row = persistedRow(persisted[index], optimistic);
+					if (!next.some((item) => item.id === row.id)) next.push(row);
+				}
+				return next;
+			});
+			return skipRefetch;
+		},
+		onUpdate: async ({ transaction }) => {
+			const snapshotRevision = getSnapshotRevision();
+			const persisted = await Promise.all(transaction.mutations.map((mutation) => client.update({
+				id: String(mutation.key),
+				data: mutation.changes
+			})));
+			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];
+					const current = byId.get(String(mutation.key));
+					if (!current) continue;
+					byId.set(String(mutation.key), persistedRow(persisted[index], {
+						...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];
+					const current = byId.get(String(mutation.key));
+					if (!current) continue;
+					const original = mutation.original;
+					const result = persistedRow(persisted[index], {
+						...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);
+				}
+				return rows.map((row) => byId.get(row.id) ?? row);
+			});
+			return skipRefetch;
+		},
+		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)));
+			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) => {
+					const original = originals.get(row.id);
+					return !original || !deepEquals(row, original);
+				});
+			});
+			return skipRefetch;
+		}
+	}));
+}
+
+//#endregion
+//#region src/factory.ts
+const SHAPE_CHANGING_FIND_OPTIONS = [
+	"columns",
+	"with",
+	"extras",
+	"groupBy"
+];
+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 createQuestpieCollections(client, options) {
+	const cache = /* @__PURE__ */ new Map();
+	const disposers = /* @__PURE__ */ new Set();
+	const syncMode = options.syncMode ?? "refetch";
+	let destroyed = false;
+	return {
+		collections: new Proxy(Object.create(null), { get(_target, property) {
+			if (typeof property !== "string") return void 0;
+			if (destroyed) throw new Error("QUESTPIE TanStack DB registry has been destroyed");
+			const cached = cache.get(property);
+			if (cached) return cached;
+			const collectionClient = client.collections[property];
+			if (!collectionClient) return void 0;
+			const findOptions = options.find?.[property];
+			assertBaseRowFindOptions(findOptions);
+			const created = createQuestpieCollection({
+				client: collectionClient,
+				name: property,
+				queryClient: options.queryClient,
+				queryKey: [
+					...options.keyPrefix ?? ["questpie", "tanstack-db"],
+					property,
+					findOptions
+				],
+				findOptions,
+				syncMode,
+				onDispose: (dispose) => {
+					disposers.add(dispose);
+					return () => disposers.delete(dispose);
+				}
+			});
+			cache.set(property, created);
+			return created;
+		} }),
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			for (const dispose of disposers) dispose();
+			disposers.clear();
+			cache.clear();
+		}
+	};
+}
+
+//#endregion
+export { and, createQuestpieCollections, eq, gt, inArray, lt, or, useLiveQuery };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@questpie/tanstack-db",
+  "version": "3.17.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/questpie/questpie.git",
+    "directory": "packages/tanstack-db"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@tanstack/db": "0.6.16",
+    "@tanstack/query-db-collection": "1.1.0",
+    "@tanstack/react-db": "0.1.94",
+    "@tanstack/react-query": "^5.0.0",
+    "bun-types": "latest",
+    "tsdown": "^0.18.3"
+  },
+  "peerDependencies": {
+    "@tanstack/db": "0.6.16",
+    "@tanstack/query-db-collection": "1.1.0",
+    "@tanstack/react-db": "0.1.94",
+    "@tanstack/react-query": "^5.0.0",
+    "questpie": "^3.17.0"
+  }
+}