@buoy-gg/react-query 1.7.2

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

@@ -0,0 +1,92 @@
+"use strict";
+
+import { useEffect, useState, useRef } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+/**
+ * Custom hook to track a single query by its queryKey with live updates
+ * Optimized to only re-render when the specific query changes
+ */
+
+/**
+ * Returns a single query instance matching the provided key and resubscribes whenever the cache
+ * entry changes. Ideal for detail panes where live updates are required without scanning the
+ * entire query cache.
+ */
+export function useGetQueryByQueryKey(queryKey) {
+  const {
+    query
+  } = useGetQueryByQueryKeyWithVersion(queryKey);
+  return query;
+}
+
+/**
+ * Returns a single query instance with a version number that increments on each cache update.
+ * Use the version as a dependency or key to ensure child components re-render when query state changes.
+ *
+ * This is necessary because React Query mutates the Query object in place, so React's
+ * shallow comparison won't detect changes to nested properties like query.state.status.
+ */
+export function useGetQueryByQueryKeyWithVersion(queryKey) {
+  const queryClient = useQueryClient();
+  const [queryState, setQueryState] = useState({
+    query: undefined,
+    version: 0
+  });
+  const queryHashRef = useRef(undefined);
+  useEffect(() => {
+    if (!queryKey) {
+      setQueryState({
+        query: undefined,
+        version: 0
+      });
+      queryHashRef.current = undefined;
+      return;
+    }
+
+    // Get initial query state
+    const query = queryClient.getQueryCache().find({
+      queryKey,
+      exact: true
+    });
+    setQueryState({
+      query,
+      version: 0
+    });
+
+    // Store the stringified queryKey for comparison
+    const queryKeyString = JSON.stringify(queryKey);
+    queryHashRef.current = queryKeyString;
+
+    // Subscribe to query cache changes but only update if our specific query changed
+    const unsubscribe = queryClient.getQueryCache().subscribe(event => {
+      // Only process events for our specific query
+      if (event.type === "updated" || event.type === "added" || event.type === "removed") {
+        if ("query" in event && event.query) {
+          // Check if the event is for our query by comparing the stringified keys
+          const eventQueryKeyString = JSON.stringify(event.query.queryKey);
+          const isOurQuery = eventQueryKeyString === queryHashRef.current;
+          if (isOurQuery) {
+            if (event.type === "removed") {
+              setQueryState({
+                query: undefined,
+                version: 0
+              });
+            } else {
+              // For 'updated' and 'added' events, use the query from the event
+              // Update both the query and increment version to force re-renders
+              setQueryState(prev => ({
+                query: event.query,
+                version: prev.version + 1
+              }));
+            }
+          }
+        }
+      }
+    });
+
+    // Cleanup subscription when component unmounts
+    return () => unsubscribe();
+  }, [queryClient, queryKey]);
+  return queryState;
+}

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

@@ -0,0 +1,25 @@
+"use strict";
+
+import { useMemo } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { getStorageQueryCounts } from "../utils/getStorageQueryCounts";
+
+/**
+ * Hook to get storage query counts with proper memoization
+ * Following rule3 - Component Composition principles:
+ * - Extract Reusable Logic: Dedicated hook for storage counting
+ * - Rigor and Justification: Proper memoization only where proven necessary
+ * - Stable references: useMemo with correct dependencies to prevent infinite loops
+ */
+export function useStorageQueryCounts() {
+  const queryClient = useQueryClient();
+
+  // Memoize counts based on query cache state changes
+  // This prevents infinite re-renders by stabilizing the counts object
+  const counts = useMemo(() => {
+    const allQueries = queryClient.getQueryCache().getAll();
+    return getStorageQueryCounts(allQueries);
+  }, [queryClient]); // Depend on queryClient, not the result of getAll()
+
+  return counts;
+}

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

@@ -0,0 +1,64 @@
+"use strict";
+
+import { useEffect, useState, useRef } from "react";
+import { onlineManager } from "@tanstack/react-query";
+import { devToolsStorageKeys, safeGetItem, safeSetItem } from "@buoy-gg/shared-ui";
+
+/**
+ * Synchronizes a local Wi-Fi toggle with React Query’s `onlineManager`, persisting the selection
+ * so developers can simulate offline mode across reloads.
+ */
+export function useWifiState() {
+  const [isOnline, setIsOnline] = useState(() => onlineManager.isOnline());
+  const hasLoadedPersistedState = useRef(false);
+
+  // Load persisted WiFi state on mount
+  useEffect(() => {
+    if (hasLoadedPersistedState.current) return;
+    const loadPersistedState = async () => {
+      try {
+        const savedState = await safeGetItem(devToolsStorageKeys.settings.wifiEnabled());
+        if (savedState !== null) {
+          const isEnabled = savedState === "true";
+          setIsOnline(isEnabled);
+          onlineManager.setOnline(isEnabled);
+        }
+        hasLoadedPersistedState.current = true;
+      } catch (error) {
+        // Failed to load WiFi state
+      }
+    };
+    loadPersistedState();
+  }, []);
+
+  // Save WiFi state when it changes
+  const saveWifiState = async enabled => {
+    try {
+      await safeSetItem(devToolsStorageKeys.settings.wifiEnabled(), enabled.toString());
+    } catch (error) {
+      // Failed to save WiFi state
+    }
+  };
+  const handleWifiToggle = () => {
+    const newOnlineState = !isOnline;
+    setIsOnline(newOnlineState);
+    onlineManager.setOnline(newOnlineState);
+    saveWifiState(newOnlineState);
+  };
+
+  // Listen to online manager changes to keep state in sync
+  useEffect(() => {
+    const unsubscribe = onlineManager.subscribe(online => {
+      setIsOnline(online);
+      // Only save if we've already loaded the persisted state to avoid overwriting on mount
+      if (hasLoadedPersistedState.current) {
+        saveWifiState(online);
+      }
+    });
+    return unsubscribe;
+  }, []);
+  return {
+    isOnline,
+    handleWifiToggle
+  };
+}

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

@@ -0,0 +1,3 @@
+"use strict";
+
+export * from "./ReactQueryDevTools";

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

@@ -0,0 +1,3 @@
+"use strict";
+
+export * from "./types";

package/lib/module/react-query/types/types.js

@@ -0,0 +1,10 @@
+"use strict";
+
+// Shared type definitions for the dev tools
+
+/**
+ * Type guard that narrows a value to a plain object (excluding arrays, Dates, Maps, etc.).
+ */
+export function isPlainObject(value) {
+  return value !== null && value !== undefined && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date) && !(value instanceof Error) && !(value instanceof Map) && !(value instanceof Set) && !(value instanceof RegExp) && typeof value !== "function";
+}

package/lib/module/react-query/utils/actions/deleteItem.js

@@ -0,0 +1,19 @@
+"use strict";
+
+import { deleteNestedDataByPath } from "../deleteNestedDataByPath";
+export default function deleteItem({
+  activeQuery,
+  dataPath,
+  queryClient
+}) {
+  if (!dataPath) {
+    // Early return if path is missing
+    return;
+  }
+  const oldData = activeQuery.state.data;
+  const newData = deleteNestedDataByPath(oldData, dataPath);
+
+  // Force a new object reference to ensure React detects the change
+  const forceNewReference = JSON.parse(JSON.stringify(newData));
+  queryClient.setQueryData(activeQuery.queryKey, forceNewReference);
+}

package/lib/module/react-query/utils/actions/invalidate.js

@@ -0,0 +1,9 @@
+"use strict";
+
+export default function invalidate({
+  query,
+  queryClient
+}) {
+  // This matches the ACTION-INVALIDATE case from the external sync system
+  queryClient.invalidateQueries(query);
+}

package/lib/module/react-query/utils/actions/refetch.js

@@ -0,0 +1,11 @@
+"use strict";
+
+export default function refetch({
+  query
+}) {
+  // This matches the ACTION-REFETCH case from the external sync system
+  const promise = query.fetch();
+  promise.catch(() => {
+    // Silently handle fetch errors
+  });
+}

package/lib/module/react-query/utils/actions/remove.js

@@ -0,0 +1,8 @@
+"use strict";
+
+export default function remove({
+  query,
+  queryClient
+}) {
+  queryClient.removeQueries(query);
+}

package/lib/module/react-query/utils/actions/reset.js

@@ -0,0 +1,11 @@
+"use strict";
+
+export default function reset({
+  query,
+  queryClient
+}) {
+  queryClient.resetQueries({
+    queryKey: query.queryKey,
+    exact: true
+  });
+}

package/lib/module/react-query/utils/actions/triggerError.js

@@ -0,0 +1,26 @@
+"use strict";
+
+export default function triggerError({
+  query,
+  queryClient
+}) {
+  if (query.state.status !== "error") {
+    // --ACTION-TRIGGER-ERROR logic--
+    // This matches the ACTION-TRIGGER-ERROR case from the external sync system
+    const error = new Error("Unknown error from devtools");
+    const __previousQueryOptions = query.options;
+    query.setState({
+      status: "error",
+      error,
+      fetchMeta: {
+        ...query.state.fetchMeta,
+        // @ts-expect-error This does exist
+        __previousQueryOptions
+      }
+    });
+  } else {
+    // --ACTION-RESTORE-ERROR logic--
+    // This matches the ACTION-RESTORE-ERROR case from the external sync system
+    queryClient.resetQueries(query);
+  }
+}

package/lib/module/react-query/utils/actions/triggerLoading.js

@@ -0,0 +1,47 @@
+"use strict";
+
+export default function triggerLoading({
+  query
+}) {
+  if (query.state.data === undefined) {
+    // --ACTION-RESTORE-LOADING logic--
+    // This matches the ACTION-RESTORE-LOADING case from the external sync system
+    const previousState = query.state;
+    const previousOptions = query.state.fetchMeta ? query.state.fetchMeta.__previousQueryOptions : null;
+    query.cancel({
+      silent: true
+    });
+    query.setState({
+      ...previousState,
+      fetchStatus: "idle",
+      fetchMeta: null
+    });
+    if (previousOptions) {
+      query.fetch(previousOptions);
+    }
+  } else {
+    // --ACTION-TRIGGER-LOADING logic--
+    // This matches the ACTION-TRIGGER-LOADING case from the external sync system
+    const __previousQueryOptions = query.options;
+
+    // Trigger a fetch in order to trigger suspense as well.
+    query.fetch({
+      ...__previousQueryOptions,
+      queryFn: () => {
+        return new Promise(() => {
+          // Never resolve - simulates perpetual loading
+        });
+      },
+      gcTime: -1
+    });
+    query.setState({
+      data: undefined,
+      status: "pending",
+      fetchMeta: {
+        ...query.state.fetchMeta,
+        // @ts-expect-error This does exist
+        __previousQueryOptions
+      }
+    });
+  }
+}

package/lib/module/react-query/utils/deleteNestedDataByPath.js

@@ -0,0 +1,51 @@
+"use strict";
+
+/**
+ * Deletes nested data by path
+ *
+ * @param {unknown} oldData Data to be updated
+ * @param {Array<string>} deletePath Path to the data to be deleted
+ * @returns newData without the deleted items by path
+ */
+export const deleteNestedDataByPath = (oldData, deletePath) => {
+  if (oldData instanceof Map) {
+    const newData = new Map(oldData);
+    if (deletePath.length === 1) {
+      newData.delete(deletePath[0]);
+      return newData;
+    }
+    const [head, ...tail] = deletePath;
+    newData.set(head, deleteNestedDataByPath(newData.get(head), tail));
+    return newData;
+  }
+  if (oldData instanceof Set) {
+    const setAsArray = deleteNestedDataByPath(Array.from(oldData), deletePath);
+    return new Set(setAsArray);
+  }
+  if (Array.isArray(oldData)) {
+    const newData = [...oldData];
+    if (deletePath.length === 1) {
+      return newData.filter((_, idx) => idx.toString() !== deletePath[0]);
+    }
+    const [head, ...tail] = deletePath;
+
+    // @ts-expect-error NAS
+    newData[head] = deleteNestedDataByPath(newData[head], tail);
+    return newData;
+  }
+  if (oldData instanceof Object) {
+    const newData = {
+      ...oldData
+    };
+    if (deletePath.length === 1) {
+      // @ts-expect-error NAS
+      delete newData[deletePath[0]];
+      return newData;
+    }
+    const [head, ...tail] = deletePath;
+    // @ts-expect-error NAS
+    newData[head] = deleteNestedDataByPath(newData[head], tail);
+    return newData;
+  }
+  return oldData;
+};

package/lib/module/react-query/utils/formatRelativeTime.js

@@ -0,0 +1,25 @@
+"use strict";
+
+/**
+ * Formats a timestamp as a relative time string (e.g., "10s ago", "5m ago", "2h ago")
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns Formatted relative time string
+ */
+export function formatRelativeTime(timestamp) {
+  const now = Date.now();
+  const diff = now - timestamp;
+  const seconds = Math.floor(diff / 1000);
+  if (seconds < 60) {
+    return `${seconds}s ago`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m ago`;
+  }
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    return `${hours}h ago`;
+  }
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

package/lib/module/react-query/utils/getQueryStatusColor.js

@@ -0,0 +1,12 @@
+"use strict";
+
+/**
+ * Maps a query’s runtime state to one of the predefined status color tokens used in the UI.
+ */
+export function getQueryStatusColor({
+  queryState,
+  observerCount,
+  isStale
+}) {
+  return queryState.fetchStatus === "fetching" ? "blue" : !observerCount ? "gray" : queryState.fetchStatus === "paused" ? "purple" : isStale ? "yellow" : "green";
+}

package/lib/module/react-query/utils/getQueryStatusLabel.js

@@ -0,0 +1,13 @@
+"use strict";
+
+/**
+ * Converts a query object into a human-friendly status string for badge rendering.
+ * Priority order: disabled > fetching > inactive > paused > stale > fresh
+ */
+export function getQueryStatusLabel(query) {
+  // Check disabled first - disabled queries won't automatically fetch
+  if (query.isDisabled()) {
+    return "disabled";
+  }
+  return query.state.fetchStatus === "fetching" ? "fetching" : !query.getObserversCount() ? "inactive" : query.state.fetchStatus === "paused" ? "paused" : query.isStale() ? "stale" : "fresh";
+}

package/lib/module/react-query/utils/getStorageQueryCounts.js

@@ -0,0 +1,31 @@
+"use strict";
+
+import { isStorageQuery, getStorageType, getCleanStorageKey } from "./storageQueryUtils";
+import { isDevToolsStorageKey } from "@buoy-gg/shared-ui";
+/**
+ * Calculate counts for each storage type from storage queries
+ * Following performance principles: no unnecessary memoization [[memory:4875074]]
+ */
+export function getStorageQueryCounts(queries) {
+  const counts = {
+    mmkv: 0,
+    async: 0,
+    secure: 0,
+    total: 0
+  };
+
+  // Filter to storage queries only, then count by type
+  const storageQueries = queries.filter(query => isStorageQuery(query.queryKey));
+  storageQueries.forEach(query => {
+    const storageType = getStorageType(query.queryKey);
+    if (storageType) {
+      // Filter out dev tool keys from the counts
+      const cleanKey = getCleanStorageKey(query.queryKey);
+      if (!isDevToolsStorageKey(cleanKey)) {
+        counts[storageType]++;
+        counts.total++;
+      }
+    }
+  });
+  return counts;
+}

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

@@ -0,0 +1,27 @@
+"use strict";
+
+// Action utilities (map default exports to named for consistency)
+export { default as invalidate } from "./actions/invalidate";
+export { default as refetch } from "./actions/refetch";
+export { default as reset } from "./actions/reset";
+export { default as remove } from "./actions/remove";
+export { default as deleteItem } from "./actions/deleteItem";
+export { default as triggerError } from "./actions/triggerError";
+export { default as triggerLoading } from "./actions/triggerLoading";
+
+// Query status utilities
+export * from "./getQueryStatusLabel";
+export * from "./getQueryStatusColor";
+
+// Storage utilities
+export * from "./getStorageQueryCounts";
+export * from "./storageQueryUtils";
+export * from "./modalStorageOperations";
+
+// Data manipulation utilities
+export * from "./updateNestedDataByPath";
+export * from "./deleteNestedDataByPath";
+export { safeStringify } from "@buoy-gg/shared-ui";
+
+// Display utilities
+export { displayValue, parseDisplayValue } from "@buoy-gg/shared-ui";

package/lib/module/react-query/utils/modalStorageOperations.js

@@ -0,0 +1,117 @@
+"use strict";
+
+import { safeSetItem, safeGetItem } from "@buoy-gg/shared-ui";
+
+// Helper functions for persisting panel state using shared storage wrapper
+const setItem = async (key, value) => {
+  await safeSetItem(key, value);
+};
+const getItem = async key => {
+  return safeGetItem(key);
+};
+// Storage operations
+/**
+ * Persist the draggable panel dimensions so future sessions can restore the last window size.
+ */
+export const savePanelDimensions = async (storagePrefix, dimensions) => {
+  try {
+    await setItem(`${storagePrefix}_panel_dimensions`, JSON.stringify(dimensions));
+  } catch {
+    // Silently fail - persistence is optional
+  }
+};
+
+/** Remember the last snap height of the panel for bottom-sheet style layouts. */
+export const savePanelHeight = async (storagePrefix, height) => {
+  try {
+    await setItem(`${storagePrefix}_panel_height`, height.toString());
+  } catch {
+    // Silently fail - persistence is optional
+  }
+};
+
+/**
+ * Persist whether the panel was in floating mode so we can reopen at the same presentation style.
+ */
+export const saveFloatingMode = async (storagePrefix, isFloating) => {
+  try {
+    await setItem(`${storagePrefix}_is_floating_mode`, isFloating.toString());
+  } catch {
+    // Silently fail - persistence is optional
+  }
+};
+
+/**
+ * Retrieve persisted panel geometry and presentation mode. Returns null values when nothing was
+ * previously stored so callers can fall back to defaults.
+ */
+export const loadPanelState = async storagePrefix => {
+  try {
+    const [dimensionsStr, heightStr, floatingModeStr] = await Promise.all([getItem(`${storagePrefix}_panel_dimensions`), getItem(`${storagePrefix}_panel_height`), getItem(`${storagePrefix}_is_floating_mode`)]);
+    const dimensions = dimensionsStr ? JSON.parse(dimensionsStr) : null;
+    const height = heightStr ? parseInt(heightStr, 10) : null;
+    const isFloating = floatingModeStr ? floatingModeStr === "true" : null;
+    return {
+      dimensions,
+      height,
+      isFloating
+    };
+  } catch {
+    // Return defaults on error
+    return {
+      dimensions: null,
+      height: null,
+      isFloating: null
+    };
+  }
+};
+
+// Modal visibility state operations
+/**
+ * Persist the comprehensive modal visibility state (open flags, selected query, etc.). Stored as a
+ * single JSON blob keyed by the provided prefix.
+ */
+export const saveModalVisibilityState = async (storagePrefix, state) => {
+  try {
+    const stateJson = JSON.stringify(state);
+    // storagePrefix already contains the full key, don't append _modal_state
+    const key = storagePrefix;
+    await setItem(key, stateJson);
+  } catch {
+    // Silently fail - persistence is a nice-to-have feature
+  }
+};
+
+/**
+ * Read previously persisted modal visibility state. Returns null when no entry is stored or the
+ * payload cannot be parsed.
+ */
+export const loadModalVisibilityState = async storagePrefix => {
+  try {
+    // storagePrefix already contains the full key, don't append _modal_state
+    const key = storagePrefix;
+    const stateStr = await getItem(key);
+    if (stateStr && stateStr !== "") {
+      const parsed = JSON.parse(stateStr);
+      return parsed;
+    }
+    return null;
+  } catch {
+    // Silently fail - persistence is a nice-to-have feature
+    return null;
+  }
+};
+
+/**
+ * Clear the cached modal visibility state. Useful when all modals close so we avoid reopening
+ * unintentionally on the next session.
+ */
+export const clearModalVisibilityState = async storagePrefix => {
+  try {
+    // storagePrefix already contains the full key, don't append _modal_state
+    const key = storagePrefix;
+    await setItem(key, "");
+  } catch {
+    // Silently fail - persistence is a nice-to-have feature
+  }
+};