@buoy-gg/react-query 1.7.2

package/lib/module/react-query/hooks/index.js

@@ -0,0 +1,23 @@
+"use strict";
+
+// Query and Mutation hooks
+export { default as useAllQueries } from "./useAllQueries";
+export { default as useAllMutations } from "./useAllMutations";
+export { useGetQueryByQueryKey, useGetQueryByQueryKeyWithVersion } from "./useSelectedQuery";
+export { useGetMutationById } from "./useSelectedMutation";
+export { default as useQueryStatusCounts } from "./useQueryStatusCounts";
+export { useStorageQueryCounts } from "./useStorageQueryCounts";
+
+// React Query state hooks
+export { useReactQueryState } from "./useReactQueryState";
+
+// Action button hooks
+export { useActionButtons } from "./useActionButtons";
+export { useMutationActionButtons } from "./useMutationActionButtons";
+
+// Modal management hooks
+export { useModalManager } from "./useModalManager";
+export { useModalPersistence } from "./useModalPersistence";
+
+// WiFi state hook
+export { useWifiState } from "./useWifiState";

package/lib/module/react-query/hooks/useActionButtons.js

@@ -0,0 +1,54 @@
+"use strict";
+
+import { useMemo } from "react";
+import triggerLoading from "../utils/actions/triggerLoading";
+import refetch from "../utils/actions/refetch";
+import triggerError from "../utils/actions/triggerError";
+import { getQueryStatusLabel } from "../utils/getQueryStatusLabel";
+/**
+ * Derives the default action button configuration for an inspected query. Encapsulates business
+ * rules around when to show refetch, loading, or error simulation actions.
+ *
+ * @param selectedQuery - The query to derive actions for
+ * @param queryClient - The query client for executing actions
+ * @param queryVersion - Optional version number that increments on query state changes.
+ *                       React Query mutates Query objects in place, so this version ensures
+ *                       the useMemo recomputes when state changes.
+ */
+export function useActionButtons(selectedQuery, queryClient, queryVersion) {
+  const actionButtons = useMemo(() => {
+    const queryStatus = selectedQuery.state.status;
+    const isFetching = getQueryStatusLabel(selectedQuery) === "fetching";
+    const buttons = [{
+      label: "Refetch",
+      bgColorClass: "btnRefetch",
+      textColorClass: "btnRefetch",
+      disabled: isFetching,
+      onPress: () => refetch({
+        query: selectedQuery
+      })
+    }, {
+      label: selectedQuery.state.fetchStatus === "fetching" ? "Restore" : "Loading",
+      bgColorClass: "btnTriggerLoading",
+      textColorClass: "btnTriggerLoading",
+      disabled: false,
+      onPress: () => triggerLoading({
+        query: selectedQuery
+      })
+    }, {
+      label: queryStatus === "error" ? "Restore" : "Error",
+      bgColorClass: "btnTriggerLoadiError",
+      textColorClass: "btnTriggerLoadiError",
+      disabled: queryStatus === "pending",
+      onPress: () => triggerError({
+        query: selectedQuery,
+        queryClient
+      })
+    }];
+    return buttons;
+    // queryVersion is the key dependency that ensures this recomputes when query state changes.
+    // React Query mutates Query objects in place, so comparing selectedQuery.state.* values
+    // doesn't work reliably (the "previous" and "current" values read from the same mutated object).
+  }, [selectedQuery, queryClient, queryVersion]);
+  return actionButtons;
+}

package/lib/module/react-query/hooks/useAllMutations.js

@@ -0,0 +1,32 @@
+"use strict";
+
+import { useEffect, useRef, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+/**
+ * Tracks all active React Query mutations with lightweight change detection. Debounces cache
+ * updates so large mutation batches do not thrash the UI thread on mobile.
+ */
+function useAllMutations() {
+  const queryClient = useQueryClient();
+  const [mutations, setMutations] = useState([]);
+  const mutationsSnapshotRef = useRef(null);
+  useEffect(() => {
+    const updateMutations = () => {
+      const newMutations = queryClient.getMutationCache().getAll();
+      const newStates = newMutations.map(m => m.state);
+      const snapshot = JSON.stringify(newStates);
+      if (mutationsSnapshotRef.current !== snapshot) {
+        mutationsSnapshotRef.current = snapshot;
+        setTimeout(() => setMutations(newMutations), 0);
+      }
+    };
+    setTimeout(updateMutations, 0);
+    const unsubscribe = queryClient.getMutationCache().subscribe(updateMutations);
+    return () => unsubscribe();
+  }, [queryClient]);
+  return {
+    mutations
+  };
+}
+export default useAllMutations;

package/lib/module/react-query/hooks/useAllQueries.js

@@ -0,0 +1,114 @@
+"use strict";
+
+import { useEffect, useState, useRef, useMemo, useCallback } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { isStorageQuery } from "../utils/storageQueryUtils";
+
+// React Query DevTools sorting logic - moved outside component for performance
+
+const getStatusRank = q => q.state.fetchStatus !== "idle" ? 0 : !q.getObserversCount() ? 3 : q.isStale() ? 2 : 1;
+const dateSort = (a, b) => a.state.dataUpdatedAt < b.state.dataUpdatedAt ? 1 : -1;
+const statusAndDateSort = (a, b) => {
+  if (getStatusRank(a) === getStatusRank(b)) {
+    return dateSort(a, b);
+  }
+  return getStatusRank(a) > getStatusRank(b) ? 1 : -1;
+};
+
+/**
+ * Optimized hook to track all queries with live updates
+ * Performance optimizations for mobile:
+ * - Filters event types to only relevant ones
+ * - Uses lightweight comparison instead of deep equality
+ * - Batches updates to reduce re-renders
+ * - Memoizes sorted results
+ */
+function useAllQueries() {
+  const queryClient = useQueryClient();
+  const [queries, setQueries] = useState(() => {
+    // Initialize with current queries to avoid flash
+    const initial = queryClient.getQueryCache().getAll().filter(query => !isStorageQuery(query.queryKey)).sort(statusAndDateSort);
+    return initial;
+  });
+
+  // Track query states using a Map for O(1) lookups
+  const queryStatesRef = useRef(new Map());
+  const updateTimerRef = useRef(undefined);
+
+  // Memoized callback to check if queries need update
+  const hasQueriesChanged = useCallback(newQueries => {
+    const statesMap = queryStatesRef.current;
+
+    // Quick length check first
+    if (newQueries.length !== statesMap.size) {
+      return true;
+    }
+
+    // Check if any query state has changed
+    for (const query of newQueries) {
+      const prevState = statesMap.get(query.queryHash);
+      if (!prevState) return true;
+
+      // Compare only relevant state properties for rendering
+      if (prevState.dataUpdatedAt !== query.state.dataUpdatedAt || prevState.errorUpdatedAt !== query.state.errorUpdatedAt || prevState.fetchStatus !== query.state.fetchStatus || prevState.status !== query.state.status || prevState.isInvalidated !== query.state.isInvalidated) {
+        return true;
+      }
+    }
+    return false;
+  }, []);
+
+  // Memoized update function
+  const updateQueries = useCallback(() => {
+    const allQueries = queryClient.getQueryCache().getAll();
+
+    // Filter out storage queries
+    const nonStorageQueries = allQueries.filter(query => !isStorageQuery(query.queryKey));
+
+    // Check if update is needed
+    if (hasQueriesChanged(nonStorageQueries)) {
+      // Update states map
+      const newStatesMap = new Map();
+      nonStorageQueries.forEach(q => {
+        newStatesMap.set(q.queryHash, q.state);
+      });
+      queryStatesRef.current = newStatesMap;
+
+      // Sort and update
+      const sortedQueries = [...nonStorageQueries].sort(statusAndDateSort);
+      setQueries(sortedQueries);
+    }
+  }, [queryClient, hasQueriesChanged]);
+  useEffect(() => {
+    // Initial update
+    updateQueries();
+
+    // Subscribe with event filtering for performance
+    const unsubscribe = queryClient.getQueryCache().subscribe(event => {
+      // Only process events that affect query list
+      if (event.type === "added" || event.type === "removed" || event.type === "updated") {
+        // Skip storage queries
+        if ("query" in event && event.query && isStorageQuery(event.query.queryKey)) {
+          return;
+        }
+
+        // Debounce updates to batch rapid changes
+        if (updateTimerRef.current) {
+          clearTimeout(updateTimerRef.current);
+        }
+        updateTimerRef.current = setTimeout(() => {
+          updateQueries();
+        }, 10); // Small delay to batch updates
+      }
+    });
+    return () => {
+      unsubscribe();
+      if (updateTimerRef.current) {
+        clearTimeout(updateTimerRef.current);
+      }
+    };
+  }, [queryClient, updateQueries]);
+
+  // Memoize the final sorted array to prevent unnecessary re-renders
+  return useMemo(() => queries, [queries]);
+}
+export default useAllQueries;

package/lib/module/react-query/hooks/useModalManager.js

@@ -0,0 +1,175 @@
+"use strict";
+
+import { useState, useEffect } from "react";
+import { useModalPersistence } from "./useModalPersistence";
+import { devToolsStorageKeys } from "@buoy-gg/shared-ui";
+
+/**
+ * Custom hook for managing modal states and related query selection
+ * Enhanced with persistence following composition principles
+ * Restores modal state on app restart
+ */
+export function useModalManager() {
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [isDebugModalOpen, setIsDebugModalOpen] = useState(false);
+  const [isEnvModalOpen, setIsEnvModalOpen] = useState(false);
+  const [isSentryModalOpen, setIsSentryModalOpen] = useState(false);
+  const [isStorageModalOpen, setIsStorageModalOpen] = useState(false);
+  const [isNetworkModalOpen, setIsNetworkModalOpen] = useState(false);
+  const [selectedQueryKey, setSelectedQueryKey] = useState(undefined);
+  const [selectedSection, setSelectedSection] = useState(null);
+  const [activeFilter, setActiveFilter] = useState(null);
+  const [isStateRestored, setIsStateRestored] = useState(false); // Default to false to prevent clearing state before restoration
+  const [activeTab, setActiveTab] = useState("queries");
+  const [selectedMutationId, setSelectedMutationId] = useState(undefined);
+
+  // Persistence hook for saving/loading modal state
+  const {
+    loadSavedState
+  } = useModalPersistence({
+    storagePrefix: devToolsStorageKeys.modal.state(),
+    isModalOpen,
+    isDebugModalOpen,
+    isEnvModalOpen,
+    isSentryModalOpen,
+    isStorageModalOpen,
+    isNetworkModalOpen,
+    selectedQueryKey,
+    selectedSection,
+    activeFilter,
+    activeTab,
+    selectedMutationId,
+    isStateRestored
+  });
+
+  // Restore saved modal state on component mount
+  useEffect(() => {
+    const restoreState = async () => {
+      // Don't set to false again if already restoring
+      if (isStateRestored) return;
+      try {
+        const savedState = await loadSavedState();
+        if (savedState) {
+          setIsModalOpen(savedState.isModalOpen);
+          setIsDebugModalOpen(savedState.isDebugModalOpen);
+          setIsEnvModalOpen(savedState.isEnvModalOpen || false);
+          setIsSentryModalOpen(savedState.isSentryModalOpen || false);
+          setIsStorageModalOpen(savedState.isStorageModalOpen || false);
+          setIsNetworkModalOpen(savedState.isNetworkModalOpen || false);
+          if (savedState.selectedQueryKey) {
+            try {
+              const queryKey = JSON.parse(savedState.selectedQueryKey);
+              setSelectedQueryKey(queryKey);
+            } catch {
+              // Silently fail if query key can't be parsed
+            }
+          }
+          if (savedState.selectedSection) {
+            setSelectedSection(savedState.selectedSection);
+          }
+          if (savedState.activeFilter) {
+            setActiveFilter(savedState.activeFilter);
+          }
+          if (savedState.activeTab) {
+            setActiveTab(savedState.activeTab);
+          }
+          if (savedState.selectedMutationId) {
+            setSelectedMutationId(Number(savedState.selectedMutationId));
+          }
+        }
+      } catch {
+        // Silently fail if state can't be restored
+      } finally {
+        // Mark restoration as complete
+        setIsStateRestored(true);
+      }
+    };
+    restoreState();
+  }, [isStateRestored, loadSavedState]);
+  const handleModalDismiss = () => {
+    setIsModalOpen(false);
+    setSelectedQueryKey(undefined);
+    // Note: Keep activeFilter when dismissing - user might want to maintain filter on next open
+  };
+  const handleDebugModalDismiss = () => {
+    setIsDebugModalOpen(false);
+    setSelectedSection(null);
+  };
+  const handleQuerySelect = query => {
+    setSelectedQueryKey(query?.queryKey);
+  };
+  const handleQueryPress = () => {
+    setIsModalOpen(true);
+  };
+  const handleStatusPress = () => {
+    setIsDebugModalOpen(true);
+  };
+  const handleEnvPress = () => {
+    setIsEnvModalOpen(true);
+  };
+  const handleSentryPress = () => {
+    setIsSentryModalOpen(true);
+  };
+  const handleStoragePress = () => {
+    setIsStorageModalOpen(true);
+  };
+  const handleEnvModalDismiss = () => {
+    setIsEnvModalOpen(false);
+  };
+  const handleSentryModalDismiss = () => {
+    setIsSentryModalOpen(false);
+  };
+  const handleStorageModalDismiss = () => {
+    setIsStorageModalOpen(false);
+  };
+  const handleNetworkPress = () => {
+    setIsNetworkModalOpen(true);
+  };
+  const handleNetworkModalDismiss = () => {
+    setIsNetworkModalOpen(false);
+  };
+  const handleMutationSelect = mutation => {
+    setSelectedMutationId(mutation?.mutationId);
+  };
+  const handleTabChange = newTab => {
+    if (newTab !== activeTab) {
+      setSelectedQueryKey(undefined);
+      setSelectedMutationId(undefined);
+      // Reset query status filters when switching tabs (they don't apply to storage)
+      setActiveFilter(null);
+    }
+    setActiveTab(newTab);
+  };
+  return {
+    isModalOpen,
+    isDebugModalOpen,
+    isEnvModalOpen,
+    isSentryModalOpen,
+    isStorageModalOpen,
+    isNetworkModalOpen,
+    selectedQueryKey,
+    selectedSection,
+    activeFilter,
+    isStateRestored,
+    activeTab,
+    selectedMutationId,
+    setSelectedSection,
+    setActiveFilter,
+    setActiveTab,
+    handleModalDismiss,
+    handleDebugModalDismiss,
+    handleEnvModalDismiss,
+    handleSentryModalDismiss,
+    handleStorageModalDismiss,
+    handleNetworkModalDismiss,
+    handleQuerySelect,
+    handleQueryPress,
+    handleStatusPress,
+    handleEnvPress,
+    handleSentryPress,
+    handleStoragePress,
+    handleNetworkPress,
+    handleTabChange,
+    handleMutationSelect
+  };
+}

package/lib/module/react-query/hooks/useModalPersistence.js

@@ -0,0 +1,67 @@
+"use strict";
+
+import { useEffect, useCallback } from "react";
+import { saveModalVisibilityState, loadModalVisibilityState, clearModalVisibilityState } from "../utils/modalStorageOperations";
+/**
+ * Hook for persisting modal state following "Extract Reusable Logic" principle
+ * Manages saving/loading modal visibility and selection state across app restarts
+ */
+export function useModalPersistence({
+  storagePrefix,
+  isModalOpen,
+  isDebugModalOpen,
+  isEnvModalOpen = false,
+  isSentryModalOpen = false,
+  isStorageModalOpen = false,
+  isNetworkModalOpen = false,
+  selectedQueryKey,
+  selectedSection,
+  activeFilter,
+  activeTab,
+  selectedMutationId,
+  isStateRestored
+}) {
+  const saveCurrentState = useCallback(async () => {
+    const state = {
+      isModalOpen,
+      isDebugModalOpen,
+      isEnvModalOpen,
+      isSentryModalOpen,
+      isStorageModalOpen,
+      isNetworkModalOpen,
+      selectedQueryKey: selectedQueryKey ? JSON.stringify(selectedQueryKey) : undefined,
+      selectedSection: selectedSection || undefined,
+      activeFilter: activeFilter || undefined,
+      activeTab: activeTab || undefined,
+      selectedMutationId: selectedMutationId?.toString() || undefined
+    };
+    await saveModalVisibilityState(storagePrefix, state);
+  }, [storagePrefix, isModalOpen, isDebugModalOpen, isEnvModalOpen, isSentryModalOpen, isStorageModalOpen, isNetworkModalOpen, selectedQueryKey, selectedSection, activeFilter, activeTab, selectedMutationId]);
+  const loadSavedState = useCallback(async () => {
+    return await loadModalVisibilityState(storagePrefix);
+  }, [storagePrefix]);
+  const clearSavedState = useCallback(async () => {
+    await clearModalVisibilityState(storagePrefix);
+  }, [storagePrefix]);
+
+  // Auto-save state when modal state changes
+  useEffect(() => {
+    // Don't persist anything until state restoration is complete to avoid race condition
+    if (!isStateRestored) {
+      return;
+    }
+
+    // Only save if a modal is actually open to avoid saving closed state
+    if (isModalOpen || isDebugModalOpen || isEnvModalOpen || isSentryModalOpen || isStorageModalOpen || isNetworkModalOpen) {
+      saveCurrentState();
+    } else {
+      // Clear saved state when all modals are closed
+      clearSavedState();
+    }
+  }, [isModalOpen, isDebugModalOpen, isEnvModalOpen, isSentryModalOpen, isStorageModalOpen, isNetworkModalOpen, selectedQueryKey, selectedSection, activeFilter, activeTab, selectedMutationId, isStateRestored, saveCurrentState, clearSavedState]);
+  return {
+    saveCurrentState,
+    loadSavedState,
+    clearSavedState
+  };
+}

package/lib/module/react-query/hooks/useMutationActionButtons.js

@@ -0,0 +1,18 @@
+"use strict";
+
+import { useMemo } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+/**
+ * Supplies action button metadata for a selected mutation. Currently exposes a remove control but
+ * centralizes logic so future actions stay consistent across the UI.
+ */
+export function useMutationActionButtons(selectedMutation) {
+  const queryClient = useQueryClient();
+  return useMemo(() => [{
+    label: "Remove",
+    bgColorClass: "btnRemove",
+    textColorClass: "btnRemove",
+    disabled: false,
+    onPress: () => queryClient.getMutationCache().remove(selectedMutation)
+  }], [selectedMutation, queryClient]);
+}

package/lib/module/react-query/hooks/useQueryStatusCounts.js

@@ -0,0 +1,108 @@
+"use strict";
+
+import { useEffect, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { getQueryStatusLabel } from "../utils/getQueryStatusLabel";
+/**
+ * Tracks how many queries fall into each status bucket (fresh, stale, fetching, etc.). Uses
+ * cache subscriptions to stay up to date without polling.
+ */
+function useQueryStatusCounts() {
+  const queryClient = useQueryClient();
+  const [counts, setCounts] = useState({
+    fresh: 0,
+    stale: 0,
+    fetching: 0,
+    paused: 0,
+    inactive: 0
+  });
+  useEffect(() => {
+    const updateCounts = () => {
+      const allQueries = queryClient.getQueryCache().getAll();
+      const newCounts = allQueries.reduce((acc, query) => {
+        const status = getQueryStatusLabel(query);
+        acc[status] = (acc[status] || 0) + 1;
+        return acc;
+      }, {
+        fresh: 0,
+        stale: 0,
+        fetching: 0,
+        paused: 0,
+        inactive: 0
+      });
+      setTimeout(() => setCounts(newCounts), 0);
+    };
+
+    // Perform an initial update
+    updateCounts();
+
+    // Subscribe to the query cache to run updates on changes
+    const unsubscribe = queryClient.getQueryCache().subscribe(updateCounts);
+
+    // Cleanup the subscription when the component unmounts
+    return () => unsubscribe();
+  }, [queryClient]);
+  return counts;
+}
+export default useQueryStatusCounts;
+
+// Mutation status counts hook
+
+/**
+ * Companion hook for query status counts that groups mutations by status and pause state.
+ */
+export function useMutationStatusCounts() {
+  const queryClient = useQueryClient();
+  const [counts, setCounts] = useState({
+    pending: 0,
+    success: 0,
+    error: 0,
+    paused: 0,
+    idle: 0
+  });
+  useEffect(() => {
+    const updateCounts = () => {
+      const allMutations = queryClient.getMutationCache().getAll();
+      const newCounts = allMutations.reduce((acc, mutation) => {
+        const status = mutation.state.status;
+        const isPaused = mutation.state.isPaused;
+        if (isPaused) {
+          acc.paused++;
+        } else {
+          switch (status) {
+            case "idle":
+              acc.idle++;
+              break;
+            case "pending":
+              acc.pending++;
+              break;
+            case "success":
+              acc.success++;
+              break;
+            case "error":
+              acc.error++;
+              break;
+          }
+        }
+        return acc;
+      }, {
+        pending: 0,
+        success: 0,
+        error: 0,
+        paused: 0,
+        idle: 0
+      });
+      setTimeout(() => setCounts(newCounts), 0);
+    };
+
+    // Perform an initial update
+    updateCounts();
+
+    // Subscribe to the mutation cache to run updates on changes
+    const unsubscribe = queryClient.getMutationCache().subscribe(updateCounts);
+
+    // Cleanup the subscription when the component unmounts
+    return () => unsubscribe();
+  }, [queryClient]);
+  return counts;
+}

package/lib/module/react-query/hooks/useReactQueryState.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Custom hook for getting React Query state information
+ * Separated from UI concerns following composition principles
+ */
+export function useReactQueryState(queryClient) {
+  const getReactBuoySubtitle = () => {
+    try {
+      const allQueries = queryClient.getQueryCache().getAll();
+      const allMutations = queryClient.getMutationCache().getAll();
+      return `${allQueries.length} queries • ${allMutations.length} mutations`;
+    } catch {
+      return "Data management & cache inspector";
+    }
+  };
+  return {
+    getReactBuoySubtitle
+  };
+}

package/lib/module/react-query/hooks/useSelectedMutation.js

@@ -0,0 +1,27 @@
+"use strict";
+
+import { useEffect, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+/**
+ * Watches the mutation cache for a specific mutation id. Useful when the UI needs to follow
+ * mutation lifecycle events (loading, success, error) for a focused inspection panel.
+ */
+export function useGetMutationById(mutationId) {
+  const queryClient = useQueryClient();
+  const [selectedMutation, setSelectedMutation] = useState(undefined);
+  useEffect(() => {
+    const updateSelectedMutation = () => {
+      if (mutationId !== undefined) {
+        const mutation = queryClient.getMutationCache().getAll().find(m => m.mutationId === mutationId);
+        setSelectedMutation(mutation);
+      } else {
+        setSelectedMutation(undefined);
+      }
+    };
+    setTimeout(updateSelectedMutation, 0);
+    const unsubscribe = queryClient.getMutationCache().subscribe(updateSelectedMutation);
+    return () => unsubscribe();
+  }, [queryClient, mutationId]);
+  return selectedMutation;
+}