chore: TiCS maintenance (#5853)

Author: abuyukyi101198

docs/component-standards/api-hooks.md

@@ -4,8 +4,8 @@
 
 - Auto-generated SDK lives in `src/app/apiclient`
 - Manually write hooks in `src/app/api/query/` using the generated react-query.ts hooks
-- Use `useWebsocketAwareQuery` for queries to auto-invalidate on websocket updates
-- Use `useMutation` with `invalidateQueries` in `onSuccess` for mutations
+- Use `useWebsocketAwareQuery` with `queryOptionsWithHeaders` for queries to auto-invalidate on websocket updates and include response headers
+- Use `useMutation` with `mutationOptionsWithHeaders` and `invalidateQueries` in `onSuccess` for mutations
 - Create mock resolvers in `src/testing/resolvers/` using MSW (Mock Service Worker)
 - Test hooks using `renderHookWithProviders` and mock resolvers
 - Follow naming convention: `use<Resource>` for list queries, `use<Action><Resource>` for single item and operation queries
@@ -22,16 +22,16 @@ Our API layer follows a three-tier architecture:
 
 ### Basic List Query
 
-Use `useWebsocketAwareQuery` to automatically invalidate when websocket updates occur:
+Use `useWebsocketAwareQuery` with `queryOptionsWithHeaders` to automatically invalidate when websocket updates occur and include response headers:
 
 ```typescript
 export const useUsers = (options?: Options<ListUsersWithSummaryData>) => {
   return useWebsocketAwareQuery(
-    listUsersWithSummaryOptions(options) as UseQueryOptions<
-      ListUsersWithSummaryData,
-      ListUsersWithSummaryError,
-      ListUsersWithSummaryResponse
-    >
+    queryOptionsWithHeaders<
+      ListUsersWithSummaryResponses,
+      ListUsersWithSummaryErrors,
+      ListUsersWithSummaryData
+    >(options, listUsersWithSummary, listUsersWithSummaryQueryKey(options))
   );
 };
 ```
@@ -41,11 +41,11 @@ export const useUsers = (options?: Options<ListUsersWithSummaryData>) => {
 ```typescript
 export const useGetUser = (options: Options<GetUserData>) => {
   return useWebsocketAwareQuery(
-    getUserOptions(options) as UseQueryOptions<
-      GetUserData,
-      GetUserError,
-      GetUserResponse
-    >
+    queryOptionsWithHeaders<GetUserResponses, GetUserErrors, GetUserData>(
+      options,
+      getUser,
+      getUserQueryKey(options)
+    )
   );
 };
 ```
@@ -57,31 +57,31 @@ For queries that transform data, use the `select` option:
 ```typescript
 export const useUserCount = (options?: Options<ListUsersWithSummaryData>) => {
   return useWebsocketAwareQuery({
-    ...listUsersWithSummaryOptions(options),
+    ...queryOptionsWithHeaders<
+      ListUsersWithSummaryResponses,
+      ListUsersWithSummaryErrors,
+      ListUsersWithSummaryData
+    >(options, listUsersWithSummary, listUsersWithSummaryQueryKey(options)),
     select: (data) => data?.total ?? 0,
-  } as UseQueryOptions<
-    ListUsersWithSummaryResponse,
-    ListUsersWithSummaryError,
-    number
-  >);
+  });
 };
 ```
 
 ## Writing Mutation Hooks
 
 ### Basic Mutation
 
-Always invalidate related queries in `onSuccess`:
+Always invalidate related queries in `onSuccess`. Use `mutationOptionsWithHeaders` to include response headers:
 
 ```typescript
 export const useCreateUser = (mutationOptions?: Options<CreateUserData>) => {
   const queryClient = useQueryClient();
-  return useMutation<
-    CreateUserResponse,
-    CreateUserError,
-    Options<CreateUserData>
-  >({
-    ...createUserMutation(mutationOptions),
+  return useMutation({
+    ...mutationOptionsWithHeaders<
+      CreateUserResponses,
+      CreateUserErrors,
+      CreateUserData
+    >(mutationOptions, createUser),
     onSuccess: () => {
       return queryClient.invalidateQueries({
         queryKey: listUsersWithSummaryQueryKey(),
@@ -96,12 +96,12 @@ export const useCreateUser = (mutationOptions?: Options<CreateUserData>) => {
 ```typescript
 export const useUpdateUser = (mutationOptions?: Options<UpdateUserData>) => {
   const queryClient = useQueryClient();
-  return useMutation<
-    UpdateUserResponse,
-    UpdateUserError,
-    Options<UpdateUserData>
-  >({
-    ...updateUserMutation(mutationOptions),
+  return useMutation({
+    ...mutationOptionsWithHeaders<
+      UpdateUserResponses,
+      UpdateUserErrors,
+      UpdateUserData
+    >(mutationOptions, updateUser),
     onSuccess: () => {
       return queryClient.invalidateQueries({
         queryKey: listUsersWithSummaryQueryKey(),
@@ -116,12 +116,12 @@ export const useUpdateUser = (mutationOptions?: Options<UpdateUserData>) => {
 ```typescript
 export const useDeleteUser = (mutationOptions?: Options<DeleteUserData>) => {
   const queryClient = useQueryClient();
-  return useMutation<
-    DeleteUserResponse,
-    DeleteUserError,
-    Options<DeleteUserData>
-  >({
-    ...deleteUserMutation(mutationOptions),
+  return useMutation({
+    ...mutationOptionsWithHeaders<
+      DeleteUserResponses,
+      DeleteUserErrors,
+      DeleteUserData
+    >(mutationOptions, deleteUser),
     onSuccess: () => {
       return queryClient.invalidateQueries({
         queryKey: listUsersWithSummaryQueryKey(),
@@ -418,13 +418,14 @@ describe("useGetUser", () => {
 
 3. **WebSocket Awareness**:
 
-   - Use `useWebsocketAwareQuery` for all queries to automatically invalidate on real-time updates
+   - Use `useWebsocketAwareQuery` with `queryOptionsWithHeaders` for all queries to automatically invalidate on real-time updates
    - Map websocket models to query keys in `base.ts` if needed
 
 4. **Type Safety**:
 
    - Always use the generated types from `@/app/apiclient`
-   - Cast query options to proper types with `as UseQueryOptions`
+   - Use `queryOptionsWithHeaders` and `mutationOptionsWithHeaders` with proper type parameters for automatic type inference
+   - Type parameters follow the pattern: `<Responses, Errors, Data>`
 
 5. **Error Handling**:
 
@@ -446,8 +447,9 @@ describe("useGetUser", () => {
 ## Common Pitfalls
 
 - **Don't** forget to invalidate queries after mutations - stale data is confusing for users
-- **Don't** use `useQuery` directly - always use `useWebsocketAwareQuery` for queries
+- **Don't** use `useQuery` directly - always use `useWebsocketAwareQuery` with `queryOptionsWithHeaders` for queries
+- **Don't** use `useMutation` directly without `mutationOptionsWithHeaders` - you'll miss response headers
 - **Don't** forget to export mock data from resolver files
 - **Don't** forget to set `resolved` flag in resolvers - it's useful for testing
 - **Don't** forget to handle empty states in tests
-- **Don't** forget to type cast query options - TypeScript won't catch type mismatches otherwise
+- **Don't** forget to provide all three type parameters (`Responses`, `Errors`, `Data`) to the utility functions

eslint.config.js

@@ -290,6 +290,7 @@ export default tseslint.config(
       "@typescript-eslint/sort-type-constituents": "error",
       // "@typescript-eslint/strict-boolean-expressions": "error",
       // "@typescript-eslint/switch-exhaustiveness-check": "error",
+      "@typescript-eslint/use-unknown-in-catch-callback-variable": "error",
     },
   },
   {

src/app/api/query/base.ts

@@ -78,22 +78,28 @@ export const useWebsocketAwareQuery = <
   const previousConnectedCount = usePrevious(connectedCount);
 
   useEffect(() => {
-    if (connectedCount !== previousConnectedCount) {
-      queryClient.invalidateQueries({ queryKey: options?.queryKey });
-    }
+    const invalidate = async () => {
+      if (connectedCount !== previousConnectedCount) {
+        await queryClient.invalidateQueries({ queryKey: options?.queryKey });
+      }
+    };
+
+    void invalidate();
   }, [connectedCount, previousConnectedCount, queryClient, options]);
 
   useEffect(() => {
-    return subscribe(({ name: model }: { name: WebSocketEndpointModel }) => {
-      // This mapped key is the key for the websocket notifications
-      // TODO: replace with a function call to deduce the key/condition using the parameters
-      const mappedKey = wsToQueryKeyMapping[model];
-      const modelQueryKey = options?.queryKey[0];
-
-      if (mappedKey && mappedKey === modelQueryKey) {
-        queryClient.invalidateQueries({ queryKey: options?.queryKey });
+    return subscribe(
+      async ({ name: model }: { name: WebSocketEndpointModel }) => {
+        // This mapped key is the key for the websocket notifications
+        // TODO: replace with a function call to deduce the key/condition using the parameters
+        const mappedKey = wsToQueryKeyMapping[model];
+        const modelQueryKey = options?.queryKey[0];
+
+        if (mappedKey && mappedKey === modelQueryKey) {
+          await queryClient.invalidateQueries({ queryKey: options?.queryKey });
+        }
       }
-    });
+    );
   }, [queryClient, subscribe, options]);
 
   return useQuery<TQueryFnData, TError, TData>(options!);

src/app/base/components/ActionForm/ActionForm.tsx

@@ -91,11 +91,11 @@ const ActionForm = <V extends object, E = null>({
   return (
     <FormikForm<V, E>
       onSubmit={(values, formikHelpers) => {
-        onSubmit(values, formikHelpers);
         // Set selected count in component state once form is submitted, so
         // that the saving label is not affected by updates to the component's
         // selectedCount prop, e.g. unselecting or deleting items.
         setSelectedOnSubmit(selectedCount);
+        return onSubmit(values, formikHelpers);
       }}
       savingLabel={
         showProcessingCount

src/app/base/components/DhcpFormFields/DhcpFormFields.tsx

@@ -141,16 +141,20 @@ export const DhcpFormFields = ({ editing }: Props): React.ReactElement => {
         name="type"
         onChange={(e: React.FormEvent) => {
           formikProps.handleChange(e);
-          formikProps.setFieldValue("entity", "").catch((reason) => {
-            throw new FormikFieldChangeError("entity", "setFieldValue", reason);
+          formikProps.setFieldValue("entity", "").catch((reason: unknown) => {
+            throw new FormikFieldChangeError(
+              "entity",
+              "setFieldValue",
+              reason as string
+            );
           });
           formikProps
             .setFieldTouched("entity", false, false)
-            .catch((reason) => {
+            .catch((reason: unknown) => {
               throw new FormikFieldChangeError(
                 "entity",
                 "setFieldTouched",
-                reason
+                reason as string
               );
             });
         }}

src/app/base/components/DhcpFormFields/MachineSelect/MachineSelect.tsx

@@ -52,8 +52,8 @@ export const MachineSelect = ({
   );
   const handleSelect = (machine: Machine | null) => {
     handleClose();
-    setFieldValue(name, machine?.system_id || null).catch((reason) => {
-      throw new FormikFieldChangeError(name, "setFieldValue", reason);
+    setFieldValue(name, machine?.system_id || null).catch((reason: unknown) => {
+      throw new FormikFieldChangeError(name, "setFieldValue", reason as string);
     });
   };
   useOnEscapePressed(handleClose);
@@ -81,11 +81,11 @@ export const MachineSelect = ({
             onClick={() => {
               setIsOpen(!isOpen);
               if (!isOpen) {
-                setFieldValue(name, "", false).catch((reason) => {
+                setFieldValue(name, "", false).catch((reason: unknown) => {
                   throw new FormikFieldChangeError(
                     name,
                     "setFieldValue",
-                    reason
+                    reason as string
                   );
                 });
               }

src/app/base/components/DynamicSelect/DynamicSelect.tsx

@@ -79,8 +79,12 @@ export const DynamicSelect = <V extends FormValues = FormValues>({
           name,
           currentOptionValues.length > 0 ? currentOptionValues[0] : "",
           false
-        ).catch((reason) => {
-          throw new FormikFieldChangeError(name, "setFieldValue", reason);
+        ).catch((reason: unknown) => {
+          throw new FormikFieldChangeError(
+            name,
+            "setFieldValue",
+            reason as string
+          );
         });
       }
     }

src/app/base/components/MacAddressField/MacAddressField.tsx

@@ -19,8 +19,12 @@ export const MacAddressField = ({
       name={name}
       onChange={(evt: React.ChangeEvent<HTMLInputElement>) => {
         setFieldValue(name, formatMacAddress(evt.target.value)).catch(
-          (reason) => {
-            throw new FormikFieldChangeError(name, "setFieldValue", reason);
+          (reason: unknown) => {
+            throw new FormikFieldChangeError(
+              name,
+              "setFieldValue",
+              reason as string
+            );
           }
         );
       }}

src/app/base/components/NodeConfigurationFields/NodeConfigurationFields.tsx

@@ -81,11 +81,11 @@ const NodeConfigurationFields = (): React.ReactElement => {
               }}
               onTagCreated={(tag) => {
                 setFieldValue("tags", values.tags.concat([tag.id])).catch(
-                  (reason) => {
+                  (reason: unknown) => {
                     throw new FormikFieldChangeError(
                       "tags",
                       "setFieldValue",
-                      reason
+                      reason as string
                     );
                   }
                 );

src/app/base/components/PowerTypeFields/BasePowerField/BasePowerField.tsx

@@ -44,13 +44,15 @@ export const BasePowerField = <V extends AnyObject>({
                 const newFieldValue = checked
                   ? fieldValue.filter((val) => val !== checkboxValue)
                   : [...fieldValue, checkboxValue];
-                setFieldValue(fieldName, newFieldValue).catch((reason) => {
-                  throw new FormikFieldChangeError(
-                    fieldName,
-                    "setFieldValue",
-                    reason
-                  );
-                });
+                setFieldValue(fieldName, newFieldValue).catch(
+                  (reason: unknown) => {
+                    throw new FormikFieldChangeError(
+                      fieldName,
+                      "setFieldValue",
+                      reason as string
+                    );
+                  }
+                );
               }}
               type="checkbox"
               value={checkboxValue}