From c3dd16d4a95d14a133a71b0ddb191272f1066c1b Mon Sep 17 00:00:00 2001
From: Chenxin Yan <yanchenxin2004@gmail.com>
Date: Thu, 23 Oct 2025 18:39:23 -0400
Subject: [PATCH 1/4] update usePreloadedQuery to take skip

---
 src/react/hydration.tsx | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/react/hydration.tsx b/src/react/hydration.tsx
index f2089582..287e183d 100644
--- a/src/react/hydration.tsx
+++ b/src/react/hydration.tsx
@@ -26,14 +26,19 @@ export type Preloaded<Query extends FunctionReference<"query">> = {
  * Throws an error if not used under {@link ConvexProvider}.
  *
  * @param preloadedQuery - The `Preloaded` query payload from a Server Component.
+ * @param options - Options for the query, including whether to skip it.
  * @returns the result of the query. Initially returns the result fetched
  * by the Server Component. Subsequently returns the result fetched by the client.
+ * If the query is skipped, returns `undefined`.
  *
  * @public
  */
 export function usePreloadedQuery<Query extends FunctionReference<"query">>(
   preloadedQuery: Preloaded<Query>,
-): Query["_returnType"] {
+  options?: { skip?: boolean },
+): Query["_returnType"] | undefined {
+  const skip = options?.skip ?? false;
+
   const args = useMemo(
     () => jsonToConvex(preloadedQuery._argsJSON),
     [preloadedQuery._argsJSON],
@@ -42,9 +47,10 @@ export function usePreloadedQuery<Query extends FunctionReference<"query">>(
     () => jsonToConvex(preloadedQuery._valueJSON),
     [preloadedQuery._valueJSON],
   );
+
   const result = useQuery(
     makeFunctionReference(preloadedQuery._name) as Query,
-    args,
+    skip ? ("skip" as const) : args,
   );
-  return result === undefined ? preloadedResult : result;
+  return skip ? undefined : result === undefined ? preloadedResult : result;
 }

From 784b9f0203670d555f5d3b40e2b0d0765f3382e6 Mon Sep 17 00:00:00 2001
From: Chenxin Yan <yanchenxin2004@gmail.com>
Date: Thu, 6 Nov 2025 16:29:55 -0500
Subject: [PATCH 2/4] update usePreloadedQuery api

---
 src/react/hydration.tsx | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/src/react/hydration.tsx b/src/react/hydration.tsx
index 287e183d..9324beeb 100644
--- a/src/react/hydration.tsx
+++ b/src/react/hydration.tsx
@@ -34,23 +34,29 @@ export type Preloaded<Query extends FunctionReference<"query">> = {
  * @public
  */
 export function usePreloadedQuery<Query extends FunctionReference<"query">>(
-  preloadedQuery: Preloaded<Query>,
-  options?: { skip?: boolean },
+  preloadedQuery: Preloaded<Query> | "skip",
 ): Query["_returnType"] | undefined {
-  const skip = options?.skip ?? false;
+  const skip = preloadedQuery === "skip";
 
   const args = useMemo(
-    () => jsonToConvex(preloadedQuery._argsJSON),
-    [preloadedQuery._argsJSON],
-  ) as Query["_args"];
+    () =>
+      (skip
+        ? undefined
+        : jsonToConvex(preloadedQuery._argsJSON)) as Query["_args"],
+    [preloadedQuery, skip],
+  );
+
   const preloadedResult = useMemo(
-    () => jsonToConvex(preloadedQuery._valueJSON),
-    [preloadedQuery._valueJSON],
+    () => (skip ? undefined : jsonToConvex(preloadedQuery._valueJSON)),
+    [preloadedQuery, skip],
   );
 
   const result = useQuery(
-    makeFunctionReference(preloadedQuery._name) as Query,
+    skip
+      ? (makeFunctionReference("_skip") as Query)
+      : (makeFunctionReference(preloadedQuery._name) as Query),
     skip ? ("skip" as const) : args,
   );
+
   return skip ? undefined : result === undefined ? preloadedResult : result;
 }

From 0a1f451d4d40165f110d023d7203c328244936c1 Mon Sep 17 00:00:00 2001
From: Chenxin Yan <yanchenxin2004@gmail.com>
Date: Thu, 6 Nov 2025 17:05:49 -0500
Subject: [PATCH 3/4] add function overload

---
 src/react/hydration.tsx | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/react/hydration.tsx b/src/react/hydration.tsx
index 9324beeb..d0561aa3 100644
--- a/src/react/hydration.tsx
+++ b/src/react/hydration.tsx
@@ -33,9 +33,17 @@ export type Preloaded<Query extends FunctionReference<"query">> = {
  *
  * @public
  */
+export function usePreloadedQuery<Query extends FunctionReference<"query">>(
+  preloadedQuery: Preloaded<Query>,
+): Query["_returnType"];
+
+export function usePreloadedQuery<Query extends FunctionReference<"query">>(
+  preloadedQuery: Preloaded<Query> | "skip",
+): Query["_returnType"] | undefined;
+
 export function usePreloadedQuery<Query extends FunctionReference<"query">>(
   preloadedQuery: Preloaded<Query> | "skip",
-): Query["_returnType"] | undefined {
+) {
   const skip = preloadedQuery === "skip";
 
   const args = useMemo(

From 12b3e64dc0f0d1f331782de9e6872596f004b66c Mon Sep 17 00:00:00 2001
From: Chenxin Yan <yanchenxin2004@gmail.com>
Date: Thu, 6 Nov 2025 17:06:17 -0500
Subject: [PATCH 4/4] update jsdoc

---
 src/react/hydration.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/react/hydration.tsx b/src/react/hydration.tsx
index d0561aa3..69ab8abc 100644
--- a/src/react/hydration.tsx
+++ b/src/react/hydration.tsx
@@ -25,11 +25,11 @@ export type Preloaded<Query extends FunctionReference<"query">> = {
  *
  * Throws an error if not used under {@link ConvexProvider}.
  *
- * @param preloadedQuery - The `Preloaded` query payload from a Server Component.
- * @param options - Options for the query, including whether to skip it.
+ * @param preloadedQuery - The `Preloaded` query payload from a Server Component,
+ * or the string `"skip"` to skip the query.
  * @returns the result of the query. Initially returns the result fetched
  * by the Server Component. Subsequently returns the result fetched by the client.
- * If the query is skipped, returns `undefined`.
+ * If the query is skipped (by passing `"skip"`), returns `undefined`.
  *
  * @public
  */