@refinedev/core 4.0.0

package/src/hooks/data/useCustom.ts

@@ -0,0 +1,177 @@
+import {
+    QueryObserverResult,
+    useQuery,
+    UseQueryOptions,
+} from "@tanstack/react-query";
+
+import {
+    CustomResponse,
+    CrudSorting,
+    CrudFilters,
+    BaseRecord,
+    HttpError,
+    MetaQuery,
+    SuccessErrorNotification,
+} from "../../interfaces";
+import {
+    useTranslate,
+    useHandleNotification,
+    useDataProvider,
+    useOnError,
+} from "@hooks";
+import { pickNotDeprecated, useActiveAuthProvider } from "@definitions/helpers";
+
+interface UseCustomConfig<TQuery, TPayload> {
+    /**
+     * @deprecated `sort` is deprecated, use `sorters` instead.
+     */
+    sort?: CrudSorting;
+    sorters?: CrudSorting;
+    filters?: CrudFilters;
+    query?: TQuery;
+    payload?: TPayload;
+    headers?: {};
+}
+
+export type UseCustomProps<TData, TError, TQuery, TPayload> = {
+    /**
+     * request's URL
+     */
+    url: string;
+    /**
+     * request's method (`GET`, `POST`, etc.)
+     */
+    method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";
+    /**
+     * The config of your request. You can send headers, payload, query, filters and sorters using this field
+     */
+    config?: UseCustomConfig<TQuery, TPayload>;
+    /**
+     * react-query's [useQuery](https://tanstack.com/query/v4/docs/reference/useQuery) options"
+     */
+    queryOptions?: UseQueryOptions<CustomResponse<TData>, TError>;
+    /**
+     * meta data for `dataProvider`
+     */
+    meta?: MetaQuery;
+    /**
+     * meta data for `dataProvider`
+     * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+     */
+    metaData?: MetaQuery;
+    /**
+     * If there is more than one `dataProvider`, you should use the `dataProviderName` that you will use.
+     */
+    dataProviderName?: string;
+} & SuccessErrorNotification;
+
+/**
+ * `useCustom` is a modified version of `react-query`'s {@link https://react-query.tanstack.com/guides/queries `useQuery`} used for custom requests.
+ *
+ * It uses the `custom` method from the `dataProvider` which is passed to `<Refine>`.
+ *
+ * @see {@link https://refine.dev/docs/core/hooks/data/useCustom} for more details.
+ *
+ * @typeParam TData - Result data of the query extends {@link https://refine.dev/docs/core/interfaceReferences#baserecord `BaseRecord`}
+ * @typeParam TError - Custom error object that extends {@link https://refine.dev/docs/core/interfaceReferences#httperror `HttpError`}
+ * @typeParam TQuery - Values for query params
+ * @typeParam TPayload - Values for params
+ *
+ */
+export const useCustom = <
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TQuery = unknown,
+    TPayload = unknown,
+>({
+    url,
+    method,
+    config,
+    queryOptions,
+    successNotification,
+    errorNotification,
+    meta,
+    metaData,
+    dataProviderName,
+}: UseCustomProps<TData, TError, TQuery, TPayload>): QueryObserverResult<
+    CustomResponse<TData>,
+    TError
+> => {
+    const dataProvider = useDataProvider();
+
+    const { custom } = dataProvider(dataProviderName);
+    const authProvider = useActiveAuthProvider();
+    const { mutate: checkError } = useOnError({
+        v3LegacyAuthProviderCompatible: Boolean(authProvider?.isLegacy),
+    });
+    const translate = useTranslate();
+    const handleNotification = useHandleNotification();
+
+    if (custom) {
+        const queryResponse = useQuery<CustomResponse<TData>, TError>(
+            [
+                dataProviderName,
+                "custom",
+                method,
+                url,
+                { ...config, ...(pickNotDeprecated(meta, metaData) || {}) },
+            ],
+            ({ queryKey, pageParam, signal }) =>
+                custom<TData>({
+                    url,
+                    method,
+                    ...config,
+                    metaData: {
+                        ...(pickNotDeprecated(meta, metaData) || {}),
+                        queryContext: {
+                            queryKey,
+                            pageParam,
+                            signal,
+                        },
+                    },
+                }),
+            {
+                ...queryOptions,
+                onSuccess: (data) => {
+                    queryOptions?.onSuccess?.(data);
+
+                    const notificationConfig =
+                        typeof successNotification === "function"
+                            ? successNotification(data, {
+                                  ...config,
+                                  ...(pickNotDeprecated(meta, metaData) || {}),
+                              })
+                            : successNotification;
+
+                    handleNotification(notificationConfig);
+                },
+                onError: (err: TError) => {
+                    checkError(err);
+                    queryOptions?.onError?.(err);
+
+                    const notificationConfig =
+                        typeof errorNotification === "function"
+                            ? errorNotification(err, {
+                                  ...config,
+                                  ...(pickNotDeprecated(meta, metaData) || {}),
+                              })
+                            : errorNotification;
+
+                    handleNotification(notificationConfig, {
+                        key: `${method}-notification`,
+                        message: translate(
+                            "notifications.error",
+                            { statusCode: err.statusCode },
+                            `Error (status code: ${err.statusCode})`,
+                        ),
+                        description: err.message,
+                        type: "error",
+                    });
+                },
+            },
+        );
+        return queryResponse;
+    } else {
+        throw Error("Not implemented custom on data provider.");
+    }
+};

package/src/hooks/data/useCustomMutation.ts

@@ -0,0 +1,188 @@
+import {
+    useMutation,
+    UseMutationOptions,
+    UseMutationResult,
+} from "@tanstack/react-query";
+
+import {
+    useDataProvider,
+    useHandleNotification,
+    useTranslate,
+    useOnError,
+} from "@hooks";
+import {
+    CreateResponse,
+    BaseRecord,
+    HttpError,
+    SuccessErrorNotification,
+    MetaQuery,
+} from "../../interfaces";
+import { pickNotDeprecated, useActiveAuthProvider } from "@definitions/helpers";
+
+interface UseCustomMutationConfig {
+    headers?: {};
+}
+
+type useCustomMutationParams<TVariables> = {
+    url: string;
+    method: "post" | "put" | "patch" | "delete";
+    values: TVariables;
+    /**
+     * Meta data for `dataProvider`
+     */
+    meta?: MetaQuery;
+    /**
+     * Meta data for `dataProvider`
+     * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+     */
+    metaData?: MetaQuery;
+    dataProviderName?: string;
+    config?: UseCustomMutationConfig;
+} & SuccessErrorNotification;
+
+export type UseCustomMutationReturnType<
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+> = UseMutationResult<
+    CreateResponse<TData>,
+    TError,
+    useCustomMutationParams<TVariables>,
+    unknown
+>;
+
+export type UseCustomMutationProps<
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+> = {
+    mutationOptions?: Omit<
+        UseMutationOptions<
+            CreateResponse<TData>,
+            TError,
+            useCustomMutationParams<TVariables>,
+            unknown
+        >,
+        "mutationFn" | "onError" | "onSuccess"
+    >;
+};
+
+/**
+ * `useCustomMutation` is a modified version of `react-query`'s {@link https://react-query.tanstack.com/reference/useMutation `useMutation`} for create mutations.
+ *
+ * It uses the `custom` method from the `dataProvider` which is passed to `<Refine>`.
+ *
+ * @see {@link https://refine.dev/docs/api-references/hooks/data/useCustomMutation} for more details.
+ *
+ * @typeParam TData - Result data of the query extends {@link https://refine.dev/docs/api-references/interfaceReferences#baserecord `BaseRecord`}
+ * @typeParam TError - Custom error object that extends {@link https://refine.dev/docs/api-references/interfaceReferences#httperror `HttpError`}
+ * @typeParam TVariables - Values for mutation function
+ *
+ */
+
+export const useCustomMutation = <
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+>({
+    mutationOptions,
+}: UseCustomMutationProps<
+    TData,
+    TError,
+    TVariables
+> = {}): UseCustomMutationReturnType<TData, TError, TVariables> => {
+    const authProvider = useActiveAuthProvider();
+    const { mutate: checkError } = useOnError({
+        v3LegacyAuthProviderCompatible: Boolean(authProvider?.isLegacy),
+    });
+    const handleNotification = useHandleNotification();
+    const dataProvider = useDataProvider();
+    const translate = useTranslate();
+
+    const mutation = useMutation<
+        CreateResponse<TData>,
+        TError,
+        useCustomMutationParams<TVariables>,
+        unknown
+    >(
+        ({
+            url,
+            method,
+            values,
+            meta,
+            metaData,
+            dataProviderName,
+            config,
+        }: useCustomMutationParams<TVariables>) => {
+            const { custom } = dataProvider(dataProviderName);
+
+            if (custom) {
+                return custom<TData>({
+                    url,
+                    method,
+                    payload: values,
+                    meta: pickNotDeprecated(meta, metaData),
+                    metaData: pickNotDeprecated(meta, metaData),
+                    headers: { ...config?.headers },
+                });
+            }
+
+            throw Error("Not implemented custom on data provider.");
+        },
+        {
+            onSuccess: (
+                data,
+                {
+                    successNotification: successNotificationFromProp,
+                    config,
+                    meta,
+                    metaData,
+                },
+            ) => {
+                const notificationConfig =
+                    typeof successNotificationFromProp === "function"
+                        ? successNotificationFromProp(data, {
+                              ...config,
+                              ...(pickNotDeprecated(meta, metaData) || {}),
+                          })
+                        : successNotificationFromProp;
+
+                handleNotification(notificationConfig);
+            },
+            onError: (
+                err: TError,
+                {
+                    errorNotification: errorNotificationFromProp,
+                    method,
+                    config,
+                    meta,
+                    metaData,
+                },
+            ) => {
+                checkError(err);
+
+                const notificationConfig =
+                    typeof errorNotificationFromProp === "function"
+                        ? errorNotificationFromProp(err, {
+                              ...config,
+                              ...(pickNotDeprecated(meta, metaData) || {}),
+                          })
+                        : errorNotificationFromProp;
+
+                handleNotification(notificationConfig, {
+                    key: `${method}-notification`,
+                    message: translate(
+                        "notifications.error",
+                        { statusCode: err.statusCode },
+                        `Error (status code: ${err.statusCode})`,
+                    ),
+                    description: err.message,
+                    type: "error",
+                });
+            },
+            ...mutationOptions,
+        },
+    );
+
+    return mutation;
+};

package/src/hooks/data/useDataProvider.tsx

@@ -0,0 +1,39 @@
+import { useCallback, useContext } from "react";
+
+import { DataContext } from "@contexts/data";
+import {
+    IDataContextProvider,
+    IDataMultipleContextProvider,
+} from "../../interfaces";
+
+export const useDataProvider = (): ((
+    /**
+     * The name of the `data provider` you want to access
+     */
+    dataProviderName?: string,
+) => IDataContextProvider) => {
+    const context = useContext<IDataMultipleContextProvider>(DataContext);
+
+    const handleDataProvider = useCallback(
+        (dataProviderName?: string) => {
+            if (dataProviderName) {
+                const dataProvider = context[dataProviderName];
+                if (!dataProvider) {
+                    throw new Error(
+                        `"${dataProviderName}" Data provider not found`,
+                    );
+                }
+                return context[dataProviderName];
+            }
+            if (context.default) {
+                return context.default;
+            } else
+                throw new Error(
+                    `There is no "default" data provider. Please pass dataProviderName.`,
+                );
+        },
+        [context],
+    );
+
+    return handleDataProvider;
+};