@sylphx/lens-react 1.2.22 → 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": "1.2.22",
+	"version": "2.0.2",
 	"description": "React bindings for Lens API framework",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -30,7 +30,7 @@
 	"author": "SylphxAI",
 	"license": "MIT",
 	"dependencies": {
-		"@sylphx/lens-client": "^1.15.3"
+		"@sylphx/lens-client": "^2.0.1"
 	},
 	"peerDependencies": {
 		"react": ">=18.0.0"