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

package/src/react-native/agent/tanstack-query-agent.ts

@@ -1,7 +1,3 @@
-import type {
-  AgentTool,
-  JSONSchema7,
-} from '@rozenite/agent-bridge';
 import type {
   Mutation,
   MutationCacheNotifyEvent,
@@ -13,47 +9,28 @@ import type {
 } from '@tanstack/react-query';
 import { onlineManager } from '@tanstack/react-query';
 import { applyTanStackQueryDevtoolsAction } from '../devtools-actions';
+import {
+  tanstackQueryToolDefinitions,
+  type TanStackQueryAgentMutationIdInput as MutationIdInput,
+  type TanStackQueryAgentOnlineStatusInput as OnlineStatusInput,
+  type TanStackQueryAgentPaginationInput as PaginationInput,
+  type TanStackQueryAgentQueryHashInput as QueryHashInput,
+  type TanStackQueryAgentQueryToggleInput as QueryToggleInput,
+  type TanStackQueryAgentSafeValue as AgentSafeValue,
+  type TanStackQueryMutationOptionsSummary,
+  type TanStackQueryObserverOptionsSummary,
+} from '../../shared/agent-tools';
 
-const pluginId = '@rozenite/tanstack-query-plugin';
 const DEFAULT_PAGE_LIMIT = 20;
 const MAX_PAGE_LIMIT = 100;
 
 type CursorKind = 'queries' | 'mutations';
 
-type PaginationInput = {
-  limit?: number;
-  cursor?: string;
-};
-
-type QueryHashInput = {
-  queryHash: string;
-};
-
-type QueryToggleInput = QueryHashInput & {
-  enabled: boolean;
-};
-
-type MutationIdInput = {
-  mutationId: number;
-};
-
-type OnlineStatusInput = {
-  online: boolean;
-};
-
 type CursorState = {
   queriesGeneration: number;
   mutationsGeneration: number;
 };
 
-type AgentSafeValue =
-  | null
-  | boolean
-  | number
-  | string
-  | AgentSafeValue[]
-  | { [key: string]: AgentSafeValue };
-
 const isPlainObject = (value: unknown): value is Record<string, unknown> => {
   return (
     !!value &&
@@ -212,202 +189,30 @@ const paginate = <T>(
   };
 };
 
-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 getCacheSummaryTool: AgentTool = {
-  name: 'get-cache-summary',
-  description:
-    'Return aggregate TanStack Query cache health and count information.',
-  inputSchema: emptyInputSchema,
-};
-
-export const getOnlineStatusTool: AgentTool = {
-  name: 'get-online-status',
-  description: 'Return the current TanStack Query onlineManager status.',
-  inputSchema: emptyInputSchema,
-};
-
-export const setOnlineStatusTool: AgentTool = {
-  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'],
-  },
-};
-
-export const listQueriesTool: AgentTool = {
-  name: 'list-queries',
-  description:
-    'List TanStack Query query summaries using cursor pagination.',
-  inputSchema: {
-    type: 'object',
-    properties: paginationProperties,
-  },
-};
-
-export const getQueryDetailsTool: AgentTool = {
-  name: 'get-query-details',
-  description:
-    'Return a JSON-safe TanStack Query query snapshot and observer summary.',
-  inputSchema: {
-    type: 'object',
-    properties: queryActionProperties,
-    required: ['queryHash'],
-  },
-};
-
-export const refetchQueryTool: AgentTool = {
-  name: 'refetch-query',
-  description: 'Refetch a TanStack Query query by queryHash.',
-  inputSchema: {
-    type: 'object',
-    properties: queryActionProperties,
-    required: ['queryHash'],
-  },
-};
-
-export const setQueryLoadingTool: AgentTool = {
-  name: 'set-query-loading',
-  description:
-    'Enable or disable TanStack Query loading-state simulation for a query by queryHash.',
-  inputSchema: {
-    type: 'object',
-    properties: queryActionProperties,
-    required: ['queryHash', 'enabled'],
-  },
-};
-
-export const setQueryErrorTool: AgentTool = {
-  name: 'set-query-error',
-  description:
-    'Enable or disable TanStack Query error-state simulation for a query by queryHash.',
-  inputSchema: {
-    type: 'object',
-    properties: queryActionProperties,
-    required: ['queryHash', 'enabled'],
-  },
-};
-
-export const invalidateQueryTool: AgentTool = {
-  name: 'invalidate-query',
-  description: 'Invalidate a TanStack Query query by queryHash.',
-  inputSchema: {
-    type: 'object',
-    properties: queryActionProperties,
-    required: ['queryHash'],
-  },
-};
-
-export const resetQueryTool: AgentTool = {
-  name: 'reset-query',
-  description: 'Reset a TanStack Query query by queryHash.',
-  inputSchema: {
-    type: 'object',
-    properties: queryActionProperties,
-    required: ['queryHash'],
-  },
-};
-
-export const removeQueryTool: AgentTool = {
-  name: 'remove-query',
-  description: 'Remove a TanStack Query query from the cache by queryHash.',
-  inputSchema: {
-    type: 'object',
-    properties: queryActionProperties,
-    required: ['queryHash'],
-  },
-};
-
-export const clearQueryCacheTool: AgentTool = {
-  name: 'clear-query-cache',
-  description: 'Clear the full TanStack Query query cache.',
-  inputSchema: emptyInputSchema,
-};
-
-export const listMutationsTool: AgentTool = {
-  name: 'list-mutations',
-  description:
-    'List TanStack Query mutation summaries using cursor pagination.',
-  inputSchema: {
-    type: 'object',
-    properties: paginationProperties,
-  },
-};
-
-export const getMutationDetailsTool: AgentTool = {
-  name: 'get-mutation-details',
-  description:
-    'Return a JSON-safe TanStack Query mutation snapshot for a mutationId.',
-  inputSchema: {
-    type: 'object',
-    properties: mutationActionProperties,
-    required: ['mutationId'],
-  },
-};
-
-export const clearMutationCacheTool: AgentTool = {
-  name: 'clear-mutation-cache',
-  description: 'Clear the full TanStack Query mutation cache.',
-  inputSchema: emptyInputSchema,
-};
-
-export const TANSTACK_QUERY_AGENT_TOOLS: AgentTool[] = [
-  getCacheSummaryTool,
-  getOnlineStatusTool,
-  setOnlineStatusTool,
-  listQueriesTool,
-  getQueryDetailsTool,
-  refetchQueryTool,
-  setQueryLoadingTool,
-  setQueryErrorTool,
-  invalidateQueryTool,
-  resetQueryTool,
-  removeQueryTool,
-  clearQueryCacheTool,
-  listMutationsTool,
-  getMutationDetailsTool,
-  clearMutationCacheTool,
-];
+export const getCacheSummaryTool = tanstackQueryToolDefinitions.getCacheSummary;
+export const getOnlineStatusTool = tanstackQueryToolDefinitions.getOnlineStatus;
+export const setOnlineStatusTool = tanstackQueryToolDefinitions.setOnlineStatus;
+export const listQueriesTool = tanstackQueryToolDefinitions.listQueries;
+export const getQueryDetailsTool = tanstackQueryToolDefinitions.getQueryDetails;
+export const refetchQueryTool = tanstackQueryToolDefinitions.refetchQuery;
+export const setQueryLoadingTool = tanstackQueryToolDefinitions.setQueryLoading;
+export const setQueryErrorTool = tanstackQueryToolDefinitions.setQueryError;
+export const invalidateQueryTool = tanstackQueryToolDefinitions.invalidateQuery;
+export const resetQueryTool = tanstackQueryToolDefinitions.resetQuery;
+export const removeQueryTool = tanstackQueryToolDefinitions.removeQuery;
+export const clearQueryCacheTool = tanstackQueryToolDefinitions.clearQueryCache;
+export const listMutationsTool = tanstackQueryToolDefinitions.listMutations;
+export const getMutationDetailsTool =
+  tanstackQueryToolDefinitions.getMutationDetails;
+export const clearMutationCacheTool =
+  tanstackQueryToolDefinitions.clearMutationCache;
+export const TANSTACK_QUERY_AGENT_TOOLS = Object.values(
+  tanstackQueryToolDefinitions,
+);
 
 const pickObserverOptionsSummary = (
   options: Record<string, unknown> | undefined
-) => {
+): TanStackQueryObserverOptionsSummary | null => {
   if (!options) {
     return null;
   }
@@ -434,7 +239,7 @@ const pickObserverOptionsSummary = (
 
 const pickMutationOptionsSummary = (
   options: MutationObserverOptions<unknown, Error, unknown, unknown>
-) => {
+): TanStackQueryMutationOptionsSummary => {
   return {
     mutationKey: serializeForAgent(options.mutationKey),
     networkMode: serializeForAgent(options.networkMode),
@@ -741,10 +546,3 @@ export const createTanStackQueryAgentController = (queryClient: QueryClient) =>
 export type TanStackQueryAgentController = ReturnType<
   typeof createTanStackQueryAgentController
 >;
-
-export type TanStackQueryAgentPaginationInput = PaginationInput;
-export type TanStackQueryAgentQueryHashInput = QueryHashInput;
-export type TanStackQueryAgentQueryToggleInput = QueryToggleInput;
-export type TanStackQueryAgentMutationIdInput = MutationIdInput;
-export type TanStackQueryAgentOnlineStatusInput = OnlineStatusInput;
-export const TANSTACK_QUERY_AGENT_PLUGIN_ID = pluginId;

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

@@ -2,29 +2,12 @@ import { useEffect, useMemo } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { useRozenitePluginAgentTool } from '@rozenite/agent-bridge';
 import {
-  clearMutationCacheTool,
-  clearQueryCacheTool,
   createTanStackQueryAgentController,
-  getCacheSummaryTool,
-  getMutationDetailsTool,
-  getOnlineStatusTool,
-  getQueryDetailsTool,
-  invalidateQueryTool,
-  listMutationsTool,
-  listQueriesTool,
-  refetchQueryTool,
-  removeQueryTool,
-  resetQueryTool,
-  setQueryErrorTool,
-  setQueryLoadingTool,
-  TANSTACK_QUERY_AGENT_PLUGIN_ID,
-  type TanStackQueryAgentMutationIdInput,
-  type TanStackQueryAgentOnlineStatusInput,
-  type TanStackQueryAgentPaginationInput,
-  type TanStackQueryAgentQueryHashInput,
-  type TanStackQueryAgentQueryToggleInput,
-  setOnlineStatusTool,
 } from './tanstack-query-agent';
+import {
+  TANSTACK_QUERY_AGENT_PLUGIN_ID,
+  tanstackQueryToolDefinitions,
+} from '../../shared/agent-tools';
 
 export const useTanStackQueryAgentTools = (queryClient: QueryClient) => {
   const controller = useMemo(
@@ -48,100 +31,91 @@ export const useTanStackQueryAgentTools = (queryClient: QueryClient) => {
 
   useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: getCacheSummaryTool,
+    tool: tanstackQueryToolDefinitions.getCacheSummary,
     handler: () => controller.getCacheSummary(),
   });
 
   useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: getOnlineStatusTool,
+    tool: tanstackQueryToolDefinitions.getOnlineStatus,
     handler: () => controller.getOnlineStatus(),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentOnlineStatusInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: setOnlineStatusTool,
-    handler: (input: TanStackQueryAgentOnlineStatusInput) =>
-      controller.setOnlineStatus(input),
+    tool: tanstackQueryToolDefinitions.setOnlineStatus,
+    handler: (input) => controller.setOnlineStatus(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentPaginationInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: listQueriesTool,
+    tool: tanstackQueryToolDefinitions.listQueries,
     handler: (input = {}) => controller.listQueries(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentQueryHashInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: getQueryDetailsTool,
-    handler: (input: TanStackQueryAgentQueryHashInput) =>
-      controller.getQueryDetails(input),
+    tool: tanstackQueryToolDefinitions.getQueryDetails,
+    handler: (input) => controller.getQueryDetails(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentQueryHashInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: refetchQueryTool,
-    handler: (input: TanStackQueryAgentQueryHashInput) =>
-      controller.refetchQuery(input),
+    tool: tanstackQueryToolDefinitions.refetchQuery,
+    handler: (input) => controller.refetchQuery(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentQueryToggleInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: setQueryLoadingTool,
-    handler: (input: TanStackQueryAgentQueryToggleInput) =>
-      controller.setQueryLoading(input),
+    tool: tanstackQueryToolDefinitions.setQueryLoading,
+    handler: (input) => controller.setQueryLoading(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentQueryToggleInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: setQueryErrorTool,
-    handler: (input: TanStackQueryAgentQueryToggleInput) =>
-      controller.setQueryError(input),
+    tool: tanstackQueryToolDefinitions.setQueryError,
+    handler: (input) => controller.setQueryError(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentQueryHashInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: invalidateQueryTool,
-    handler: (input: TanStackQueryAgentQueryHashInput) =>
-      controller.invalidateQuery(input),
+    tool: tanstackQueryToolDefinitions.invalidateQuery,
+    handler: (input) => controller.invalidateQuery(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentQueryHashInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: resetQueryTool,
-    handler: (input: TanStackQueryAgentQueryHashInput) =>
-      controller.resetQuery(input),
+    tool: tanstackQueryToolDefinitions.resetQuery,
+    handler: (input) => controller.resetQuery(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentQueryHashInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: removeQueryTool,
-    handler: (input: TanStackQueryAgentQueryHashInput) =>
-      controller.removeQuery(input),
+    tool: tanstackQueryToolDefinitions.removeQuery,
+    handler: (input) => controller.removeQuery(input),
   });
 
   useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: clearQueryCacheTool,
+    tool: tanstackQueryToolDefinitions.clearQueryCache,
     handler: () => controller.clearQueryCache(),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentPaginationInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: listMutationsTool,
+    tool: tanstackQueryToolDefinitions.listMutations,
     handler: (input = {}) => controller.listMutations(input),
   });
 
-  useRozenitePluginAgentTool<TanStackQueryAgentMutationIdInput>({
+  useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: getMutationDetailsTool,
-    handler: (input: TanStackQueryAgentMutationIdInput) =>
-      controller.getMutationDetails(input),
+    tool: tanstackQueryToolDefinitions.getMutationDetails,
+    handler: (input) => controller.getMutationDetails(input),
   });
 
   useRozenitePluginAgentTool({
     pluginId: TANSTACK_QUERY_AGENT_PLUGIN_ID,
-    tool: clearMutationCacheTool,
+    tool: tanstackQueryToolDefinitions.clearMutationCache,
     handler: () => controller.clearMutationCache(),
   });
 };

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

@@ -7,6 +7,9 @@ type QueryScopedActionInput = {
     'CLEAR_MUTATION_CACHE' | 'CLEAR_QUERY_CACHE'
   >;
   queryHash: string;
+  metadata?: {
+    data?: unknown;
+  };
 };
 
 type CacheScopedActionInput = {
@@ -33,7 +36,7 @@ const getActiveQuery = (queryClient: QueryClient, queryHash?: string) => {
 
 export const applyTanStackQueryDevtoolsAction = async (
   queryClient: QueryClient,
-  input: TanStackQueryDevtoolsActionInput
+  input: TanStackQueryDevtoolsActionInput,
 ) => {
   switch (input.type) {
     case 'CLEAR_QUERY_CACHE': {
@@ -49,8 +52,9 @@ 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,
@@ -61,6 +65,16 @@ export const applyTanStackQueryDevtoolsAction = async (
       };
     }
 
+    case 'SET_QUERY_DATA': {
+      const activeQuery = getActiveQuery(queryClient, input.queryHash);
+      queryClient.setQueryData(activeQuery.queryKey, input.metadata?.data);
+      return {
+        applied: true,
+        action: input.type,
+        queryHash: activeQuery.queryHash,
+      };
+    }
+
     case 'TRIGGER_ERROR': {
       const activeQuery = getActiveQuery(queryClient, input.queryHash);
       const previousQueryOptions = activeQuery.options;

package/src/react-native/useHandleDevToolsMessages.ts

@@ -5,7 +5,7 @@ import { applyTanStackQueryDevtoolsAction } from './devtools-actions';
 
 export const useHandleDevToolsMessages = (
   queryClient: QueryClient,
-  client: TanStackQueryPluginClient | null
+  client: TanStackQueryPluginClient | null,
 ) => {
   useEffect(() => {
     if (!client) {
@@ -14,16 +14,19 @@ export const useHandleDevToolsMessages = (
 
     const subscription = client.onMessage(
       'devtools-action',
-      ({ type, queryHash }) => {
-        void applyTanStackQueryDevtoolsAction(queryClient, { type, queryHash })
-          .catch((error) => {
-            const message =
-              error instanceof Error ? error.message : String(error);
-            console.warn(
-              `[Rozenite, tanstack-query-plugin] Failed to apply devtools action "${type}": ${message}`
-            );
-          });
-      }
+      ({ 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 () => {