Enhanced version of `useSuspenseQuery` in Apollo Client for better DX with Suspense

use-suspense-query-deferred.ts

import { useDeferredValue } from "react";
import { useSpinDelay } from "spin-delay";
import { equal } from "@wry/equality";
import {
  type DocumentNode,
  type TypedDocumentNode,
  type OperationVariables,
} from "@apollo/client";
import { useSuspenseQuery as useApolloSuspenseQuery } from "@apollo/client/react";

/**
 * Enhance `useSuspenseQuery` hook to stop the hook from suspending when variables
 * change and instead return a `suspending` flag that can be used to shown an inline
 * loading indicator.
 *
 * More info: https://www.teemutaskula.com/blog/exploring-query-suspense#deferring-with-usedeferredvalue
 * (the article is written for React Query but the same concept applies to Apollo)
 */
export function useSuspenseQueryDeferred<
  TData = unknown,
  TVariables extends OperationVariables = OperationVariables
>(
  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options?: useApolloSuspenseQuery.Options<NoInfer<TVariables>>
) {
  const deferredVariables = useDeferredValue(options?.variables);

  const result = useApolloSuspenseQuery<TData, TVariables>(query, {
    ...options!, // TODO: figure out TS issue if `!` is removed
    variables: deferredVariables,
  });

  /**
   * Add smart delay to prevent spinner flickering when variables change,
   * and tell when the query is suspending so that we can show an inline
   * loading indicator.
   */
  const isSuspending = useSpinDelay(
    !equal(deferredVariables, options?.variables)
  );

  return { ...result, isSuspending };
}