@questpie/tanstack-query 3.15.2 → 3.17.0

package/README.md

@@ -219,6 +219,13 @@ export default async function PostsPage() {
 }
 ```
 
+TanStack Query's dehydrated state remains a JavaScript object and retains
+QUESTPIE `Date` values. TanStack Start's Seroval hydration preserves them across
+its serialization boundary. Other hosts must use their documented Date-aware
+transport. If you move the state through an application-owned JSON-only
+boundary, use a Date-aware serializer; never revive all ISO-looking strings
+heuristically because `f.date()` and ordinary string fields must remain strings.
+
 ## Query Key Structure
 
 ```ts

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { DefaultError, QueryKey, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
-import { ApplyQuery, CollectionRelations, CollectionSelect, FindManyOptions, FindOneOptionsBase, FindResult, GetCollection, GetGlobal, GlobalRelations, GlobalSelect, QuestpieApp, QuestpieClient, RealtimeAPI, ResolveRelationsDeep, TopicConfig, With, buildCollectionTopic, buildGlobalTopic } from "questpie/client";
+import { ApplyQuery, CollectionRelations, CollectionSelect, FindManyOptions, FindOneOptionsBase, FindResult, GetCollection, GetGlobal, GlobalRelations, GlobalSelect, QuestpieApp, QuestpieClient, RealtimeAPI, ResolveRelationsDeep, TopicConfig, With, applyRealtimeFindEvent, applyRealtimeScalarEvent, applyRealtimeSingleEvent, buildCollectionTopic, buildGlobalTopic } from "questpie/client";
 import { AnyChannelDefinition, ChannelParamsOf, ChannelPresenceOf } from "questpie/channels";
 
 //#region src/index.d.ts
@@ -18,11 +18,11 @@ type QueryBuilder<TFn extends AnyAsyncFn> = HasArgs<TFn> extends false ? () => U
 /**
  * Per-query realtime flag — the second argument to `find` / `count` / `get`.
  */
-type RealtimeQueryConfig = {
+type RealtimeQueryConfig<TData = unknown> = Omit<UseQueryOptions<TData>, "queryFn" | "queryKey"> & {
   /**
-   * Subscribe the query to live snapshots over the multiplexed SSE stream.
-   * The server supplies both the initial value and later full snapshots through
-   * the same stream (via `experimental_streamedQuery`).
+   * Subscribe the query to the multiplexed realtime stream. The initial value
+   * and later keyed changes share one stream, so realtime mode performs no
+   * separate REST fetch.
    */
   realtime?: boolean;
 };
@@ -30,7 +30,7 @@ type RealtimeQueryConfig = {
  * Builder for reads that also have a live form — same as `QueryBuilder`
  * plus the optional `{ realtime }` second argument.
  */
-type LiveQueryBuilder<TFn extends AnyAsyncFn> = undefined extends FirstArg<TFn> ? (options?: FirstArg<TFn>, queryConfig?: RealtimeQueryConfig) => UseQueryOptions<QueryData<TFn>> : (options: FirstArg<TFn>, queryConfig?: RealtimeQueryConfig) => UseQueryOptions<QueryData<TFn>>;
+type LiveQueryBuilder<TFn extends AnyAsyncFn> = undefined extends FirstArg<TFn> ? (options?: FirstArg<TFn>, queryConfig?: RealtimeQueryConfig<QueryData<TFn>>) => UseQueryOptions<QueryData<TFn>> : (options: FirstArg<TFn>, queryConfig?: RealtimeQueryConfig<QueryData<TFn>>) => UseQueryOptions<QueryData<TFn>>;
 type KeyBuilder<TFn extends AnyAsyncFn> = HasArgs<TFn> extends false ? () => QueryKey : undefined extends FirstArg<TFn> ? (options?: FirstArg<TFn>) => QueryKey : (options: FirstArg<TFn>) => QueryKey;
 type MutationVariables<TFn extends AnyAsyncFn> = HasArgs<TFn> extends false ? void : undefined extends FirstArg<TFn> ? FirstArg<TFn> | void : FirstArg<TFn>;
 type MutationBuilder<TVariables, TData> = () => UseMutationOptions<TData, DefaultError, TVariables>;
@@ -64,6 +64,9 @@ type CollectionCreate<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>
 type CollectionUpdate<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["update"];
 type CollectionDelete<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["delete"];
 type CollectionRestore<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["restore"];
+type CollectionPurgeById<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1] extends {
+  purgeById: infer TPurge extends AnyAsyncFn;
+} ? TPurge : never;
 type CollectionFindVersions<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["findVersions"];
 type CollectionRevertToVersion<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["revertToVersion"];
 type CollectionTransitionStage<TApp extends QuestpieApp, K$1 extends CollectionKeys<TApp>> = QuestpieClient<TApp>["collections"][K$1]["transitionStage"];
@@ -91,7 +94,7 @@ type CollectionQueryOptionsAPI<TApp extends QuestpieApp, K$1 extends CollectionK
    * client's `find()` (a `ReturnType`-based extraction would instantiate the
    * client generic at its constraint and collapse docs to `{}`).
    */
-  find: <TQuery extends FindManyOptions<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>> | undefined = undefined>(options?: TQuery, queryConfig?: RealtimeQueryConfig) => UseQueryOptions<FindResult<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>, TQuery>>;
+  find: <TQuery extends FindManyOptions<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>> | undefined = undefined>(options?: TQuery, queryConfig?: RealtimeQueryConfig<FindResult<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>, TQuery>>) => UseQueryOptions<FindResult<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>, TQuery>>;
   count: LiveQueryBuilder<CollectionCount<TApp, K$1>>;
   findOne: <TQuery extends FindOneOptionsBase<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>> | undefined = undefined>(options?: TQuery) => UseQueryOptions<ApplyQuery<CollectionSelectOf<TApp, K$1>, CollectionRelationsOf<TApp, K$1>, TQuery> | null>;
   create: MutationBuilder<FirstArg<CollectionCreate<TApp, K$1>>, QueryData<CollectionCreate<TApp, K$1>>>;
@@ -111,7 +114,9 @@ type CollectionQueryOptionsAPI<TApp extends QuestpieApp, K$1 extends CollectionK
     success: boolean;
     count: number;
   }>;
-};
+} & ([CollectionPurgeById<TApp, K$1>] extends [never] ? {} : {
+  purgeById: MutationBuilder<FirstArg<CollectionPurgeById<TApp, K$1>>, QueryData<CollectionPurgeById<TApp, K$1>>>;
+});
 type GlobalQueryOptionsAPI<TApp extends QuestpieApp, K$1 extends GlobalKeys<TApp>> = {
   /** Generic per call — mirrors the direct client's `get()` narrowing. */
   get: <TQuery extends {
@@ -176,4 +181,4 @@ type QuestpieQueryOptionsProxy<TApp extends QuestpieApp = QuestpieApp> = {
  */
 declare function createQuestpieQueryOptions<TApp extends QuestpieApp = QuestpieApp>(client: QuestpieClient<TApp>, config?: QuestpieQueryOptionsConfig): QuestpieQueryOptionsProxy<TApp>;
 //#endregion
-export { type DefaultError, type QueryKey, QuestpieQueryErrorMap, QuestpieQueryOptionsConfig, QuestpieQueryOptionsProxy, type RealtimeAPI, RealtimeQueryConfig, type TopicConfig, type UseMutationOptions, type UseQueryOptions, buildCollectionTopic, buildGlobalTopic, createQuestpieQueryOptions };
+export { type DefaultError, type QueryKey, QuestpieQueryErrorMap, QuestpieQueryOptionsConfig, QuestpieQueryOptionsProxy, type RealtimeAPI, RealtimeQueryConfig, type TopicConfig, type UseMutationOptions, type UseQueryOptions, applyRealtimeFindEvent, applyRealtimeScalarEvent, applyRealtimeSingleEvent, buildCollectionTopic, buildGlobalTopic, createQuestpieQueryOptions };

package/dist/index.mjs

@@ -1,8 +1,27 @@
 import { experimental_streamedQuery, mutationOptions, queryOptions } from "@tanstack/react-query";
-import { buildCollectionTopic, buildCollectionTopic as buildCollectionTopic$1, buildGlobalTopic, buildGlobalTopic as buildGlobalTopic$1 } from "questpie/client";
+import { applyRealtimeFindEvent, applyRealtimeFindEvent as applyRealtimeFindEvent$1, applyRealtimeScalarEvent, applyRealtimeScalarEvent as applyRealtimeScalarEvent$1, applyRealtimeSingleEvent, applyRealtimeSingleEvent as applyRealtimeSingleEvent$1, buildCollectionTopic, buildCollectionTopic as buildCollectionTopic$1, buildGlobalTopic, buildGlobalTopic as buildGlobalTopic$1 } from "questpie/client";
 
 //#region src/index.ts
 const defaultErrorMap = (error) => error instanceof Error ? error : new Error(typeof error === "string" ? error : "Unknown error");
+const isNonRetryableError = (error) => Boolean(error && typeof error === "object" && "retryable" in error && error.retryable === false);
+const mapRealtimeError = (error, errorMap) => {
+	const mapped = errorMap(error);
+	if (isNonRetryableError(error) && (!mapped || typeof mapped !== "object" || !("retryable" in mapped))) {
+		if (mapped && typeof mapped === "object" && Object.isExtensible(mapped)) {
+			Object.defineProperty(mapped, "retryable", {
+				value: false,
+				enumerable: true
+			});
+			return mapped;
+		}
+		return Object.assign(/* @__PURE__ */ new Error("Non-retryable realtime query failed"), {
+			cause: mapped,
+			retryable: false
+		});
+	}
+	return mapped;
+};
+const realtimeRetry = (failureCount, error) => !isNonRetryableError(error) && failureCount < 3;
 const buildKey = (prefix, parts) => prefix.length ? [...prefix, ...parts] : parts;
 const sanitizeKeyPart = (value) => {
 	if (value === null || value === void 0) return value;
@@ -41,9 +60,9 @@ const wrapMutationFn = (mutationFn, errorMap) => {
 async function* streamRealtimeQuery(options) {
 	const { realtime, topic, signal, errorMap } = options;
 	try {
-		for await (const snapshot of realtime.stream(topic, signal)) yield snapshot;
+		for await (const event of realtime.streamEvents(topic, signal)) yield event;
 	} catch (error) {
-		throw errorMap(error);
+		throw mapRealtimeError(error, errorMap);
 	}
 }
 /**
@@ -87,9 +106,14 @@ function createQuestpieQueryOptions(client, config = {}) {
 					normalizeQueryKeyOptions(options)
 				]);
 				if (queryConfig?.realtime && client.realtime) {
+					const { realtime: _realtime, ...overrides } = queryConfig;
 					const topic = buildCollectionTopic$1(collectionName, options);
 					return queryOptions({
 						queryKey: qKey,
+						retry: realtimeRetry,
+						staleTime: 0,
+						refetchOnMount: "always",
+						...overrides,
 						queryFn: experimental_streamedQuery({
 							streamFn: ({ signal }) => streamRealtimeQuery({
 								realtime: client.realtime,
@@ -97,7 +121,7 @@ function createQuestpieQueryOptions(client, config = {}) {
 								signal,
 								errorMap
 							}),
-							reducer: (_, chunk) => chunk,
+							reducer: applyRealtimeFindEvent$1,
 							initialValue: void 0,
 							refetchMode: "append"
 						})
@@ -117,9 +141,14 @@ function createQuestpieQueryOptions(client, config = {}) {
 					normalizeQueryKeyOptions(options)
 				]);
 				if (queryConfig?.realtime && client.realtime) {
+					const { realtime: _realtime, ...overrides } = queryConfig;
 					const topic = buildCollectionTopic$1(collectionName, options, "count");
 					return queryOptions({
 						queryKey: qKey,
+						retry: realtimeRetry,
+						staleTime: 0,
+						refetchOnMount: "always",
+						...overrides,
 						queryFn: experimental_streamedQuery({
 							streamFn: ({ signal }) => streamRealtimeQuery({
 								realtime: client.realtime,
@@ -127,7 +156,7 @@ function createQuestpieQueryOptions(client, config = {}) {
 								signal,
 								errorMap
 							}),
-							reducer: (_, chunk) => chunk,
+							reducer: (current, event) => applyRealtimeScalarEvent$1(current, event),
 							initialValue: void 0,
 							refetchMode: "append"
 						})
@@ -196,6 +225,18 @@ function createQuestpieQueryOptions(client, config = {}) {
 					...stage ? { stage } : {}
 				} : void 0), errorMap)
 			}),
+			purgeById: () => mutationOptions({
+				mutationKey: buildKey(keyPrefix, [
+					...baseKey,
+					"purgeById",
+					locale,
+					stage
+				]),
+				mutationFn: wrapMutationFn((variables) => collection.purgeById(variables, locale || stage ? {
+					...locale ? { locale } : {},
+					...stage ? { stage } : {}
+				} : void 0), errorMap)
+			}),
 			findVersions: (params) => queryOptions({
 				queryKey: buildKey(keyPrefix, [
 					...baseKey,
@@ -273,9 +314,14 @@ function createQuestpieQueryOptions(client, config = {}) {
 					normalizeQueryKeyOptions(options)
 				]);
 				if (queryConfig?.realtime && client.realtime) {
+					const { realtime: _realtime, ...overrides } = queryConfig;
 					const topic = buildGlobalTopic$1(globalName, options);
 					return queryOptions({
 						queryKey: qKey,
+						retry: realtimeRetry,
+						staleTime: 0,
+						refetchOnMount: "always",
+						...overrides,
 						queryFn: experimental_streamedQuery({
 							streamFn: ({ signal }) => streamRealtimeQuery({
 								realtime: client.realtime,
@@ -283,7 +329,7 @@ function createQuestpieQueryOptions(client, config = {}) {
 								signal,
 								errorMap
 							}),
-							reducer: (_, chunk) => chunk,
+							reducer: (current, event) => applyRealtimeSingleEvent$1(current, event),
 							initialValue: void 0,
 							refetchMode: "append"
 						})
@@ -451,4 +497,4 @@ function createQuestpieQueryOptions(client, config = {}) {
 }
 
 //#endregion
-export { buildCollectionTopic, buildGlobalTopic, createQuestpieQueryOptions };
+export { applyRealtimeFindEvent, applyRealtimeScalarEvent, applyRealtimeSingleEvent, buildCollectionTopic, buildGlobalTopic, createQuestpieQueryOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@questpie/tanstack-query",
-	"version": "3.15.2",
+	"version": "3.17.0",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/questpie/questpie.git",
@@ -32,15 +32,17 @@
 	},
 	"scripts": {
 		"build": "tsdown",
-		"check-types": "tsc --noEmit"
+		"check-types": "tsc --noEmit",
+		"test": "bun test"
 	},
 	"devDependencies": {
 		"bun-types": "latest",
+		"seroval": "1.5.4",
 		"tsdown": "^0.18.3",
 		"zod": "^4.2.1"
 	},
 	"peerDependencies": {
 		"@tanstack/react-query": "^5.0.0",
-		"questpie": "^3.0.0"
+		"questpie": "^3.17.0"
 	}
 }