@sylphx/lens-react 2.0.1 → 2.0.2

package/dist/index.d.ts

@@ -45,8 +45,7 @@ declare function LensProvider({ client, children }: LensProviderProps): ReactEle
 */
 declare function useLensClient<TRouter = any>(): LensClient<any, any> & TRouter;
 import { MutationResult, QueryResult } from "@sylphx/lens-client";
-/** Query input - can be a query, null/undefined, or an accessor function */
-type QueryInput<T> = QueryResult<T> | null | undefined | (() => QueryResult<T> | null | undefined);
+import { DependencyList } from "react";
 /** Result of useQuery hook */
 interface UseQueryResult<T> {
 	/** Query data (null if loading or error) */
@@ -75,62 +74,98 @@ interface UseMutationResult<
 	reset: () => void;
 }
 /** Options for useQuery */
-interface UseQueryOptions {
+interface UseQueryOptions<
+	TData = unknown,
+	TSelected = TData
+> {
 	/** Skip the query (don't execute) */
 	skip?: boolean;
+	/** Transform the query result */
+	select?: (data: TData) => TSelected;
 }
+/** Route function type - takes params and returns QueryResult */
+type RouteFunction<
+	TParams,
+	TResult
+> = (params: TParams) => QueryResult<TResult>;
+/** Accessor function type - returns QueryResult or null */
+type QueryAccessor<T> = () => QueryResult<T> | null | undefined;
+/** Mutation function type */
+type MutationFn<
+	TInput,
+	TOutput
+> = (input: TInput) => Promise<MutationResult<TOutput>>;
 /**
-* Subscribe to a query with reactive updates
+* Subscribe to a query with reactive updates.
+*
+* Two usage patterns:
 *
-* @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
-* @param options - Query options
+* **1. Route + Params (recommended)** - Stable references, no infinite loops
+* ```tsx
+* const { data } = useQuery(client.user.get, { id: userId });
+* ```
+*
+* **2. Accessor + Deps (escape hatch)** - For complex/composed queries
+* ```tsx
+* const { data } = useQuery(() => client.user.get({ id }).pipe(transform), [id]);
+* ```
 *
 * @example
 * ```tsx
-* // Basic usage
+* // Basic usage - Route + Params
 * function UserProfile({ userId }: { userId: string }) {
 *   const client = useLensClient();
-*   const { data: user, loading, error } = useQuery(client.user.get({ id: userId }));
+*   const { data: user, loading, error } = useQuery(client.user.get, { id: userId });
 *
 *   if (loading) return <Spinner />;
 *   if (error) return <Error message={error.message} />;
-*   if (!user) return <NotFound />;
+*   return <h1>{user?.name}</h1>;
+* }
 *
-*   return <h1>{user.name}</h1>;
+* // With select transform
+* function UserName({ userId }: { userId: string }) {
+*   const client = useLensClient();
+*   const { data: name } = useQuery(client.user.get, { id: userId }, {
+*     select: (user) => user.name
+*   });
+*   return <span>{name}</span>;
 * }
 *
-* // Conditional query (null when condition not met)
+* // Conditional query
 * function SessionInfo({ sessionId }: { sessionId: string | null }) {
 *   const client = useLensClient();
 *   const { data } = useQuery(
-*     sessionId ? client.session.get({ id: sessionId }) : null
+*     sessionId ? client.session.get : null,
+*     { id: sessionId ?? '' }
 *   );
-*   // data is null when sessionId is null
 *   return <span>{data?.totalTokens}</span>;
 * }
 *
-* // Accessor function (reactive inputs)
-* function ReactiveQuery({ sessionId }: { sessionId: Signal<string | null> }) {
+* // Skip query
+* function ConditionalQuery({ userId, shouldFetch }: { userId: string; shouldFetch: boolean }) {
 *   const client = useLensClient();
-*   const { data } = useQuery(() =>
-*     sessionId.value ? client.session.get({ id: sessionId.value }) : null
-*   );
-*   return <span>{data?.totalTokens}</span>;
+*   const { data } = useQuery(client.user.get, { id: userId }, { skip: !shouldFetch });
 * }
 *
-* // Skip query conditionally
-* function ConditionalQuery({ shouldFetch }: { shouldFetch: boolean }) {
+* // Complex queries with accessor (escape hatch)
+* function ComplexQuery({ userId }: { userId: string }) {
 *   const client = useLensClient();
-*   const { data } = useQuery(client.user.list(), { skip: !shouldFetch });
+*   const { data } = useQuery(
+*     () => client.user.get({ id: userId }),
+*     [userId]
+*   );
 * }
 * ```
 */
-declare function useQuery<T>(queryInput: QueryInput<T>, options?: UseQueryOptions): UseQueryResult<T>;
-/** Mutation function type */
-type MutationFn<
-	TInput,
-	TOutput
-> = (input: TInput) => Promise<MutationResult<TOutput>>;
+declare function useQuery<
+	TParams,
+	TResult,
+	TSelected = TResult
+>(route: RouteFunction<TParams, TResult> | null, params: TParams, options?: UseQueryOptions<TResult, TSelected>): UseQueryResult<TSelected>;
+declare function useQuery<
+	TResult,
+	TSelected = TResult
+>(accessor: QueryAccessor<TResult>, deps: DependencyList, options?: UseQueryOptions<TResult, TSelected>): UseQueryResult<TSelected>;
 /**
 * Execute mutations with loading/error state
 *
@@ -196,45 +231,44 @@ interface UseLazyQueryResult<T> {
 /**
 * Execute a query on demand (not on mount)
 *
-* @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
-*
 * @example
 * ```tsx
+* // Route + Params pattern
 * function SearchUsers() {
 *   const client = useLensClient();
 *   const [searchTerm, setSearchTerm] = useState('');
 *   const { execute, data, loading } = useLazyQuery(
-*     client.user.search({ query: searchTerm })
+*     client.user.search,
+*     { query: searchTerm }
 *   );
 *
-*   const handleSearch = async () => {
-*     const users = await execute();
-*     console.log('Found:', users);
-*   };
-*
 *   return (
 *     <div>
-*       <input
-*         value={searchTerm}
-*         onChange={e => setSearchTerm(e.target.value)}
-*       />
-*       <button onClick={handleSearch} disabled={loading}>
-*         Search
-*       </button>
+*       <input value={searchTerm} onChange={e => setSearchTerm(e.target.value)} />
+*       <button onClick={execute} disabled={loading}>Search</button>
 *       {data?.map(user => <UserCard key={user.id} user={user} />)}
 *     </div>
 *   );
 * }
 *
-* // With accessor function
-* function LazyReactiveQuery({ sessionId }: { sessionId: Signal<string | null> }) {
+* // Accessor pattern
+* function LazyComplexQuery({ userId }: { userId: string }) {
 *   const client = useLensClient();
-*   const { execute, data } = useLazyQuery(() =>
-*     sessionId.value ? client.session.get({ id: sessionId.value }) : null
+*   const { execute, data } = useLazyQuery(
+*     () => client.user.get({ id: userId }),
+*     [userId]
 *   );
 *   return <button onClick={execute}>Load</button>;
 * }
 * ```
 */
-declare function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T>;
-export { useQuery, useMutation, useLensClient, useLazyQuery, UseQueryResult, UseQueryOptions, UseMutationResult, UseLazyQueryResult, QueryInput, MutationFn, LensProviderProps, LensProvider };
+declare function useLazyQuery<
+	TParams,
+	TResult,
+	TSelected = TResult
+>(route: RouteFunction<TParams, TResult> | null, params: TParams, options?: UseQueryOptions<TResult, TSelected>): UseLazyQueryResult<TSelected>;
+declare function useLazyQuery<
+	TResult,
+	TSelected = TResult
+>(accessor: QueryAccessor<TResult>, deps: DependencyList, options?: UseQueryOptions<TResult, TSelected>): UseLazyQueryResult<TSelected>;
+export { useQuery, useMutation, useLensClient, useLazyQuery, UseQueryResult, UseQueryOptions, UseMutationResult, UseLazyQueryResult, RouteFunction, QueryAccessor, MutationFn, LensProviderProps, LensProvider };

package/dist/index.js

@@ -17,20 +17,35 @@ function useLensClient() {
 }
 // src/hooks.ts
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-function resolveQuery(input) {
-  return typeof input === "function" ? input() : input;
-}
-function useQuery(queryInput, options) {
-  const query = useMemo(() => resolveQuery(queryInput), [queryInput]);
+function useQuery(routeOrAccessor, paramsOrDeps, options) {
+  const isAccessorMode = Array.isArray(paramsOrDeps);
+  const paramsKey = !isAccessorMode ? JSON.stringify(paramsOrDeps) : null;
+  const query = useMemo(() => {
+    if (options?.skip)
+      return null;
+    if (isAccessorMode) {
+      const accessor = routeOrAccessor;
+      return accessor();
+    }
+    if (!routeOrAccessor)
+      return null;
+    const route = routeOrAccessor;
+    return route(paramsOrDeps);
+  }, isAccessorMode ? [options?.skip, ...paramsOrDeps] : [routeOrAccessor, paramsKey, options?.skip]);
+  const selectRef = useRef(options?.select);
+  selectRef.current = options?.select;
   const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(!options?.skip && query != null);
+  const [loading, setLoading] = useState(query != null && !options?.skip);
   const [error, setError] = useState(null);
   const mountedRef = useRef(true);
   const queryRef = useRef(query);
   queryRef.current = query;
+  const transform = useCallback((value) => {
+    return selectRef.current ? selectRef.current(value) : value;
+  }, []);
   useEffect(() => {
     mountedRef.current = true;
-    if (query == null || options?.skip) {
+    if (query == null) {
       setData(null);
       setLoading(false);
       setError(null);
@@ -40,13 +55,13 @@ function useQuery(queryInput, options) {
     setError(null);
     const unsubscribe = query.subscribe((value) => {
       if (mountedRef.current) {
-        setData(value);
+        setData(transform(value));
         setLoading(false);
       }
     });
     query.then((value) => {
       if (mountedRef.current) {
-        setData(value);
+        setData(transform(value));
         setLoading(false);
       }
     }, (err) => {
@@ -59,16 +74,16 @@ function useQuery(queryInput, options) {
       mountedRef.current = false;
       unsubscribe();
     };
-  }, [query, options?.skip]);
+  }, [query, transform]);
   const refetch = useCallback(() => {
     const currentQuery = queryRef.current;
-    if (currentQuery == null || options?.skip)
+    if (currentQuery == null)
       return;
     setLoading(true);
     setError(null);
     currentQuery.then((value) => {
       if (mountedRef.current) {
-        setData(value);
+        setData(transform(value));
         setLoading(false);
       }
     }, (err) => {
@@ -77,7 +92,7 @@ function useQuery(queryInput, options) {
         setLoading(false);
       }
     });
-  }, [options?.skip]);
+  }, [transform]);
   return { data, loading, error, refetch };
 }
 function useMutation(mutationFn) {
@@ -119,13 +134,18 @@ function useMutation(mutationFn) {
   }, []);
   return { mutate, loading, error, data, reset };
 }
-function useLazyQuery(queryInput) {
+function useLazyQuery(routeOrAccessor, paramsOrDeps, options) {
   const [data, setData] = useState(null);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState(null);
   const mountedRef = useRef(true);
-  const queryInputRef = useRef(queryInput);
-  queryInputRef.current = queryInput;
+  const isAccessorMode = Array.isArray(paramsOrDeps);
+  const routeOrAccessorRef = useRef(routeOrAccessor);
+  routeOrAccessorRef.current = routeOrAccessor;
+  const paramsOrDepsRef = useRef(paramsOrDeps);
+  paramsOrDepsRef.current = paramsOrDeps;
+  const selectRef = useRef(options?.select);
+  selectRef.current = options?.select;
   useEffect(() => {
     mountedRef.current = true;
     return () => {
@@ -133,7 +153,16 @@ function useLazyQuery(queryInput) {
     };
   }, []);
   const execute = useCallback(async () => {
-    const query = resolveQuery(queryInputRef.current);
+    let query;
+    if (isAccessorMode) {
+      const accessor = routeOrAccessorRef.current;
+      query = accessor();
+    } else {
+      const route = routeOrAccessorRef.current;
+      if (route) {
+        query = route(paramsOrDepsRef.current);
+      }
+    }
     if (query == null) {
       setData(null);
       setLoading(false);
@@ -143,10 +172,11 @@ function useLazyQuery(queryInput) {
     setError(null);
     try {
       const result = await query;
+      const selected = selectRef.current ? selectRef.current(result) : result;
       if (mountedRef.current) {
-        setData(result);
+        setData(selected);
       }
-      return result;
+      return selected;
     } catch (err) {
       const queryError = err instanceof Error ? err : new Error(String(err));
       if (mountedRef.current) {
@@ -158,7 +188,7 @@ function useLazyQuery(queryInput) {
         setLoading(false);
       }
     }
-  }, []);
+  }, [isAccessorMode]);
   const reset = useCallback(() => {
     setLoading(false);
     setError(null);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/lens-react",
-	"version": "2.0.1",
+	"version": "2.0.2",
 	"description": "React bindings for Lens API framework",
 	"type": "module",
 	"main": "./dist/index.js",

package/src/hooks.test.tsx

@@ -88,14 +88,14 @@ function createMockQueryResult<T>(initialValue: T | null = null): QueryResult<T>
 }
 
 // =============================================================================
-// Tests: useQuery
+// Tests: useQuery (Accessor + Deps pattern)
 // =============================================================================
 
 describe("useQuery", () => {
 	test("returns loading state initially", () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		expect(result.current.loading).toBe(true);
 		expect(result.current.data).toBe(null);
@@ -105,7 +105,7 @@ describe("useQuery", () => {
 	test("returns data when query resolves", async () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		// Simulate data loading
 		act(() => {
@@ -123,7 +123,7 @@ describe("useQuery", () => {
 	test("returns error when query fails", async () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		// Simulate error
 		act(() => {
@@ -147,7 +147,7 @@ describe("useQuery", () => {
 			},
 		} as unknown as QueryResult<{ id: string }>;
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		await waitFor(() => {
 			expect(result.current.error?.message).toBe("String error");
@@ -157,65 +157,32 @@ describe("useQuery", () => {
 	test("skips query when skip option is true", () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery, { skip: true }));
+		const { result } = renderHook(() => useQuery(() => mockQuery, [], { skip: true }));
 
 		expect(result.current.loading).toBe(false);
 		expect(result.current.data).toBe(null);
 	});
 
-	test("handles null query", () => {
-		const { result } = renderHook(() => useQuery(null));
+	test("handles null query from accessor", () => {
+		const { result } = renderHook(() => useQuery(() => null, []));
 
 		expect(result.current.loading).toBe(false);
 		expect(result.current.data).toBe(null);
 		expect(result.current.error).toBe(null);
 	});
 
-	test("handles undefined query", () => {
-		const { result } = renderHook(() => useQuery(undefined));
+	test("handles undefined query from accessor", () => {
+		const { result } = renderHook(() => useQuery(() => undefined, []));
 
 		expect(result.current.loading).toBe(false);
 		expect(result.current.data).toBe(null);
 		expect(result.current.error).toBe(null);
 	});
 
-	test("handles accessor function returning query", async () => {
-		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
-		const accessor = () => mockQuery;
-
-		const { result } = renderHook(() => useQuery(accessor));
-
-		act(() => {
-			mockQuery._setValue({ id: "123", name: "John" });
-		});
-
-		await waitFor(() => {
-			expect(result.current.data).toEqual({ id: "123", name: "John" });
-		});
-	});
-
-	test("handles accessor function returning null", () => {
-		const accessor = () => null;
-
-		const { result } = renderHook(() => useQuery(accessor));
-
-		expect(result.current.loading).toBe(false);
-		expect(result.current.data).toBe(null);
-	});
-
-	test("handles accessor function returning undefined", () => {
-		const accessor = () => undefined;
-
-		const { result } = renderHook(() => useQuery(accessor));
-
-		expect(result.current.loading).toBe(false);
-		expect(result.current.data).toBe(null);
-	});
-
 	test("updates when query subscription emits", async () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		// First value
 		act(() => {
@@ -239,7 +206,7 @@ describe("useQuery", () => {
 	test("refetch reloads the query", async () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		// Initial load
 		act(() => {
@@ -267,7 +234,7 @@ describe("useQuery", () => {
 	test("refetch handles errors", async () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		// Initial load succeeds
 		act(() => {
@@ -287,7 +254,7 @@ describe("useQuery", () => {
 		} as unknown as QueryResult<{ id: string; name: string }>;
 
 		// Update the query to use failing query
-		const { result: result2 } = renderHook(() => useQuery(failingQuery));
+		const { result: result2 } = renderHook(() => useQuery(() => failingQuery, []));
 
 		await waitFor(() => {
 			expect(result2.current.error?.message).toBe("Refetch failed");
@@ -295,7 +262,7 @@ describe("useQuery", () => {
 	});
 
 	test("refetch does nothing when query is null", () => {
-		const { result } = renderHook(() => useQuery(null));
+		const { result } = renderHook(() => useQuery(() => null, []));
 
 		act(() => {
 			result.current.refetch();
@@ -308,7 +275,7 @@ describe("useQuery", () => {
 	test("refetch does nothing when skip is true", () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useQuery(mockQuery, { skip: true }));
+		const { result } = renderHook(() => useQuery(() => mockQuery, [], { skip: true }));
 
 		act(() => {
 			result.current.refetch();
@@ -330,7 +297,7 @@ describe("useQuery", () => {
 			},
 		} as unknown as QueryResult<{ id: string; name: string }>;
 
-		const { result } = renderHook(() => useQuery(mockQuery));
+		const { result } = renderHook(() => useQuery(() => mockQuery, []));
 
 		await waitFor(() => {
 			expect(result.current.data).toEqual({ id: "123", name: "John" });
@@ -362,7 +329,7 @@ describe("useQuery", () => {
 			};
 		};
 
-		const { unmount } = renderHook(() => useQuery(mockQuery));
+		const { unmount } = renderHook(() => useQuery(() => mockQuery, []));
 
 		unmount();
 
@@ -372,7 +339,7 @@ describe("useQuery", () => {
 	test("does not update state after unmount", async () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { unmount } = renderHook(() => useQuery(mockQuery));
+		const { unmount } = renderHook(() => useQuery(() => mockQuery, []));
 
 		// Unmount before query resolves
 		unmount();
@@ -387,12 +354,12 @@ describe("useQuery", () => {
 		expect(true).toBe(true);
 	});
 
-	test("handles query change", async () => {
+	test("handles query change via deps", async () => {
 		const mockQuery1 = createMockQueryResult<{ id: string; name: string }>();
 		const mockQuery2 = createMockQueryResult<{ id: string; name: string }>();
 
-		let currentQuery = mockQuery1;
-		const { result, rerender } = renderHook(() => useQuery(currentQuery));
+		let queryId = 1;
+		const { result, rerender } = renderHook(() => useQuery(() => (queryId === 1 ? mockQuery1 : mockQuery2), [queryId]));
 
 		// Load first query
 		act(() => {
@@ -404,7 +371,7 @@ describe("useQuery", () => {
 		});
 
 		// Change to second query
-		currentQuery = mockQuery2;
+		queryId = 2;
 		rerender();
 
 		expect(result.current.loading).toBe(true);
@@ -423,7 +390,7 @@ describe("useQuery", () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
 		let skip = true;
-		const { result, rerender } = renderHook(() => useQuery(mockQuery, { skip }));
+		const { result, rerender } = renderHook(() => useQuery(() => mockQuery, [], { skip }));
 
 		expect(result.current.loading).toBe(false);
 
@@ -446,7 +413,7 @@ describe("useQuery", () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
 		let skip = false;
-		const { result, rerender } = renderHook(() => useQuery(mockQuery, { skip }));
+		const { result, rerender } = renderHook(() => useQuery(() => mockQuery, [], { skip }));
 
 		act(() => {
 			mockQuery._setValue({ id: "123", name: "John" });
@@ -464,6 +431,46 @@ describe("useQuery", () => {
 		expect(result.current.data).toBe(null);
 		expect(result.current.error).toBe(null);
 	});
+
+	test("select transforms the data", async () => {
+		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
+
+		const { result } = renderHook(() =>
+			useQuery(() => mockQuery, [], {
+				select: (data) => data.name.toUpperCase(),
+			}),
+		);
+
+		act(() => {
+			mockQuery._setValue({ id: "123", name: "John" });
+		});
+
+		await waitFor(() => {
+			expect(result.current.data).toBe("JOHN");
+		});
+	});
+
+	test("Route + Params pattern works", async () => {
+		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
+		const route = (_params: { id: string }) => mockQuery;
+
+		const { result } = renderHook(() => useQuery(route, { id: "123" }));
+
+		act(() => {
+			mockQuery._setValue({ id: "123", name: "John" });
+		});
+
+		await waitFor(() => {
+			expect(result.current.data).toEqual({ id: "123", name: "John" });
+		});
+	});
+
+	test("Route + Params with null route", () => {
+		const { result } = renderHook(() => useQuery(null, { id: "123" }));
+
+		expect(result.current.loading).toBe(false);
+		expect(result.current.data).toBe(null);
+	});
 });
 
 // =============================================================================
@@ -657,14 +664,14 @@ describe("useMutation", () => {
 });
 
 // =============================================================================
-// Tests: useLazyQuery
+// Tests: useLazyQuery (Accessor + Deps pattern)
 // =============================================================================
 
 describe("useLazyQuery", () => {
 	test("does not execute query on mount", () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useLazyQuery(mockQuery));
+		const { result } = renderHook(() => useLazyQuery(() => mockQuery, []));
 
 		expect(result.current.loading).toBe(false);
 		expect(result.current.data).toBe(null);
@@ -676,7 +683,7 @@ describe("useLazyQuery", () => {
 			name: "John",
 		});
 
-		const { result } = renderHook(() => useLazyQuery(mockQuery));
+		const { result } = renderHook(() => useLazyQuery(() => mockQuery, []));
 
 		let queryResult: { id: string; name: string } | undefined;
 		await act(async () => {
@@ -691,7 +698,7 @@ describe("useLazyQuery", () => {
 		// Create a mock query that rejects
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result } = renderHook(() => useLazyQuery(mockQuery));
+		const { result } = renderHook(() => useLazyQuery(() => mockQuery, []));
 
 		// Set error before execute
 		act(() => {
@@ -717,7 +724,7 @@ describe("useLazyQuery", () => {
 			},
 		} as unknown as QueryResult<{ id: string }>;
 
-		const { result } = renderHook(() => useLazyQuery(mockQuery));
+		const { result } = renderHook(() => useLazyQuery(() => mockQuery, []));
 
 		await act(async () => {
 			try {
@@ -736,7 +743,7 @@ describe("useLazyQuery", () => {
 			name: "John",
 		});
 
-		const { result } = renderHook(() => useLazyQuery(mockQuery));
+		const { result } = renderHook(() => useLazyQuery(() => mockQuery, []));
 
 		await act(async () => {
 			await result.current.execute();
@@ -753,8 +760,8 @@ describe("useLazyQuery", () => {
 		expect(result.current.loading).toBe(false);
 	});
 
-	test("handles null query", async () => {
-		const { result } = renderHook(() => useLazyQuery(null));
+	test("handles null query from accessor", async () => {
+		const { result } = renderHook(() => useLazyQuery(() => null, []));
 
 		let queryResult: any;
 		await act(async () => {
@@ -766,8 +773,8 @@ describe("useLazyQuery", () => {
 		expect(result.current.loading).toBe(false);
 	});
 
-	test("handles undefined query", async () => {
-		const { result } = renderHook(() => useLazyQuery(undefined));
+	test("handles undefined query from accessor", async () => {
+		const { result } = renderHook(() => useLazyQuery(() => undefined, []));
 
 		let queryResult: any;
 		await act(async () => {
@@ -779,36 +786,6 @@ describe("useLazyQuery", () => {
 		expect(result.current.loading).toBe(false);
 	});
 
-	test("handles accessor function returning query", async () => {
-		const mockQuery = createMockQueryResult<{ id: string; name: string }>({
-			id: "123",
-			name: "John",
-		});
-		const accessor = () => mockQuery;
-
-		const { result } = renderHook(() => useLazyQuery(accessor));
-
-		let queryResult: { id: string; name: string } | undefined;
-		await act(async () => {
-			queryResult = await result.current.execute();
-		});
-
-		expect(queryResult).toEqual({ id: "123", name: "John" });
-	});
-
-	test("handles accessor function returning null", async () => {
-		const accessor = () => null;
-
-		const { result } = renderHook(() => useLazyQuery(accessor));
-
-		let queryResult: any;
-		await act(async () => {
-			queryResult = await result.current.execute();
-		});
-
-		expect(queryResult).toBe(null);
-	});
-
 	test("uses latest query value from accessor on execute", async () => {
 		let currentValue = "first";
 		const mockQuery1 = createMockQueryResult<string>("first");
@@ -816,7 +793,7 @@ describe("useLazyQuery", () => {
 
 		const accessor = () => (currentValue === "first" ? mockQuery1 : mockQuery2);
 
-		const { result } = renderHook(() => useLazyQuery(accessor));
+		const { result } = renderHook(() => useLazyQuery(accessor, []));
 
 		// First execute
 		let queryResult1: string | undefined;
@@ -841,7 +818,7 @@ describe("useLazyQuery", () => {
 	test("shows loading state during execution", async () => {
 		const mockQuery = createMockQueryResult<{ id: string }>();
 
-		const { result } = renderHook(() => useLazyQuery(mockQuery));
+		const { result } = renderHook(() => useLazyQuery(() => mockQuery, []));
 
 		// Execute and set value
 		let executePromise: Promise<{ id: string }>;
@@ -858,7 +835,7 @@ describe("useLazyQuery", () => {
 	test("does not update state after unmount", async () => {
 		const mockQuery = createMockQueryResult<{ id: string; name: string }>();
 
-		const { result, unmount } = renderHook(() => useLazyQuery(mockQuery));
+		const { result, unmount } = renderHook(() => useLazyQuery(() => mockQuery, []));
 
 		// Start execution, unmount, then resolve
 		const executePromise = result.current.execute();
@@ -867,72 +844,83 @@ describe("useLazyQuery", () => {
 		// Resolve after unmount
 		await act(async () => {
 			mockQuery._setValue({ id: "123", name: "John" });
-			await executePromise;
+			try {
+				await executePromise;
+			} catch {
+				// May reject due to unmount
+			}
 		});
 
 		// Test passes if no error is thrown (state update after unmount would cause error)
 		expect(true).toBe(true);
 	});
 
-	test("clears error on successful execute after previous error", async () => {
-		const mockQuery1 = createMockQueryResult<{ id: string }>();
-		const mockQuery2 = createMockQueryResult<{ id: string }>({ id: "123" });
+	test("can execute multiple times", async () => {
+		let count = 0;
+		const createQuery = () => {
+			count++;
+			return createMockQueryResult<{ count: number }>({ count });
+		};
 
-		const { result, rerender } = renderHook(({ query }) => useLazyQuery(query), {
-			initialProps: { query: mockQuery1 },
-		});
+		const { result } = renderHook(() => useLazyQuery(() => createQuery(), []));
 
-		// First execution fails
+		// First execution
 		await act(async () => {
-			const executePromise = result.current.execute();
-			mockQuery1._setError(new Error("Query failed"));
-			try {
-				await executePromise;
-			} catch {
-				// Expected error
-			}
+			await result.current.execute();
 		});
 
-		expect(result.current.error?.message).toBe("Query failed");
-
-		// Switch to successful query
-		rerender({ query: mockQuery2 });
+		expect(result.current.data?.count).toBe(1);
 
-		// Second execution succeeds
+		// Second execution
 		await act(async () => {
 			await result.current.execute();
 		});
 
-		expect(result.current.error).toBe(null);
-		expect(result.current.data).toEqual({ id: "123" });
+		expect(result.current.data?.count).toBe(2);
 	});
 
-	test("can execute multiple times", async () => {
-		const mockQuery1 = createMockQueryResult<{ count: number }>();
-		const mockQuery2 = createMockQueryResult<{ count: number }>();
+	test("Route + Params pattern works", async () => {
+		const mockQuery = createMockQueryResult<{ id: string; name: string }>({
+			id: "123",
+			name: "John",
+		});
+		const route = (_params: { id: string }) => mockQuery;
+
+		const { result } = renderHook(() => useLazyQuery(route, { id: "123" }));
 
-		const { result, rerender } = renderHook(({ query }) => useLazyQuery(query), {
-			initialProps: { query: mockQuery1 },
+		await act(async () => {
+			await result.current.execute();
 		});
 
-		// First execution
+		expect(result.current.data).toEqual({ id: "123", name: "John" });
+	});
+
+	test("Route + Params with null route", async () => {
+		const { result } = renderHook(() => useLazyQuery(null, { id: "123" }));
+
 		await act(async () => {
-			const executePromise = result.current.execute();
-			mockQuery1._setValue({ count: 1 });
-			await executePromise;
+			await result.current.execute();
 		});
 
-		expect(result.current.data?.count).toBe(1);
+		expect(result.current.data).toBe(null);
+	});
 
-		// Change to second query and execute again
-		rerender({ query: mockQuery2 });
+	test("select transforms the data", async () => {
+		const mockQuery = createMockQueryResult<{ id: string; name: string }>({
+			id: "123",
+			name: "John",
+		});
+
+		const { result } = renderHook(() =>
+			useLazyQuery(() => mockQuery, [], {
+				select: (data) => data.name.toUpperCase(),
+			}),
+		);
 
 		await act(async () => {
-			const executePromise = result.current.execute();
-			mockQuery2._setValue({ count: 2 });
-			await executePromise;
+			await result.current.execute();
 		});
 
-		expect(result.current.data?.count).toBe(2);
+		expect(result.current.data).toBe("JOHN");
 	});
 });

package/src/hooks.ts

@@ -10,7 +10,8 @@
  *
  * function UserProfile({ userId }: { userId: string }) {
  *   const client = useLensClient();
- *   const { data: user, loading } = useQuery(client.user.get({ id: userId }));
+ *   // Route + Params pattern (recommended)
+ *   const { data: user, loading } = useQuery(client.user.get, { id: userId });
  *   if (loading) return <Spinner />;
  *   return <h1>{user?.name}</h1>;
  * }
@@ -25,18 +26,7 @@
  */
 
 import type { MutationResult, QueryResult } from "@sylphx/lens-client";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-
-// =============================================================================
-// Query Input Types
-// =============================================================================
-
-/** Query input - can be a query, null/undefined, or an accessor function */
-export type QueryInput<T> =
-	| QueryResult<T>
-	| null
-	| undefined
-	| (() => QueryResult<T> | null | undefined);
+import { type DependencyList, useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 // =============================================================================
 // Types
@@ -69,75 +59,144 @@ export interface UseMutationResult<TInput, TOutput> {
 }
 
 /** Options for useQuery */
-export interface UseQueryOptions {
+export interface UseQueryOptions<TData = unknown, TSelected = TData> {
 	/** Skip the query (don't execute) */
 	skip?: boolean;
+	/** Transform the query result */
+	select?: (data: TData) => TSelected;
 }
 
+/** Route function type - takes params and returns QueryResult */
+export type RouteFunction<TParams, TResult> = (params: TParams) => QueryResult<TResult>;
+
+/** Accessor function type - returns QueryResult or null */
+export type QueryAccessor<T> = () => QueryResult<T> | null | undefined;
+
+/** Mutation function type */
+export type MutationFn<TInput, TOutput> = (input: TInput) => Promise<MutationResult<TOutput>>;
+
 // =============================================================================
-// useQuery Hook
+// useQuery Hook - Route + Params (Primary API)
 // =============================================================================
 
-/** Helper to resolve query input (handles accessor functions) */
-function resolveQuery<T>(input: QueryInput<T>): QueryResult<T> | null | undefined {
-	return typeof input === "function" ? input() : input;
-}
-
 /**
- * Subscribe to a query with reactive updates
+ * Subscribe to a query with reactive updates.
+ *
+ * Two usage patterns:
  *
- * @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
- * @param options - Query options
+ * **1. Route + Params (recommended)** - Stable references, no infinite loops
+ * ```tsx
+ * const { data } = useQuery(client.user.get, { id: userId });
+ * ```
+ *
+ * **2. Accessor + Deps (escape hatch)** - For complex/composed queries
+ * ```tsx
+ * const { data } = useQuery(() => client.user.get({ id }).pipe(transform), [id]);
+ * ```
  *
  * @example
  * ```tsx
- * // Basic usage
+ * // Basic usage - Route + Params
  * function UserProfile({ userId }: { userId: string }) {
  *   const client = useLensClient();
- *   const { data: user, loading, error } = useQuery(client.user.get({ id: userId }));
+ *   const { data: user, loading, error } = useQuery(client.user.get, { id: userId });
  *
  *   if (loading) return <Spinner />;
  *   if (error) return <Error message={error.message} />;
- *   if (!user) return <NotFound />;
+ *   return <h1>{user?.name}</h1>;
+ * }
  *
- *   return <h1>{user.name}</h1>;
+ * // With select transform
+ * function UserName({ userId }: { userId: string }) {
+ *   const client = useLensClient();
+ *   const { data: name } = useQuery(client.user.get, { id: userId }, {
+ *     select: (user) => user.name
+ *   });
+ *   return <span>{name}</span>;
  * }
  *
- * // Conditional query (null when condition not met)
+ * // Conditional query
  * function SessionInfo({ sessionId }: { sessionId: string | null }) {
  *   const client = useLensClient();
  *   const { data } = useQuery(
- *     sessionId ? client.session.get({ id: sessionId }) : null
+ *     sessionId ? client.session.get : null,
+ *     { id: sessionId ?? '' }
  *   );
- *   // data is null when sessionId is null
  *   return <span>{data?.totalTokens}</span>;
  * }
  *
- * // Accessor function (reactive inputs)
- * function ReactiveQuery({ sessionId }: { sessionId: Signal<string | null> }) {
+ * // Skip query
+ * function ConditionalQuery({ userId, shouldFetch }: { userId: string; shouldFetch: boolean }) {
  *   const client = useLensClient();
- *   const { data } = useQuery(() =>
- *     sessionId.value ? client.session.get({ id: sessionId.value }) : null
- *   );
- *   return <span>{data?.totalTokens}</span>;
+ *   const { data } = useQuery(client.user.get, { id: userId }, { skip: !shouldFetch });
  * }
  *
- * // Skip query conditionally
- * function ConditionalQuery({ shouldFetch }: { shouldFetch: boolean }) {
+ * // Complex queries with accessor (escape hatch)
+ * function ComplexQuery({ userId }: { userId: string }) {
  *   const client = useLensClient();
- *   const { data } = useQuery(client.user.list(), { skip: !shouldFetch });
+ *   const { data } = useQuery(
+ *     () => client.user.get({ id: userId }),
+ *     [userId]
+ *   );
  * }
  * ```
  */
-export function useQuery<T>(
-	queryInput: QueryInput<T>,
-	options?: UseQueryOptions,
-): UseQueryResult<T> {
-	// Resolve query (handles accessor functions)
-	const query = useMemo(() => resolveQuery(queryInput), [queryInput]);
-
-	const [data, setData] = useState<T | null>(null);
-	const [loading, setLoading] = useState(!options?.skip && query != null);
+
+// Overload 1: Route + Params (recommended)
+export function useQuery<TParams, TResult, TSelected = TResult>(
+	route: RouteFunction<TParams, TResult> | null,
+	params: TParams,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseQueryResult<TSelected>;
+
+// Overload 2: Accessor + Deps (escape hatch for complex queries)
+export function useQuery<TResult, TSelected = TResult>(
+	accessor: QueryAccessor<TResult>,
+	deps: DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseQueryResult<TSelected>;
+
+// Implementation
+export function useQuery<TParams, TResult, TSelected = TResult>(
+	routeOrAccessor: RouteFunction<TParams, TResult> | QueryAccessor<TResult> | null,
+	paramsOrDeps: TParams | DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseQueryResult<TSelected> {
+	// Detect which overload is being used
+	const isAccessorMode = Array.isArray(paramsOrDeps);
+
+	// Stable params key for Route + Params mode
+	const paramsKey = !isAccessorMode ? JSON.stringify(paramsOrDeps) : null;
+
+	// Create query - memoized based on route/params or deps
+	const query = useMemo(
+		() => {
+			if (options?.skip) return null;
+
+			if (isAccessorMode) {
+				// Accessor mode: call the function
+				const accessor = routeOrAccessor as QueryAccessor<TResult>;
+				return accessor();
+			}
+			// Route + Params mode
+			if (!routeOrAccessor) return null;
+			const route = routeOrAccessor as RouteFunction<TParams, TResult>;
+			return route(paramsOrDeps as TParams);
+		},
+		// biome-ignore lint/correctness/useExhaustiveDependencies: Dynamic deps based on overload mode - intentional
+		isAccessorMode
+			? // eslint-disable-next-line react-hooks/exhaustive-deps
+				[options?.skip, ...(paramsOrDeps as DependencyList)]
+			: // eslint-disable-next-line react-hooks/exhaustive-deps
+				[routeOrAccessor, paramsKey, options?.skip],
+	);
+
+	// Use ref for select to avoid it being a dependency
+	const selectRef = useRef(options?.select);
+	selectRef.current = options?.select;
+
+	const [data, setData] = useState<TSelected | null>(null);
+	const [loading, setLoading] = useState(query != null && !options?.skip);
 	const [error, setError] = useState<Error | null>(null);
 
 	// Track mounted state
@@ -147,12 +206,17 @@ export function useQuery<T>(
 	const queryRef = useRef(query);
 	queryRef.current = query;
 
+	// Transform helper
+	const transform = useCallback((value: TResult): TSelected => {
+		return selectRef.current ? selectRef.current(value) : (value as unknown as TSelected);
+	}, []);
+
 	// Subscribe to query
 	useEffect(() => {
 		mountedRef.current = true;
 
 		// Handle null/undefined query
-		if (query == null || options?.skip) {
+		if (query == null) {
 			setData(null);
 			setLoading(false);
 			setError(null);
@@ -165,7 +229,7 @@ export function useQuery<T>(
 		// Subscribe to updates
 		const unsubscribe = query.subscribe((value) => {
 			if (mountedRef.current) {
-				setData(value);
+				setData(transform(value));
 				setLoading(false);
 			}
 		});
@@ -174,7 +238,7 @@ export function useQuery<T>(
 		query.then(
 			(value) => {
 				if (mountedRef.current) {
-					setData(value);
+					setData(transform(value));
 					setLoading(false);
 				}
 			},
@@ -190,12 +254,12 @@ export function useQuery<T>(
 			mountedRef.current = false;
 			unsubscribe();
 		};
-	}, [query, options?.skip]);
+	}, [query, transform]);
 
 	// Refetch function
 	const refetch = useCallback(() => {
 		const currentQuery = queryRef.current;
-		if (currentQuery == null || options?.skip) return;
+		if (currentQuery == null) return;
 
 		setLoading(true);
 		setError(null);
@@ -203,7 +267,7 @@ export function useQuery<T>(
 		currentQuery.then(
 			(value) => {
 				if (mountedRef.current) {
-					setData(value);
+					setData(transform(value));
 					setLoading(false);
 				}
 			},
@@ -214,7 +278,7 @@ export function useQuery<T>(
 				}
 			},
 		);
-	}, [options?.skip]);
+	}, [transform]);
 
 	return { data, loading, error, refetch };
 }
@@ -223,9 +287,6 @@ export function useQuery<T>(
 // useMutation Hook
 // =============================================================================
 
-/** Mutation function type */
-export type MutationFn<TInput, TOutput> = (input: TInput) => Promise<MutationResult<TOutput>>;
-
 /**
  * Execute mutations with loading/error state
  *
@@ -348,57 +409,77 @@ export interface UseLazyQueryResult<T> {
 /**
  * Execute a query on demand (not on mount)
  *
- * @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
- *
  * @example
  * ```tsx
+ * // Route + Params pattern
  * function SearchUsers() {
  *   const client = useLensClient();
  *   const [searchTerm, setSearchTerm] = useState('');
  *   const { execute, data, loading } = useLazyQuery(
- *     client.user.search({ query: searchTerm })
+ *     client.user.search,
+ *     { query: searchTerm }
  *   );
  *
- *   const handleSearch = async () => {
- *     const users = await execute();
- *     console.log('Found:', users);
- *   };
- *
  *   return (
  *     <div>
- *       <input
- *         value={searchTerm}
- *         onChange={e => setSearchTerm(e.target.value)}
- *       />
- *       <button onClick={handleSearch} disabled={loading}>
- *         Search
- *       </button>
+ *       <input value={searchTerm} onChange={e => setSearchTerm(e.target.value)} />
+ *       <button onClick={execute} disabled={loading}>Search</button>
  *       {data?.map(user => <UserCard key={user.id} user={user} />)}
  *     </div>
  *   );
  * }
  *
- * // With accessor function
- * function LazyReactiveQuery({ sessionId }: { sessionId: Signal<string | null> }) {
+ * // Accessor pattern
+ * function LazyComplexQuery({ userId }: { userId: string }) {
  *   const client = useLensClient();
- *   const { execute, data } = useLazyQuery(() =>
- *     sessionId.value ? client.session.get({ id: sessionId.value }) : null
+ *   const { execute, data } = useLazyQuery(
+ *     () => client.user.get({ id: userId }),
+ *     [userId]
  *   );
  *   return <button onClick={execute}>Load</button>;
  * }
  * ```
  */
-export function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T> {
-	const [data, setData] = useState<T | null>(null);
+
+// Overload 1: Route + Params
+export function useLazyQuery<TParams, TResult, TSelected = TResult>(
+	route: RouteFunction<TParams, TResult> | null,
+	params: TParams,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseLazyQueryResult<TSelected>;
+
+// Overload 2: Accessor + Deps
+export function useLazyQuery<TResult, TSelected = TResult>(
+	accessor: QueryAccessor<TResult>,
+	deps: DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseLazyQueryResult<TSelected>;
+
+// Implementation
+export function useLazyQuery<TParams, TResult, TSelected = TResult>(
+	routeOrAccessor: RouteFunction<TParams, TResult> | QueryAccessor<TResult> | null,
+	paramsOrDeps: TParams | DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseLazyQueryResult<TSelected> {
+	const [data, setData] = useState<TSelected | null>(null);
 	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState<Error | null>(null);
 
 	// Track mounted state
 	const mountedRef = useRef(true);
 
-	// Store queryInput ref for execute (so it uses latest value)
-	const queryInputRef = useRef(queryInput);
-	queryInputRef.current = queryInput;
+	// Detect which overload
+	const isAccessorMode = Array.isArray(paramsOrDeps);
+
+	// Store refs for execute (so it uses latest values)
+	const routeOrAccessorRef = useRef(routeOrAccessor);
+	routeOrAccessorRef.current = routeOrAccessor;
+
+	const paramsOrDepsRef = useRef(paramsOrDeps);
+	paramsOrDepsRef.current = paramsOrDeps;
+
+	const selectRef = useRef(options?.select);
+	selectRef.current = options?.select;
 
 	useEffect(() => {
 		mountedRef.current = true;
@@ -408,13 +489,23 @@ export function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T
 	}, []);
 
 	// Execute function
-	const execute = useCallback(async (): Promise<T> => {
-		const query = resolveQuery(queryInputRef.current);
+	const execute = useCallback(async (): Promise<TSelected> => {
+		let query: QueryResult<TResult> | null | undefined;
+
+		if (isAccessorMode) {
+			const accessor = routeOrAccessorRef.current as QueryAccessor<TResult>;
+			query = accessor();
+		} else {
+			const route = routeOrAccessorRef.current as RouteFunction<TParams, TResult> | null;
+			if (route) {
+				query = route(paramsOrDepsRef.current as TParams);
+			}
+		}
 
 		if (query == null) {
 			setData(null);
 			setLoading(false);
-			return null as T;
+			return null as TSelected;
 		}
 
 		setLoading(true);
@@ -422,12 +513,15 @@ export function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T
 
 		try {
 			const result = await query;
+			const selected = selectRef.current
+				? selectRef.current(result)
+				: (result as unknown as TSelected);
 
 			if (mountedRef.current) {
-				setData(result);
+				setData(selected);
 			}
 
-			return result;
+			return selected;
 		} catch (err) {
 			const queryError = err instanceof Error ? err : new Error(String(err));
 			if (mountedRef.current) {
@@ -439,7 +533,7 @@ export function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T
 				setLoading(false);
 			}
 		}
-	}, []);
+	}, [isAccessorMode]);
 
 	// Reset function
 	const reset = useCallback(() => {

package/src/index.ts

@@ -18,7 +18,8 @@ export { LensProvider, type LensProviderProps, useLensClient } from "./context.j
 export {
 	type MutationFn,
 	// Types
-	type QueryInput,
+	type QueryAccessor,
+	type RouteFunction,
 	type UseLazyQueryResult,
 	type UseMutationResult,
 	type UseQueryOptions,