@sylphx/lens-react 1.0.5 → 1.2.0

package/dist/index.d.ts

@@ -45,6 +45,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);
 /** Result of useQuery hook */
 interface UseQueryResult<T> {
 	/** Query data (null if loading or error) */
@@ -80,7 +82,7 @@ interface UseQueryOptions {
 /**
 * Subscribe to a query with reactive updates
 *
-* @param query - QueryResult from client API call
+* @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
 * @param options - Query options
 *
 * @example
@@ -97,14 +99,23 @@ interface UseQueryOptions {
 *   return <h1>{user.name}</h1>;
 * }
 *
-* // With select (type-safe field selection)
-* function UserName({ userId }: { userId: string }) {
+* // Conditional query (null when condition not met)
+* function SessionInfo({ sessionId }: { sessionId: string | null }) {
 *   const client = useLensClient();
 *   const { data } = useQuery(
-*     client.user.get({ id: userId }).select({ name: true })
+*     sessionId ? client.session.get({ id: sessionId }) : null
 *   );
-*   // data is { name: string } | null
-*   return <span>{data?.name}</span>;
+*   // 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
+*   );
+*   return <span>{data?.totalTokens}</span>;
 * }
 *
 * // Skip query conditionally
@@ -114,7 +125,7 @@ interface UseQueryOptions {
 * }
 * ```
 */
-declare function useQuery<T>(query: QueryResult<T>, options?: UseQueryOptions): UseQueryResult<T>;
+declare function useQuery<T>(queryInput: QueryInput<T>, options?: UseQueryOptions): UseQueryResult<T>;
 /** Mutation function type */
 type MutationFn<
 	TInput,
@@ -185,7 +196,7 @@ interface UseLazyQueryResult<T> {
 /**
 * Execute a query on demand (not on mount)
 *
-* @param query - QueryResult from client API call
+* @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
 *
 * @example
 * ```tsx
@@ -214,7 +225,16 @@ interface UseLazyQueryResult<T> {
 *     </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
+*   );
+*   return <button onClick={execute}>Load</button>;
+* }
 * ```
 */
-declare function useLazyQuery<T>(query: QueryResult<T>): UseLazyQueryResult<T>;
-export { useQuery, useMutation, useLensClient, useLazyQuery, UseQueryResult, UseQueryOptions, UseMutationResult, UseLazyQueryResult, MutationFn, LensProviderProps, LensProvider };
+declare function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T>;
+export { useQuery, useMutation, useLensClient, useLazyQuery, UseQueryResult, UseQueryOptions, UseMutationResult, UseLazyQueryResult, QueryInput, MutationFn, LensProviderProps, LensProvider };

package/dist/index.js

@@ -16,16 +16,24 @@ function useLensClient() {
   return client;
 }
 // src/hooks.ts
-import { useCallback, useEffect, useRef, useState } from "react";
-function useQuery(query, options) {
+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]);
   const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(!options?.skip);
+  const [loading, setLoading] = useState(!options?.skip && query != null);
   const [error, setError] = useState(null);
   const mountedRef = useRef(true);
+  const queryRef = useRef(query);
+  queryRef.current = query;
   useEffect(() => {
     mountedRef.current = true;
-    if (options?.skip) {
+    if (query == null || options?.skip) {
+      setData(null);
       setLoading(false);
+      setError(null);
       return;
     }
     setLoading(true);
@@ -53,11 +61,12 @@ function useQuery(query, options) {
     };
   }, [query, options?.skip]);
   const refetch = useCallback(() => {
-    if (options?.skip)
+    const currentQuery = queryRef.current;
+    if (currentQuery == null || options?.skip)
       return;
     setLoading(true);
     setError(null);
-    query.then((value) => {
+    currentQuery.then((value) => {
       if (mountedRef.current) {
         setData(value);
         setLoading(false);
@@ -68,7 +77,7 @@ function useQuery(query, options) {
         setLoading(false);
       }
     });
-  }, [query, options?.skip]);
+  }, [options?.skip]);
   return { data, loading, error, refetch };
 }
 function useMutation(mutationFn) {
@@ -110,11 +119,13 @@ function useMutation(mutationFn) {
   }, []);
   return { mutate, loading, error, data, reset };
 }
-function useLazyQuery(query) {
+function useLazyQuery(queryInput) {
   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;
   useEffect(() => {
     mountedRef.current = true;
     return () => {
@@ -122,6 +133,12 @@ function useLazyQuery(query) {
     };
   }, []);
   const execute = useCallback(async () => {
+    const query = resolveQuery(queryInputRef.current);
+    if (query == null) {
+      setData(null);
+      setLoading(false);
+      return null;
+    }
     setLoading(true);
     setError(null);
     try {
@@ -141,7 +158,7 @@ function useLazyQuery(query) {
         setLoading(false);
       }
     }
-  }, [query]);
+  }, []);
   const reset = useCallback(() => {
     setLoading(false);
     setError(null);

package/package.json

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

package/src/hooks.ts

@@ -25,7 +25,18 @@
  */
 
 import type { MutationResult, QueryResult } from "@sylphx/lens-client";
-import { useCallback, useEffect, useRef, useState } from "react";
+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);
 
 // =============================================================================
 // Types
@@ -67,10 +78,15 @@ export interface UseQueryOptions {
 // 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
  *
- * @param query - QueryResult from client API call
+ * @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
  * @param options - Query options
  *
  * @example
@@ -87,14 +103,23 @@ export interface UseQueryOptions {
  *   return <h1>{user.name}</h1>;
  * }
  *
- * // With select (type-safe field selection)
- * function UserName({ userId }: { userId: string }) {
+ * // Conditional query (null when condition not met)
+ * function SessionInfo({ sessionId }: { sessionId: string | null }) {
  *   const client = useLensClient();
  *   const { data } = useQuery(
- *     client.user.get({ id: userId }).select({ name: true })
+ *     sessionId ? client.session.get({ id: sessionId }) : null
  *   );
- *   // data is { name: string } | null
- *   return <span>{data?.name}</span>;
+ *   // 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
+ *   );
+ *   return <span>{data?.totalTokens}</span>;
  * }
  *
  * // Skip query conditionally
@@ -104,20 +129,30 @@ export interface UseQueryOptions {
  * }
  * ```
  */
-export function useQuery<T>(query: QueryResult<T>, options?: UseQueryOptions): UseQueryResult<T> {
+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);
+	const [loading, setLoading] = useState(!options?.skip && query != null);
 	const [error, setError] = useState<Error | null>(null);
 
 	// Track mounted state
 	const mountedRef = useRef(true);
 
+	// Store query ref for refetch
+	const queryRef = useRef(query);
+	queryRef.current = query;
+
 	// Subscribe to query
 	useEffect(() => {
 		mountedRef.current = true;
 
-		if (options?.skip) {
+		// Handle null/undefined query
+		if (query == null || options?.skip) {
+			setData(null);
 			setLoading(false);
+			setError(null);
 			return;
 		}
 
@@ -156,12 +191,13 @@ export function useQuery<T>(query: QueryResult<T>, options?: UseQueryOptions): U
 
 	// Refetch function
 	const refetch = useCallback(() => {
-		if (options?.skip) return;
+		const currentQuery = queryRef.current;
+		if (currentQuery == null || options?.skip) return;
 
 		setLoading(true);
 		setError(null);
 
-		query.then(
+		currentQuery.then(
 			(value) => {
 				if (mountedRef.current) {
 					setData(value);
@@ -175,7 +211,7 @@ export function useQuery<T>(query: QueryResult<T>, options?: UseQueryOptions): U
 				}
 			},
 		);
-	}, [query, options?.skip]);
+	}, [options?.skip]);
 
 	return { data, loading, error, refetch };
 }
@@ -309,7 +345,7 @@ export interface UseLazyQueryResult<T> {
 /**
  * Execute a query on demand (not on mount)
  *
- * @param query - QueryResult from client API call
+ * @param queryInput - QueryResult, null/undefined, or accessor function returning QueryResult
  *
  * @example
  * ```tsx
@@ -338,9 +374,18 @@ export interface UseLazyQueryResult<T> {
  *     </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
+ *   );
+ *   return <button onClick={execute}>Load</button>;
+ * }
  * ```
  */
-export function useLazyQuery<T>(query: QueryResult<T>): UseLazyQueryResult<T> {
+export function useLazyQuery<T>(queryInput: QueryInput<T>): UseLazyQueryResult<T> {
 	const [data, setData] = useState<T | null>(null);
 	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState<Error | null>(null);
@@ -348,6 +393,10 @@ export function useLazyQuery<T>(query: QueryResult<T>): UseLazyQueryResult<T> {
 	// Track mounted state
 	const mountedRef = useRef(true);
 
+	// Store queryInput ref for execute (so it uses latest value)
+	const queryInputRef = useRef(queryInput);
+	queryInputRef.current = queryInput;
+
 	useEffect(() => {
 		mountedRef.current = true;
 		return () => {
@@ -357,6 +406,14 @@ export function useLazyQuery<T>(query: QueryResult<T>): UseLazyQueryResult<T> {
 
 	// Execute function
 	const execute = useCallback(async (): Promise<T> => {
+		const query = resolveQuery(queryInputRef.current);
+
+		if (query == null) {
+			setData(null);
+			setLoading(false);
+			return null as T;
+		}
+
 		setLoading(true);
 		setError(null);
 
@@ -379,7 +436,7 @@ export function useLazyQuery<T>(query: QueryResult<T>): UseLazyQueryResult<T> {
 				setLoading(false);
 			}
 		}
-	}, [query]);
+	}, []);
 
 	// Reset function
 	const reset = useCallback(() => {

package/src/index.ts

@@ -22,6 +22,7 @@ export {
 	// Mutation hook
 	useMutation,
 	// Types
+	type QueryInput,
 	type UseQueryResult,
 	type UseLazyQueryResult,
 	type UseMutationResult,