Add support for conditional query execution via function parameters (#39)

* refactor: make args parameter optional in useQuery function with empty object default
* feat: add skip functionality to useQuery for conditional query execution
* docs: add section on conditionally skipping queries
* refactor: clean up code comments
* docs: add troubleshooting guide for effect_in_teardown errors with useQuery
* test: add e2e test for skipQuery functionality

Author: mmailaender

README.md

@@ -65,30 +65,61 @@ and [Chat.svelte](src/routes/Chat.svelte) for how to use `useQuery()`
 Running a mutation looks like
 
 ```svelte
-<script>
-import { api } from "../../convex/_generated/api.js"; // depending on file location
-import { useConvexClient, useQuery } from "convex-svelte";
-const client = useConvexClient();
-
-let toSend = $state('');
-let author = $state('me');
-
-function onSubmit(e: SubmitEvent) {
-	const data = Object.fromEntries(new FormData(e.target as HTMLFormElement).entries());
-	client.mutation(api.messages.send, {
-		author: data.author as string,
-		body: data.body as string
-	});
-}
+<script lang="ts">
+	import { api } from '../../convex/_generated/api.js'; // depending on file location
+	import { useConvexClient } from 'convex-svelte';
+	const client = useConvexClient();
+
+	let toSend = $state('');
+	let author = $state('me');
+
+	function handleSubmit(event: SubmitEvent) {
+		event.preventDefault();
+
+		const data = Object.fromEntries(new FormData(event.target as HTMLFormElement).entries());
+		client.mutation(api.messages.send, {
+			author: data.author as string,
+			body: data.body as string
+		});
+	}
 </script>
 
-<form on:submit|preventDefault={onSubmit}>
-	<input type="text" id="author" name="author" />
-	<input type="text" id="body" name="body" bind:value={toSend} />
+<form onsubmit={handleSubmit}>
+	<input type="text" name="author" bind:value={author} />
+	<input type="text" name="body" bind:value={toSend} />
 	<button type="submit" disabled={!toSend}>Send</button>
 </form>
 ```
 
+### Conditionally skipping queries
+
+You can conditionally skip a query by returning the string `'skip'` from the arguments function.
+This is useful when a query depends on some condition, like authentication state or user input.
+
+```svelte
+<script lang="ts">
+import { useQuery } from "convex-svelte";
+import { api } from "../convex/_generated/api.js";
+
+let auth = $state({ isAuthenticated: true });
+
+const activeUserResponse = useQuery(
+  api.users.queries.getActiveUser,
+  () => (auth.isAuthenticated ? {} : 'skip')
+);
+</script>
+
+{#if activeUserResponse.isLoading}
+  Loading user...
+{:else if activeUserResponse.error}
+  Error: {activeUserResponse.error}
+{:else if activeUserResponse.data}
+  Welcome, {activeUserResponse.data.name}!
+{/if}
+```
+
+When a query is skipped, `isLoading` will be `false`, `error` will be `null`, and `data` will be `undefined`.
+
 ### Server-side rendering
 
 `useQuery()` accepts an `initialData` option in its third argument.
@@ -130,6 +161,16 @@ export const load = (async () => {
 
 Combining specifying `initialData` and either setting the `keepPreviousData` option to true or never modifying the arguments passed to a query should be enough to avoid ever seeing a loading state for a `useQuery()`.
 
+### Troubleshooting
+
+#### effect_in_teardown Error
+
+If you encounter `effect_in_teardown` errors when using `useQuery` in components that can be conditionally rendered (like dialogs, modals, or popups), this is caused by wrapping `useQuery` in a `$derived` block that depends on reactive state.
+
+When `useQuery` is wrapped in `$derived`, state changes during component cleanup can trigger re-evaluation of the `$derived`, which attempts to create a new `useQuery` instance. Since `useQuery` internally creates a `$effect`, and effects cannot be created during cleanup, this throws an error.
+
+Use [Conditionally skipping queries](#conditionally-skipping-queries) instead. By calling `useQuery` unconditionally at the top level and passing a function that returns `'skip'`, the function is evaluated inside `useQuery`'s own effect tracking, preventing query recreation during cleanup.
+
 ### Deploying a Svelte App
 
 In production build pipelines use the build command

e2e/skipQuery.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from '@playwright/test';
+
+test('skipQuery prevents query execution', async ({ page }) => {
+  await page.goto('/tests/skip-query');
+  
+  // Initially, query should run and load data
+  await expect(page.getByTestId('loading')).toBeVisible();
+  await expect(page.getByTestId('data')).toBeVisible({ timeout: 5000 });
+  
+  // Check the skip checkbox
+  await page.getByTestId('skip-checkbox').check();
+  
+  // When skipped, should show "No data" (not loading, no error, no data)
+  await expect(page.getByTestId('no-data')).toBeVisible();
+  
+  // Uncheck to verify it resumes
+  await page.getByTestId('skip-checkbox').uncheck();
+  
+  // Should load again
+  await expect(page.getByTestId('data')).toBeVisible({ timeout: 5000 });
+});

src/lib/client.svelte.ts

@@ -36,6 +36,10 @@ export const setupConvex = (url: string, options: ConvexClientOptions = {}) => {
 	$effect(() => () => client.close());
 };
 
+// Internal sentinel for "skip" so we don't pass the literal string through everywhere
+const SKIP = Symbol('convex.useQuery.skip');
+type Skip = typeof SKIP;
+
 type UseQueryOptions<Query extends FunctionReference<'query'>> = {
 	// Use this data and assume it is up to date (typically for SSR and hydration)
 	initialData?: FunctionReturnType<Query>;
@@ -53,153 +57,192 @@ type UseQueryReturn<Query extends FunctionReference<'query'>> =
  * Subscribe to a Convex query and return a reactive query result object.
  * Pass reactive args object or a closure returning args to update args reactively.
  *
- * @param query - a FunctionRefernece like `api.dir1.dir2.filename.func`.
- * @param args - The arguments to the query function.
+ * Supports React-style `"skip"` to avoid subscribing:
+ *   useQuery(api.users.get, () => (isAuthed ? {} : 'skip'))
+ *
+ * @param query - a FunctionReference like `api.dir1.dir2.filename.func`.
+ * @param args - Arguments object / closure, or the string `"skip"` (or a closure returning it).
  * @param options - UseQueryOptions like `initialData` and `keepPreviousData`.
  * @returns an object containing data, isLoading, error, and isStale.
  */
 export function useQuery<Query extends FunctionReference<'query'>>(
 	query: Query,
-	args: FunctionArgs<Query> | (() => FunctionArgs<Query>),
+	args: FunctionArgs<Query> | 'skip' | (() => FunctionArgs<Query> | 'skip') = {},
 	options: UseQueryOptions<Query> | (() => UseQueryOptions<Query>) = {}
 ): UseQueryReturn<Query> {
 	const client = useConvexClient();
 	if (typeof query === 'string') {
 		throw new Error('Query must be a functionReference object, not a string');
 	}
+
 	const state: {
 		result: FunctionReturnType<Query> | Error | undefined;
 		// The last result we actually received, if this query has ever received one.
 		lastResult: FunctionReturnType<Query> | Error | undefined;
 		// The args (query key) of the last result that was received.
-		argsForLastResult: FunctionArgs<Query>;
+		argsForLastResult: FunctionArgs<Query> | Skip | undefined;
 		// If the args have never changed, fine to use initialData if provided.
 		haveArgsEverChanged: boolean;
 	} = $state({
 		result: parseOptions(options).initialData,
-		argsForLastResult: undefined,
 		lastResult: undefined,
+		argsForLastResult: undefined,
 		haveArgsEverChanged: false
 	});
 
 	// When args change we need to unsubscribe to the old query and subscribe
 	// to the new one.
 	$effect(() => {
 		const argsObject = parseArgs(args);
+
+		// If skipped, don't create any subscription
+		if (argsObject === SKIP) {
+			// Clear transient result to mimic React: not loading, no data
+			state.result = undefined;
+			state.argsForLastResult = SKIP;
+			return;
+		}
+
 		const unsubscribe = client.onUpdate(
 			query,
 			argsObject,
 			(dataFromServer) => {
 				const copy = structuredClone(dataFromServer);
-
 				state.result = copy;
 				state.argsForLastResult = argsObject;
 				state.lastResult = copy;
 			},
 			(e: Error) => {
 				state.result = e;
 				state.argsForLastResult = argsObject;
-				// is it important to copy the error here?
 				const copy = structuredClone(e);
 				state.lastResult = copy;
 			}
 		);
+
+		// Cleanup on args change/unmount
 		return unsubscribe;
 	});
 
-	// Are the args (the query key) the same as the last args we received a result for?
+	/*
+	 ** staleness & args tracking **
+	 * Are the args (the query key) the same as the last args we received a result for?
+	 */
+	const currentArgs = $derived(parseArgs(args));
+	const initialArgs = parseArgs(args);
+
 	const sameArgsAsLastResult = $derived(
-		!!state.argsForLastResult &&
-			JSON.stringify(convexToJson(state.argsForLastResult)) ===
-				JSON.stringify(convexToJson(parseArgs(args)))
+		state.argsForLastResult !== undefined &&
+			currentArgs !== SKIP &&
+			state.argsForLastResult !== SKIP &&
+			jsonEqualArgs(
+				state.argsForLastResult as Record<string, Value>,
+				currentArgs as Record<string, Value>
+			)
 	);
+
 	const staleAllowed = $derived(!!(parseOptions(options).keepPreviousData && state.lastResult));
+	const isSkipped = $derived(currentArgs === SKIP);
 
-	// Not reactive
-	const initialArgs = parseArgs(args);
 	// Once args change, move off of initialData.
 	$effect(() => {
 		if (!untrack(() => state.haveArgsEverChanged)) {
-			if (
-				JSON.stringify(convexToJson(parseArgs(args))) !== JSON.stringify(convexToJson(initialArgs))
-			) {
+			const curr = parseArgs(args);
+			if (!argsKeyEqual(initialArgs, curr)) {
 				state.haveArgsEverChanged = true;
 				const opts = parseOptions(options);
 				if (opts.initialData !== undefined) {
-					state.argsForLastResult = $state.snapshot(initialArgs);
-					state.lastResult = parseOptions(options).initialData;
+					state.argsForLastResult = initialArgs === SKIP ? SKIP : $state.snapshot(initialArgs);
+					state.lastResult = opts.initialData;
 				}
 			}
 		}
 	});
 
-	// Return value or undefined; never an error object.
+	/*
+	 ** compute sync result **
+	 * Return value or undefined; never an error object.
+	 */
 	const syncResult: FunctionReturnType<Query> | undefined = $derived.by(() => {
+		if (isSkipped) return undefined;
+
 		const opts = parseOptions(options);
 		if (opts.initialData && !state.haveArgsEverChanged) {
 			return state.result;
 		}
+
 		let value;
 		try {
 			value = client.disabled
 				? undefined
-				: client.client.localQueryResult(getFunctionName(query), parseArgs(args));
+				: client.client.localQueryResult(
+						getFunctionName(query),
+						currentArgs as Record<string, Value>
+					);
 		} catch (e) {
 			if (!(e instanceof Error)) {
-				// This should not happen by the API of localQueryResult().
 				console.error('threw non-Error instance', e);
 				throw e;
 			}
 			value = e;
 		}
-		// If state result has updated then it's time to check the for a new local value
+		// Touch reactive state.result so updates retrigger computations
 		state.result;
 		return value;
 	});
 
 	const result = $derived.by(() => {
 		return syncResult !== undefined ? syncResult : staleAllowed ? state.lastResult : undefined;
 	});
+
 	const isStale = $derived(
-		syncResult === undefined && staleAllowed && !sameArgsAsLastResult && result !== undefined
+		!isSkipped &&
+			syncResult === undefined &&
+			staleAllowed &&
+			!sameArgsAsLastResult &&
+			result !== undefined
 	);
+
 	const data = $derived.by(() => {
-		if (result instanceof Error) {
-			return undefined;
-		}
+		if (result instanceof Error) return undefined;
 		return result;
 	});
+
 	const error = $derived.by(() => {
-		if (result instanceof Error) {
-			return result;
-		}
+		if (result instanceof Error) return result;
 		return undefined;
 	});
 
-	// This TypeScript cast promises data is not undefined if error and isLoading are checked first.
+	/*
+	 ** public shape **
+	 * This TypeScript cast promises data is not undefined if error and isLoading are checked first.
+	 */
 	return {
 		get data() {
 			return data;
 		},
 		get isLoading() {
-			return error === undefined && data === undefined;
+			return isSkipped ? false : error === undefined && data === undefined;
 		},
 		get error() {
 			return error;
 		},
 		get isStale() {
-			return isStale;
+			return isSkipped ? false : isStale;
 		}
 	} as UseQueryReturn<Query>;
 }
 
-// args can be an object or a closure returning one
+/**
+ *  args can be an object, "skip", or a closure returning either 
+ **/
 function parseArgs(
-	args: Record<string, Value> | (() => Record<string, Value>)
-): Record<string, Value> {
+	args: Record<string, Value> | 'skip' | (() => Record<string, Value> | 'skip')
+): Record<string, Value> | Skip {
 	if (typeof args === 'function') {
 		args = args();
 	}
+	if (args === 'skip') return SKIP;
 	return $state.snapshot(args);
 }
 
@@ -212,3 +255,13 @@ function parseOptions<Query extends FunctionReference<'query'>>(
 	}
 	return $state.snapshot(options);
 }
+
+function jsonEqualArgs(a: Record<string, Value>, b: Record<string, Value>): boolean {
+	return JSON.stringify(convexToJson(a)) === JSON.stringify(convexToJson(b));
+}
+
+function argsKeyEqual(a: Record<string, Value> | Skip, b: Record<string, Value> | Skip): boolean {
+	if (a === SKIP && b === SKIP) return true;
+	if (a === SKIP || b === SKIP) return false;
+	return jsonEqualArgs(a, b);
+}