@sylphx/lens-react 2.3.3 → 2.4.0

package/dist/index.d.ts

@@ -1,13 +1,35 @@
 import { LensClientConfig, QueryResult, SelectionObject, TypedClientConfig } from "@sylphx/lens-client";
 import { MutationDef, QueryDef, RouterDef, RouterRoutes } from "@sylphx/lens-core";
+/**
+* Debug callbacks for query hooks.
+* @internal For debugging purposes only - not recommended for production use.
+*/
+interface QueryDebugOptions<T> {
+	/** Called when data is received */
+	onData?: (data: T) => void;
+	/** Called when an error occurs */
+	onError?: (error: Error) => void;
+	/** Called when subscription starts */
+	onSubscribe?: () => void;
+	/** Called when subscription ends */
+	onUnsubscribe?: () => void;
+}
 /** Query hook options */
-interface QueryHookOptions<TInput> {
+interface QueryHookOptions<
+	TInput,
+	TOutput = unknown
+> {
 	/** Query input parameters */
 	input?: TInput;
 	/** Field selection */
 	select?: SelectionObject;
 	/** Skip query execution */
 	skip?: boolean;
+	/**
+	* Debug callbacks for development.
+	* @internal For debugging purposes only - not recommended for production use.
+	*/
+	debug?: QueryDebugOptions<TOutput>;
 }
 /** Query hook result */
 interface QueryHookResult<T> {
@@ -59,7 +81,7 @@ interface QueryEndpoint<
 		select?: SelectionObject;
 	}): QueryResult<TOutput>;
 	/** React hook for reactive queries */
-	useQuery: (options?: TInput extends void ? QueryHookOptions<void> | void : QueryHookOptions<TInput>) => QueryHookResult<TOutput>;
+	useQuery: (options?: TInput extends void ? QueryHookOptions<void, TOutput> | void : QueryHookOptions<TInput, TOutput>) => QueryHookResult<TOutput>;
 }
 /** Mutation endpoint with React hooks */
 interface MutationEndpoint<

package/dist/index.js

@@ -21,12 +21,16 @@ function queryReducer(state, action) {
 }
 function createUseQueryHook(getEndpoint) {
   return function useQuery(options) {
+    const inputKey = JSON.stringify(options?.input);
+    const selectKey = JSON.stringify(options?.select);
+    const debugRef = useRef(options?.debug);
+    debugRef.current = options?.debug;
     const query = useMemo(() => {
       if (options?.skip)
         return null;
       const endpoint = getEndpoint();
       return endpoint({ input: options?.input, select: options?.select });
-    }, [options?.input, options?.select, options?.skip, getEndpoint]);
+    }, [inputKey, selectKey, options?.skip]);
     const initialState = {
       data: null,
       loading: query != null && !options?.skip,
@@ -43,32 +47,35 @@ function createUseQueryHook(getEndpoint) {
         return;
       }
       dispatch({ type: "START" });
+      debugRef.current?.onSubscribe?.();
       let hasReceivedData = false;
       const unsubscribe = query.subscribe((value) => {
         if (mountedRef.current) {
           hasReceivedData = true;
           dispatch({ type: "SUCCESS", data: value });
+          debugRef.current?.onData?.(value);
         }
       });
       query.then((value) => {
         if (mountedRef.current) {
           if (!hasReceivedData) {
             dispatch({ type: "SUCCESS", data: value });
+            debugRef.current?.onData?.(value);
           } else {
             dispatch({ type: "LOADING_DONE" });
           }
         }
       }, (err) => {
         if (mountedRef.current) {
-          dispatch({
-            type: "ERROR",
-            error: err instanceof Error ? err : new Error(String(err))
-          });
+          const error = err instanceof Error ? err : new Error(String(err));
+          dispatch({ type: "ERROR", error });
+          debugRef.current?.onError?.(error);
         }
       });
       return () => {
         mountedRef.current = false;
         unsubscribe();
+        debugRef.current?.onUnsubscribe?.();
       };
     }, [query]);
     const refetch = useCallback(() => {

package/package.json

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

package/src/create.tsx

@@ -39,14 +39,34 @@ import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "r
 // Types
 // =============================================================================
 
+/**
+ * Debug callbacks for query hooks.
+ * @internal For debugging purposes only - not recommended for production use.
+ */
+export interface QueryDebugOptions<T> {
+	/** Called when data is received */
+	onData?: (data: T) => void;
+	/** Called when an error occurs */
+	onError?: (error: Error) => void;
+	/** Called when subscription starts */
+	onSubscribe?: () => void;
+	/** Called when subscription ends */
+	onUnsubscribe?: () => void;
+}
+
 /** Query hook options */
-export interface QueryHookOptions<TInput> {
+export interface QueryHookOptions<TInput, TOutput = unknown> {
 	/** Query input parameters */
 	input?: TInput;
 	/** Field selection */
 	select?: SelectionObject;
 	/** Skip query execution */
 	skip?: boolean;
+	/**
+	 * Debug callbacks for development.
+	 * @internal For debugging purposes only - not recommended for production use.
+	 */
+	debug?: QueryDebugOptions<TOutput>;
 }
 
 /** Query hook result */
@@ -92,7 +112,9 @@ export interface QueryEndpoint<TInput, TOutput> {
 
 	/** React hook for reactive queries */
 	useQuery: (
-		options?: TInput extends void ? QueryHookOptions<void> | void : QueryHookOptions<TInput>,
+		options?: TInput extends void
+			? QueryHookOptions<void, TOutput> | void
+			: QueryHookOptions<TInput, TOutput>,
 	) => QueryHookResult<TOutput>;
 }
 
@@ -164,13 +186,23 @@ function queryReducer<T>(state: QueryState<T>, action: QueryAction<T>): QuerySta
 function createUseQueryHook<TInput, TOutput>(
 	getEndpoint: () => (options: unknown) => QueryResult<TOutput>,
 ) {
-	return function useQuery(options?: QueryHookOptions<TInput>): QueryHookResult<TOutput> {
+	return function useQuery(options?: QueryHookOptions<TInput, TOutput>): QueryHookResult<TOutput> {
+		// Use JSON.stringify for stable dependency comparison
+		// This prevents re-fetching when input object reference changes but content is the same
+		const inputKey = JSON.stringify(options?.input);
+		const selectKey = JSON.stringify(options?.select);
+
+		// Store debug callbacks in ref to avoid dependency issues
+		const debugRef = useRef(options?.debug);
+		debugRef.current = options?.debug;
+
 		// Get query result from base client
+		// biome-ignore lint/correctness/useExhaustiveDependencies: Using JSON.stringify keys (inputKey, selectKey) for stable comparison instead of object references
 		const query = useMemo(() => {
 			if (options?.skip) return null;
 			const endpoint = getEndpoint();
 			return endpoint({ input: options?.input, select: options?.select });
-		}, [options?.input, options?.select, options?.skip, getEndpoint]);
+		}, [inputKey, selectKey, options?.skip]);
 
 		// State management
 		const initialState: QueryState<TOutput> = {
@@ -195,6 +227,7 @@ function createUseQueryHook<TInput, TOutput>(
 			}
 
 			dispatch({ type: "START" });
+			debugRef.current?.onSubscribe?.();
 
 			let hasReceivedData = false;
 
@@ -202,6 +235,7 @@ function createUseQueryHook<TInput, TOutput>(
 				if (mountedRef.current) {
 					hasReceivedData = true;
 					dispatch({ type: "SUCCESS", data: value });
+					debugRef.current?.onData?.(value);
 				}
 			});
 
@@ -210,6 +244,7 @@ function createUseQueryHook<TInput, TOutput>(
 					if (mountedRef.current) {
 						if (!hasReceivedData) {
 							dispatch({ type: "SUCCESS", data: value });
+							debugRef.current?.onData?.(value);
 						} else {
 							dispatch({ type: "LOADING_DONE" });
 						}
@@ -217,10 +252,9 @@ function createUseQueryHook<TInput, TOutput>(
 				},
 				(err) => {
 					if (mountedRef.current) {
-						dispatch({
-							type: "ERROR",
-							error: err instanceof Error ? err : new Error(String(err)),
-						});
+						const error = err instanceof Error ? err : new Error(String(err));
+						dispatch({ type: "ERROR", error });
+						debugRef.current?.onError?.(error);
 					}
 				},
 			);
@@ -228,6 +262,7 @@ function createUseQueryHook<TInput, TOutput>(
 			return () => {
 				mountedRef.current = false;
 				unsubscribe();
+				debugRef.current?.onUnsubscribe?.();
 			};
 		}, [query]);