@specverse/engines 4.1.21 → 4.1.23

package/libs/instance-factories/views/templates/react/hooks-generator.ts

@@ -1,16 +1,29 @@
 /**
- * React Hooks Generator
+ * React Hooks Generator — per-model convenience hook.
  *
- * Generates React custom hooks for data fetching and mutations
+ * Emits `use${Model}()` which is a thin delegator over the canonical
+ * hooks in `hooks/useApi.ts`. Historically this generator produced
+ * its own `useQuery(...)` + `useMutation(...)` blocks with private
+ * query keys (`['poll', id]`, `['polls', filters]`), which meant:
+ *
+ *   1. WebSocket events invalidating `['entities', modelName]` never
+ *      reached views that consumed this hook.
+ *   2. The conformance check `no-bare-usequery-in-views` lit up for
+ *      every per-model hook file.
+ *
+ * v2: delegate everything to `useEntitiesQuery` and
+ * `useExecuteOperationMutation` so there's exactly one cache key
+ * per model and one mutation pipeline across the whole frontend.
+ *
+ * The public API of `use${Model}()` is preserved for callers that
+ * depend on it: { [model], [models], isLoading, error, refetch,
+ * create, update, delete, isCreating, isUpdating, isDeleting }.
  */
 
 import type { TemplateContext } from '@specverse/types';
 
-/**
- * Generate React custom hook for a model
- */
 export default function generateReactHook(context: TemplateContext): string {
-  const { model, controller, spec } = context;
+  const { model } = context;
 
   if (!model) {
     throw new Error('Model is required in template context');
@@ -19,104 +32,75 @@ export default function generateReactHook(context: TemplateContext): string {
   const modelName = model.name;
   const hookName = `use${modelName}`;
   const controllerName = `${modelName}Controller`;
+  const singular = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+  const plural = singular + 's';
 
   return `/**
  * ${hookName}
- * Custom React hook for ${modelName} data fetching and mutations
+ *
+ * Thin delegator over the canonical useApi hooks. All state flows
+ * through \`['entities', '${modelName}']\` so WebSocket invalidation
+ * reaches every view consuming this hook.
  */
 
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { executeOperation } from '../lib/apiClient';
+import { useMemo } from 'react';
+import {
+  useEntitiesQuery,
+  useExecuteOperationMutation,
+} from './useApi';
 import type { ${modelName} } from '../types/${modelName}';
 
-interface Use${modelName}Options {
+interface ${capitalize(hookName)}Options {
   id?: string;
   list?: boolean;
   filters?: Record<string, any>;
 }
 
-/**
- * ${hookName} - Fetch and mutate ${modelName} data
- */
-export function ${hookName}(options: Use${modelName}Options = {}) {
-  const queryClient = useQueryClient();
-  const { id, list, filters } = options;
-
-  // Fetch single ${modelName}
-  const { data: ${modelName.toLowerCase()}, isLoading: singleLoading, error: singleError } = useQuery({
-    queryKey: ['${modelName.toLowerCase()}', id],
-    queryFn: async () => {
-      if (!id) return null;
-      return await executeOperation('${controllerName}', 'retrieve', { id });
-    },
-    enabled: !!id && !list,
-  });
-
-  // Fetch list of ${modelName}s
-  const { data: ${modelName.toLowerCase()}s, isLoading: listLoading, error: listError } = useQuery({
-    queryKey: ['${modelName.toLowerCase()}s', filters],
-    queryFn: async () => {
-      return await executeOperation('${controllerName}', 'list', filters || {});
-    },
-    enabled: list,
-  });
-
-  const isLoading = list ? listLoading : singleLoading;
-  const error = list ? listError : singleError;
-
-  // Create mutation
-  const createMutation = useMutation({
-    mutationFn: async (data: Partial<${modelName}>) => {
-      return await executeOperation('${controllerName}', 'create', data);
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
-
-  // Update mutation
-  const updateMutation = useMutation({
-    mutationFn: async ({ id, data }: { id: string; data: Partial<${modelName}> }) => {
-      return await executeOperation('${controllerName}', 'update', { id, ...data });
-    },
-    onSuccess: (_, variables) => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}', variables.id] });
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
-
-  // Delete mutation
-  const deleteMutation = useMutation({
-    mutationFn: async (id: string) => {
-      return await executeOperation('${controllerName}', 'delete', { id });
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
-
-  // Refetch functions
-  const refetch = () => {
-    if (list) {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    } else if (id) {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}', id] });
+export function ${hookName}(opts: ${capitalize(hookName)}Options = {}) {
+  const { id, filters: _filters } = opts;
+
+  // Canonical list query — one cache key per model. The list flag
+  // is preserved for backwards compatibility but the query always
+  // runs; React Query dedupes across consumers automatically.
+  const query = useEntitiesQuery('${controllerName}', '${modelName}');
+  const ${plural} = (query.data as ${modelName}[] | undefined) || [];
+
+  // Single-entity lookup is client-side against the canonical list
+  // so both the detail view and the list view share one source of
+  // truth. If the caller needs server-side hydration for a single
+  // entity, they should call useEntitiesQuery directly with a
+  // filtered controller endpoint.
+  const ${singular} = useMemo<${modelName} | null>(() => {
+    if (!id) return null;
+    for (const entity of ${plural}) {
+      const entityId = (entity as any)?.id || (entity as any)?.data?.id;
+      if (entityId === id) return entity;
     }
-  };
+    return null;
+  }, [id, ${plural}]);
+
+  const mutation = useExecuteOperationMutation();
 
   return {
-    ${modelName.toLowerCase()},
-    ${modelName.toLowerCase()}s,
-    isLoading,
-    error,
-    refetch,
-    create: createMutation.mutateAsync,
-    update: updateMutation.mutateAsync,
-    delete: deleteMutation.mutateAsync,
-    isCreating: createMutation.isPending,
-    isUpdating: updateMutation.isPending,
-    isDeleting: deleteMutation.isPending,
+    ${singular},
+    ${plural},
+    isLoading: query.isLoading,
+    error: query.error,
+    refetch: () => { /* handled by useEntitiesQuery refetchInterval + WS invalidation */ },
+    create: (data: Partial<${modelName}>) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'create', data: data as Record<string, unknown> }),
+    update: (args: { id: string; data: Partial<${modelName}> }) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'update', entityId: args.id, data: args.data as Record<string, unknown> }),
+    delete: (entityId: string) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'delete', entityId, data: {} }),
+    isCreating: mutation.isPending,
+    isUpdating: mutation.isPending,
+    isDeleting: mutation.isPending,
   };
 }
 `;
 }
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "4.1.21",
+  "version": "4.1.23",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry",
   "type": "module",
   "main": "dist/index.js",