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

[alicanerdurmaz]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://refine.dev/docs/guides-concepts/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://refine.dev/docs/guides-concepts/contributing/#creating-a-changeset

What is the current behavior?

The useCustom hook returns a result.data property that always contains an empty object during loading states. This causes type safety issues where TypeScript cannot properly catch potential runtime errors when accessing nested properties.

For example:

const { result } = useCustom<MyData>({ url: "api/endpoint", method: "get" });
// TypeScript doesn't catch this error - result.data is empty object during loading
result.data.someProperty.map(() => console.log);

This is an undocumented breaking change that can lead to runtime errors.

What is the new behavior?

The result property is now deprecated with proper warnings and documentation:

1. JSDoc deprecation: Added @deprecated comment to the type definition directing users to use query.data?.data
2. Documentation updated: Added migration guide and examples showing the correct usage pattern
3. Examples updated: Updated existing examples to use the new recommended pattern

Recommended usage:

const {
  query: { data },
} = useCustom<MyData>({ url: "api/endpoint", method: "get" });
const responseData = data?.data; // Properly typed and null-safe

This provides better type safety and aligns with TanStack Query patterns.

fixes #7088

Notes for reviewers

• The result property is not removed, only deprecated - this maintains backward compatibility
• Updated two example files to demonstrate the new pattern with cleaner variable naming
• The changeset explains the migration path for users

[changeset-bot]

🦋 Changeset detected

Latest commit: e7b22ae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@refinedev/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for refine-doc-live-previews ready!

Name	Link
🔨 Latest commit	e7b22ae
🔍 Latest deploy log	https://app.netlify.com/projects/refine-doc-live-previews/deploys/691adb2e79ebc800080087d2
😎 Deploy Preview	https://deploy-preview-7110--refine-doc-live-previews.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[cypress]

refine    Run #12351

Run Properties:   Passed #12351  •  cc22f050cb ℹ️: Merge e7b22ae70a39eab041fceb09a590aa5a99c4d263 into 0c8767113fda3edcc044518218d5...

Project	refine
Branch Review	fix/deprecate-use-custom-returned-result-value
Run status	Passed #12351
Run duration	20m 05s
Commit	cc22f050cb ℹ️: Merge e7b22ae70a39eab041fceb09a590aa5a99c4d263 into 0c8767113fda3edcc044518218d5...
Committer	Alican Erdurmaz
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	0
Pending	22
Skipped	0
Passing	378
View all changes introduced in this branch ↗︎

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.