@sylphx/lens-react 2.0.1 → 2.1.0

package/dist/index.d.ts

@@ -44,9 +44,8 @@ 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 { LensClient as LensClient2, MutationResult, QueryResult } from "@sylphx/lens-client";
+import { DependencyList } from "react";
 /** Result of useQuery hook */
 interface UseQueryResult<T> {
 	/** Query data (null if loading or error) */
@@ -75,72 +74,117 @@ 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;
 }
+/** Client type for callbacks */
+type Client = LensClient2<any, any>;
+/** Route selector - callback that returns a route function */
+type RouteSelector<
+	TParams,
+	TResult
+> = (client: Client) => ((params: TParams) => QueryResult<TResult>) | null;
+/** Query accessor selector - callback that returns QueryResult */
+type QuerySelector<TResult> = (client: Client) => QueryResult<TResult> | null | undefined;
+/** Mutation selector - callback that returns mutation function */
+type MutationSelector<
+	TInput,
+	TOutput
+> = (client: Client) => (input: TInput) => Promise<MutationResult<TOutput>>;
 /**
-* Subscribe to a query with reactive updates
+* Subscribe to a query with reactive updates.
+* Client is automatically injected from LensProvider context.
+*
+* Two usage patterns:
+*
+* **1. Route + Params (recommended)** - Stable references, no infinite loops
+* ```tsx
+* const { data } = useQuery((client) => client.user.get, { id: userId });
+* ```
 *
-* @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
-* @param options - Query options
+* **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]
+*   );
 * }
 * ```
 */
-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
+>(selector: RouteSelector<TParams, TResult>, params: TParams, options?: UseQueryOptions<TResult, TSelected>): UseQueryResult<TSelected>;
+declare function useQuery<
+	TResult,
+	TSelected = TResult
+>(selector: QuerySelector<TResult>, deps: DependencyList, options?: UseQueryOptions<TResult, TSelected>): UseQueryResult<TSelected>;
 /**
-* 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 {
@@ -166,8 +210,7 @@ type MutationFn<
 *
 * // 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 });
@@ -179,7 +222,7 @@ type MutationFn<
 declare function useMutation<
 	TInput,
 	TOutput
->(mutationFn: MutationFn<TInput, TOutput>): UseMutationResult<TInput, TOutput>;
+>(selector: MutationSelector<TInput, TOutput>): UseMutationResult<TInput, TOutput>;
 /** Result of useLazyQuery hook */
 interface UseLazyQueryResult<T> {
 	/** Execute the query */
@@ -194,47 +237,45 @@ interface UseLazyQueryResult<T> {
 	reset: () => void;
 }
 /**
-* 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>;
 * }
 * ```
 */
-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
+>(selector: RouteSelector<TParams, TResult>, params: TParams, options?: UseQueryOptions<TResult, TSelected>): UseLazyQueryResult<TSelected>;
+declare function useLazyQuery<
+	TResult,
+	TSelected = TResult
+>(selector: QuerySelector<TResult>, deps: DependencyList, options?: UseQueryOptions<TResult, TSelected>): UseLazyQueryResult<TSelected>;
+export { useQuery, useMutation, useLensClient, useLazyQuery, UseQueryResult, UseQueryOptions, UseMutationResult, UseLazyQueryResult, RouteSelector, QuerySelector, MutationSelector, LensProviderProps, LensProvider };

package/dist/index.js

@@ -17,20 +17,37 @@ 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(selector, paramsOrDeps, options) {
+  const client = useLensClient();
+  const isAccessorMode = Array.isArray(paramsOrDeps);
+  const paramsKey = !isAccessorMode ? JSON.stringify(paramsOrDeps) : null;
+  const query = useMemo(() => {
+    if (options?.skip)
+      return null;
+    if (isAccessorMode) {
+      const querySelector = selector;
+      return querySelector(client);
+    }
+    const routeSelector = selector;
+    const route = routeSelector(client);
+    if (!route)
+      return null;
+    return route(paramsOrDeps);
+  }, isAccessorMode ? [client, options?.skip, ...paramsOrDeps] : [client, selector, 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);
@@ -38,15 +55,19 @@ function useQuery(queryInput, options) {
     }
     setLoading(true);
     setError(null);
+    let hasReceivedData = false;
     const unsubscribe = query.subscribe((value) => {
       if (mountedRef.current) {
-        setData(value);
+        hasReceivedData = true;
+        setData(transform(value));
         setLoading(false);
       }
     });
     query.then((value) => {
+      if (mountedRef.current && !hasReceivedData) {
+        setData(transform(value));
+      }
       if (mountedRef.current) {
-        setData(value);
         setLoading(false);
       }
     }, (err) => {
@@ -59,16 +80,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,14 +98,18 @@ function useQuery(queryInput, options) {
         setLoading(false);
       }
     });
-  }, [options?.skip]);
+  }, [transform]);
   return { data, loading, error, refetch };
 }
-function useMutation(mutationFn) {
+function useMutation(selector) {
+  const client = useLensClient();
+  const mutationFn = selector(client);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState(null);
   const [data, setData] = useState(null);
   const mountedRef = useRef(true);
+  const mutationRef = useRef(mutationFn);
+  mutationRef.current = mutationFn;
   useEffect(() => {
     mountedRef.current = true;
     return () => {
@@ -95,7 +120,7 @@ function useMutation(mutationFn) {
     setLoading(true);
     setError(null);
     try {
-      const result = await mutationFn(input);
+      const result = await mutationRef.current(input);
       if (mountedRef.current) {
         setData(result.data);
       }
@@ -111,7 +136,7 @@ function useMutation(mutationFn) {
         setLoading(false);
       }
     }
-  }, [mutationFn]);
+  }, []);
   const reset = useCallback(() => {
     setLoading(false);
     setError(null);
@@ -119,13 +144,19 @@ function useMutation(mutationFn) {
   }, []);
   return { mutate, loading, error, data, reset };
 }
-function useLazyQuery(queryInput) {
+function useLazyQuery(selector, paramsOrDeps, options) {
+  const client = useLensClient();
   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 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;
     return () => {
@@ -133,7 +164,17 @@ function useLazyQuery(queryInput) {
     };
   }, []);
   const execute = useCallback(async () => {
-    const query = resolveQuery(queryInputRef.current);
+    let query;
+    if (isAccessorMode) {
+      const querySelector = selectorRef.current;
+      query = querySelector(client);
+    } else {
+      const routeSelector = selectorRef.current;
+      const route = routeSelector(client);
+      if (route) {
+        query = route(paramsOrDepsRef.current);
+      }
+    }
     if (query == null) {
       setData(null);
       setLoading(false);
@@ -143,10 +184,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 +200,7 @@ function useLazyQuery(queryInput) {
         setLoading(false);
       }
     }
-  }, []);
+  }, [client, 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.1.0",
 	"description": "React bindings for Lens API framework",
 	"type": "module",
 	"main": "./dist/index.js",