@rozenite/tanstack-query-plugin 1.7.0-rc.2 → 1.8.0

package/src/shared/agent-tools.ts

@@ -0,0 +1,403 @@
+import {
+  defineAgentToolContract,
+  type AgentToolContract,
+  type JSONSchema7,
+} from '@rozenite/agent-shared';
+import type { FetchStatus, MutationStatus, QueryStatus } from '@tanstack/react-query';
+import type { applyTanStackQueryDevtoolsAction } from '../react-native/devtools-actions';
+
+export const TANSTACK_QUERY_AGENT_PLUGIN_ID = '@rozenite/tanstack-query-plugin';
+
+export type TanStackQueryAgentPaginationInput = {
+  limit?: number;
+  cursor?: string;
+};
+
+export type TanStackQueryAgentQueryHashInput = {
+  queryHash: string;
+};
+
+export type TanStackQueryAgentQueryToggleInput =
+  TanStackQueryAgentQueryHashInput & {
+    enabled: boolean;
+  };
+
+export type TanStackQueryAgentMutationIdInput = {
+  mutationId: number;
+};
+
+export type TanStackQueryAgentOnlineStatusInput = {
+  online: boolean;
+};
+
+export type TanStackQueryAgentSafeValue =
+  | null
+  | boolean
+  | number
+  | string
+  | TanStackQueryAgentSafeValue[]
+  | { [key: string]: TanStackQueryAgentSafeValue };
+
+export type TanStackQueryCacheSummary = {
+  online: boolean;
+  queries: {
+    total: number;
+    active: number;
+    fetching: number;
+    pending: number;
+    success: number;
+    error: number;
+    invalidated: number;
+  };
+  mutations: {
+    total: number;
+    pending: number;
+    success: number;
+    error: number;
+    paused: number;
+  };
+};
+
+export type TanStackQueryPage = {
+  limit: number;
+  hasMore: boolean;
+  nextCursor?: string;
+};
+
+export type TanStackQueryQuerySummary = {
+  queryHash: string;
+  queryKey: TanStackQueryAgentSafeValue;
+  status: QueryStatus;
+  fetchStatus: FetchStatus;
+  observersCount: number;
+  isInvalidated: boolean;
+  dataUpdatedAt: number;
+  errorUpdatedAt: number;
+  hasData: boolean;
+  hasError: boolean;
+};
+
+export type TanStackQueryObserverOptionsSummary = {
+  enabled: TanStackQueryAgentSafeValue;
+  networkMode: TanStackQueryAgentSafeValue;
+  staleTime: TanStackQueryAgentSafeValue;
+  gcTime: TanStackQueryAgentSafeValue;
+  retry: TanStackQueryAgentSafeValue;
+  retryDelay: TanStackQueryAgentSafeValue;
+  refetchInterval: TanStackQueryAgentSafeValue;
+  refetchOnMount: TanStackQueryAgentSafeValue;
+  refetchOnReconnect: TanStackQueryAgentSafeValue;
+  refetchOnWindowFocus: TanStackQueryAgentSafeValue;
+  subscribed: TanStackQueryAgentSafeValue;
+  meta: TanStackQueryAgentSafeValue;
+  hasQueryFn: boolean;
+  hasSelect: boolean;
+  hasPlaceholderData: boolean;
+  hasInitialData: boolean;
+};
+
+export type TanStackQueryListQueriesResult = TanStackQueryCacheSummary & {
+  total: number;
+  items: TanStackQueryQuerySummary[];
+  page: TanStackQueryPage;
+};
+
+export type TanStackQueryGetQueryDetailsResult = {
+  summary: TanStackQueryCacheSummary;
+  query: TanStackQueryQuerySummary & {
+    data: TanStackQueryAgentSafeValue;
+    error: TanStackQueryAgentSafeValue;
+    observers: Array<{
+      queryHash: string;
+      options: TanStackQueryObserverOptionsSummary | null;
+    }>;
+  };
+};
+
+export type TanStackQueryActionResult = Awaited<
+  ReturnType<typeof applyTanStackQueryDevtoolsAction>
+>;
+
+export type TanStackQueryMutationSummary = {
+  mutationId: number;
+  mutationKey: TanStackQueryAgentSafeValue;
+  status: MutationStatus;
+  isPaused: boolean;
+  submittedAt: number;
+  failureCount: number;
+  hasData: boolean;
+  hasError: boolean;
+};
+
+export type TanStackQueryMutationOptionsSummary = {
+  mutationKey: TanStackQueryAgentSafeValue;
+  networkMode: TanStackQueryAgentSafeValue;
+  gcTime: TanStackQueryAgentSafeValue;
+  retry: TanStackQueryAgentSafeValue;
+  retryDelay: TanStackQueryAgentSafeValue;
+  meta: TanStackQueryAgentSafeValue;
+  scope: TanStackQueryAgentSafeValue;
+  hasMutationFn: boolean;
+  hasOnMutate: boolean;
+  hasOnSuccess: boolean;
+  hasOnError: boolean;
+  hasOnSettled: boolean;
+};
+
+export type TanStackQueryListMutationsResult = TanStackQueryCacheSummary & {
+  total: number;
+  items: TanStackQueryMutationSummary[];
+  page: TanStackQueryPage;
+};
+
+export type TanStackQueryGetMutationDetailsResult = {
+  summary: TanStackQueryCacheSummary;
+  mutation: TanStackQueryMutationSummary & {
+    variables: TanStackQueryAgentSafeValue;
+    data: TanStackQueryAgentSafeValue;
+    error: TanStackQueryAgentSafeValue;
+    context: TanStackQueryAgentSafeValue;
+    failureReason: TanStackQueryAgentSafeValue;
+    options: TanStackQueryMutationOptionsSummary;
+  };
+};
+
+export type TanStackQueryGetCacheSummaryArgs = undefined;
+export type TanStackQueryGetCacheSummaryResult = TanStackQueryCacheSummary;
+export type TanStackQueryGetOnlineStatusArgs = undefined;
+export type TanStackQueryGetOnlineStatusResult = { online: boolean };
+export type TanStackQuerySetOnlineStatusArgs = TanStackQueryAgentOnlineStatusInput;
+export type TanStackQuerySetOnlineStatusResult = { online: boolean };
+export type TanStackQueryListQueriesArgs = TanStackQueryAgentPaginationInput;
+export type TanStackQueryGetQueryDetailsArgs = TanStackQueryAgentQueryHashInput;
+export type TanStackQueryRefetchQueryArgs = TanStackQueryAgentQueryHashInput;
+export type TanStackQuerySetQueryLoadingArgs = TanStackQueryAgentQueryToggleInput;
+export type TanStackQuerySetQueryErrorArgs = TanStackQueryAgentQueryToggleInput;
+export type TanStackQueryInvalidateQueryArgs = TanStackQueryAgentQueryHashInput;
+export type TanStackQueryResetQueryArgs = TanStackQueryAgentQueryHashInput;
+export type TanStackQueryRemoveQueryArgs = TanStackQueryAgentQueryHashInput;
+export type TanStackQueryClearQueryCacheArgs = undefined;
+export type TanStackQueryClearQueryCacheResult = TanStackQueryActionResult;
+export type TanStackQueryListMutationsArgs = TanStackQueryAgentPaginationInput;
+export type TanStackQueryGetMutationDetailsArgs = TanStackQueryAgentMutationIdInput;
+export type TanStackQueryClearMutationCacheArgs = undefined;
+export type TanStackQueryClearMutationCacheResult = TanStackQueryActionResult;
+
+const queryActionProperties = {
+  queryHash: {
+    type: 'string',
+    description: 'TanStack Query queryHash identifying the query.',
+  },
+} satisfies Record<string, JSONSchema7>;
+
+const mutationActionProperties = {
+  mutationId: {
+    type: 'number',
+    description: 'TanStack Query mutationId identifying the mutation.',
+  },
+} satisfies Record<string, JSONSchema7>;
+
+const paginationProperties = {
+  limit: {
+    type: 'number',
+    description: 'Maximum number of items to return. Defaults to 20. Maximum 100.',
+  },
+  cursor: {
+    type: 'string',
+    description: 'Opaque pagination cursor from a previous list call.',
+  },
+} satisfies Record<string, JSONSchema7>;
+
+const emptyInputSchema: JSONSchema7 = {
+  type: 'object',
+  properties: {},
+};
+
+export const tanstackQueryToolDefinitions = {
+  getCacheSummary: defineAgentToolContract<
+    TanStackQueryGetCacheSummaryArgs,
+    TanStackQueryGetCacheSummaryResult
+  >({
+    name: 'get-cache-summary',
+    description:
+      'Return aggregate TanStack Query cache health and count information.',
+    inputSchema: emptyInputSchema,
+  }),
+  getOnlineStatus: defineAgentToolContract<
+    TanStackQueryGetOnlineStatusArgs,
+    TanStackQueryGetOnlineStatusResult
+  >({
+    name: 'get-online-status',
+    description: 'Return the current TanStack Query onlineManager status.',
+    inputSchema: emptyInputSchema,
+  }),
+  setOnlineStatus: defineAgentToolContract<
+    TanStackQuerySetOnlineStatusArgs,
+    TanStackQuerySetOnlineStatusResult
+  >({
+    name: 'set-online-status',
+    description:
+      'Set the TanStack Query onlineManager status for testing offline/online behavior.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        online: {
+          type: 'boolean',
+          description: 'Whether the TanStack Query onlineManager should be online.',
+        },
+      },
+      required: ['online'],
+    },
+  }),
+  listQueries: defineAgentToolContract<
+    TanStackQueryListQueriesArgs,
+    TanStackQueryListQueriesResult
+  >({
+    name: 'list-queries',
+    description: 'List TanStack Query query summaries using cursor pagination.',
+    inputSchema: {
+      type: 'object',
+      properties: paginationProperties,
+    },
+  }),
+  getQueryDetails: defineAgentToolContract<
+    TanStackQueryGetQueryDetailsArgs,
+    TanStackQueryGetQueryDetailsResult
+  >({
+    name: 'get-query-details',
+    description:
+      'Return a JSON-safe TanStack Query query snapshot and observer summary.',
+    inputSchema: {
+      type: 'object',
+      properties: queryActionProperties,
+      required: ['queryHash'],
+    },
+  }),
+  refetchQuery: defineAgentToolContract<
+    TanStackQueryRefetchQueryArgs,
+    TanStackQueryActionResult
+  >({
+    name: 'refetch-query',
+    description: 'Refetch a TanStack Query query by queryHash.',
+    inputSchema: {
+      type: 'object',
+      properties: queryActionProperties,
+      required: ['queryHash'],
+    },
+  }),
+  setQueryLoading: defineAgentToolContract<
+    TanStackQuerySetQueryLoadingArgs,
+    TanStackQueryActionResult
+  >({
+    name: 'set-query-loading',
+    description:
+      'Enable or disable TanStack Query loading-state simulation for a query by queryHash.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...queryActionProperties,
+        enabled: {
+          type: 'boolean',
+          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.',
+        },
+      },
+      required: ['queryHash', 'enabled'],
+    },
+  }),
+  invalidateQuery: defineAgentToolContract<
+    TanStackQueryInvalidateQueryArgs,
+    TanStackQueryActionResult
+  >({
+    name: 'invalidate-query',
+    description: 'Invalidate a TanStack Query query by queryHash.',
+    inputSchema: {
+      type: 'object',
+      properties: queryActionProperties,
+      required: ['queryHash'],
+    },
+  }),
+  resetQuery: defineAgentToolContract<
+    TanStackQueryResetQueryArgs,
+    TanStackQueryActionResult
+  >({
+    name: 'reset-query',
+    description: 'Reset a TanStack Query query by queryHash.',
+    inputSchema: {
+      type: 'object',
+      properties: queryActionProperties,
+      required: ['queryHash'],
+    },
+  }),
+  removeQuery: defineAgentToolContract<
+    TanStackQueryRemoveQueryArgs,
+    TanStackQueryActionResult
+  >({
+    name: 'remove-query',
+    description: 'Remove a TanStack Query query from the cache by queryHash.',
+    inputSchema: {
+      type: 'object',
+      properties: queryActionProperties,
+      required: ['queryHash'],
+    },
+  }),
+  clearQueryCache: defineAgentToolContract<
+    TanStackQueryClearQueryCacheArgs,
+    TanStackQueryClearQueryCacheResult
+  >({
+    name: 'clear-query-cache',
+    description: 'Clear the full TanStack Query query cache.',
+    inputSchema: emptyInputSchema,
+  }),
+  listMutations: defineAgentToolContract<
+    TanStackQueryListMutationsArgs,
+    TanStackQueryListMutationsResult
+  >({
+    name: 'list-mutations',
+    description: 'List TanStack Query mutation summaries using cursor pagination.',
+    inputSchema: {
+      type: 'object',
+      properties: paginationProperties,
+    },
+  }),
+  getMutationDetails: defineAgentToolContract<
+    TanStackQueryGetMutationDetailsArgs,
+    TanStackQueryGetMutationDetailsResult
+  >({
+    name: 'get-mutation-details',
+    description:
+      'Return a JSON-safe TanStack Query mutation snapshot for a mutationId.',
+    inputSchema: {
+      type: 'object',
+      properties: mutationActionProperties,
+      required: ['mutationId'],
+    },
+  }),
+  clearMutationCache: defineAgentToolContract<
+    TanStackQueryClearMutationCacheArgs,
+    TanStackQueryClearMutationCacheResult
+  >({
+    name: 'clear-mutation-cache',
+    description: 'Clear the full TanStack Query mutation cache.',
+    inputSchema: emptyInputSchema,
+  }),
+} as const satisfies Record<string, AgentToolContract<unknown, unknown>>;

package/src/shared/hydrate.ts

@@ -14,6 +14,7 @@ import type {
   SerializableObserver,
   PartialQueryState,
 } from './types';
+import { applyRemoteQueryState, instrumentQuery } from './query-data-sync';
 
 const mockQueryFn = () => {
   return Promise.resolve(null);
@@ -22,7 +23,7 @@ const mockQueryFn = () => {
 const hydrateObservers = (
   client: QueryClient,
   queryHash: string,
-  dehydratedObservers: SerializableObserver[]
+  dehydratedObservers: SerializableObserver[],
 ) => {
   const query = client.getQueryCache().get(queryHash);
 
@@ -50,7 +51,7 @@ const hydrateObservers = (
 
     const observer = new QueryObserver(
       client,
-      hydratedOptions as QueryObserverOptions
+      hydratedOptions as QueryObserverOptions,
     );
     query.addObserver(observer);
   });
@@ -58,7 +59,7 @@ const hydrateObservers = (
 
 const hydrateMutation = (
   client: QueryClient,
-  dehydratedMutation: SerializableMutation
+  dehydratedMutation: SerializableMutation,
 ) => {
   const mutationCache = client.getMutationCache();
   const { options, state } = dehydratedMutation;
@@ -79,7 +80,7 @@ const hydrateMutation = (
 
 const hydrateQuery = (
   client: QueryClient,
-  dehydratedQuery: SerializableQuery
+  dehydratedQuery: SerializableQuery,
 ) => {
   const queryCache = client.getQueryCache();
   const { queryKey, state, queryHash, observers } = dehydratedQuery;
@@ -94,7 +95,7 @@ const hydrateQuery = (
       query.state.dataUpdatedAt < state.dataUpdatedAt ||
       query.state.fetchStatus !== state.fetchStatus
     ) {
-      query.setState({
+      applyRemoteQueryState(query, {
         ...hydratedState,
         data,
       });
@@ -117,20 +118,22 @@ const hydrateQuery = (
       {
         ...hydratedState,
         data,
-      }
+      },
     );
   }
 
+  instrumentQuery(query);
+
   hydrateObservers(client, queryHash, observers);
 };
 
 export const hydrateQueryClient = (
   client: QueryClient,
-  dehydratedState: SerializableQueryClient
+  dehydratedState: SerializableQueryClient,
 ): void => {
   // Hydrate mutations
   dehydratedState.mutations.forEach((mutation) =>
-    hydrateMutation(client, mutation)
+    hydrateMutation(client, mutation),
   );
 
   // Hydrate queries
@@ -148,7 +151,7 @@ export const applyQueryEvent = (
     | 'observerResultsUpdated'
     | 'observerOptionsUpdated',
   data: SerializableQuery | PartialQueryState,
-  action?: string
+  action?: string,
 ): void => {
   const queryCache = queryClient.getQueryCache();
 
@@ -186,7 +189,7 @@ export const applyQueryEvent = (
 // New function to handle action-based partial state updates
 export const applyPartialQueryState = (
   queryClient: QueryClient,
-  data: PartialQueryState
+  data: PartialQueryState,
 ): void => {
   const queryCache = queryClient.getQueryCache();
   const query = queryCache.get(data.queryHash);
@@ -199,7 +202,7 @@ export const applyPartialQueryState = (
 
   // Apply the partial state changes
   if (data.state) {
-    query.setState(data.state);
+    applyRemoteQueryState(query, data.state);
   }
 };
 
@@ -213,7 +216,7 @@ export const applyMutationEvent = (
     | 'observerRemoved'
     | 'observerResultsUpdated'
     | 'observerOptionsUpdated',
-  data: SerializableMutation
+  data: SerializableMutation,
 ): void => {
   const mutationCache = queryClient.getMutationCache();
 
@@ -244,7 +247,7 @@ export const applyQueryObserverEvent = (
   data: {
     queryHash: string;
     observers: SerializableObserver[];
-  }
+  },
 ): void => {
   hydrateObservers(queryClient, data.queryHash, data.observers);
 };

package/src/shared/messaging.ts

@@ -15,6 +15,9 @@ export type TanStackQueryPluginEventMap = {
   'devtools-action': {
     type: DevToolsActionType;
     queryHash: string;
+    metadata?: {
+      data?: unknown;
+    };
   };
   'request-initial-data': unknown;
   'sync-data': {

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

@@ -0,0 +1,93 @@
+import { describe, expect, it, vi } from 'vitest';
+import { QueryClient } from '@tanstack/react-query';
+import {
+  applyRemoteQueryState,
+  instrumentQuery,
+  instrumentQueryClient,
+} from './query-data-sync';
+
+const createQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        gcTime: Infinity,
+      },
+    },
+  });
+
+describe('query data sync instrumentation', () => {
+  it('emits query data updates for data-only setState edits', () => {
+    const queryClient = createQueryClient();
+    const handler = vi.fn();
+
+    queryClient.setQueryData(['edited'], { value: 1 });
+    const query = queryClient.getQueryCache().find({ queryKey: ['edited'] })!;
+
+    instrumentQuery(query, handler);
+
+    query.setState({
+      ...query.state,
+      data: { value: 2 },
+    });
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: { value: 2 },
+      }),
+    );
+  });
+
+  it('emits query data updates for setQueryData user edits', () => {
+    const queryClient = createQueryClient();
+    const handler = vi.fn();
+
+    instrumentQueryClient(queryClient, handler);
+
+    queryClient.setQueryData(['edited'], { value: 1 });
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: { value: 1 },
+      }),
+    );
+  });
+
+  it('does not emit query data updates for non-data state changes', () => {
+    const queryClient = createQueryClient();
+    const handler = vi.fn();
+
+    queryClient.setQueryData(['edited'], { value: 1 });
+    const query = queryClient.getQueryCache().find({ queryKey: ['edited'] })!;
+
+    instrumentQuery(query, handler);
+
+    query.setState({
+      data: undefined,
+      status: 'pending',
+      fetchStatus: 'fetching',
+    });
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('does not emit query data updates for remote state application', () => {
+    const queryClient = createQueryClient();
+    const handler = vi.fn();
+
+    queryClient.setQueryData(['edited'], { value: 1 });
+    const query = queryClient.getQueryCache().find({ queryKey: ['edited'] })!;
+
+    instrumentQuery(query, handler);
+
+    applyRemoteQueryState(query, {
+      ...query.state,
+      data: { value: 2 },
+    });
+
+    expect(handler).not.toHaveBeenCalled();
+    expect(query.state.data).toEqual({ value: 2 });
+  });
+});