@trackunit/react-graphql-hooks 1.14.53 → 1.15.0

package/index.cjs.js

@@ -2,11 +2,11 @@
 
 require('react/jsx-runtime');
 var i18nLibraryTranslation = require('@trackunit/i18n-library-translation');
-var sharedUtils = require('@trackunit/shared-utils');
 var client = require('@apollo/client');
 var esToolkit = require('es-toolkit');
 var react = require('react');
 var reactComponents = require('@trackunit/react-components');
+var sharedUtils = require('@trackunit/shared-utils');
 
 var defaultTranslations = {
 	
@@ -50,29 +50,6 @@ const setupLibraryTranslations = () => {
     i18nLibraryTranslation.registerTranslations(translations);
 };
 
-/**
- * Creates a union of two arrays of edges by a key on the node.
- *
- * @template TEdge
- * @param key The key to use to determine uniqueness
- * @param previousEdges The previous array of edges to merge with the new array
- * @param newEdges The new array of edges to merge with the previous array
- * @returns {TEdge[]} A new array with the edges from the previous array and the new array, but only if the item's key is unique.
- */
-const unionEdgesByNodeKey = (key, previousEdges, newEdges) => {
-    const previousIds = previousEdges?.map(edge => edge.node[key]) || [];
-    const newIds = newEdges?.map(edge => edge.node[key]) || [];
-    const mergedIds = [...previousIds, ...newIds];
-    const uniqueIds = [...new Set(mergedIds)];
-    return uniqueIds
-        .map(id => {
-        const previousEdge = previousEdges?.find(edge => edge.node[key] === id);
-        const newEdge = newEdges?.find(edge => edge.node[key] === id);
-        return newEdge || previousEdge;
-    })
-        .filter(sharedUtils.truthy);
-};
-
 /**
  * A wrapper around Apollo Client's useLazyQuery that provides stable data by default.
  *
@@ -128,21 +105,38 @@ const useLazyQuery = (document, options) => {
 };
 
 /**
- * Converts pagination variables from cursor-based (first/after) to page-based (page/pageSize) if needed.
- * Returns the appropriate variables based on the pagination type.
+ * Creates a union of two arrays of edges by a key on the node.
+ *
+ * @template TEdge
+ * @param key The key to use to determine uniqueness
+ * @param previousEdges The previous array of edges to merge with the new array
+ * @param newEdges The new array of edges to merge with the previous array
+ * @returns {TEdge[]} A new array with the edges from the previous array and the new array, but only if the item's key is unique.
  */
-const convertPaginationVariables = (baseVariables, paginationVars) => {
-    const usesPageBasedPagination = baseVariables !== undefined && "page" in baseVariables && "pageSize" in baseVariables;
-    const paginationVariables = usesPageBasedPagination
-        ? {
-            pageSize: paginationVars.first,
-            page: Number(paginationVars.after ?? 0),
-        }
-        : { ...paginationVars };
-    return {
-        ...baseVariables,
-        ...paginationVariables,
-    };
+const unionEdgesByNodeKey = (key, previousEdges, newEdges) => {
+    const previousIds = previousEdges?.map(edge => edge.node[key]) || [];
+    const newIds = newEdges?.map(edge => edge.node[key]) || [];
+    const mergedIds = [...previousIds, ...newIds];
+    const uniqueIds = [...new Set(mergedIds)];
+    return uniqueIds
+        .map(id => {
+        const previousEdge = previousEdges?.find(edge => edge.node[key] === id);
+        const newEdge = newEdges?.find(edge => edge.node[key] === id);
+        return newEdge || previousEdge;
+    })
+        .filter(sharedUtils.truthy);
+};
+
+/**
+ * Creates a direction-aware wrapper around `unionEdgesByNodeKey`.
+ * For backward fetches, the argument order is swapped so new (earlier) edges
+ * come first and previous edges are appended.
+ */
+const createDirectionAwareUnion = (direction) => {
+    if (direction === "backward") {
+        return (key, previousEdges, newEdges) => unionEdgesByNodeKey(key, newEdges, previousEdges);
+    }
+    return unionEdgesByNodeKey;
 };
 /**
  * Creates an update query handler for Apollo's fetchMore.
@@ -163,11 +157,21 @@ const createUpdateQueryHandler = (params) => {
             }
             return undefined;
         }
+        // Apollo can return undefined fetchMoreResult when the query document
+        // changes and triggers a spurious re-execution (e.g. dynamic query
+        // rebuilt from visibleColumns). Skip the update and keep previous data.
+        if (fetchMoreResult === undefined || fetchMoreResult === null) {
+            params.onLoadingComplete();
+            return _previousResult;
+        }
         // Type assertion required: Apollo's fetchMoreResult has complex internal types
         // that need to be cast to our TData generic for type-safe usage
         const typedResult = fetchMoreResult;
         params.onLastFetchedUpdate(typedResult);
-        const result = params.onUpdate(params.prev, typedResult);
+        const options = {
+            unionEdgesByNodeKey: createDirectionAwareUnion(params.direction),
+        };
+        const result = params.onUpdate(params.prev, typedResult, options);
         params.onPageInfoUpdate(result.pageInfo ?? null);
         params.onDataUpdate(result.data);
         params.onLoadingComplete();
@@ -201,51 +205,27 @@ const createPaginationReducer = () => {
 };
 
 /**
- * Hook to stabilize variables based on deep equality comparison.
- * Prevents unnecessary re-fetches when parent components pass new variable objects
- * with the same content.
+ * Stabilizes variables via deep equality and manages an AbortController for
+ * cancelling in-flight requests when variables change.
  */
-const useStableVariables = (variables) => {
+const useStableVariablesWithAbort = (variables, skip = false) => {
     const [stableVariables, setStableVariables] = react.useState(variables);
+    const [abortController, setAbortController] = react.useState(() => new AbortController());
+    const [prevVariables, setPrevVariables] = react.useState(variables);
+    if (!esToolkit.isEqual(variables, prevVariables)) {
+        setPrevVariables(variables);
+        setStableVariables(variables);
+        if (!skip) {
+            abortController.abort();
+            setAbortController(new AbortController());
+        }
+    }
     reactComponents.useWatch({
         value: variables,
         onChange: setStableVariables,
         skip: !Boolean(variables),
     });
-    return [stableVariables, setStableVariables];
-};
-/**
- * Hook to manage AbortController for cancellable requests.
- * Returns an abort signal that can be passed to fetch requests and a function to create new controllers.
- */
-const useAbortableRequest = (props, setStableVariables) => {
-    const [abortController, setAbortController] = react.useState(() => new AbortController());
-    const [prevVariables, setPrevVariables] = react.useState(props.variables);
-    if (!esToolkit.isEqual(props.variables, prevVariables)) {
-        setPrevVariables(props.variables);
-        setStableVariables(props.variables);
-        if (!props.skip) {
-            abortController.abort();
-            const newAbortController = new AbortController();
-            setAbortController(newAbortController);
-        }
-    }
-    const abortControllerRef = react.useRef(abortController);
-    react.useEffect(() => {
-        abortControllerRef.current = abortController;
-    }, [abortController]);
-    return { abortSignal: abortController.signal };
-};
-/**
- * Hook to sync a value to a ref and return the ref.
- * Useful for avoiding dependency cycles in effects.
- */
-const useSyncedRef = (value) => {
-    const ref = react.useRef(value);
-    react.useEffect(() => {
-        ref.current = value;
-    }, [value]);
-    return ref;
+    return { stableVariables, abortController };
 };
 /**
  * `usePaginationQuery` fetches data from a GraphQL query with Relay-style cursor pagination.
@@ -260,7 +240,7 @@ const useSyncedRef = (value) => {
  * or event log with infinite scroll via the Table component.
  *
  * ### When not to use
- * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from Apollo Client directly.
+ * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from this library directly.
  *
  * @example
  * const {
@@ -269,8 +249,7 @@ const useSyncedRef = (value) => {
  *   pagination,
  *   lastFetchedData,
  * } = usePaginationQuery(MyAssetsDocument, {
- *   updateQuery: (previous, newData) => {
- *     // Here you can use the unionEdgesByNodeKey utils to merge your edges together.
+ *   updateQuery: (previous, newData, { unionEdgesByNodeKey }) => {
  *     if (newData?.assets?.edges) {
  *       return {
  *         data: {
@@ -289,141 +268,188 @@ const useSyncedRef = (value) => {
  * @template TData - The type of the query result data.
  * @template TVariables - The type of the query variables.
  * @param document - The GraphQL query document.
- * @param props - The properties for configuring the query. This includes the `updateQuery` function for merging new and existing data, and options for pagination such as `pageSize`. Also includes other lazy query hook options from Apollo Client.
+ * @param props - The properties for configuring the query. This includes the `updateQuery` function for merging new and existing data, and options for pagination such as `pageSize`. Also includes other lazy query hook options.
  * @returns {PaginationQuery<TData>} The pagination query result containing data, loading state, pagination controls, and lastFetchedData.
  */
 const usePaginationQuery = (document, props) => {
-    // Use reducer to manage interconnected pagination state
+    const pageSize = props.pageSize ?? props.variables?.first ?? reactComponents.defaultPageSize;
+    const { stableVariables, abortController } = useStableVariablesWithAbort(props.variables, props.skip);
     const [state, dispatch] = react.useReducer(createPaginationReducer(), {
         data: undefined,
         lastFetchedData: undefined,
         resetTrigger: 0,
     });
-    // Stabilize variables to prevent unnecessary re-fetches
-    const [stableVariables, setStableVariables] = useStableVariables(props.variables);
-    // Manage abort controller for cancellable requests
-    const { abortSignal } = useAbortableRequest(props, setStableVariables);
-    const internalProps = react.useMemo(() => {
-        return {
-            ...props,
-            variables: stableVariables,
-        };
-    }, [props, stableVariables]);
+    const updateQueryRef = react.useRef(props.updateQuery);
+    react.useEffect(() => {
+        updateQueryRef.current = props.updateQuery;
+    }, [props.updateQuery]);
+    const onErrorRef = react.useRef(props.onError);
+    react.useEffect(() => {
+        onErrorRef.current = props.onError;
+    }, [props.onError]);
+    const onCompletedRef = react.useRef(props.onCompleted);
+    react.useEffect(() => {
+        onCompletedRef.current = props.onCompleted;
+    }, [props.onCompleted]);
+    // Tracks whether data has been successfully fetched at least once. Until then,
+    // we must not call reset() because it wipes the initialCursor that
+    // useRelayPagination is holding.
+    const hasLoadedDataRef = react.useRef(false);
+    const onReset = react.useCallback(() => {
+        dispatch({ type: "INCREMENT_RESET_TRIGGER" });
+    }, []);
+    react.useEffect(() => {
+        onReset();
+    }, [document, onReset]);
+    const { table: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage }, variables: { first, after, last, before }, } = reactComponents.useRelayPagination({
+        pageSize,
+        onReset,
+        initialCursor: props.initialCursor,
+    });
     const [, { previousData, fetchMore, networkStatus, loading: lazyLoading }] = useLazyQuery(document, {
-        ...internalProps,
+        ...props,
+        variables: stableVariables !== undefined
+            ? {
+                ...stableVariables,
+                first: pageSize,
+                ...(props.initialCursor !== undefined ? { after: props.initialCursor } : {}),
+            }
+            : undefined,
         context: {
-            ...internalProps.context,
+            ...props.context,
             fetchOptions: {
-                ...internalProps.context?.fetchOptions,
-                signal: abortSignal,
+                ...props.context?.fetchOptions,
+                signal: abortController.signal,
             },
         },
-        pollInterval: internalProps.pollInterval,
-        notifyOnNetworkStatusChange: true, // Needed to update networkStatus
+        notifyOnNetworkStatusChange: true,
         onCompleted: completedData => {
             if (networkStatus === client.NetworkStatus.refetch) {
-                // trigger reset for refetchQueries for the provided document.
                 dispatch({ type: "INCREMENT_RESET_TRIGGER" });
             }
-            if (internalProps.onCompleted) {
-                internalProps.onCompleted(completedData);
-            }
-        },
-        // This is safe since we have no cache
+            onCompletedRef.current?.(completedData);
+        }, // This is safe since we have no cache
         // and without it it will make a magic extra call to the query check this
         // https://stackoverflow.com/questions/66441463/fetchmore-request-executed-twice-every-time
         nextFetchPolicy: "network-only",
         initialFetchPolicy: "network-only",
     });
-    const onReset = react.useCallback(() => {
-        dispatch({ type: "INCREMENT_RESET_TRIGGER" });
-    }, []);
-    react.useEffect(() => {
-        onReset();
-    }, [document, onReset]);
-    const { table: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage }, variables: { first, after, last, before }, } = reactComponents.useRelayPagination({
-        pageSize: internalProps.pageSize ?? internalProps.variables?.first ?? reactComponents.defaultPageSize,
-        onReset,
-    });
-    const doFetchMore = react.useCallback((variables, prev) => {
-        if (internalProps.skip) {
-            setIsLoading(false);
+    const executeFetch = react.useCallback((variables, prev, direction) => {
+        if (props.skip) {
+            if (props.initialCursor === undefined) {
+                setIsLoading(false);
+            }
             return;
         }
         setIsLoading(true);
-        // Convert pagination variables based on pagination type (cursor vs page-based)
-        const fetchMoreVariables = convertPaginationVariables(internalProps.variables, variables);
+        const signal = abortController.signal;
+        const fetchMoreVariables = { ...stableVariables, ...variables };
         fetchMore({
             variables: fetchMoreVariables,
             updateQuery: createUpdateQueryHandler({
-                abortSignal,
+                abortSignal: signal,
                 prev,
-                onUpdate: internalProps.updateQuery,
-                onDataUpdate: (data) => dispatch({ type: "SET_DATA", payload: data }),
+                direction,
+                onUpdate: updateQueryRef.current,
+                onDataUpdate: (data) => {
+                    hasLoadedDataRef.current = true;
+                    dispatch({ type: "SET_DATA", payload: data });
+                },
                 onLastFetchedUpdate: (data) => dispatch({ type: "SET_LAST_FETCHED_DATA", payload: data }),
-                onPageInfoUpdate: setPageInfo,
+                onPageInfoUpdate: incoming => {
+                    if (direction === "initial") {
+                        setPageInfo(incoming);
+                        return;
+                    }
+                    setPageInfo(prevPageInfo => {
+                        if (direction === "forward") {
+                            return {
+                                ...prevPageInfo,
+                                hasNextPage: incoming?.hasNextPage,
+                                endCursor: incoming?.endCursor,
+                            };
+                        }
+                        return {
+                            ...prevPageInfo,
+                            hasPreviousPage: incoming?.hasPreviousPage,
+                            startCursor: incoming?.startCursor,
+                        };
+                    });
+                },
                 onLoadingComplete: () => setIsLoading(false),
             }),
-            // It is apparently not possible to use the onError from the useLazyQuery hook so we have to handle it here.
-            // However, if you need to pass in your own onError function, you can do so in the props of the hook.
-            // But we ignore the error if the request was aborted.
         }).catch(error => {
             setIsLoading(false);
-            if (abortSignal.aborted) {
+            if (signal.aborted) {
                 return;
             }
-            if (internalProps.onError) {
-                return internalProps.onError(error);
-            }
-            else {
-                throw error;
+            if (onErrorRef.current) {
+                return onErrorRef.current(error);
             }
+            throw error;
         });
-    }, [internalProps, setIsLoading, fetchMore, abortSignal, setPageInfo]);
+    }, [props.skip, props.initialCursor, stableVariables, setIsLoading, fetchMore, abortController, setPageInfo]);
+    // Single ref for values that effects need without triggering re-runs.
+    // Defined after executeFetch so it can be initialized with the real value.
+    const latestRef = react.useRef({
+        first,
+        after,
+        last,
+        before,
+        data: state.data,
+        executeFetch,
+    });
+    // Sync ref after each render — runs before fetch effects (declaration order)
+    react.useEffect(() => {
+        latestRef.current.first = first;
+        latestRef.current.after = after;
+        latestRef.current.last = last;
+        latestRef.current.before = before;
+        latestRef.current.data = state.data;
+        latestRef.current.executeFetch = executeFetch;
+    });
+    // Reset accumulated data when variables change (skip until first load
+    // to preserve initialCursor)
     react.useEffect(() => {
+        if (!hasLoadedDataRef.current) {
+            return;
+        }
         dispatch({ type: "RESET" });
         reset();
     }, [stableVariables, reset]);
-    // Store pagination values in refs to avoid triggering unnecessary effect re-runs
-    const firstRef = useSyncedRef(first);
-    const lastRef = useSyncedRef(last);
-    const beforeRef = useSyncedRef(before);
-    const dataRef = useSyncedRef(state.data);
-    const doFetchMoreRef = useSyncedRef(doFetchMore);
     // Fetch initial page when variables or reset trigger changes
     react.useEffect(() => {
         const fetchVariables = {
-            first: firstRef.current,
+            first: latestRef.current.first ?? pageSize,
             last: undefined,
             before: undefined,
-            after: undefined,
+            after: latestRef.current.after ?? undefined,
         };
-        doFetchMoreRef.current(fetchVariables, undefined);
-        // Refs are stable and don't need to trigger re-runs, but included to satisfy linter
-    }, [stableVariables, state.resetTrigger, firstRef, doFetchMoreRef]);
-    // Fetch next/previous page when after cursor changes
+        latestRef.current.executeFetch(fetchVariables, undefined, "initial");
+    }, [stableVariables, state.resetTrigger, pageSize]);
+    // Fetch next/previous page when relay cursor changes
     react.useEffect(() => {
+        if (!hasLoadedDataRef.current) {
+            return;
+        }
         if (after !== undefined && after !== null) {
-            const fetchVariables = {
-                first: firstRef.current,
-                after,
-                last: lastRef.current,
-                before: beforeRef.current,
-            };
-            doFetchMoreRef.current(fetchVariables, dataRef.current);
+            const { first: f, last: l, before: b } = latestRef.current;
+            latestRef.current.executeFetch({ first: f, after, last: l, before: b }, latestRef.current.data, "forward");
+            return;
         }
-        // Refs are stable and don't need to trigger re-runs, but included to satisfy linter
-    }, [after, firstRef, lastRef, beforeRef, dataRef, doFetchMoreRef]);
-    return react.useMemo(() => {
-        return {
-            data: state.data ?? previousData,
-            previousData,
-            loading: isLoading || lazyLoading,
-            pagination: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage },
-            lastFetchedData: state.lastFetchedData,
-            reset,
-        };
-    }, [
+        if (before !== undefined && before !== null) {
+            const { first: f, after: a, last: l } = latestRef.current;
+            latestRef.current.executeFetch({ first: f, after: a, last: l, before }, latestRef.current.data, "backward");
+        }
+    }, [after, before]);
+    return react.useMemo(() => ({
+        data: state.data ?? previousData,
+        previousData,
+        loading: isLoading || lazyLoading,
+        pagination: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage },
+        lastFetchedData: state.lastFetchedData,
+        reset,
+    }), [
         state.data,
         state.lastFetchedData,
         isLoading,
@@ -500,7 +526,6 @@ const useQuery = (document, options) => {
  */
 setupLibraryTranslations();
 
-exports.unionEdgesByNodeKey = unionEdgesByNodeKey;
 exports.useLazyQuery = useLazyQuery;
 exports.usePaginationQuery = usePaginationQuery;
 exports.useQuery = useQuery;

package/index.esm.js

@@ -1,10 +1,10 @@
 import 'react/jsx-runtime';
 import { registerTranslations } from '@trackunit/i18n-library-translation';
-import { truthy, objectKeys } from '@trackunit/shared-utils';
 import { useLazyQuery as useLazyQuery$1, NetworkStatus, useQuery as useQuery$1 } from '@apollo/client';
 import { omit, isEqual } from 'es-toolkit';
-import { useMemo, useReducer, useCallback, useEffect, useState, useRef } from 'react';
-import { useRelayPagination, defaultPageSize, useWatch } from '@trackunit/react-components';
+import { useMemo, useReducer, useRef, useEffect, useCallback, useState } from 'react';
+import { defaultPageSize, useRelayPagination, useWatch } from '@trackunit/react-components';
+import { truthy, objectKeys } from '@trackunit/shared-utils';
 
 var defaultTranslations = {
 	
@@ -48,29 +48,6 @@ const setupLibraryTranslations = () => {
     registerTranslations(translations);
 };
 
-/**
- * Creates a union of two arrays of edges by a key on the node.
- *
- * @template TEdge
- * @param key The key to use to determine uniqueness
- * @param previousEdges The previous array of edges to merge with the new array
- * @param newEdges The new array of edges to merge with the previous array
- * @returns {TEdge[]} A new array with the edges from the previous array and the new array, but only if the item's key is unique.
- */
-const unionEdgesByNodeKey = (key, previousEdges, newEdges) => {
-    const previousIds = previousEdges?.map(edge => edge.node[key]) || [];
-    const newIds = newEdges?.map(edge => edge.node[key]) || [];
-    const mergedIds = [...previousIds, ...newIds];
-    const uniqueIds = [...new Set(mergedIds)];
-    return uniqueIds
-        .map(id => {
-        const previousEdge = previousEdges?.find(edge => edge.node[key] === id);
-        const newEdge = newEdges?.find(edge => edge.node[key] === id);
-        return newEdge || previousEdge;
-    })
-        .filter(truthy);
-};
-
 /**
  * A wrapper around Apollo Client's useLazyQuery that provides stable data by default.
  *
@@ -126,21 +103,38 @@ const useLazyQuery = (document, options) => {
 };
 
 /**
- * Converts pagination variables from cursor-based (first/after) to page-based (page/pageSize) if needed.
- * Returns the appropriate variables based on the pagination type.
+ * Creates a union of two arrays of edges by a key on the node.
+ *
+ * @template TEdge
+ * @param key The key to use to determine uniqueness
+ * @param previousEdges The previous array of edges to merge with the new array
+ * @param newEdges The new array of edges to merge with the previous array
+ * @returns {TEdge[]} A new array with the edges from the previous array and the new array, but only if the item's key is unique.
  */
-const convertPaginationVariables = (baseVariables, paginationVars) => {
-    const usesPageBasedPagination = baseVariables !== undefined && "page" in baseVariables && "pageSize" in baseVariables;
-    const paginationVariables = usesPageBasedPagination
-        ? {
-            pageSize: paginationVars.first,
-            page: Number(paginationVars.after ?? 0),
-        }
-        : { ...paginationVars };
-    return {
-        ...baseVariables,
-        ...paginationVariables,
-    };
+const unionEdgesByNodeKey = (key, previousEdges, newEdges) => {
+    const previousIds = previousEdges?.map(edge => edge.node[key]) || [];
+    const newIds = newEdges?.map(edge => edge.node[key]) || [];
+    const mergedIds = [...previousIds, ...newIds];
+    const uniqueIds = [...new Set(mergedIds)];
+    return uniqueIds
+        .map(id => {
+        const previousEdge = previousEdges?.find(edge => edge.node[key] === id);
+        const newEdge = newEdges?.find(edge => edge.node[key] === id);
+        return newEdge || previousEdge;
+    })
+        .filter(truthy);
+};
+
+/**
+ * Creates a direction-aware wrapper around `unionEdgesByNodeKey`.
+ * For backward fetches, the argument order is swapped so new (earlier) edges
+ * come first and previous edges are appended.
+ */
+const createDirectionAwareUnion = (direction) => {
+    if (direction === "backward") {
+        return (key, previousEdges, newEdges) => unionEdgesByNodeKey(key, newEdges, previousEdges);
+    }
+    return unionEdgesByNodeKey;
 };
 /**
  * Creates an update query handler for Apollo's fetchMore.
@@ -161,11 +155,21 @@ const createUpdateQueryHandler = (params) => {
             }
             return undefined;
         }
+        // Apollo can return undefined fetchMoreResult when the query document
+        // changes and triggers a spurious re-execution (e.g. dynamic query
+        // rebuilt from visibleColumns). Skip the update and keep previous data.
+        if (fetchMoreResult === undefined || fetchMoreResult === null) {
+            params.onLoadingComplete();
+            return _previousResult;
+        }
         // Type assertion required: Apollo's fetchMoreResult has complex internal types
         // that need to be cast to our TData generic for type-safe usage
         const typedResult = fetchMoreResult;
         params.onLastFetchedUpdate(typedResult);
-        const result = params.onUpdate(params.prev, typedResult);
+        const options = {
+            unionEdgesByNodeKey: createDirectionAwareUnion(params.direction),
+        };
+        const result = params.onUpdate(params.prev, typedResult, options);
         params.onPageInfoUpdate(result.pageInfo ?? null);
         params.onDataUpdate(result.data);
         params.onLoadingComplete();
@@ -199,51 +203,27 @@ const createPaginationReducer = () => {
 };
 
 /**
- * Hook to stabilize variables based on deep equality comparison.
- * Prevents unnecessary re-fetches when parent components pass new variable objects
- * with the same content.
+ * Stabilizes variables via deep equality and manages an AbortController for
+ * cancelling in-flight requests when variables change.
  */
-const useStableVariables = (variables) => {
+const useStableVariablesWithAbort = (variables, skip = false) => {
     const [stableVariables, setStableVariables] = useState(variables);
+    const [abortController, setAbortController] = useState(() => new AbortController());
+    const [prevVariables, setPrevVariables] = useState(variables);
+    if (!isEqual(variables, prevVariables)) {
+        setPrevVariables(variables);
+        setStableVariables(variables);
+        if (!skip) {
+            abortController.abort();
+            setAbortController(new AbortController());
+        }
+    }
     useWatch({
         value: variables,
         onChange: setStableVariables,
         skip: !Boolean(variables),
     });
-    return [stableVariables, setStableVariables];
-};
-/**
- * Hook to manage AbortController for cancellable requests.
- * Returns an abort signal that can be passed to fetch requests and a function to create new controllers.
- */
-const useAbortableRequest = (props, setStableVariables) => {
-    const [abortController, setAbortController] = useState(() => new AbortController());
-    const [prevVariables, setPrevVariables] = useState(props.variables);
-    if (!isEqual(props.variables, prevVariables)) {
-        setPrevVariables(props.variables);
-        setStableVariables(props.variables);
-        if (!props.skip) {
-            abortController.abort();
-            const newAbortController = new AbortController();
-            setAbortController(newAbortController);
-        }
-    }
-    const abortControllerRef = useRef(abortController);
-    useEffect(() => {
-        abortControllerRef.current = abortController;
-    }, [abortController]);
-    return { abortSignal: abortController.signal };
-};
-/**
- * Hook to sync a value to a ref and return the ref.
- * Useful for avoiding dependency cycles in effects.
- */
-const useSyncedRef = (value) => {
-    const ref = useRef(value);
-    useEffect(() => {
-        ref.current = value;
-    }, [value]);
-    return ref;
+    return { stableVariables, abortController };
 };
 /**
  * `usePaginationQuery` fetches data from a GraphQL query with Relay-style cursor pagination.
@@ -258,7 +238,7 @@ const useSyncedRef = (value) => {
  * or event log with infinite scroll via the Table component.
  *
  * ### When not to use
- * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from Apollo Client directly.
+ * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from this library directly.
  *
  * @example
  * const {
@@ -267,8 +247,7 @@ const useSyncedRef = (value) => {
  *   pagination,
  *   lastFetchedData,
  * } = usePaginationQuery(MyAssetsDocument, {
- *   updateQuery: (previous, newData) => {
- *     // Here you can use the unionEdgesByNodeKey utils to merge your edges together.
+ *   updateQuery: (previous, newData, { unionEdgesByNodeKey }) => {
  *     if (newData?.assets?.edges) {
  *       return {
  *         data: {
@@ -287,141 +266,188 @@ const useSyncedRef = (value) => {
  * @template TData - The type of the query result data.
  * @template TVariables - The type of the query variables.
  * @param document - The GraphQL query document.
- * @param props - The properties for configuring the query. This includes the `updateQuery` function for merging new and existing data, and options for pagination such as `pageSize`. Also includes other lazy query hook options from Apollo Client.
+ * @param props - The properties for configuring the query. This includes the `updateQuery` function for merging new and existing data, and options for pagination such as `pageSize`. Also includes other lazy query hook options.
  * @returns {PaginationQuery<TData>} The pagination query result containing data, loading state, pagination controls, and lastFetchedData.
  */
 const usePaginationQuery = (document, props) => {
-    // Use reducer to manage interconnected pagination state
+    const pageSize = props.pageSize ?? props.variables?.first ?? defaultPageSize;
+    const { stableVariables, abortController } = useStableVariablesWithAbort(props.variables, props.skip);
     const [state, dispatch] = useReducer(createPaginationReducer(), {
         data: undefined,
         lastFetchedData: undefined,
         resetTrigger: 0,
     });
-    // Stabilize variables to prevent unnecessary re-fetches
-    const [stableVariables, setStableVariables] = useStableVariables(props.variables);
-    // Manage abort controller for cancellable requests
-    const { abortSignal } = useAbortableRequest(props, setStableVariables);
-    const internalProps = useMemo(() => {
-        return {
-            ...props,
-            variables: stableVariables,
-        };
-    }, [props, stableVariables]);
+    const updateQueryRef = useRef(props.updateQuery);
+    useEffect(() => {
+        updateQueryRef.current = props.updateQuery;
+    }, [props.updateQuery]);
+    const onErrorRef = useRef(props.onError);
+    useEffect(() => {
+        onErrorRef.current = props.onError;
+    }, [props.onError]);
+    const onCompletedRef = useRef(props.onCompleted);
+    useEffect(() => {
+        onCompletedRef.current = props.onCompleted;
+    }, [props.onCompleted]);
+    // Tracks whether data has been successfully fetched at least once. Until then,
+    // we must not call reset() because it wipes the initialCursor that
+    // useRelayPagination is holding.
+    const hasLoadedDataRef = useRef(false);
+    const onReset = useCallback(() => {
+        dispatch({ type: "INCREMENT_RESET_TRIGGER" });
+    }, []);
+    useEffect(() => {
+        onReset();
+    }, [document, onReset]);
+    const { table: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage }, variables: { first, after, last, before }, } = useRelayPagination({
+        pageSize,
+        onReset,
+        initialCursor: props.initialCursor,
+    });
     const [, { previousData, fetchMore, networkStatus, loading: lazyLoading }] = useLazyQuery(document, {
-        ...internalProps,
+        ...props,
+        variables: stableVariables !== undefined
+            ? {
+                ...stableVariables,
+                first: pageSize,
+                ...(props.initialCursor !== undefined ? { after: props.initialCursor } : {}),
+            }
+            : undefined,
         context: {
-            ...internalProps.context,
+            ...props.context,
             fetchOptions: {
-                ...internalProps.context?.fetchOptions,
-                signal: abortSignal,
+                ...props.context?.fetchOptions,
+                signal: abortController.signal,
             },
         },
-        pollInterval: internalProps.pollInterval,
-        notifyOnNetworkStatusChange: true, // Needed to update networkStatus
+        notifyOnNetworkStatusChange: true,
         onCompleted: completedData => {
             if (networkStatus === NetworkStatus.refetch) {
-                // trigger reset for refetchQueries for the provided document.
                 dispatch({ type: "INCREMENT_RESET_TRIGGER" });
             }
-            if (internalProps.onCompleted) {
-                internalProps.onCompleted(completedData);
-            }
-        },
-        // This is safe since we have no cache
+            onCompletedRef.current?.(completedData);
+        }, // This is safe since we have no cache
         // and without it it will make a magic extra call to the query check this
         // https://stackoverflow.com/questions/66441463/fetchmore-request-executed-twice-every-time
         nextFetchPolicy: "network-only",
         initialFetchPolicy: "network-only",
     });
-    const onReset = useCallback(() => {
-        dispatch({ type: "INCREMENT_RESET_TRIGGER" });
-    }, []);
-    useEffect(() => {
-        onReset();
-    }, [document, onReset]);
-    const { table: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage }, variables: { first, after, last, before }, } = useRelayPagination({
-        pageSize: internalProps.pageSize ?? internalProps.variables?.first ?? defaultPageSize,
-        onReset,
-    });
-    const doFetchMore = useCallback((variables, prev) => {
-        if (internalProps.skip) {
-            setIsLoading(false);
+    const executeFetch = useCallback((variables, prev, direction) => {
+        if (props.skip) {
+            if (props.initialCursor === undefined) {
+                setIsLoading(false);
+            }
             return;
         }
         setIsLoading(true);
-        // Convert pagination variables based on pagination type (cursor vs page-based)
-        const fetchMoreVariables = convertPaginationVariables(internalProps.variables, variables);
+        const signal = abortController.signal;
+        const fetchMoreVariables = { ...stableVariables, ...variables };
         fetchMore({
             variables: fetchMoreVariables,
             updateQuery: createUpdateQueryHandler({
-                abortSignal,
+                abortSignal: signal,
                 prev,
-                onUpdate: internalProps.updateQuery,
-                onDataUpdate: (data) => dispatch({ type: "SET_DATA", payload: data }),
+                direction,
+                onUpdate: updateQueryRef.current,
+                onDataUpdate: (data) => {
+                    hasLoadedDataRef.current = true;
+                    dispatch({ type: "SET_DATA", payload: data });
+                },
                 onLastFetchedUpdate: (data) => dispatch({ type: "SET_LAST_FETCHED_DATA", payload: data }),
-                onPageInfoUpdate: setPageInfo,
+                onPageInfoUpdate: incoming => {
+                    if (direction === "initial") {
+                        setPageInfo(incoming);
+                        return;
+                    }
+                    setPageInfo(prevPageInfo => {
+                        if (direction === "forward") {
+                            return {
+                                ...prevPageInfo,
+                                hasNextPage: incoming?.hasNextPage,
+                                endCursor: incoming?.endCursor,
+                            };
+                        }
+                        return {
+                            ...prevPageInfo,
+                            hasPreviousPage: incoming?.hasPreviousPage,
+                            startCursor: incoming?.startCursor,
+                        };
+                    });
+                },
                 onLoadingComplete: () => setIsLoading(false),
             }),
-            // It is apparently not possible to use the onError from the useLazyQuery hook so we have to handle it here.
-            // However, if you need to pass in your own onError function, you can do so in the props of the hook.
-            // But we ignore the error if the request was aborted.
         }).catch(error => {
             setIsLoading(false);
-            if (abortSignal.aborted) {
+            if (signal.aborted) {
                 return;
             }
-            if (internalProps.onError) {
-                return internalProps.onError(error);
-            }
-            else {
-                throw error;
+            if (onErrorRef.current) {
+                return onErrorRef.current(error);
             }
+            throw error;
         });
-    }, [internalProps, setIsLoading, fetchMore, abortSignal, setPageInfo]);
+    }, [props.skip, props.initialCursor, stableVariables, setIsLoading, fetchMore, abortController, setPageInfo]);
+    // Single ref for values that effects need without triggering re-runs.
+    // Defined after executeFetch so it can be initialized with the real value.
+    const latestRef = useRef({
+        first,
+        after,
+        last,
+        before,
+        data: state.data,
+        executeFetch,
+    });
+    // Sync ref after each render — runs before fetch effects (declaration order)
+    useEffect(() => {
+        latestRef.current.first = first;
+        latestRef.current.after = after;
+        latestRef.current.last = last;
+        latestRef.current.before = before;
+        latestRef.current.data = state.data;
+        latestRef.current.executeFetch = executeFetch;
+    });
+    // Reset accumulated data when variables change (skip until first load
+    // to preserve initialCursor)
     useEffect(() => {
+        if (!hasLoadedDataRef.current) {
+            return;
+        }
         dispatch({ type: "RESET" });
         reset();
     }, [stableVariables, reset]);
-    // Store pagination values in refs to avoid triggering unnecessary effect re-runs
-    const firstRef = useSyncedRef(first);
-    const lastRef = useSyncedRef(last);
-    const beforeRef = useSyncedRef(before);
-    const dataRef = useSyncedRef(state.data);
-    const doFetchMoreRef = useSyncedRef(doFetchMore);
     // Fetch initial page when variables or reset trigger changes
     useEffect(() => {
         const fetchVariables = {
-            first: firstRef.current,
+            first: latestRef.current.first ?? pageSize,
             last: undefined,
             before: undefined,
-            after: undefined,
+            after: latestRef.current.after ?? undefined,
         };
-        doFetchMoreRef.current(fetchVariables, undefined);
-        // Refs are stable and don't need to trigger re-runs, but included to satisfy linter
-    }, [stableVariables, state.resetTrigger, firstRef, doFetchMoreRef]);
-    // Fetch next/previous page when after cursor changes
+        latestRef.current.executeFetch(fetchVariables, undefined, "initial");
+    }, [stableVariables, state.resetTrigger, pageSize]);
+    // Fetch next/previous page when relay cursor changes
     useEffect(() => {
+        if (!hasLoadedDataRef.current) {
+            return;
+        }
         if (after !== undefined && after !== null) {
-            const fetchVariables = {
-                first: firstRef.current,
-                after,
-                last: lastRef.current,
-                before: beforeRef.current,
-            };
-            doFetchMoreRef.current(fetchVariables, dataRef.current);
+            const { first: f, last: l, before: b } = latestRef.current;
+            latestRef.current.executeFetch({ first: f, after, last: l, before: b }, latestRef.current.data, "forward");
+            return;
         }
-        // Refs are stable and don't need to trigger re-runs, but included to satisfy linter
-    }, [after, firstRef, lastRef, beforeRef, dataRef, doFetchMoreRef]);
-    return useMemo(() => {
-        return {
-            data: state.data ?? previousData,
-            previousData,
-            loading: isLoading || lazyLoading,
-            pagination: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage },
-            lastFetchedData: state.lastFetchedData,
-            reset,
-        };
-    }, [
+        if (before !== undefined && before !== null) {
+            const { first: f, after: a, last: l } = latestRef.current;
+            latestRef.current.executeFetch({ first: f, after: a, last: l, before }, latestRef.current.data, "backward");
+        }
+    }, [after, before]);
+    return useMemo(() => ({
+        data: state.data ?? previousData,
+        previousData,
+        loading: isLoading || lazyLoading,
+        pagination: { setIsLoading, isLoading, setPageInfo, pageInfo, reset, nextPage, previousPage },
+        lastFetchedData: state.lastFetchedData,
+        reset,
+    }), [
         state.data,
         state.lastFetchedData,
         isLoading,
@@ -498,4 +524,4 @@ const useQuery = (document, options) => {
  */
 setupLibraryTranslations();
 
-export { unionEdgesByNodeKey, useLazyQuery, usePaginationQuery, useQuery };
+export { useLazyQuery, usePaginationQuery, useQuery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-graphql-hooks",
-  "version": "1.14.53",
+  "version": "1.15.0",
   "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.51",
-    "@trackunit/shared-utils": "1.13.60",
+    "@trackunit/i18n-library-translation": "1.12.52",
+    "@trackunit/shared-utils": "1.13.61",
     "es-toolkit": "^1.39.10",
-    "@trackunit/react-components": "1.17.48"
+    "@trackunit/react-components": "1.18.0"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/index.d.ts

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

package/src/paginationQueryUtils.d.ts

@@ -1,10 +1,8 @@
-import { OperationVariables as ApolloOperationVariables } from "@apollo/client/core/types";
 import { RelayPageInfo } from "@trackunit/react-components";
-type RelayPaginationQueryVariables = {
-    first?: number | null;
-    last?: number | null;
-    before?: string | null;
-    after?: string | null;
+import { unionEdgesByNodeKey } from "./unionEdgesByNodeKey";
+export type FetchDirection = "forward" | "backward" | "initial";
+export type UpdateQueryOptions = {
+    readonly unionEdgesByNodeKey: typeof unionEdgesByNodeKey;
 };
 export type PaginationState<TData> = {
     data: TData | undefined;
@@ -22,11 +20,6 @@ export type PaginationAction<TData> = {
 } | {
     type: "INCREMENT_RESET_TRIGGER";
 };
-/**
- * Converts pagination variables from cursor-based (first/after) to page-based (page/pageSize) if needed.
- * Returns the appropriate variables based on the pagination type.
- */
-export declare const convertPaginationVariables: <TVariables extends ApolloOperationVariables>(baseVariables: TVariables | undefined, paginationVars: RelayPaginationQueryVariables) => TVariables;
 /**
  * Creates an update query handler for Apollo's fetchMore.
  * Handles aborted requests and merges new data with existing data.
@@ -34,7 +27,8 @@ export declare const convertPaginationVariables: <TVariables extends ApolloOpera
 export declare const createUpdateQueryHandler: <TData, TPreviousResult>(params: {
     abortSignal: AbortSignal;
     prev: TData | undefined;
-    onUpdate: (prev: TData | undefined, newData: TData) => {
+    direction: FetchDirection;
+    onUpdate: (prev: TData | undefined, newData: TData, options: UpdateQueryOptions) => {
         data: TData;
         pageInfo?: RelayPageInfo | null;
     };
@@ -50,4 +44,3 @@ export declare const createUpdateQueryHandler: <TData, TPreviousResult>(params:
  * Handles data updates, reset, and reset trigger increments.
  */
 export declare const createPaginationReducer: <TData>() => (state: PaginationState<TData>, action: PaginationAction<TData>) => PaginationState<TData>;
-export {};

package/src/usePaginationQuery.d.ts

@@ -1,5 +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";
 /**
  * This type is used to return the data from the query, the pagination object and the last fetched data.
  */
@@ -18,9 +19,11 @@ export interface PaginationQueryProps<TData, TVariables extends ApolloOperationV
      *
      * @param previous The previous data from the query, which can be undefined if no previous data exists.
      * @param newData The new data to merge with the previous data.
+     * @param options Contains `unionEdgesByNodeKey` which is direction-aware — for backward
+     *   fetches it automatically swaps argument order so new (earlier) edges come first.
      * @returns an object containing the merged data, with an optional pageInfo field of type RelayPageInfo or null.
      */
-    updateQuery: (previous: TData | undefined, newData: TData) => {
+    updateQuery: (previous: TData | undefined, newData: TData, options: UpdateQueryOptions) => {
         data: TData;
         pageInfo?: RelayPageInfo | null;
     };
@@ -34,6 +37,11 @@ export interface PaginationQueryProps<TData, TVariables extends ApolloOperationV
      * A boolean value that specifies whether to skip the query.
      */
     skip?: boolean;
+    /**
+     * When provided, pagination starts from this cursor (middle of the dataset)
+     * instead of from the beginning. Useful for resuming scroll position from a URL.
+     */
+    initialCursor?: string;
 }
 /**
  * `usePaginationQuery` fetches data from a GraphQL query with Relay-style cursor pagination.
@@ -48,7 +56,7 @@ export interface PaginationQueryProps<TData, TVariables extends ApolloOperationV
  * or event log with infinite scroll via the Table component.
  *
  * ### When not to use
- * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from Apollo Client directly.
+ * Do not use usePaginationQuery for single-entity queries without pagination — use `useQuery` from this library directly.
  *
  * @example
  * const {
@@ -57,8 +65,7 @@ export interface PaginationQueryProps<TData, TVariables extends ApolloOperationV
  *   pagination,
  *   lastFetchedData,
  * } = usePaginationQuery(MyAssetsDocument, {
- *   updateQuery: (previous, newData) => {
- *     // Here you can use the unionEdgesByNodeKey utils to merge your edges together.
+ *   updateQuery: (previous, newData, { unionEdgesByNodeKey }) => {
  *     if (newData?.assets?.edges) {
  *       return {
  *         data: {
@@ -77,7 +84,7 @@ export interface PaginationQueryProps<TData, TVariables extends ApolloOperationV
  * @template TData - The type of the query result data.
  * @template TVariables - The type of the query variables.
  * @param document - The GraphQL query document.
- * @param props - The properties for configuring the query. This includes the `updateQuery` function for merging new and existing data, and options for pagination such as `pageSize`. Also includes other lazy query hook options from Apollo Client.
+ * @param props - The properties for configuring the query. This includes the `updateQuery` function for merging new and existing data, and options for pagination such as `pageSize`. Also includes other lazy query hook options.
  * @returns {PaginationQuery<TData>} The pagination query result containing data, loading state, pagination controls, and lastFetchedData.
  */
 export declare const usePaginationQuery: <TData, TVariables extends ApolloOperationVariables>(document: TypedDocumentNode<TData, TVariables>, props: PaginationQueryProps<TData, TVariables>) => PaginationQuery<TData>;