@rozenite/tanstack-query-plugin 1.13.0 → 2.1.0

package/src/react-native/agent/useTanStackQueryAgentTools.ts

@@ -1,19 +1,14 @@
 import { useEffect, useMemo } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { useRozenitePluginAgentTool } from '@rozenite/agent-bridge';
-import {
-  createTanStackQueryAgentController,
-} from './tanstack-query-agent';
+import { createTanStackQueryAgentController } from './tanstack-query-agent';
 import {
   TANSTACK_QUERY_AGENT_PLUGIN_ID,
   tanstackQueryToolDefinitions,
 } from '../../shared/agent-tools';
 
 export const useTanStackQueryAgentTools = (queryClient: QueryClient) => {
-  const controller = useMemo(
-    () => createTanStackQueryAgentController(queryClient),
-    [queryClient]
-  );
+  const controller = useMemo(() => createTanStackQueryAgentController(queryClient), [queryClient]);
 
   useEffect(() => {
     const unsubscribeQueryCache = queryClient

package/src/react-native/devtools-actions.ts

@@ -2,10 +2,7 @@ import { QueryClient } from '@tanstack/react-query';
 import { DevToolsActionType } from '../shared/types';
 
 type QueryScopedActionInput = {
-  type: Exclude<
-    DevToolsActionType,
-    'CLEAR_MUTATION_CACHE' | 'CLEAR_QUERY_CACHE'
-  >;
+  type: Exclude<DevToolsActionType, 'CLEAR_MUTATION_CACHE' | 'CLEAR_QUERY_CACHE'>;
   queryHash: string;
   metadata?: {
     data?: unknown;
@@ -17,9 +14,7 @@ type CacheScopedActionInput = {
   queryHash?: string;
 };
 
-export type TanStackQueryDevtoolsActionInput =
-  | QueryScopedActionInput
-  | CacheScopedActionInput;
+export type TanStackQueryDevtoolsActionInput = QueryScopedActionInput | CacheScopedActionInput;
 
 const getActiveQuery = (queryClient: QueryClient, queryHash?: string) => {
   if (!queryHash) {
@@ -52,9 +47,7 @@ export const applyTanStackQueryDevtoolsAction = async (
     }
 
     case 'CLEAR_MUTATION_CACHE': {
-      const mutationCountBefore = queryClient
-        .getMutationCache()
-        .getAll().length;
+      const mutationCountBefore = queryClient.getMutationCache().getAll().length;
       queryClient.getMutationCache().clear();
       return {
         applied: true,

package/src/react-native/useHandleDevToolsMessages.ts

@@ -12,22 +12,18 @@ export const useHandleDevToolsMessages = (
       return;
     }
 
-    const subscription = client.onMessage(
-      'devtools-action',
-      ({ type, queryHash, metadata }) => {
-        void applyTanStackQueryDevtoolsAction(queryClient, {
-          type,
-          queryHash,
-          metadata,
-        }).catch((error) => {
-          const message =
-            error instanceof Error ? error.message : String(error);
-          console.warn(
-            `[Rozenite, tanstack-query-plugin] Failed to apply devtools action "${type}": ${message}`,
-          );
-        });
-      },
-    );
+    const subscription = client.onMessage('devtools-action', ({ type, queryHash, metadata }) => {
+      void applyTanStackQueryDevtoolsAction(queryClient, {
+        type,
+        queryHash,
+        metadata,
+      }).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(
+          `[Rozenite, tanstack-query-plugin] Failed to apply devtools action "${type}": ${message}`,
+        );
+      });
+    });
 
     return () => {
       subscription.remove();

package/src/react-native/useHandleInitialData.ts

@@ -5,7 +5,7 @@ import { dehydrateQueryClient } from '../shared/dehydrate';
 
 export const useHandleInitialData = (
   queryClient: QueryClient,
-  client: TanStackQueryPluginClient | null
+  client: TanStackQueryPluginClient | null,
 ) => {
   useEffect(() => {
     if (!client) {
@@ -17,6 +17,13 @@ export const useHandleInitialData = (
       client.send('sync-data', { data: dehydratedState });
     });
 
+    // This hook runs last in `useTanStackQueryDevTools`, so by the time the
+    // panel reacts to this every handler is listening. The panel is recreated on
+    // every app reload and asks for the cache as soon as it boots, which usually
+    // beats the app's React tree to the punch; without this its only request is
+    // dropped and the panel stays empty until the app is restarted.
+    client.send('device-ready', {});
+
     return () => {
       subscription.remove();
     };

package/src/react-native/useSyncTanStackCache.ts

@@ -6,20 +6,14 @@ import {
 import { useEffect, useMemo, useRef } from 'react';
 import equal from 'fast-deep-equal';
 import { TanStackQueryPluginClient } from '../shared/messaging';
-import {
-  dehydrateQuery,
-  dehydrateMutation,
-  dehydrateObservers,
-} from '../shared/dehydrate';
+import { dehydrateQuery, dehydrateMutation, dehydrateObservers } from '../shared/dehydrate';
 import { SerializableObserver, PartialQueryState } from '../shared/types';
 
 export const useSyncTanStackCache = (
   queryClient: QueryClient,
-  client: TanStackQueryPluginClient | null
+  client: TanStackQueryPluginClient | null,
 ) => {
-  const previousObserversRef = useRef<Map<string, SerializableObserver[]>>(
-    new Map()
-  );
+  const previousObserversRef = useRef<Map<string, SerializableObserver[]>>(new Map());
 
   const handler = useMemo(() => {
     return (event: QueryCacheNotifyEvent | MutationCacheNotifyEvent): void => {
@@ -187,9 +181,7 @@ export const useSyncTanStackCache = (
           type === 'observerOptionsUpdated'
         ) {
           const dehydratedObservers = dehydrateObservers(query);
-          const previousObservers = previousObserversRef.current.get(
-            query.queryHash
-          );
+          const previousObservers = previousObserversRef.current.get(query.queryHash);
 
           // For observerOptionsUpdated, only send if the observers actually changed
           if (type === 'observerOptionsUpdated' && previousObservers) {
@@ -199,10 +191,7 @@ export const useSyncTanStackCache = (
             }
           }
 
-          previousObserversRef.current.set(
-            query.queryHash,
-            dehydratedObservers
-          );
+          previousObserversRef.current.set(query.queryHash, dehydratedObservers);
 
           client.send('sync-query-event', {
             type,
@@ -231,12 +220,8 @@ export const useSyncTanStackCache = (
       return;
     }
 
-    const mutationCacheSubscription = queryClient
-      .getMutationCache()
-      .subscribe(handler);
-    const queryCacheSubscription = queryClient
-      .getQueryCache()
-      .subscribe(handler);
+    const mutationCacheSubscription = queryClient.getMutationCache().subscribe(handler);
+    const queryCacheSubscription = queryClient.getQueryCache().subscribe(handler);
 
     return () => {
       mutationCacheSubscription();

package/src/shared/agent-tools.ts

@@ -1,5 +1,6 @@
 import {
   defineAgentToolContract,
+  definePaginatedAgentToolContract,
   type AgentToolContract,
   type JSONSchema7,
 } from '@rozenite/agent-shared';
@@ -17,10 +18,9 @@ export type TanStackQueryAgentQueryHashInput = {
   queryHash: string;
 };
 
-export type TanStackQueryAgentQueryToggleInput =
-  TanStackQueryAgentQueryHashInput & {
-    enabled: boolean;
-  };
+export type TanStackQueryAgentQueryToggleInput = TanStackQueryAgentQueryHashInput & {
+  enabled: boolean;
+};
 
 export type TanStackQueryAgentMutationIdInput = {
   mutationId: number;
@@ -219,8 +219,7 @@ export const tanstackQueryToolDefinitions = {
     TanStackQueryGetCacheSummaryResult
   >({
     name: 'get-cache-summary',
-    description:
-      'Return aggregate TanStack Query cache health and count information.',
+    description: 'Return aggregate TanStack Query cache health and count information.',
     inputSchema: emptyInputSchema,
   }),
   getOnlineStatus: defineAgentToolContract<
@@ -236,8 +235,7 @@ export const tanstackQueryToolDefinitions = {
     TanStackQuerySetOnlineStatusResult
   >({
     name: 'set-online-status',
-    description:
-      'Set the TanStack Query onlineManager status for testing offline/online behavior.',
+    description: 'Set the TanStack Query onlineManager status for testing offline/online behavior.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -249,7 +247,7 @@ export const tanstackQueryToolDefinitions = {
       required: ['online'],
     },
   }),
-  listQueries: defineAgentToolContract<
+  listQueries: definePaginatedAgentToolContract<
     TanStackQueryListQueriesArgs,
     TanStackQueryListQueriesResult
   >({
@@ -259,24 +257,36 @@ export const tanstackQueryToolDefinitions = {
       type: 'object',
       properties: paginationProperties,
     },
+    pagination: {
+      kind: 'cursor',
+      fields: [
+        'queryHash',
+        'queryKey',
+        'status',
+        'fetchStatus',
+        'observersCount',
+        'isInvalidated',
+        'dataUpdatedAt',
+        'errorUpdatedAt',
+        'hasData',
+        'hasError',
+      ],
+      defaultFields: ['queryHash', 'queryKey', 'status', 'fetchStatus', 'hasError'],
+    },
   }),
   getQueryDetails: defineAgentToolContract<
     TanStackQueryGetQueryDetailsArgs,
     TanStackQueryGetQueryDetailsResult
   >({
     name: 'get-query-details',
-    description:
-      'Return a JSON-safe TanStack Query query snapshot and observer summary.',
+    description: 'Return a JSON-safe TanStack Query query snapshot and observer summary.',
     inputSchema: {
       type: 'object',
       properties: queryActionProperties,
       required: ['queryHash'],
     },
   }),
-  refetchQuery: defineAgentToolContract<
-    TanStackQueryRefetchQueryArgs,
-    TanStackQueryActionResult
-  >({
+  refetchQuery: defineAgentToolContract<TanStackQueryRefetchQueryArgs, TanStackQueryActionResult>({
     name: 'refetch-query',
     description: 'Refetch a TanStack Query query by queryHash.',
     inputSchema: {
@@ -298,32 +308,30 @@ export const tanstackQueryToolDefinitions = {
         ...queryActionProperties,
         enabled: {
           type: 'boolean',
-          description:
-            'Whether the loading-state simulation should be enabled.',
+          description: 'Whether the loading-state simulation should be enabled.',
         },
       },
       required: ['queryHash', 'enabled'],
     },
   }),
-  setQueryError: defineAgentToolContract<
-    TanStackQuerySetQueryErrorArgs,
-    TanStackQueryActionResult
-  >({
-    name: 'set-query-error',
-    description:
-      'Enable or disable TanStack Query error-state simulation for a query by queryHash.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...queryActionProperties,
-        enabled: {
-          type: 'boolean',
-          description: 'Whether the error-state simulation should be enabled.',
+  setQueryError: defineAgentToolContract<TanStackQuerySetQueryErrorArgs, TanStackQueryActionResult>(
+    {
+      name: 'set-query-error',
+      description:
+        'Enable or disable TanStack Query error-state simulation for a query by queryHash.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          ...queryActionProperties,
+          enabled: {
+            type: 'boolean',
+            description: 'Whether the error-state simulation should be enabled.',
+          },
         },
+        required: ['queryHash', 'enabled'],
       },
-      required: ['queryHash', 'enabled'],
     },
-  }),
+  ),
   invalidateQuery: defineAgentToolContract<
     TanStackQueryInvalidateQueryArgs,
     TanStackQueryActionResult
@@ -336,10 +344,7 @@ export const tanstackQueryToolDefinitions = {
       required: ['queryHash'],
     },
   }),
-  resetQuery: defineAgentToolContract<
-    TanStackQueryResetQueryArgs,
-    TanStackQueryActionResult
-  >({
+  resetQuery: defineAgentToolContract<TanStackQueryResetQueryArgs, TanStackQueryActionResult>({
     name: 'reset-query',
     description: 'Reset a TanStack Query query by queryHash.',
     inputSchema: {
@@ -348,10 +353,7 @@ export const tanstackQueryToolDefinitions = {
       required: ['queryHash'],
     },
   }),
-  removeQuery: defineAgentToolContract<
-    TanStackQueryRemoveQueryArgs,
-    TanStackQueryActionResult
-  >({
+  removeQuery: defineAgentToolContract<TanStackQueryRemoveQueryArgs, TanStackQueryActionResult>({
     name: 'remove-query',
     description: 'Remove a TanStack Query query from the cache by queryHash.',
     inputSchema: {
@@ -368,7 +370,7 @@ export const tanstackQueryToolDefinitions = {
     description: 'Clear the full TanStack Query query cache.',
     inputSchema: emptyInputSchema,
   }),
-  listMutations: defineAgentToolContract<
+  listMutations: definePaginatedAgentToolContract<
     TanStackQueryListMutationsArgs,
     TanStackQueryListMutationsResult
   >({
@@ -378,14 +380,27 @@ export const tanstackQueryToolDefinitions = {
       type: 'object',
       properties: paginationProperties,
     },
+    pagination: {
+      kind: 'cursor',
+      fields: [
+        'mutationId',
+        'mutationKey',
+        'status',
+        'isPaused',
+        'submittedAt',
+        'failureCount',
+        'hasData',
+        'hasError',
+      ],
+      defaultFields: ['mutationId', 'mutationKey', 'status', 'hasError'],
+    },
   }),
   getMutationDetails: defineAgentToolContract<
     TanStackQueryGetMutationDetailsArgs,
     TanStackQueryGetMutationDetailsResult
   >({
     name: 'get-mutation-details',
-    description:
-      'Return a JSON-safe TanStack Query mutation snapshot for a mutationId.',
+    description: 'Return a JSON-safe TanStack Query mutation snapshot for a mutationId.',
     inputSchema: {
       type: 'object',
       properties: mutationActionProperties,

package/src/shared/dehydrate.ts

@@ -32,9 +32,7 @@ export const dehydrateMutation = (mutation: Mutation): SerializableMutation => {
   };
 };
 
-export const dehydrateQueryClient = (
-  queryClient: QueryClient
-): SerializableQueryClient => {
+export const dehydrateQueryClient = (queryClient: QueryClient): SerializableQueryClient => {
   return {
     queries: queryClient.getQueryCache().getAll().map(dehydrateQuery),
     mutations: queryClient.getMutationCache().getAll().map(dehydrateMutation),

package/src/shared/hydrate.ts

@@ -49,26 +49,24 @@ const hydrateObservers = (
 
     hydratedOptions.queryFn = mockQueryFn;
 
-    const observer = new QueryObserver(
-      client,
-      hydratedOptions as QueryObserverOptions,
-    );
+    const observer = new QueryObserver(client, hydratedOptions as QueryObserverOptions);
     query.addObserver(observer);
   });
 };
 
-const hydrateMutation = (
-  client: QueryClient,
-  dehydratedMutation: SerializableMutation,
-) => {
+const hydrateMutation = (client: QueryClient, dehydratedMutation: SerializableMutation) => {
   const mutationCache = client.getMutationCache();
   const { options, state } = dehydratedMutation;
 
   const existingMutation = mutationCache.find({
     mutationKey: options.mutationKey,
   });
-  const hydratedState: MutationState<unknown, Error, void, unknown> =
-    state as MutationState<unknown, Error, void, unknown>;
+  const hydratedState: MutationState<unknown, Error, void, unknown> = state as MutationState<
+    unknown,
+    Error,
+    void,
+    unknown
+  >;
   const hydratedOptions: MutationOptions = options;
 
   if (existingMutation) {
@@ -78,10 +76,7 @@ const hydrateMutation = (
   mutationCache.build(client, hydratedOptions, hydratedState);
 };
 
-const hydrateQuery = (
-  client: QueryClient,
-  dehydratedQuery: SerializableQuery,
-) => {
+const hydrateQuery = (client: QueryClient, dehydratedQuery: SerializableQuery) => {
   const queryCache = client.getQueryCache();
   const { queryKey, state, queryHash, observers } = dehydratedQuery;
 
@@ -132,9 +127,7 @@ export const hydrateQueryClient = (
   dehydratedState: SerializableQueryClient,
 ): void => {
   // Hydrate mutations
-  dehydratedState.mutations.forEach((mutation) =>
-    hydrateMutation(client, mutation),
-  );
+  dehydratedState.mutations.forEach((mutation) => hydrateMutation(client, mutation));
 
   // Hydrate queries
   dehydratedState.queries.forEach((query) => hydrateQuery(client, query));
@@ -187,10 +180,7 @@ export const applyQueryEvent = (
 };
 
 // New function to handle action-based partial state updates
-export const applyPartialQueryState = (
-  queryClient: QueryClient,
-  data: PartialQueryState,
-): void => {
+export const applyPartialQueryState = (queryClient: QueryClient, data: PartialQueryState): void => {
   const queryCache = queryClient.getQueryCache();
   const query = queryCache.get(data.queryHash);
 

package/src/shared/messaging.ts

@@ -19,6 +19,13 @@ export type TanStackQueryPluginEventMap = {
       data?: unknown;
     };
   };
+  /**
+   * Announced by the device once it is listening for panel messages. The panel
+   * is recreated on every app reload and asks for the cache immediately, which
+   * can land before the app's React tree has mounted the plugin; this lets the
+   * panel ask again instead of staying empty until the app is restarted.
+   */
+  'device-ready': unknown;
   'request-initial-data': unknown;
   'sync-data': {
     data: SerializableQueryClient;
@@ -53,5 +60,4 @@ export type TanStackQueryPluginEventMap = {
   };
 };
 
-export type TanStackQueryPluginClient =
-  RozeniteDevToolsClient<TanStackQueryPluginEventMap>;
+export type TanStackQueryPluginClient = RozeniteDevToolsClient<TanStackQueryPluginEventMap>;

package/src/shared/query-data-sync.test.ts

@@ -1,10 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { QueryClient } from '@tanstack/react-query';
-import {
-  applyRemoteQueryState,
-  instrumentQuery,
-  instrumentQueryClient,
-} from './query-data-sync';
+import { applyRemoteQueryState, instrumentQuery, instrumentQueryClient } from './query-data-sync';
 
 const createQueryClient = () =>
   new QueryClient({

package/src/shared/query-data-sync.ts

@@ -1,9 +1,4 @@
-import {
-  Query,
-  QueryClient,
-  QueryKey,
-  QueryState,
-} from '@tanstack/react-query';
+import { Query, QueryClient, QueryKey, QueryState } from '@tanstack/react-query';
 
 type QuerySetState = Query['setState'];
 type QueryClientSetQueryData = QueryClient['setQueryData'];
@@ -16,27 +11,17 @@ type SyncQueryDataPayload = {
 type QueryDataSyncHandler = (payload: SyncQueryDataPayload) => void;
 
 const originalQuerySetStateMap = new WeakMap<Query, QuerySetState>();
-const originalSetQueryDataMap = new WeakMap<
-  QueryClient,
-  QueryClientSetQueryData
->();
+const originalSetQueryDataMap = new WeakMap<QueryClient, QueryClientSetQueryData>();
 const instrumentedQueryClients = new WeakSet<QueryClient>();
 const instrumentedQueries = new WeakSet<Query>();
-const queryClientHandlers = new WeakMap<
-  QueryClient,
-  QueryDataSyncHandler | undefined
->();
+const queryClientHandlers = new WeakMap<QueryClient, QueryDataSyncHandler | undefined>();
 const queryHandlers = new WeakMap<Query, QueryDataSyncHandler | undefined>();
 
 const getOriginalQuerySetState = (query: Query): QuerySetState => {
   return originalQuerySetStateMap.get(query) ?? query.setState.bind(query);
 };
 
-const emitIfDataChanged = (
-  query: Query,
-  previousData: unknown,
-  handler?: QueryDataSyncHandler,
-) => {
+const emitIfDataChanged = (query: Query, previousData: unknown, handler?: QueryDataSyncHandler) => {
   if (!handler || Object.is(previousData, query.state.data)) {
     return;
   }
@@ -47,10 +32,7 @@ const emitIfDataChanged = (
   });
 };
 
-const isDataOnlyStateUpdate = (
-  previousState: QueryState,
-  nextState: Partial<QueryState>,
-) => {
+const isDataOnlyStateUpdate = (previousState: QueryState, nextState: Partial<QueryState>) => {
   if (!('data' in nextState)) {
     return false;
   }
@@ -63,18 +45,12 @@ const isDataOnlyStateUpdate = (
   return changedKeys.every((key) => key === 'data');
 };
 
-export const applyRemoteQueryState = (
-  query: Query,
-  state: Partial<QueryState>,
-) => {
+export const applyRemoteQueryState = (query: Query, state: Partial<QueryState>) => {
   const originalSetState = getOriginalQuerySetState(query);
   originalSetState(state);
 };
 
-export const instrumentQuery = (
-  query: Query,
-  handler?: QueryDataSyncHandler,
-) => {
+export const instrumentQuery = (query: Query, handler?: QueryDataSyncHandler) => {
   queryHandlers.set(query, handler);
 
   if (instrumentedQueries.has(query)) {
@@ -104,10 +80,7 @@ const resolveQueryHash = (queryClient: QueryClient, queryKey: QueryKey) => {
   return queryClient.getQueryCache().find({ queryKey })?.queryHash;
 };
 
-export const instrumentQueryClient = (
-  queryClient: QueryClient,
-  handler?: QueryDataSyncHandler,
-) => {
+export const instrumentQueryClient = (queryClient: QueryClient, handler?: QueryDataSyncHandler) => {
   queryClientHandlers.set(queryClient, handler);
 
   if (instrumentedQueryClients.has(queryClient)) {

package/src/shared/useSyncOnlineStatus.ts

@@ -2,9 +2,7 @@ import { useEffect } from 'react';
 import { onlineManager } from '@tanstack/react-query';
 import { TanStackQueryPluginClient } from './messaging';
 
-export const useSyncOnlineStatus = (
-  client: TanStackQueryPluginClient | null
-) => {
+export const useSyncOnlineStatus = (client: TanStackQueryPluginClient | null) => {
   useEffect(() => {
     if (!client) {
       return;
@@ -14,12 +12,9 @@ export const useSyncOnlineStatus = (
       client.send('online-status-changed', { online });
     });
 
-    const onlineMessageSubscription = client.onMessage(
-      'online-status-changed',
-      ({ online }) => {
-        onlineManager.setOnline(online);
-      }
-    );
+    const onlineMessageSubscription = client.onMessage('online-status-changed', ({ online }) => {
+      onlineManager.setOnline(online);
+    });
 
     return () => {
       onlineManagerSubscription();