@trackunit/react-graphql-hooks 1.15.7 → 1.15.9

package/index.cjs.js

@@ -104,6 +104,32 @@ const useLazyQuery = (document, options) => {
     return react.useMemo(() => [executeQuery, enhancedResult], [executeQuery, enhancedResult]);
 };
 
+/**
+ * Creates a reducer function for managing pagination state.
+ * Handles data updates, reset, and reset trigger increments.
+ */
+const createPaginationReducer = () => {
+    return (state, action) => {
+        switch (action.type) {
+            case "SET_DATA": {
+                return { ...state, data: action.payload };
+            }
+            case "SET_LAST_FETCHED_DATA": {
+                return { ...state, lastFetchedData: action.payload };
+            }
+            case "RESET": {
+                return { ...state, data: undefined, lastFetchedData: undefined };
+            }
+            case "INCREMENT_RESET_TRIGGER": {
+                return { ...state, resetTrigger: state.resetTrigger + 1 };
+            }
+            default: {
+                throw new Error(`${action} is not a known action type`);
+            }
+        }
+    };
+};
+
 /**
  * Creates a union of two arrays of edges by a key on the node.
  *
@@ -144,13 +170,9 @@ const createDirectionAwareUnion = (direction) => {
  */
 const createUpdateQueryHandler = (params) => {
     return (_previousResult, { fetchMoreResult }) => {
-        // Handle aborted requests by returning previous data
         if (params.abortSignal.aborted) {
-            // If prev does not hold any data we don't want to return it,
-            // since it will make the cache output an error to the console.
             // https://github.com/apollographql/apollo-client/issues/8677
             if (params.prev !== undefined && params.prev !== null) {
-                // Type assertion required: Apollo's updateQuery expects its own result type
                 return sharedUtils.objectKeys(params.prev).length === 0
                     ? undefined
                     : params.prev;
@@ -178,30 +200,27 @@ const createUpdateQueryHandler = (params) => {
         return result.data;
     };
 };
+
 /**
- * Creates a reducer function for managing pagination state.
- * Handles data updates, reset, and reset trigger increments.
+ * Extracts declared variable names from a GraphQL document so the hook
+ * only injects relay pagination variables the query actually accepts.
+ *
+ * Finds the first OperationDefinition in the document regardless of
+ * position — this handles documents where fragment definitions appear
+ * before the query.
  */
-const createPaginationReducer = () => {
-    return (state, action) => {
-        switch (action.type) {
-            case "SET_DATA": {
-                return { ...state, data: action.payload };
-            }
-            case "SET_LAST_FETCHED_DATA": {
-                return { ...state, lastFetchedData: action.payload };
-            }
-            case "RESET": {
-                return { ...state, data: undefined, lastFetchedData: undefined };
-            }
-            case "INCREMENT_RESET_TRIGGER": {
-                return { ...state, resetTrigger: state.resetTrigger + 1 };
-            }
-            default: {
-                throw new Error(`${action} is not a known action type`);
-            }
+const useQueryVariableNames = (document) => {
+    return react.useMemo(() => {
+        const definition = document.definitions.find(def => def.kind === "OperationDefinition");
+        if (definition === undefined) {
+            return new Set();
         }
-    };
+        const varDefs = definition.variableDefinitions;
+        if (varDefs === undefined) {
+            return new Set();
+        }
+        return new Set(varDefs.map(v => v.variable.name.value));
+    }, [document]);
 };
 
 /**
@@ -220,23 +239,9 @@ const useStableVariablesWithAbort = (variables, skip = false) => {
             setAbortController(new AbortController());
         }
     }
-    return { stableVariables, abortController };
-};
-/**
- * Extracts declared variable names from a GraphQL document so the hook
- * only injects relay pagination variables the query actually accepts.
- */
-const getQueryVariableNames = (document) => {
-    const definition = document.definitions[0];
-    if (definition === undefined || definition.kind !== "OperationDefinition") {
-        return new Set();
-    }
-    const varDefs = definition.variableDefinitions;
-    if (varDefs === undefined) {
-        return new Set();
-    }
-    return new Set(varDefs.map(v => v.variable.name.value));
+    return react.useMemo(() => ({ stableVariables, abortController }), [stableVariables, abortController]);
 };
+
 /**
  * `usePaginationQuery` fetches data from a GraphQL query with Relay-style cursor pagination.
  * It manages page accumulation, loading state, and provides `pagination` controls (including `fetchNext`)
@@ -252,7 +257,8 @@ const getQueryVariableNames = (document) => {
  * ### When not to use
  * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from this library directly.
  *
- * @example
+ * @example basic usage
+ * ```tsx
  * const {
  *   data,
  *   loading,
@@ -275,6 +281,24 @@ const getQueryVariableNames = (document) => {
  *     return { data: newData, pageInfo: newData.assets.pageInfo };
  *   },
  * });
+ * ```
+ * @example pagination example with url sync
+ * ```tsx
+ * const { initialCursor, updateCursor } = useCursorUrlSync({ paramName: "myTableCursor" });
+ * const { data, pagination } = usePaginationQuery(GetAssetsDocument, {
+ *   initialCursor: initialCursor,
+ *   variables: {
+ *     after: undefined,
+ *     before: undefined,
+ *     first: pageSize,
+ *     last: undefined,
+ *   },
+ * });
+ *
+ * useBidirectionalScroll({
+ *   onTopItemChange: updateCursor,
+ * });
+ * ```
  * @template TData - The type of the query result data.
  * @template TVariables - The type of the query variables.
  * @param document - The GraphQL query document.
@@ -282,8 +306,8 @@ const getQueryVariableNames = (document) => {
  * @returns {PaginationQuery<TData>} The pagination query result containing data, loading state, pagination controls, and lastFetchedData.
  */
 const usePaginationQuery = (document, props) => {
-    const pageSize = props.pageSize ?? props.variables?.first ?? reactComponents.defaultPageSize;
-    const declaredVarNames = react.useMemo(() => getQueryVariableNames(document), [document]);
+    const pageSize = react.useMemo(() => props.pageSize ?? props.variables?.first ?? reactComponents.defaultPageSize, [props.pageSize, props.variables]);
+    const declaredVarNames = useQueryVariableNames(document);
     const { stableVariables, abortController } = useStableVariablesWithAbort(props.variables, props.skip);
     const [state, dispatch] = react.useReducer(createPaginationReducer(), {
         data: undefined,
@@ -306,10 +330,14 @@ const usePaginationQuery = (document, props) => {
     // we must not call reset() because it wipes the initialCursor that
     // useRelayPagination is holding.
     const hasLoadedDataRef = react.useRef(false);
+    const isInitializedRef = react.useRef(false);
     const onReset = react.useCallback(() => {
         dispatch({ type: "INCREMENT_RESET_TRIGGER" });
     }, []);
     react.useEffect(() => {
+        if (!isInitializedRef.current) {
+            return;
+        }
         onReset();
     }, [document, onReset]);
     const { table: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage }, variables: { first, after, last, before }, } = reactComponents.useRelayPagination({
@@ -318,8 +346,7 @@ const usePaginationQuery = (document, props) => {
         initialCursor: props.initialCursor,
     });
     const { skip: _skip, updateQuery: _uq, pageSize: _ps, initialCursor: _ic, variables: _vars, ...lazyQueryProps } = props;
-    const networkStatusRef = react.useRef(0);
-    const [, { previousData, fetchMore, networkStatus, loading: lazyLoading }] = useLazyQuery(document, {
+    const [, { previousData, fetchMore, loading: lazyLoading }] = useLazyQuery(document, {
         ...lazyQueryProps,
         variables: stableVariables !== undefined
             ? {
@@ -337,9 +364,6 @@ const usePaginationQuery = (document, props) => {
         },
         notifyOnNetworkStatusChange: true,
         onCompleted: completedData => {
-            if (networkStatusRef.current === client.NetworkStatus.refetch) {
-                dispatch({ type: "INCREMENT_RESET_TRIGGER" });
-            }
             onCompletedRef.current?.(completedData);
         },
         // This is safe since we have no cache and want to control fetch outselves
@@ -347,9 +371,6 @@ const usePaginationQuery = (document, props) => {
         nextFetchPolicy: "standby",
         initialFetchPolicy: "standby",
     });
-    react.useEffect(() => {
-        networkStatusRef.current = networkStatus;
-    }, [networkStatus]);
     const executeFetch = react.useCallback((variables, prev, direction) => {
         if (props.skip) {
             if (props.initialCursor === undefined) {
@@ -434,27 +455,29 @@ const usePaginationQuery = (document, props) => {
         latestRef.current.data = state.data;
         latestRef.current.executeFetch = executeFetch;
     });
-    // Reset accumulated data when variables change (skip until first load
-    // to preserve initialCursor)
-    const pendingResetRef = react.useRef(false);
+    // Reset accumulated data when variables change. Before first load we only
+    // bump the trigger (preserving initialCursor); after first load we also
+    // clear data and reset relay pagination.
     react.useEffect(() => {
-        if (!hasLoadedDataRef.current) {
+        if (!isInitializedRef.current) {
             return;
         }
-        pendingResetRef.current = true;
-        dispatch({ type: "RESET" });
-        reset();
+        if (hasLoadedDataRef.current) {
+            hasLoadedDataRef.current = false;
+            dispatch({ type: "RESET" });
+            reset();
+        }
+        else {
+            dispatch({ type: "INCREMENT_RESET_TRIGGER" });
+        }
     }, [stableVariables, reset]);
-    // Fetch initial page when variables or reset trigger changes.
-    // When stableVariables changes after data is loaded, the reset effect above
-    // also increments resetTrigger — which would cause this effect to fire twice.
-    // The pendingReset guard skips the first (stableVariables-triggered) fire so
-    // only the resetTrigger-triggered fire fetches.
     react.useEffect(() => {
-        if (pendingResetRef.current) {
-            pendingResetRef.current = false;
-            return;
-        }
+        isInitializedRef.current = true;
+    }, []);
+    // Fetch the initial page on mount and whenever resetTrigger changes.
+    // Variable changes flow through the reset effect above which increments
+    // resetTrigger, so stableVariables is intentionally NOT a dependency here.
+    react.useEffect(() => {
         const fetchVariables = {
             first: latestRef.current.first ?? pageSize,
             last: undefined,
@@ -462,7 +485,7 @@ const usePaginationQuery = (document, props) => {
             after: latestRef.current.after ?? undefined,
         };
         latestRef.current.executeFetch(fetchVariables, undefined, "initial");
-    }, [stableVariables, state.resetTrigger, pageSize]);
+    }, [state.resetTrigger, pageSize]);
     // Fetch next/previous page when relay cursor changes
     react.useEffect(() => {
         if (!hasLoadedDataRef.current) {

package/index.esm.js

@@ -2,7 +2,7 @@ import 'react/jsx-runtime';
 import { registerTranslations } from '@trackunit/i18n-library-translation';
 import { useLazyQuery as useLazyQuery$1, NetworkStatus, useQuery as useQuery$1 } from '@apollo/client';
 import { omit, isEqual } from 'es-toolkit';
-import { useMemo, useReducer, useRef, useEffect, useCallback, useState } from 'react';
+import { useMemo, useState, useReducer, useRef, useEffect, useCallback } from 'react';
 import { defaultPageSize, useRelayPagination } from '@trackunit/react-components';
 import { truthy, objectKeys } from '@trackunit/shared-utils';
 
@@ -102,6 +102,32 @@ const useLazyQuery = (document, options) => {
     return useMemo(() => [executeQuery, enhancedResult], [executeQuery, enhancedResult]);
 };
 
+/**
+ * Creates a reducer function for managing pagination state.
+ * Handles data updates, reset, and reset trigger increments.
+ */
+const createPaginationReducer = () => {
+    return (state, action) => {
+        switch (action.type) {
+            case "SET_DATA": {
+                return { ...state, data: action.payload };
+            }
+            case "SET_LAST_FETCHED_DATA": {
+                return { ...state, lastFetchedData: action.payload };
+            }
+            case "RESET": {
+                return { ...state, data: undefined, lastFetchedData: undefined };
+            }
+            case "INCREMENT_RESET_TRIGGER": {
+                return { ...state, resetTrigger: state.resetTrigger + 1 };
+            }
+            default: {
+                throw new Error(`${action} is not a known action type`);
+            }
+        }
+    };
+};
+
 /**
  * Creates a union of two arrays of edges by a key on the node.
  *
@@ -142,13 +168,9 @@ const createDirectionAwareUnion = (direction) => {
  */
 const createUpdateQueryHandler = (params) => {
     return (_previousResult, { fetchMoreResult }) => {
-        // Handle aborted requests by returning previous data
         if (params.abortSignal.aborted) {
-            // If prev does not hold any data we don't want to return it,
-            // since it will make the cache output an error to the console.
             // https://github.com/apollographql/apollo-client/issues/8677
             if (params.prev !== undefined && params.prev !== null) {
-                // Type assertion required: Apollo's updateQuery expects its own result type
                 return objectKeys(params.prev).length === 0
                     ? undefined
                     : params.prev;
@@ -176,30 +198,27 @@ const createUpdateQueryHandler = (params) => {
         return result.data;
     };
 };
+
 /**
- * Creates a reducer function for managing pagination state.
- * Handles data updates, reset, and reset trigger increments.
+ * Extracts declared variable names from a GraphQL document so the hook
+ * only injects relay pagination variables the query actually accepts.
+ *
+ * Finds the first OperationDefinition in the document regardless of
+ * position — this handles documents where fragment definitions appear
+ * before the query.
  */
-const createPaginationReducer = () => {
-    return (state, action) => {
-        switch (action.type) {
-            case "SET_DATA": {
-                return { ...state, data: action.payload };
-            }
-            case "SET_LAST_FETCHED_DATA": {
-                return { ...state, lastFetchedData: action.payload };
-            }
-            case "RESET": {
-                return { ...state, data: undefined, lastFetchedData: undefined };
-            }
-            case "INCREMENT_RESET_TRIGGER": {
-                return { ...state, resetTrigger: state.resetTrigger + 1 };
-            }
-            default: {
-                throw new Error(`${action} is not a known action type`);
-            }
+const useQueryVariableNames = (document) => {
+    return useMemo(() => {
+        const definition = document.definitions.find(def => def.kind === "OperationDefinition");
+        if (definition === undefined) {
+            return new Set();
         }
-    };
+        const varDefs = definition.variableDefinitions;
+        if (varDefs === undefined) {
+            return new Set();
+        }
+        return new Set(varDefs.map(v => v.variable.name.value));
+    }, [document]);
 };
 
 /**
@@ -218,23 +237,9 @@ const useStableVariablesWithAbort = (variables, skip = false) => {
             setAbortController(new AbortController());
         }
     }
-    return { stableVariables, abortController };
-};
-/**
- * Extracts declared variable names from a GraphQL document so the hook
- * only injects relay pagination variables the query actually accepts.
- */
-const getQueryVariableNames = (document) => {
-    const definition = document.definitions[0];
-    if (definition === undefined || definition.kind !== "OperationDefinition") {
-        return new Set();
-    }
-    const varDefs = definition.variableDefinitions;
-    if (varDefs === undefined) {
-        return new Set();
-    }
-    return new Set(varDefs.map(v => v.variable.name.value));
+    return useMemo(() => ({ stableVariables, abortController }), [stableVariables, abortController]);
 };
+
 /**
  * `usePaginationQuery` fetches data from a GraphQL query with Relay-style cursor pagination.
  * It manages page accumulation, loading state, and provides `pagination` controls (including `fetchNext`)
@@ -250,7 +255,8 @@ const getQueryVariableNames = (document) => {
  * ### When not to use
  * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from this library directly.
  *
- * @example
+ * @example basic usage
+ * ```tsx
  * const {
  *   data,
  *   loading,
@@ -273,6 +279,24 @@ const getQueryVariableNames = (document) => {
  *     return { data: newData, pageInfo: newData.assets.pageInfo };
  *   },
  * });
+ * ```
+ * @example pagination example with url sync
+ * ```tsx
+ * const { initialCursor, updateCursor } = useCursorUrlSync({ paramName: "myTableCursor" });
+ * const { data, pagination } = usePaginationQuery(GetAssetsDocument, {
+ *   initialCursor: initialCursor,
+ *   variables: {
+ *     after: undefined,
+ *     before: undefined,
+ *     first: pageSize,
+ *     last: undefined,
+ *   },
+ * });
+ *
+ * useBidirectionalScroll({
+ *   onTopItemChange: updateCursor,
+ * });
+ * ```
  * @template TData - The type of the query result data.
  * @template TVariables - The type of the query variables.
  * @param document - The GraphQL query document.
@@ -280,8 +304,8 @@ const getQueryVariableNames = (document) => {
  * @returns {PaginationQuery<TData>} The pagination query result containing data, loading state, pagination controls, and lastFetchedData.
  */
 const usePaginationQuery = (document, props) => {
-    const pageSize = props.pageSize ?? props.variables?.first ?? defaultPageSize;
-    const declaredVarNames = useMemo(() => getQueryVariableNames(document), [document]);
+    const pageSize = useMemo(() => props.pageSize ?? props.variables?.first ?? defaultPageSize, [props.pageSize, props.variables]);
+    const declaredVarNames = useQueryVariableNames(document);
     const { stableVariables, abortController } = useStableVariablesWithAbort(props.variables, props.skip);
     const [state, dispatch] = useReducer(createPaginationReducer(), {
         data: undefined,
@@ -304,10 +328,14 @@ const usePaginationQuery = (document, props) => {
     // we must not call reset() because it wipes the initialCursor that
     // useRelayPagination is holding.
     const hasLoadedDataRef = useRef(false);
+    const isInitializedRef = useRef(false);
     const onReset = useCallback(() => {
         dispatch({ type: "INCREMENT_RESET_TRIGGER" });
     }, []);
     useEffect(() => {
+        if (!isInitializedRef.current) {
+            return;
+        }
         onReset();
     }, [document, onReset]);
     const { table: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage }, variables: { first, after, last, before }, } = useRelayPagination({
@@ -316,8 +344,7 @@ const usePaginationQuery = (document, props) => {
         initialCursor: props.initialCursor,
     });
     const { skip: _skip, updateQuery: _uq, pageSize: _ps, initialCursor: _ic, variables: _vars, ...lazyQueryProps } = props;
-    const networkStatusRef = useRef(0);
-    const [, { previousData, fetchMore, networkStatus, loading: lazyLoading }] = useLazyQuery(document, {
+    const [, { previousData, fetchMore, loading: lazyLoading }] = useLazyQuery(document, {
         ...lazyQueryProps,
         variables: stableVariables !== undefined
             ? {
@@ -335,9 +362,6 @@ const usePaginationQuery = (document, props) => {
         },
         notifyOnNetworkStatusChange: true,
         onCompleted: completedData => {
-            if (networkStatusRef.current === NetworkStatus.refetch) {
-                dispatch({ type: "INCREMENT_RESET_TRIGGER" });
-            }
             onCompletedRef.current?.(completedData);
         },
         // This is safe since we have no cache and want to control fetch outselves
@@ -345,9 +369,6 @@ const usePaginationQuery = (document, props) => {
         nextFetchPolicy: "standby",
         initialFetchPolicy: "standby",
     });
-    useEffect(() => {
-        networkStatusRef.current = networkStatus;
-    }, [networkStatus]);
     const executeFetch = useCallback((variables, prev, direction) => {
         if (props.skip) {
             if (props.initialCursor === undefined) {
@@ -432,27 +453,29 @@ const usePaginationQuery = (document, props) => {
         latestRef.current.data = state.data;
         latestRef.current.executeFetch = executeFetch;
     });
-    // Reset accumulated data when variables change (skip until first load
-    // to preserve initialCursor)
-    const pendingResetRef = useRef(false);
+    // Reset accumulated data when variables change. Before first load we only
+    // bump the trigger (preserving initialCursor); after first load we also
+    // clear data and reset relay pagination.
     useEffect(() => {
-        if (!hasLoadedDataRef.current) {
+        if (!isInitializedRef.current) {
             return;
         }
-        pendingResetRef.current = true;
-        dispatch({ type: "RESET" });
-        reset();
+        if (hasLoadedDataRef.current) {
+            hasLoadedDataRef.current = false;
+            dispatch({ type: "RESET" });
+            reset();
+        }
+        else {
+            dispatch({ type: "INCREMENT_RESET_TRIGGER" });
+        }
     }, [stableVariables, reset]);
-    // Fetch initial page when variables or reset trigger changes.
-    // When stableVariables changes after data is loaded, the reset effect above
-    // also increments resetTrigger — which would cause this effect to fire twice.
-    // The pendingReset guard skips the first (stableVariables-triggered) fire so
-    // only the resetTrigger-triggered fire fetches.
     useEffect(() => {
-        if (pendingResetRef.current) {
-            pendingResetRef.current = false;
-            return;
-        }
+        isInitializedRef.current = true;
+    }, []);
+    // Fetch the initial page on mount and whenever resetTrigger changes.
+    // Variable changes flow through the reset effect above which increments
+    // resetTrigger, so stableVariables is intentionally NOT a dependency here.
+    useEffect(() => {
         const fetchVariables = {
             first: latestRef.current.first ?? pageSize,
             last: undefined,
@@ -460,7 +483,7 @@ const usePaginationQuery = (document, props) => {
             after: latestRef.current.after ?? undefined,
         };
         latestRef.current.executeFetch(fetchVariables, undefined, "initial");
-    }, [stableVariables, state.resetTrigger, pageSize]);
+    }, [state.resetTrigger, pageSize]);
     // Fetch next/previous page when relay cursor changes
     useEffect(() => {
         if (!hasLoadedDataRef.current) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-graphql-hooks",
-  "version": "1.15.7",
+  "version": "1.15.9",
   "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.12.55",
-    "@trackunit/shared-utils": "1.13.64",
+    "@trackunit/i18n-library-translation": "1.12.56",
+    "@trackunit/shared-utils": "1.13.65",
     "es-toolkit": "^1.39.10",
-    "@trackunit/react-components": "1.18.4"
+    "@trackunit/react-components": "1.18.5"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { UpdateQueryOptions } from "./paginationQueryUtils";
 export * from "./useLazyQuery";
 export * from "./usePaginationQuery";
 export * from "./useQuery";
+export type { UpdateQueryOptions } from "./utils/createUpdateQueryHandler";

package/src/usePaginationQuery.d.ts

@@ -1,6 +1,6 @@
 import { LazyQueryHookOptions as ApolloLazyQueryHookOptions, OperationVariables as ApolloOperationVariables, TypedDocumentNode as ApolloTypedDocumentNode } from "@apollo/client";
 import { RelayPageInfo, RelayTableSupport } from "@trackunit/react-components";
-import { type UpdateQueryOptions } from "./paginationQueryUtils";
+import { type UpdateQueryOptions } from "./utils/createUpdateQueryHandler";
 /**
  * This type is used to return the data from the query, the pagination object and the last fetched data.
  */
@@ -58,7 +58,8 @@ export interface PaginationQueryProps<TData, TVariables extends ApolloOperationV
  * ### When not to use
  * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from this library directly.
  *
- * @example
+ * @example basic usage
+ * ```tsx
  * const {
  *   data,
  *   loading,
@@ -81,6 +82,24 @@ export interface PaginationQueryProps<TData, TVariables extends ApolloOperationV
  *     return { data: newData, pageInfo: newData.assets.pageInfo };
  *   },
  * });
+ * ```
+ * @example pagination example with url sync
+ * ```tsx
+ * const { initialCursor, updateCursor } = useCursorUrlSync({ paramName: "myTableCursor" });
+ * const { data, pagination } = usePaginationQuery(GetAssetsDocument, {
+ *   initialCursor: initialCursor,
+ *   variables: {
+ *     after: undefined,
+ *     before: undefined,
+ *     first: pageSize,
+ *     last: undefined,
+ *   },
+ * });
+ *
+ * useBidirectionalScroll({
+ *   onTopItemChange: updateCursor,
+ * });
+ * ```
  * @template TData - The type of the query result data.
  * @template TVariables - The type of the query variables.
  * @param document - The GraphQL query document.

package/src/utils/createPaginationReducer.d.ts

@@ -0,0 +1,21 @@
+export type PaginationState<TData> = {
+    data: TData | undefined;
+    lastFetchedData: TData | undefined;
+    resetTrigger: number;
+};
+export type PaginationAction<TData> = {
+    type: "SET_DATA";
+    payload: TData;
+} | {
+    type: "SET_LAST_FETCHED_DATA";
+    payload: TData;
+} | {
+    type: "RESET";
+} | {
+    type: "INCREMENT_RESET_TRIGGER";
+};
+/**
+ * Creates a reducer function for managing pagination state.
+ * Handles data updates, reset, and reset trigger increments.
+ */
+export declare const createPaginationReducer: <TData>() => (state: PaginationState<TData>, action: PaginationAction<TData>) => PaginationState<TData>;

package/src/{paginationQueryUtils.d.ts → utils/createUpdateQueryHandler.d.ts}

@@ -1,25 +1,9 @@
-import { RelayPageInfo } from "@trackunit/react-components";
-import { unionEdgesByNodeKey } from "./unionEdgesByNodeKey";
+import type { RelayPageInfo } from "@trackunit/react-components";
+import { unionEdgesByNodeKey } from "../unionEdgesByNodeKey";
 export type FetchDirection = "forward" | "backward" | "initial";
 export type UpdateQueryOptions = {
     readonly unionEdgesByNodeKey: typeof unionEdgesByNodeKey;
 };
-export type PaginationState<TData> = {
-    data: TData | undefined;
-    lastFetchedData: TData | undefined;
-    resetTrigger: number;
-};
-export type PaginationAction<TData> = {
-    type: "SET_DATA";
-    payload: TData;
-} | {
-    type: "SET_LAST_FETCHED_DATA";
-    payload: TData;
-} | {
-    type: "RESET";
-} | {
-    type: "INCREMENT_RESET_TRIGGER";
-};
 /**
  * Creates an update query handler for Apollo's fetchMore.
  * Handles aborted requests and merges new data with existing data.
@@ -39,8 +23,3 @@ export declare const createUpdateQueryHandler: <TData, TPreviousResult>(params:
 }) => (_previousResult: TPreviousResult, { fetchMoreResult }: {
     fetchMoreResult?: unknown;
 }) => TPreviousResult;
-/**
- * Creates a reducer function for managing pagination state.
- * Handles data updates, reset, and reset trigger increments.
- */
-export declare const createPaginationReducer: <TData>() => (state: PaginationState<TData>, action: PaginationAction<TData>) => PaginationState<TData>;

package/src/utils/useQueryVariableNames.d.ts

@@ -0,0 +1,22 @@
+type GraphQLDocument = {
+    readonly definitions: ReadonlyArray<{
+        readonly kind: string;
+        readonly variableDefinitions?: ReadonlyArray<{
+            readonly variable: {
+                readonly name: {
+                    readonly value: string;
+                };
+            };
+        }>;
+    }>;
+};
+/**
+ * Extracts declared variable names from a GraphQL document so the hook
+ * only injects relay pagination variables the query actually accepts.
+ *
+ * Finds the first OperationDefinition in the document regardless of
+ * position — this handles documents where fragment definitions appear
+ * before the query.
+ */
+export declare const useQueryVariableNames: (document: GraphQLDocument) => ReadonlySet<string>;
+export {};

package/src/utils/useStableVariablesWithAbort.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stabilizes variables via deep equality and manages an AbortController for
+ * cancelling in-flight requests when variables change.
+ */
+export declare const useStableVariablesWithAbort: <TVariables>(variables: TVariables | undefined, skip?: boolean) => {
+    stableVariables: TVariables | undefined;
+    abortController: AbortController;
+};