@sylphx/lens-react 2.0.1 → 2.1.0

package/src/hooks.ts

@@ -6,37 +6,29 @@
  *
  * @example
  * ```tsx
- * import { useLensClient, useQuery, useMutation } from '@sylphx/lens-react';
+ * import { useQuery, useMutation } from '@sylphx/lens-react';
  *
  * function UserProfile({ userId }: { userId: string }) {
- *   const client = useLensClient();
- *   const { data: user, loading } = useQuery(client.user.get({ id: userId }));
+ *   // Client is automatically injected from context
+ *   const { data: user, loading } = useQuery(
+ *     (client) => client.user.get,
+ *     { id: userId }
+ *   );
  *   if (loading) return <Spinner />;
  *   return <h1>{user?.name}</h1>;
  * }
  *
  * function CreatePost() {
- *   const client = useLensClient();
- *   const { mutate, loading } = useMutation(client.post.create);
+ *   const { mutate, loading } = useMutation((client) => client.post.create);
  *   const handleCreate = () => mutate({ title: 'Hello' });
  *   return <button onClick={handleCreate} disabled={loading}>Create</button>;
  * }
  * ```
  */
 
-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 { LensClient, MutationResult, QueryResult } from "@sylphx/lens-client";
+import { type DependencyList, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useLensClient } from "./context.js";
 
 // =============================================================================
 // Types
@@ -69,75 +61,159 @@ 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;
 }
 
+/** Client type for callbacks */
+type Client = LensClient<any, any>;
+
+/** Route selector - callback that returns a route function */
+export type RouteSelector<TParams, TResult> = (
+	client: Client,
+) => ((params: TParams) => QueryResult<TResult>) | null;
+
+/** Query accessor selector - callback that returns QueryResult */
+export type QuerySelector<TResult> = (client: Client) => QueryResult<TResult> | null | undefined;
+
+/** Mutation selector - callback that returns mutation function */
+export type MutationSelector<TInput, TOutput> = (
+	client: Client,
+) => (input: TInput) => Promise<MutationResult<TOutput>>;
+
 // =============================================================================
 // useQuery Hook
 // =============================================================================
 
-/** 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.
+ * Client is automatically injected from LensProvider context.
  *
- * @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
- * @param options - Query options
+ * Two usage patterns:
+ *
+ * **1. Route + Params (recommended)** - Stable references, no infinite loops
+ * ```tsx
+ * const { data } = useQuery((client) => client.user.get, { id: userId });
+ * ```
+ *
+ * **2. Accessor + Deps (escape hatch)** - For complex/composed queries
+ * ```tsx
+ * const { data } = useQuery((client) => client.user.get({ id }), [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) => 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 { data: name } = useQuery(
+ *     (client) => client.user.get,
+ *     { id: userId },
+ *     { select: (user) => user.name }
+ *   );
+ *   return <span>{name}</span>;
  * }
  *
- * // Conditional query (null when condition not met)
+ * // Conditional query (return null to skip)
  * function SessionInfo({ sessionId }: { sessionId: string | null }) {
- *   const client = useLensClient();
  *   const { data } = useQuery(
- *     sessionId ? client.session.get({ id: sessionId }) : null
+ *     (client) => 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> }) {
- *   const client = useLensClient();
- *   const { data } = useQuery(() =>
- *     sessionId.value ? client.session.get({ id: sessionId.value }) : null
+ * // Skip query with option
+ * function ConditionalQuery({ userId, shouldFetch }: { userId: string; shouldFetch: boolean }) {
+ *   const { data } = useQuery(
+ *     (client) => client.user.get,
+ *     { id: userId },
+ *     { skip: !shouldFetch }
  *   );
- *   return <span>{data?.totalTokens}</span>;
  * }
  *
- * // Skip query conditionally
- * function ConditionalQuery({ shouldFetch }: { shouldFetch: boolean }) {
- *   const client = useLensClient();
- *   const { data } = useQuery(client.user.list(), { skip: !shouldFetch });
+ * // Complex queries with accessor (escape hatch)
+ * function ComplexQuery({ userId }: { userId: string }) {
+ *   const { data } = useQuery(
+ *     (client) => 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>(
+	selector: RouteSelector<TParams, TResult>,
+	params: TParams,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseQueryResult<TSelected>;
+
+// Overload 2: Accessor + Deps (escape hatch for complex queries)
+export function useQuery<TResult, TSelected = TResult>(
+	selector: QuerySelector<TResult>,
+	deps: DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseQueryResult<TSelected>;
+
+// Implementation
+export function useQuery<TParams, TResult, TSelected = TResult>(
+	selector: RouteSelector<TParams, TResult> | QuerySelector<TResult>,
+	paramsOrDeps: TParams | DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseQueryResult<TSelected> {
+	const client = useLensClient();
+
+	// 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: selector returns QueryResult directly
+				const querySelector = selector as QuerySelector<TResult>;
+				return querySelector(client);
+			}
+			// Route + Params mode: selector returns route function
+			const routeSelector = selector as RouteSelector<TParams, TResult>;
+			const route = routeSelector(client);
+			if (!route) return null;
+			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
+				[client, options?.skip, ...(paramsOrDeps as DependencyList)]
+			: // eslint-disable-next-line react-hooks/exhaustive-deps
+				[client, selector, 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 +223,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);
@@ -162,19 +243,26 @@ export function useQuery<T>(
 		setLoading(true);
 		setError(null);
 
-		// Subscribe to updates
+		// Track if subscribe has provided data (to avoid duplicate updates from then)
+		let hasReceivedData = false;
+
+		// Subscribe to updates - primary data source for streaming
 		const unsubscribe = query.subscribe((value) => {
 			if (mountedRef.current) {
-				setData(value);
+				hasReceivedData = true;
+				setData(transform(value));
 				setLoading(false);
 			}
 		});
 
-		// Handle initial load via promise (for one-shot queries)
+		// Handle completion/error via promise
+		// Only setData if subscribe hasn't already provided data (one-shot queries)
 		query.then(
 			(value) => {
+				if (mountedRef.current && !hasReceivedData) {
+					setData(transform(value));
+				}
 				if (mountedRef.current) {
-					setData(value);
 					setLoading(false);
 				}
 			},
@@ -190,12 +278,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 +291,7 @@ export function useQuery<T>(
 		currentQuery.then(
 			(value) => {
 				if (mountedRef.current) {
-					setData(value);
+					setData(transform(value));
 					setLoading(false);
 				}
 			},
@@ -214,7 +302,7 @@ export function useQuery<T>(
 				}
 			},
 		);
-	}, [options?.skip]);
+	}, [transform]);
 
 	return { data, loading, error, refetch };
 }
@@ -223,19 +311,18 @@ 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
+ * Execute mutations with loading/error state.
+ * Client is automatically injected from LensProvider context.
  *
- * @param mutationFn - Mutation function from client API
+ * @param selector - Callback that returns mutation function from client
  *
  * @example
  * ```tsx
  * function CreatePost() {
- *   const client = useLensClient();
- *   const { mutate, loading, error, data } = useMutation(client.post.create);
+ *   const { mutate, loading, error, data } = useMutation(
+ *     (client) => client.post.create
+ *   );
  *
  *   const handleSubmit = async (formData: FormData) => {
  *     try {
@@ -261,8 +348,7 @@ export type MutationFn<TInput, TOutput> = (input: TInput) => Promise<MutationRes
  *
  * // With optimistic updates
  * function UpdatePost({ postId }: { postId: string }) {
- *   const client = useLensClient();
- *   const { mutate } = useMutation(client.post.update);
+ *   const { mutate } = useMutation((client) => client.post.update);
  *
  *   const handleUpdate = async (title: string) => {
  *     const result = await mutate({ id: postId, title });
@@ -272,8 +358,11 @@ export type MutationFn<TInput, TOutput> = (input: TInput) => Promise<MutationRes
  * ```
  */
 export function useMutation<TInput, TOutput>(
-	mutationFn: MutationFn<TInput, TOutput>,
+	selector: MutationSelector<TInput, TOutput>,
 ): UseMutationResult<TInput, TOutput> {
+	const client = useLensClient();
+	const mutationFn = selector(client);
+
 	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState<Error | null>(null);
 	const [data, setData] = useState<TOutput | null>(null);
@@ -281,6 +370,10 @@ export function useMutation<TInput, TOutput>(
 	// Track mounted state
 	const mountedRef = useRef(true);
 
+	// Store mutation ref for latest version
+	const mutationRef = useRef(mutationFn);
+	mutationRef.current = mutationFn;
+
 	useEffect(() => {
 		mountedRef.current = true;
 		return () => {
@@ -289,33 +382,30 @@ export function useMutation<TInput, TOutput>(
 	}, []);
 
 	// Mutation wrapper
-	const mutate = useCallback(
-		async (input: TInput): Promise<MutationResult<TOutput>> => {
-			setLoading(true);
-			setError(null);
+	const mutate = useCallback(async (input: TInput): Promise<MutationResult<TOutput>> => {
+		setLoading(true);
+		setError(null);
 
-			try {
-				const result = await mutationFn(input);
+		try {
+			const result = await mutationRef.current(input);
 
-				if (mountedRef.current) {
-					setData(result.data);
-				}
+			if (mountedRef.current) {
+				setData(result.data);
+			}
 
-				return result;
-			} catch (err) {
-				const mutationError = err instanceof Error ? err : new Error(String(err));
-				if (mountedRef.current) {
-					setError(mutationError);
-				}
-				throw mutationError;
-			} finally {
-				if (mountedRef.current) {
-					setLoading(false);
-				}
+			return result;
+		} catch (err) {
+			const mutationError = err instanceof Error ? err : new Error(String(err));
+			if (mountedRef.current) {
+				setError(mutationError);
 			}
-		},
-		[mutationFn],
-	);
+			throw mutationError;
+		} finally {
+			if (mountedRef.current) {
+				setLoading(false);
+			}
+		}
+	}, []);
 
 	// Reset function
 	const reset = useCallback(() => {
@@ -346,59 +436,80 @@ export interface UseLazyQueryResult<T> {
 }
 
 /**
- * Execute a query on demand (not on mount)
- *
- * @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
+ * Execute a query on demand (not on mount).
+ * Client is automatically injected from LensProvider context.
  *
  * @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) => 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> }) {
- *   const client = useLensClient();
- *   const { execute, data } = useLazyQuery(() =>
- *     sessionId.value ? client.session.get({ id: sessionId.value }) : null
+ * // Accessor pattern
+ * function LazyComplexQuery({ userId }: { userId: string }) {
+ *   const { execute, data } = useLazyQuery(
+ *     (client) => 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>(
+	selector: RouteSelector<TParams, TResult>,
+	params: TParams,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseLazyQueryResult<TSelected>;
+
+// Overload 2: Accessor + Deps
+export function useLazyQuery<TResult, TSelected = TResult>(
+	selector: QuerySelector<TResult>,
+	deps: DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseLazyQueryResult<TSelected>;
+
+// Implementation
+export function useLazyQuery<TParams, TResult, TSelected = TResult>(
+	selector: RouteSelector<TParams, TResult> | QuerySelector<TResult>,
+	paramsOrDeps: TParams | DependencyList,
+	options?: UseQueryOptions<TResult, TSelected>,
+): UseLazyQueryResult<TSelected> {
+	const client = useLensClient();
+
+	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 selectorRef = useRef(selector);
+	selectorRef.current = selector;
+
+	const paramsOrDepsRef = useRef(paramsOrDeps);
+	paramsOrDepsRef.current = paramsOrDeps;
+
+	const selectRef = useRef(options?.select);
+	selectRef.current = options?.select;
 
 	useEffect(() => {
 		mountedRef.current = true;
@@ -408,13 +519,24 @@ 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 querySelector = selectorRef.current as QuerySelector<TResult>;
+			query = querySelector(client);
+		} else {
+			const routeSelector = selectorRef.current as RouteSelector<TParams, TResult>;
+			const route = routeSelector(client);
+			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 +544,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 +564,7 @@ export function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T
 				setLoading(false);
 			}
 		}
-	}, []);
+	}, [client, isAccessorMode]);
 
 	// Reset function
 	const reset = useCallback(() => {

package/src/index.ts

@@ -16,16 +16,17 @@ export { LensProvider, type LensProviderProps, useLensClient } from "./context.j
 // =============================================================================
 
 export {
-	type MutationFn,
 	// Types
-	type QueryInput,
+	type MutationSelector,
+	type QuerySelector,
+	type RouteSelector,
 	type UseLazyQueryResult,
 	type UseMutationResult,
 	type UseQueryOptions,
 	type UseQueryResult,
+	// Query hooks
 	useLazyQuery,
 	// Mutation hook
 	useMutation,
-	// Query hooks
 	useQuery,
 } from "./hooks.js";