feat(core): deprecate useCustom result property for better type safety

.changeset/five-doors-film.md

@@ -0,0 +1,25 @@
+---
+"@refinedev/core": patch
+---
+
+feat(core): deprecate `result` property in favor of `query.data`
+
+The `result.data` property in `useCustom` hook has been deprecated. This property always returns an empty object during loading state, which could lead to runtime errors when accessing nested properties without proper null checks.
+
+**Migration Guide:**
+
+Instead of using `result.data`, use `query.data.data` to access your custom response data:
+
+```diff
+const { result, query } = useCustom({
+  url: "https://api.example.com/endpoint",
+  method: "get",
+});
+
+- const data = result.data;
++ const data = query.data?.data;
+```
+
+This change provides better type safety and aligns with the underlying React Query behavior, ensuring TypeScript can properly catch potential runtime errors.
+
+Resolves #7088

documentation/docs/data/hooks/use-custom/index.md

@@ -32,7 +32,9 @@ interface PostUniqueCheckResponse {
 
 const apiUrl = useApiUrl();
 
-const { data, isLoading } = useCustom<PostUniqueCheckResponse>({
+const {
+  query: { data, isLoading },
+} = useCustom<PostUniqueCheckResponse>({
   url: `${apiUrl}/posts-unique-check`,
   method: "get",
   config: {
@@ -316,10 +318,11 @@ useCustom({
 
 ### Return value
 
-| Description                             | Type                                                                                                                |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| Result of the TanStack Query's useQuery | [`QueryObserverResult<CustomResponse<TData>, TError>`](https://tanstack.com/query/v4/docs/react/reference/useQuery) |
-| overtime                                | `{ elapsedTime?: number }`                                                                                          |
+| Description                                       | Type                                                                                                                |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| query                                             | [`QueryObserverResult<CustomResponse<TData>, TError>`](https://tanstack.com/query/v4/docs/react/reference/useQuery) |
+| overtime                                          | `{ elapsedTime?: number }`                                                                                          |
+| result <div className="required">Deprecated</div> | `{ data: CustomResponse<TData>["data"] }` Use `query.data?.data` instead                                            |
 
 [baserecord]: /docs/core/interface-references#baserecord
 [httperror]: /docs/core/interface-references#httperror

examples/app-crm-minimal/src/routes/dashboard/index.tsx

@@ -13,42 +13,40 @@ import {
 import { DASHBOARD_TOTAL_COUNTS_QUERY } from "./queries";
 
 export const DashboardPage = () => {
-  const {
-    query: { isLoading },
-
-    result: data,
-  } = useCustom<DashboardTotalCountsQuery>({
+  const { query } = useCustom<DashboardTotalCountsQuery>({
     url: "",
     method: "get",
     meta: { gqlQuery: DASHBOARD_TOTAL_COUNTS_QUERY },
   });
 
+  const { isLoading } = query;
+  const data = query.data?.data;
+
   return (
     <div className="page-container">
       <Row gutter={[32, 32]}>
         <Col xs={24} sm={24} xl={8}>
           <DashboardTotalCountCard
             resource="companies"
             isLoading={isLoading}
-            totalCount={data?.data.companies.totalCount}
+            totalCount={data?.companies.totalCount}
           />
         </Col>
         <Col xs={24} sm={24} xl={8}>
           <DashboardTotalCountCard
             resource="contacts"
             isLoading={isLoading}
-            totalCount={data?.data.contacts.totalCount}
+            totalCount={data?.contacts.totalCount}
           />
         </Col>
         <Col xs={24} sm={24} xl={8}>
           <DashboardTotalCountCard
             resource="deals"
             isLoading={isLoading}
-            totalCount={data?.data.deals.totalCount}
+            totalCount={data?.deals.totalCount}
           />
         </Col>
-      </Row>
-
+      </Row>{" "}
       <Row
         gutter={[32, 32]}
         style={{
@@ -76,7 +74,6 @@ export const DashboardPage = () => {
           <DashboardDealsChart />
         </Col>
       </Row>
-
       <Row
         gutter={[32, 32]}
         style={{

examples/blog-refine-tremor/src/pages/dashboard/index.tsx

@@ -30,29 +30,34 @@ const calculatePercentage = (total: number, target: number): number => {
 export const DashboardPage: React.FC = () => {
   const API_URL = useApiUrl("metrics");
 
-  const { result: dailyRevenue } = useCustom({
+  const { query: dailyRevenueQuery } = useCustom({
     url: `${API_URL}/dailyRevenue`,
     method: "get",
     config: {
       query,
     },
   });
 
-  const { result: dailyOrders } = useCustom({
+  const { query: dailyOrdersQuery } = useCustom({
     url: `${API_URL}/dailyOrders`,
     method: "get",
     config: {
       query,
     },
   });
 
-  const { result: newCustomers } = useCustom({
+  const { query: newCustomersQuery } = useCustom({
     url: `${API_URL}/newCustomers`,
     method: "get",
     config: {
       query,
     },
   });
+
+  const dailyRevenue = dailyRevenueQuery.data?.data;
+  const dailyOrders = dailyOrdersQuery.data?.data;
+  const newCustomers = newCustomersQuery.data?.data;
+
   return (
     <main className="m-2">
       <Title>Dashboard</Title>
@@ -67,40 +72,34 @@ export const DashboardPage: React.FC = () => {
             <Grid numItemsMd={2} numItemsLg={3} className="mt-6 gap-6">
               <KpiCard
                 title="Weekly Revenue"
-                total={`$ ${dailyRevenue?.data.total ?? 0}`}
-                trend={dailyRevenue?.data.trend ?? 0}
+                total={`$ ${dailyRevenue?.total ?? 0}`}
+                trend={dailyRevenue?.trend ?? 0}
                 target="$ 10,500"
                 percentage={calculatePercentage(
-                  dailyRevenue?.data.total ?? 0,
+                  dailyRevenue?.total ?? 0,
                   10_500,
                 )}
               />
               <KpiCard
                 title="Weekly Orders"
-                total={`${dailyOrders?.data.total ?? 0}`}
-                trend={dailyOrders?.data.trend ?? 0}
+                total={`${dailyOrders?.total ?? 0}`}
+                trend={dailyOrders?.trend ?? 0}
                 target="500"
-                percentage={calculatePercentage(
-                  dailyOrders?.data.total ?? 0,
-                  500,
-                )}
+                percentage={calculatePercentage(dailyOrders?.total ?? 0, 500)}
               />
               <KpiCard
                 title="New Customers"
-                total={`${newCustomers?.data.total ?? 0}`}
-                trend={newCustomers?.data.trend ?? 0}
+                total={`${newCustomers?.total ?? 0}`}
+                trend={newCustomers?.trend ?? 0}
                 target="200"
-                percentage={calculatePercentage(
-                  newCustomers?.data.total ?? 0,
-                  200,
-                )}
+                percentage={calculatePercentage(newCustomers?.total ?? 0, 200)}
               />
             </Grid>
             <div className="mt-6">
               <ChartView
-                revenue={dailyRevenue?.data.data ?? []}
-                orders={dailyOrders?.data.data ?? []}
-                customers={newCustomers?.data.data ?? []}
+                revenue={dailyRevenue?.data ?? []}
+                orders={dailyOrders?.data ?? []}
+                customers={newCustomers?.data ?? []}
               />
             </div>
           </TabPanel>

packages/core/src/hooks/data/useCustom.ts

@@ -109,6 +109,9 @@ export type UseCustomProps<TQueryFnData, TError, TQuery, TPayload, TData> = {
 
 export type UseCustomReturnType<TData, TError> = {
   query: QueryObserverResult<CustomResponse<TData>, TError>;
+  /**
+   * @deprecated Please use `query.data.data` instead.
+   */
   result: {
     data: CustomResponse<TData>["data"];
   };