@trackunit/react-graphql-hooks 1.7.12 → 1.7.13

package/index.cjs.js

@@ -4,9 +4,9 @@ require('react/jsx-runtime');
 var i18nLibraryTranslation = require('@trackunit/i18n-library-translation');
 var sharedUtils = require('@trackunit/shared-utils');
 var ApolloClient = require('@apollo/client');
+var react = require('react');
 var reactTablePagination = require('@trackunit/react-table-pagination');
 var esToolkit = require('es-toolkit');
-var react = require('react');
 
 function _interopNamespaceDefault(e) {
   var n = Object.create(null);
@@ -92,6 +92,59 @@ const unionEdgesByNodeKey = (key, previousEdges, newEdges) => {
         .filter(sharedUtils.truthy);
 };
 
+/**
+ * A wrapper around Apollo Client's useLazyQuery that provides stable data by default.
+ *
+ * This hook prevents UI flickering during refetches by returning the previous data
+ * when new data is loading, unless stableData is set to false.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with stable data and polling loading (both are defaults)
+ * const [executeQuery, { data, loading, error }] = useLazyQuery(GetAssetsDocument);
+ *
+ * // Execute with polling - loading will be true during polls by default
+ * executeQuery({ variables: { first: 10 }, pollInterval: 5000 });
+ *
+ * // Disable loading indicator during polling
+ * const [executeQuery, { data, loading, error }] = useLazyQuery(GetAssetsDocument, {
+ *   showLoadingDuringPolling: false, // loading will NOT be true during polls
+ * });
+ * ```
+ * @template TData The type of data returned by the query
+ * @template TVariables The type of variables accepted by the query
+ * @param document The GraphQL document (query)
+ * @param options The lazy query options including stableData and showLoadingDuringPolling flags
+ * @returns {Array} A tuple with the execute function and query result with stable data behavior and optional polling loading state
+ */
+const useLazyQuery = (document, options = {}) => {
+    const { stableData = true, showLoadingDuringPolling = true, ...apolloOptions } = options;
+    // Enable network status notifications when we want to show loading during polling
+    const apolloOptionsWithNotify = react.useMemo(() => ({
+        ...apolloOptions,
+        notifyOnNetworkStatusChange: showLoadingDuringPolling || apolloOptions.notifyOnNetworkStatusChange,
+    }), [apolloOptions, showLoadingDuringPolling]);
+    const [executeQuery, result] = ApolloClient__namespace.useLazyQuery(document, apolloOptionsWithNotify);
+    const enhancedResult = react.useMemo(() => {
+        const baseResult = stableData
+            ? {
+                ...result,
+                data: result.data ?? result.previousData,
+            }
+            : result;
+        // If showLoadingDuringPolling is enabled, check for polling network status
+        if (showLoadingDuringPolling) {
+            const isPolling = result.networkStatus === ApolloClient__namespace.NetworkStatus.poll;
+            return {
+                ...baseResult,
+                loading: baseResult.loading || isPolling,
+            };
+        }
+        return baseResult;
+    }, [result, stableData, showLoadingDuringPolling]);
+    return [executeQuery, enhancedResult];
+};
+
 /**
  * This hook is used to fetch data from a GraphQL query and support pagination, it will help maintain the data and the pagination.
  *
@@ -167,7 +220,7 @@ const usePaginationQuery = (document, { ...props }) => {
             variables: stableVariables,
         };
     }, [props, stableVariables]);
-    const [, { fetchMore, networkStatus }] = ApolloClient__namespace.useLazyQuery(document, {
+    const [, { previousData, fetchMore, networkStatus, loading: lazyLoading }] = useLazyQuery(document, {
         ...internalProps,
         context: {
             ...internalProps.context,
@@ -176,12 +229,16 @@ const usePaginationQuery = (document, { ...props }) => {
                 signal: abortController.signal,
             },
         },
+        pollInterval: internalProps.pollInterval,
         notifyOnNetworkStatusChange: true, // Needed to update networkStatus
-        onCompleted: () => {
+        onCompleted: completedData => {
             if (networkStatus === ApolloClient__namespace.NetworkStatus.refetch) {
                 // trigger reset for refetchQueries for the provided document.
                 setResetTrigger(prev => prev + 1);
             }
+            if (internalProps.onCompleted) {
+                internalProps.onCompleted(completedData);
+            }
         },
         // This is safe since we have no cache
         // and without it it will make a magic extra call to the query check this
@@ -209,11 +266,10 @@ const usePaginationQuery = (document, { ...props }) => {
         const fetchMoreVariables = {
             ...internalProps.variables,
             ...(internalProps.variables && "page" in internalProps.variables && "pageSize" in internalProps.variables
-                ?
-                    {
-                        pageSize: variables.first,
-                        page: Number(variables.after) || 0,
-                    }
+                ? {
+                    pageSize: variables.first,
+                    page: Number(variables.after) || 0,
+                }
                 : { ...variables }),
         };
         fetchMore({
@@ -304,13 +360,80 @@ const usePaginationQuery = (document, { ...props }) => {
     }, [after]);
     return react.useMemo(() => {
         return {
-            data,
-            loading: isLoading,
+            data: data || previousData,
+            previousData,
+            loading: isLoading || lazyLoading,
             pagination: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage },
             lastFetchedData,
             reset,
         };
-    }, [data, isLoading, setIsLoading, setPageInfo, pageInfo, reset, nextPage, previousPage, lastFetchedData]);
+    }, [
+        data,
+        isLoading,
+        lazyLoading,
+        setIsLoading,
+        setPageInfo,
+        pageInfo,
+        reset,
+        nextPage,
+        previousPage,
+        lastFetchedData,
+        previousData,
+    ]);
+};
+
+/**
+ * A wrapper around Apollo Client's useQuery that provides stable data by default.
+ *
+ * This hook prevents UI flickering during refetches by returning the previous data
+ * when new data is loading, unless stableData is set to false.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with stable data and polling loading (both are defaults)
+ * const { data, loading, error } = useQuery(GetAssetsDocument, {
+ *   variables: { first: 10 },
+ *   pollInterval: 5000,
+ * });
+ *
+ * // Disable loading indicator during polling
+ * const { data, loading, error } = useQuery(GetAssetsDocument, {
+ *   variables: { first: 10 },
+ *   pollInterval: 5000,
+ *   showLoadingDuringPolling: false, // loading will NOT be true during polls
+ * });
+ * ```
+ * @template TData The type of data returned by the query
+ * @template TVariables The type of variables accepted by the query
+ * @param document The GraphQL document (query)
+ * @param options The query options including stableData and showLoadingDuringPolling flags
+ * @returns {object} The query result with stable data behavior and optional polling loading state
+ */
+const useQuery = (document, options = {}) => {
+    const { stableData = true, showLoadingDuringPolling = true, ...apolloOptions } = options;
+    // Enable network status notifications when we want to show loading during polling
+    const apolloOptionsWithNotify = react.useMemo(() => ({
+        ...apolloOptions,
+        notifyOnNetworkStatusChange: showLoadingDuringPolling || apolloOptions.notifyOnNetworkStatusChange,
+    }), [apolloOptions, showLoadingDuringPolling]);
+    const result = ApolloClient__namespace.useQuery(document, apolloOptionsWithNotify);
+    return react.useMemo(() => {
+        const baseResult = stableData
+            ? {
+                ...result,
+                data: result.data ?? result.previousData,
+            }
+            : result;
+        // If showLoadingDuringPolling is enabled, check for polling network status
+        if (showLoadingDuringPolling) {
+            const isPolling = result.networkStatus === ApolloClient__namespace.NetworkStatus.poll;
+            return {
+                ...baseResult,
+                loading: baseResult.loading || isPolling,
+            };
+        }
+        return baseResult;
+    }, [result, stableData, showLoadingDuringPolling]);
 };
 
 /*
@@ -323,4 +446,6 @@ const usePaginationQuery = (document, { ...props }) => {
 setupLibraryTranslations();
 
 exports.unionEdgesByNodeKey = unionEdgesByNodeKey;
+exports.useLazyQuery = useLazyQuery;
 exports.usePaginationQuery = usePaginationQuery;
+exports.useQuery = useQuery;

package/index.esm.js

@@ -2,9 +2,9 @@ import 'react/jsx-runtime';
 import { registerTranslations } from '@trackunit/i18n-library-translation';
 import { truthy, objectKeys } from '@trackunit/shared-utils';
 import * as ApolloClient from '@apollo/client';
+import { useMemo, useState, useRef, useEffect, useCallback } from 'react';
 import { useRelayPagination, defaultPageSize } from '@trackunit/react-table-pagination';
 import { isEqual } from 'es-toolkit';
-import { useState, useRef, useEffect, useMemo, useCallback } from 'react';
 
 var defaultTranslations = {
 	
@@ -71,6 +71,59 @@ const unionEdgesByNodeKey = (key, previousEdges, newEdges) => {
         .filter(truthy);
 };
 
+/**
+ * A wrapper around Apollo Client's useLazyQuery that provides stable data by default.
+ *
+ * This hook prevents UI flickering during refetches by returning the previous data
+ * when new data is loading, unless stableData is set to false.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with stable data and polling loading (both are defaults)
+ * const [executeQuery, { data, loading, error }] = useLazyQuery(GetAssetsDocument);
+ *
+ * // Execute with polling - loading will be true during polls by default
+ * executeQuery({ variables: { first: 10 }, pollInterval: 5000 });
+ *
+ * // Disable loading indicator during polling
+ * const [executeQuery, { data, loading, error }] = useLazyQuery(GetAssetsDocument, {
+ *   showLoadingDuringPolling: false, // loading will NOT be true during polls
+ * });
+ * ```
+ * @template TData The type of data returned by the query
+ * @template TVariables The type of variables accepted by the query
+ * @param document The GraphQL document (query)
+ * @param options The lazy query options including stableData and showLoadingDuringPolling flags
+ * @returns {Array} A tuple with the execute function and query result with stable data behavior and optional polling loading state
+ */
+const useLazyQuery = (document, options = {}) => {
+    const { stableData = true, showLoadingDuringPolling = true, ...apolloOptions } = options;
+    // Enable network status notifications when we want to show loading during polling
+    const apolloOptionsWithNotify = useMemo(() => ({
+        ...apolloOptions,
+        notifyOnNetworkStatusChange: showLoadingDuringPolling || apolloOptions.notifyOnNetworkStatusChange,
+    }), [apolloOptions, showLoadingDuringPolling]);
+    const [executeQuery, result] = ApolloClient.useLazyQuery(document, apolloOptionsWithNotify);
+    const enhancedResult = useMemo(() => {
+        const baseResult = stableData
+            ? {
+                ...result,
+                data: result.data ?? result.previousData,
+            }
+            : result;
+        // If showLoadingDuringPolling is enabled, check for polling network status
+        if (showLoadingDuringPolling) {
+            const isPolling = result.networkStatus === ApolloClient.NetworkStatus.poll;
+            return {
+                ...baseResult,
+                loading: baseResult.loading || isPolling,
+            };
+        }
+        return baseResult;
+    }, [result, stableData, showLoadingDuringPolling]);
+    return [executeQuery, enhancedResult];
+};
+
 /**
  * This hook is used to fetch data from a GraphQL query and support pagination, it will help maintain the data and the pagination.
  *
@@ -146,7 +199,7 @@ const usePaginationQuery = (document, { ...props }) => {
             variables: stableVariables,
         };
     }, [props, stableVariables]);
-    const [, { fetchMore, networkStatus }] = ApolloClient.useLazyQuery(document, {
+    const [, { previousData, fetchMore, networkStatus, loading: lazyLoading }] = useLazyQuery(document, {
         ...internalProps,
         context: {
             ...internalProps.context,
@@ -155,12 +208,16 @@ const usePaginationQuery = (document, { ...props }) => {
                 signal: abortController.signal,
             },
         },
+        pollInterval: internalProps.pollInterval,
         notifyOnNetworkStatusChange: true, // Needed to update networkStatus
-        onCompleted: () => {
+        onCompleted: completedData => {
             if (networkStatus === ApolloClient.NetworkStatus.refetch) {
                 // trigger reset for refetchQueries for the provided document.
                 setResetTrigger(prev => prev + 1);
             }
+            if (internalProps.onCompleted) {
+                internalProps.onCompleted(completedData);
+            }
         },
         // This is safe since we have no cache
         // and without it it will make a magic extra call to the query check this
@@ -188,11 +245,10 @@ const usePaginationQuery = (document, { ...props }) => {
         const fetchMoreVariables = {
             ...internalProps.variables,
             ...(internalProps.variables && "page" in internalProps.variables && "pageSize" in internalProps.variables
-                ?
-                    {
-                        pageSize: variables.first,
-                        page: Number(variables.after) || 0,
-                    }
+                ? {
+                    pageSize: variables.first,
+                    page: Number(variables.after) || 0,
+                }
                 : { ...variables }),
         };
         fetchMore({
@@ -283,13 +339,80 @@ const usePaginationQuery = (document, { ...props }) => {
     }, [after]);
     return useMemo(() => {
         return {
-            data,
-            loading: isLoading,
+            data: data || previousData,
+            previousData,
+            loading: isLoading || lazyLoading,
             pagination: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage },
             lastFetchedData,
             reset,
         };
-    }, [data, isLoading, setIsLoading, setPageInfo, pageInfo, reset, nextPage, previousPage, lastFetchedData]);
+    }, [
+        data,
+        isLoading,
+        lazyLoading,
+        setIsLoading,
+        setPageInfo,
+        pageInfo,
+        reset,
+        nextPage,
+        previousPage,
+        lastFetchedData,
+        previousData,
+    ]);
+};
+
+/**
+ * A wrapper around Apollo Client's useQuery that provides stable data by default.
+ *
+ * This hook prevents UI flickering during refetches by returning the previous data
+ * when new data is loading, unless stableData is set to false.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with stable data and polling loading (both are defaults)
+ * const { data, loading, error } = useQuery(GetAssetsDocument, {
+ *   variables: { first: 10 },
+ *   pollInterval: 5000,
+ * });
+ *
+ * // Disable loading indicator during polling
+ * const { data, loading, error } = useQuery(GetAssetsDocument, {
+ *   variables: { first: 10 },
+ *   pollInterval: 5000,
+ *   showLoadingDuringPolling: false, // loading will NOT be true during polls
+ * });
+ * ```
+ * @template TData The type of data returned by the query
+ * @template TVariables The type of variables accepted by the query
+ * @param document The GraphQL document (query)
+ * @param options The query options including stableData and showLoadingDuringPolling flags
+ * @returns {object} The query result with stable data behavior and optional polling loading state
+ */
+const useQuery = (document, options = {}) => {
+    const { stableData = true, showLoadingDuringPolling = true, ...apolloOptions } = options;
+    // Enable network status notifications when we want to show loading during polling
+    const apolloOptionsWithNotify = useMemo(() => ({
+        ...apolloOptions,
+        notifyOnNetworkStatusChange: showLoadingDuringPolling || apolloOptions.notifyOnNetworkStatusChange,
+    }), [apolloOptions, showLoadingDuringPolling]);
+    const result = ApolloClient.useQuery(document, apolloOptionsWithNotify);
+    return useMemo(() => {
+        const baseResult = stableData
+            ? {
+                ...result,
+                data: result.data ?? result.previousData,
+            }
+            : result;
+        // If showLoadingDuringPolling is enabled, check for polling network status
+        if (showLoadingDuringPolling) {
+            const isPolling = result.networkStatus === ApolloClient.NetworkStatus.poll;
+            return {
+                ...baseResult,
+                loading: baseResult.loading || isPolling,
+            };
+        }
+        return baseResult;
+    }, [result, stableData, showLoadingDuringPolling]);
 };
 
 /*
@@ -301,4 +424,4 @@ const usePaginationQuery = (document, { ...props }) => {
  */
 setupLibraryTranslations();
 
-export { unionEdgesByNodeKey, usePaginationQuery };
+export { unionEdgesByNodeKey, useLazyQuery, usePaginationQuery, useQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-graphql-hooks",
-  "version": "1.7.12",
+  "version": "1.7.13",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -9,10 +9,10 @@
   "dependencies": {
     "@apollo/client": "3.13.8",
     "react": "19.0.0",
-    "@trackunit/i18n-library-translation": "1.7.10",
-    "@trackunit/shared-utils": "1.9.7",
-    "@trackunit/react-table-pagination": "1.7.7",
-    "@trackunit/react-test-setup": "1.4.7",
+    "@trackunit/i18n-library-translation": "1.7.11",
+    "@trackunit/shared-utils": "1.9.8",
+    "@trackunit/react-table-pagination": "1.7.8",
+    "@trackunit/react-test-setup": "1.4.8",
     "es-toolkit": "^1.39.10"
   },
   "module": "./index.esm.js",

package/src/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./unionEdgesByNodeKey";
+export * from "./useLazyQuery";
 export * from "./usePaginationQuery";
+export * from "./useQuery";

package/src/translation.d.ts

@@ -12,7 +12,9 @@ export declare const namespace = "react.graphql-hooks";
  */
 export declare const translations: TranslationResource<TranslationKeys>;
 /**
- *  Local useTranslation for this specific library
+ * Local useTranslation for this specific library
+ *
+ * @returns {object} The translation function for this specific library
  */
 export declare const useTranslation: () => [TransForLibs<never>, import("i18next").i18n, boolean] & {
     t: TransForLibs<never>;
@@ -25,6 +27,9 @@ export declare const useTranslation: () => [TransForLibs<never>, import("i18next
 export type TranslationFunction = TransForLibs<TranslationKeys>;
 /**
  * Trans for this specific library.
+ *
+ * @param {object} props The props for the Trans component
+ * @returns {object} The Trans component
  */
 export declare const Trans: (props: NamespaceTransProps<TranslationKeys>) => import("react/jsx-runtime").JSX.Element;
 /**

package/src/useLazyQuery.d.ts

@@ -0,0 +1,45 @@
+import * as ApolloClient from "@apollo/client";
+type TypedDocumentNode<TData, TVariables> = ApolloClient.TypedDocumentNode<TData, TVariables>;
+export interface LazyQueryProps<TData, TVariables extends ApolloClient.OperationVariables = ApolloClient.OperationVariables> extends ApolloClient.LazyQueryHookOptions<TData, TVariables> {
+    /**
+     * A boolean value that specifies whether to return stable data (data || previousData).
+     * When true, the hook will return the current data if available, otherwise the previous data.
+     * This prevents UI flickering during refetches by maintaining the last known data.
+     * Defaults to true.
+     */
+    stableData?: boolean;
+    /**
+     * A boolean value that specifies whether the loading state should be true during polling.
+     * When true, loading will be true during poll requests (requires notifyOnNetworkStatusChange: true).
+     * This allows you to show loading indicators during background polling.
+     * Defaults to true.
+     */
+    showLoadingDuringPolling?: boolean;
+}
+/**
+ * A wrapper around Apollo Client's useLazyQuery that provides stable data by default.
+ *
+ * This hook prevents UI flickering during refetches by returning the previous data
+ * when new data is loading, unless stableData is set to false.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with stable data and polling loading (both are defaults)
+ * const [executeQuery, { data, loading, error }] = useLazyQuery(GetAssetsDocument);
+ *
+ * // Execute with polling - loading will be true during polls by default
+ * executeQuery({ variables: { first: 10 }, pollInterval: 5000 });
+ *
+ * // Disable loading indicator during polling
+ * const [executeQuery, { data, loading, error }] = useLazyQuery(GetAssetsDocument, {
+ *   showLoadingDuringPolling: false, // loading will NOT be true during polls
+ * });
+ * ```
+ * @template TData The type of data returned by the query
+ * @template TVariables The type of variables accepted by the query
+ * @param document The GraphQL document (query)
+ * @param options The lazy query options including stableData and showLoadingDuringPolling flags
+ * @returns {Array} A tuple with the execute function and query result with stable data behavior and optional polling loading state
+ */
+export declare const useLazyQuery: <TData, TVariables extends ApolloClient.OperationVariables>(document: TypedDocumentNode<TData, TVariables>, options?: LazyQueryProps<TData, TVariables>) => [ApolloClient.LazyQueryExecFunction<TData, TVariables>, ApolloClient.LazyQueryResult<TData, TVariables>];
+export {};

package/src/usePaginationQuery.d.ts

@@ -8,6 +8,7 @@ export type PaginationQuery<TData> = {
     loading: boolean;
     lastFetchedData?: TData;
     pagination: RelayTableSupport;
+    previousData: TData | undefined;
     reset: () => void;
 };
 type TypedDocumentNode<TData, TVariables> = ApolloClient.TypedDocumentNode<TData, TVariables>;

package/src/useQuery.d.ts

@@ -0,0 +1,47 @@
+import * as ApolloClient from "@apollo/client";
+type TypedDocumentNode<TData, TVariables> = ApolloClient.TypedDocumentNode<TData, TVariables>;
+export interface QueryProps<TData, TVariables extends ApolloClient.OperationVariables = ApolloClient.OperationVariables> extends ApolloClient.QueryHookOptions<TData, TVariables> {
+    /**
+     * A boolean value that specifies whether to return stable data (data || previousData).
+     * When true, the hook will return the current data if available, otherwise the previous data.
+     * This prevents UI flickering during refetches by maintaining the last known data.
+     * Defaults to true.
+     */
+    stableData?: boolean;
+    /**
+     * A boolean value that specifies whether the loading state should be true during polling.
+     * When true, loading will be true during poll requests (requires notifyOnNetworkStatusChange: true).
+     * This allows you to show loading indicators during background polling.
+     * Defaults to true.
+     */
+    showLoadingDuringPolling?: boolean;
+}
+/**
+ * A wrapper around Apollo Client's useQuery that provides stable data by default.
+ *
+ * This hook prevents UI flickering during refetches by returning the previous data
+ * when new data is loading, unless stableData is set to false.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with stable data and polling loading (both are defaults)
+ * const { data, loading, error } = useQuery(GetAssetsDocument, {
+ *   variables: { first: 10 },
+ *   pollInterval: 5000,
+ * });
+ *
+ * // Disable loading indicator during polling
+ * const { data, loading, error } = useQuery(GetAssetsDocument, {
+ *   variables: { first: 10 },
+ *   pollInterval: 5000,
+ *   showLoadingDuringPolling: false, // loading will NOT be true during polls
+ * });
+ * ```
+ * @template TData The type of data returned by the query
+ * @template TVariables The type of variables accepted by the query
+ * @param document The GraphQL document (query)
+ * @param options The query options including stableData and showLoadingDuringPolling flags
+ * @returns {object} The query result with stable data behavior and optional polling loading state
+ */
+export declare const useQuery: <TData, TVariables extends ApolloClient.OperationVariables>(document: TypedDocumentNode<TData, TVariables>, options?: QueryProps<TData, TVariables>) => ApolloClient.QueryResult<TData, TVariables>;
+export {};