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: e438b49

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	e438b49
🔍 Latest deploy log	https://app.netlify.com/projects/refine-doc-live-previews/deploys/691465ff20dd0500082bb919
😎 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 #12343

Run Properties:   Passed #12343  •  8af1aa2fff ℹ️: Merge e438b492aafd0ca9ecb70643ca6367be5e54067b into 820981779628219e05eef4c2320a...

Project	refine
Branch Review	fix/deprecate-use-custom-returned-result-value
Run status	Passed #12343
Run duration	19m 07s
Commit	8af1aa2fff ℹ️: Merge e438b492aafd0ca9ecb70643ca6367be5e54067b into 820981779628219e05eef4c2320a...
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 ↗︎