ConvexReactClient.prewarmQuery({query, args}) (#39826)

Today this is just a more convenient and discoverable way to write
```
const watch = this.watchQuery(query, args);
const unsubscribe = watch.onUpdate(() => {});
setTimeout(unsubscribe, 5000);
```
The behavior of this method might change in the future, making it more like a browser prefetch where subscribing is not guaranteed in some cases, e.g. low bandwidth client or high server load.

GitOrigin-RevId: 0180c833200bcf6cc10c481526dbe14fa218ad8b

Author: thomasballinger

npm-packages/common/config/rush/pnpm-lock.yaml

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- `ConvexReactClient.prewarmQuery({query, args})` method for subscribing to a
+  query for 5 seconds. Prewarming indicates likely future interest in a
+  subscription and is currently implemented by subscribing to the query for 5
+  seconds.
+
+  The return value of this method may change and the arguments may change in the
+  future so this API should be considered unstable but adapting to these changes
+  shouldn't be difficult.
+
 - Expose the schemaValidation property of schema, intended for runtime tests or
   assertions that it is indeed enabled.
 

npm-packages/convex/CHANGELOG.md

@@ -0,0 +1,52 @@
+import { test } from "vitest";
+import { makeFunctionReference } from "../server/index.js";
+import { EmptyObject } from "../server/registration.js";
+import { ConvexReactClient } from "../react/client.js";
+import { convexQueryOptions } from "./query_options.js";
+
+const apiQueryFuncWithArgs = makeFunctionReference<
+  "query",
+  { name: string },
+  string
+>("jeans style");
+const apiQueryFuncWithoutArgs = makeFunctionReference<
+  "query",
+  EmptyObject,
+  string
+>("jeans style");
+
+test("convexQueryOptions", async () => {
+  const _opts = convexQueryOptions({
+    query: apiQueryFuncWithArgs,
+    args: { name: "hey" },
+  });
+
+  // @ts-expect-error This should be an error
+  const _opts2 = convexQueryOptions({
+    query: apiQueryFuncWithArgs,
+  });
+
+  const _opts3 = convexQueryOptions({
+    query: apiQueryFuncWithoutArgs,
+    args: {},
+  });
+
+  // @ts-expect-error For now args are always required, even at the top level.
+  const _opts4 = convexQueryOptions({
+    query: apiQueryFuncWithoutArgs,
+  });
+
+  const _opts5 = convexQueryOptions({
+    query: apiQueryFuncWithoutArgs,
+    // @ts-expect-error This should be an error
+    args: { name: "hey" },
+  });
+});
+
+test("prewarmQuery types", async () => {
+  const client = {
+    prewarmQuery: () => {},
+  } as unknown as ConvexReactClient;
+
+  client.prewarmQuery({ query: apiQueryFuncWithArgs, args: { name: "hi" } });
+});

npm-packages/convex/src/browser/query_options.test.ts

@@ -0,0 +1,26 @@
+/**
+ * Query options are a potential new API for a variety of functions, but in particular a new overload of the React hook for queries.
+ *
+ * Inspired by https://tanstack.com/query/v5/docs/framework/react/guides/query-options
+ */
+import type { FunctionArgs, FunctionReference } from "../server/api.js";
+
+// TODO if this type can encompass all use cases we can add not requiring args for queries
+// that don't take arguments. Goal would be that queryOptions allows leaving out args,
+// but queryOptions returns an object that always contains args. Helpers, "middleware,"
+// anything that intercepts these arguments
+/**
+ * Query options.
+ */
+export type ConvexQueryOptions<Query extends FunctionReference<"query">> = {
+  query: Query;
+  args: FunctionArgs<Query>;
+  extendSubscriptionFor?: number;
+};
+
+// This helper helps more once we have more inference happening.
+export function convexQueryOptions<Query extends FunctionReference<"query">>(
+  options: ConvexQueryOptions<Query>,
+): ConvexQueryOptions<Query> {
+  return options;
+}

npm-packages/convex/src/browser/query_options.ts

@@ -27,6 +27,11 @@ import {
   instantiateNoopLogger,
   Logger,
 } from "../browser/logging.js";
+import { ConvexQueryOptions } from "../browser/query_options.js";
+
+// When no arguments are passed, extend subscriptions (for APIs that do this by default)
+// for this amount after the subscription would otherwise be dropped.
+const DEFAULT_EXTEND_SUBSCRIPTION_FOR = 5_000;
 
 if (typeof React === "undefined") {
   throw new Error("Required dependency 'react' not found");
@@ -427,6 +432,33 @@ export class ConvexReactClient {
     };
   }
 
+  // Let's try out a queryOptions-style API.
+  // This method is similar to the React Query API `queryClient.prefetchQuery()`.
+  // In the future an ensureQueryData(): Promise<Data> method could exist.
+  /**
+   * Indicates likely future interest in a query subscription.
+   *
+   * The implementation currently immediately subscribes to a query. In the future this method
+   * may prioritize some queries over others, fetch the query result without subscribing, or
+   * do nothing in slow network connections or high load scenarios.
+   *
+   * To use this in a React component, call useQuery() and ignore the return value.
+   *
+   * @param queryOptions - A query (function reference from an api object) and its args, plus
+   * an optional extendSubscriptionFor for how long to subscribe to the query.
+   */
+  prewarmQuery<Query extends FunctionReference<"query">>(
+    queryOptions: ConvexQueryOptions<Query> & {
+      extendSubscriptionFor?: number;
+    },
+  ) {
+    const extendSubscriptionFor =
+      queryOptions.extendSubscriptionFor ?? DEFAULT_EXTEND_SUBSCRIPTION_FOR;
+    const watch = this.watchQuery(queryOptions.query, queryOptions.args || {});
+    const unsubscribe = watch.onUpdate(() => {});
+    setTimeout(unsubscribe, extendSubscriptionFor);
+  }
+
   /**
    * Execute a mutation function.
    *

npm-packages/convex/src/react/client.ts

@@ -0,0 +1,5 @@
+# To access values in this file from the frontend with Vite, use
+# import.meta.env.VARIABLE_NAME_HERE
+# this line and below will be removed when publishing demos
+VITE_CONVEX_URL="http://127.0.0.1:8000"
+# this line and above will be removed when publishing demos

npm-packages/demos/prewarming/.env

@@ -0,0 +1,4 @@
+node_modules
+.DS_Store
+dist
+.env.local

npm-packages/demos/prewarming/.gitignore

@@ -0,0 +1,20 @@
+# TypeScript and Schemas Example App
+
+This example demonstrates how to write a Convex app in
+[TypeScript](https://docs.convex.dev/using/typescript).
+
+The Convex functions are written in `.ts` files and the React components use
+`.tsx`.
+
+This app also defines a Convex
+[schema](https://docs.convex.dev/database/schemas) in `convex/schema.ts` to
+create TypeScript types specific to the app's data model.
+
+## Running the App
+
+Run:
+
+```
+npm install
+npm run dev
+```

npm-packages/demos/prewarming/README.md

@@ -0,0 +1,90 @@
+# Welcome to your Convex functions directory!
+
+Write your Convex functions here.
+See https://docs.convex.dev/functions for more.
+
+A query function that takes two arguments looks like:
+
+```ts
+// convex/myFunctions.ts
+import { query } from "./_generated/server";
+import { v } from "convex/values";
+
+export const myQueryFunction = query({
+  // Validators for arguments.
+  args: {
+    first: v.number(),
+    second: v.string(),
+  },
+
+  // Function implementation.
+  handler: async (ctx, args) => {
+    // Read the database as many times as you need here.
+    // See https://docs.convex.dev/database/reading-data.
+    const documents = await ctx.db.query("tablename").collect();
+
+    // Arguments passed from the client are properties of the args object.
+    console.log(args.first, args.second);
+
+    // Write arbitrary JavaScript here: filter, aggregate, build derived data,
+    // remove non-public properties, or create new objects.
+    return documents;
+  },
+});
+```
+
+Using this query function in a React component looks like:
+
+```ts
+const data = useQuery(api.myFunctions.myQueryFunction, {
+  first: 10,
+  second: "hello",
+});
+```
+
+A mutation function looks like:
+
+```ts
+// convex/myFunctions.ts
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const myMutationFunction = mutation({
+  // Validators for arguments.
+  args: {
+    first: v.string(),
+    second: v.string(),
+  },
+
+  // Function implementation.
+  handler: async (ctx, args) => {
+    // Insert or modify documents in the database here.
+    // Mutations can also read from the database like queries.
+    // See https://docs.convex.dev/database/writing-data.
+    const message = { body: args.first, author: args.second };
+    const id = await ctx.db.insert("messages", message);
+
+    // Optionally, return a value from your mutation.
+    return await ctx.db.get(id);
+  },
+});
+```
+
+Using this mutation function in a React component looks like:
+
+```ts
+const mutation = useMutation(api.myFunctions.myMutationFunction);
+function handleButtonPress() {
+  // fire and forget, the most common way to use mutations
+  mutation({ first: "Hello!", second: "me" });
+  // OR
+  // use the result once the mutation has completed
+  mutation({ first: "Hello!", second: "me" }).then((result) =>
+    console.log(result),
+  );
+}
+```
+
+Use the Convex CLI to push your functions to a deployment. See everything
+the Convex CLI can do by running `npx convex -h` in your project root
+directory. To learn more, launch the docs with `npx convex docs`.

npm-packages/demos/prewarming/convex/README.md

@@ -0,0 +1,36 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import type * as messages from "../messages.js";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+declare const fullApi: ApiFromModules<{
+  messages: typeof messages;
+}>;
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;