@refinedev/core 4.0.0

package/src/hooks/breadcrumb/index.ts

@@ -0,0 +1,126 @@
+import React, { useContext } from "react";
+import warnOnce from "warn-once";
+
+import { useResource, useTranslate } from "@hooks";
+import { TranslationContext } from "@contexts/translation";
+import { humanizeString, pickNotDeprecated } from "@definitions";
+
+import { IResourceItem } from "../../interfaces";
+import { useRouterType } from "@contexts/router-picker";
+import { getActionRoutesFromResource } from "@definitions/helpers/router";
+import { pickResource } from "../../definitions/helpers/pick-resource/index";
+import { composeRoute } from "@definitions/helpers/router/compose-route";
+import { useParsed } from "@hooks/router/use-parsed";
+
+export type BreadcrumbsType = {
+    label: string;
+    href?: string;
+    icon?: React.ReactNode;
+};
+
+type UseBreadcrumbReturnType = {
+    breadcrumbs: BreadcrumbsType[];
+};
+
+type UseBreadcrumbProps = {
+    /**
+     * Additional params to be used in the route generation process.
+     */
+    meta?: Record<string, string | number>;
+};
+
+export const useBreadcrumb = ({
+    meta: metaFromProps = {},
+}: UseBreadcrumbProps = {}): UseBreadcrumbReturnType => {
+    const routerType = useRouterType();
+    const { i18nProvider } = useContext(TranslationContext);
+    const parsed = useParsed();
+
+    const translate = useTranslate();
+
+    const { resources, resource, action } = useResource();
+
+    const breadcrumbs: BreadcrumbsType[] = [];
+
+    if (!resource?.name) {
+        return { breadcrumbs };
+    }
+
+    const addBreadcrumb = (parentName: string | IResourceItem) => {
+        const parentResource =
+            typeof parentName === "string"
+                ? pickResource(
+                      parentName,
+                      resources,
+                      routerType === "legacy",
+                  ) ?? { name: parentName }
+                : parentName;
+
+        if (parentResource) {
+            const grandParentName = pickNotDeprecated(
+                parentResource?.meta?.parent,
+                parentResource?.parentName,
+            );
+            if (grandParentName) {
+                addBreadcrumb(grandParentName);
+            }
+            const listActionOfResource = getActionRoutesFromResource(
+                parentResource,
+                resources,
+                routerType === "legacy",
+            ).find((r) => r.action === "list");
+
+            const hrefRaw = listActionOfResource?.resource?.list
+                ? listActionOfResource?.route
+                : undefined;
+
+            const href = hrefRaw
+                ? routerType === "legacy"
+                    ? hrefRaw
+                    : composeRoute(hrefRaw, parsed, metaFromProps)
+                : undefined;
+
+            breadcrumbs.push({
+                label:
+                    pickNotDeprecated(
+                        parentResource.meta?.label,
+                        parentResource.options?.label,
+                    ) ??
+                    translate(
+                        `${parentResource.name}.${parentResource.name}`,
+                        humanizeString(parentResource.name),
+                    ),
+                href: href,
+                icon: pickNotDeprecated(
+                    parentResource.meta?.icon,
+                    parentResource.options?.icon,
+                    parentResource.icon,
+                ),
+            });
+        }
+    };
+
+    addBreadcrumb(resource);
+
+    if (action && action !== "list") {
+        const key = `actions.${action}`;
+        const actionLabel = translate(key);
+        if (typeof i18nProvider !== "undefined" && actionLabel === key) {
+            warnOnce(
+                true,
+                `[useBreadcrumb]: Breadcrumb missing translate key for the "${action}" action. Please add "actions.${action}" key to your translation file.\nFor more information, see https://refine.dev/docs/core/hooks/useBreadcrumb/#i18n-support`,
+            );
+            breadcrumbs.push({
+                label: translate(`buttons.${action}`, humanizeString(action)),
+            });
+        } else {
+            breadcrumbs.push({
+                label: translate(key, humanizeString(action)),
+            });
+        }
+    }
+
+    return {
+        breadcrumbs,
+    };
+};

package/src/hooks/data/index.ts

@@ -0,0 +1,18 @@
+export { useList } from "./useList";
+export { useOne } from "./useOne";
+export { useMany } from "./useMany";
+
+export { useUpdate } from "./useUpdate";
+export { useCreate, UseCreateReturnType } from "./useCreate";
+export { useDelete } from "./useDelete";
+
+export { useCreateMany, UseCreateManyReturnType } from "./useCreateMany";
+export { useUpdateMany } from "./useUpdateMany";
+export { useDeleteMany } from "./useDeleteMany";
+
+export { useApiUrl } from "./useApiUrl";
+export { useCustom } from "./useCustom";
+export { useCustomMutation } from "./useCustomMutation";
+
+export { useDataProvider } from "./useDataProvider";
+export { useInfiniteList } from "./useInfiniteList";

package/src/hooks/data/useApiUrl.ts

@@ -0,0 +1,9 @@
+import { useDataProvider } from "@hooks";
+
+export const useApiUrl = (dataProviderName?: string): string => {
+    const dataProvider = useDataProvider();
+
+    const { getApiUrl } = dataProvider(dataProviderName);
+
+    return getApiUrl();
+};

package/src/hooks/data/useCreate.ts

@@ -0,0 +1,258 @@
+import {
+    useMutation,
+    UseMutationOptions,
+    UseMutationResult,
+} from "@tanstack/react-query";
+import pluralize from "pluralize";
+import {
+    pickDataProvider,
+    pickNotDeprecated,
+    useActiveAuthProvider,
+} from "@definitions/helpers";
+
+import {
+    CreateResponse,
+    BaseRecord,
+    HttpError,
+    SuccessErrorNotification,
+    MetaQuery,
+    IQueryKeys,
+} from "../../interfaces";
+import {
+    useResource,
+    useTranslate,
+    usePublish,
+    useHandleNotification,
+    useDataProvider,
+    useLog,
+    useInvalidate,
+    useOnError,
+} from "@hooks";
+
+type useCreateParams<TVariables> = {
+    /**
+     * Resource name for API data interactions
+     */
+    resource: string;
+    /**
+     * Values for mutation function
+     */
+    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;
+    /**
+     * If there is more than one `dataProvider`, you should use the `dataProviderName` that you will use.
+     */
+    dataProviderName?: string;
+    /**
+     * You can use it to manage the invalidations that will occur at the end of the mutation.
+     */
+    invalidates?: Array<keyof IQueryKeys>;
+} & SuccessErrorNotification;
+
+export type UseCreateReturnType<
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+> = UseMutationResult<
+    CreateResponse<TData>,
+    TError,
+    useCreateParams<TVariables>,
+    unknown
+>;
+
+export type UseCreateProps<
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+> = {
+    mutationOptions?: Omit<
+        UseMutationOptions<
+            CreateResponse<TData>,
+            TError,
+            useCreateParams<TVariables>,
+            unknown
+        >,
+        "mutationFn" | "onError" | "onSuccess"
+    >;
+};
+
+/**
+ * `useCreate` is a modified version of `react-query`'s {@link https://react-query.tanstack.com/reference/useMutation `useMutation`} for create mutations.
+ *
+ * It uses `create` method as mutation function from the `dataProvider` which is passed to `<Refine>`.
+ *
+ * @see {@link https://refine.dev/docs/api-references/hooks/data/useCreate} 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 useCreate = <
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+>({
+    mutationOptions,
+}: UseCreateProps<TData, TError, TVariables> = {}): UseCreateReturnType<
+    TData,
+    TError,
+    TVariables
+> => {
+    const authProvider = useActiveAuthProvider();
+    const { mutate: checkError } = useOnError({
+        v3LegacyAuthProviderCompatible: Boolean(authProvider?.isLegacy),
+    });
+    const dataProvider = useDataProvider();
+    const invalidateStore = useInvalidate();
+
+    const { resources } = useResource();
+
+    const translate = useTranslate();
+    const publish = usePublish();
+    const { log } = useLog();
+    const handleNotification = useHandleNotification();
+
+    const mutation = useMutation<
+        CreateResponse<TData>,
+        TError,
+        useCreateParams<TVariables>,
+        unknown
+    >(
+        ({
+            resource,
+            values,
+            meta,
+            metaData,
+            dataProviderName,
+        }: useCreateParams<TVariables>) => {
+            return dataProvider(
+                pickDataProvider(resource, dataProviderName, resources),
+            ).create<TData, TVariables>({
+                resource,
+                variables: values,
+                meta: pickNotDeprecated(meta, metaData),
+                metaData: pickNotDeprecated(meta, metaData),
+            });
+        },
+        {
+            onSuccess: (
+                data,
+                {
+                    resource,
+                    successNotification: successNotificationFromProp,
+                    dataProviderName,
+                    invalidates = ["list", "many"],
+                    values,
+                    meta,
+                    metaData,
+                },
+            ) => {
+                const resourceSingular = pluralize.singular(resource);
+
+                const notificationConfig =
+                    typeof successNotificationFromProp === "function"
+                        ? successNotificationFromProp(data, values, resource)
+                        : successNotificationFromProp;
+
+                handleNotification(notificationConfig, {
+                    key: `create-${resource}-notification`,
+                    message: translate(
+                        "notifications.createSuccess",
+                        {
+                            resource: translate(
+                                `${resource}.${resource}`,
+                                resourceSingular,
+                            ),
+                        },
+                        `Successfully created ${resourceSingular}`,
+                    ),
+                    description: translate("notifications.success", "Success"),
+                    type: "success",
+                });
+
+                invalidateStore({
+                    resource,
+                    dataProviderName: pickDataProvider(
+                        resource,
+                        dataProviderName,
+                        resources,
+                    ),
+                    invalidates,
+                });
+
+                publish?.({
+                    channel: `resources/${resource}`,
+                    type: "created",
+                    payload: {
+                        ids: data?.data?.id ? [data.data.id] : undefined,
+                    },
+                    date: new Date(),
+                });
+
+                const { fields, operation, variables, ...rest } =
+                    pickNotDeprecated(meta, metaData) || {};
+
+                log?.mutate({
+                    action: "create",
+                    resource,
+                    data: values,
+                    meta: {
+                        dataProviderName: pickDataProvider(
+                            resource,
+                            dataProviderName,
+                            resources,
+                        ),
+                        id: data?.data?.id ?? undefined,
+                        ...rest,
+                    },
+                });
+            },
+            onError: (
+                err: TError,
+                {
+                    resource,
+                    errorNotification: errorNotificationFromProp,
+                    values,
+                },
+            ) => {
+                checkError(err);
+                const resourceSingular = pluralize.singular(resource);
+
+                const notificationConfig =
+                    typeof errorNotificationFromProp === "function"
+                        ? errorNotificationFromProp(err, values, resource)
+                        : errorNotificationFromProp;
+
+                handleNotification(notificationConfig, {
+                    key: `create-${resource}-notification`,
+                    description: err.message,
+                    message: translate(
+                        "notifications.createError",
+                        {
+                            resource: translate(
+                                `${resource}.${resource}`,
+                                resourceSingular,
+                            ),
+                            statusCode: err.statusCode,
+                        },
+                        `There was an error creating ${resourceSingular} (status code: ${err.statusCode})`,
+                    ),
+                    type: "error",
+                });
+            },
+            ...mutationOptions,
+        },
+    );
+
+    return mutation;
+};

package/src/hooks/data/useCreateMany.ts

@@ -0,0 +1,239 @@
+import {
+    useMutation,
+    UseMutationOptions,
+    UseMutationResult,
+} from "@tanstack/react-query";
+import pluralize from "pluralize";
+
+import {
+    BaseRecord,
+    CreateManyResponse,
+    HttpError,
+    SuccessErrorNotification,
+    MetaQuery,
+    IQueryKeys,
+} from "../../interfaces";
+import {
+    useResource,
+    useTranslate,
+    usePublish,
+    useHandleNotification,
+    useDataProvider,
+    useInvalidate,
+    useLog,
+} from "@hooks";
+import {
+    handleMultiple,
+    pickDataProvider,
+    pickNotDeprecated,
+} from "@definitions";
+
+type useCreateManyParams<TVariables> = {
+    resource: string;
+    values: TVariables[];
+    meta?: MetaQuery;
+    metaData?: MetaQuery;
+    dataProviderName?: string;
+    invalidates?: Array<keyof IQueryKeys>;
+} & SuccessErrorNotification;
+
+export type UseCreateManyReturnType<
+    TData extends BaseRecord = BaseRecord,
+    TError = HttpError,
+    TVariables = {},
+> = UseMutationResult<
+    CreateManyResponse<TData>,
+    TError,
+    useCreateManyParams<TVariables>,
+    unknown
+>;
+
+export type UseCreateManyProps<
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+> = {
+    mutationOptions?: Omit<
+        UseMutationOptions<
+            CreateManyResponse<TData>,
+            TError,
+            useCreateManyParams<TVariables>
+        >,
+        "mutationFn" | "onError" | "onSuccess"
+    >;
+};
+
+/**
+ * `useCreateMany` is a modified version of `react-query`'s {@link https://react-query.tanstack.com/reference/useMutation `useMutation`} for multiple create mutations.
+ *
+ * It uses `createMany` method as mutation function from the `dataProvider` which is passed to `<Refine>`.
+ *
+ * @see {@link https://refine.dev/docs/core/hooks/data/useCreateMany} 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 TVariables - Values for mutation function
+ *
+ */
+export const useCreateMany = <
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = {},
+>({
+    mutationOptions,
+}: UseCreateManyProps<TData, TError, TVariables> = {}): UseCreateManyReturnType<
+    TData,
+    TError,
+    TVariables
+> => {
+    const dataProvider = useDataProvider();
+
+    const { resources } = useResource();
+    const translate = useTranslate();
+    const publish = usePublish();
+    const handleNotification = useHandleNotification();
+    const invalidateStore = useInvalidate();
+    const { log } = useLog();
+
+    const mutation = useMutation<
+        CreateManyResponse<TData>,
+        TError,
+        useCreateManyParams<TVariables>
+    >(
+        ({
+            resource,
+            values,
+            meta,
+            metaData,
+            dataProviderName,
+        }: useCreateManyParams<TVariables>) => {
+            const selectedDataProvider = dataProvider(
+                pickDataProvider(resource, dataProviderName, resources),
+            );
+
+            if (selectedDataProvider.createMany) {
+                return selectedDataProvider.createMany<TData, TVariables>({
+                    resource,
+                    variables: values,
+                    meta: pickNotDeprecated(meta, metaData),
+                    metaData: pickNotDeprecated(meta, metaData),
+                });
+            } else {
+                return handleMultiple(
+                    values.map((val) =>
+                        selectedDataProvider.create<TData, TVariables>({
+                            resource,
+                            variables: val,
+                            meta: pickNotDeprecated(meta, metaData),
+                            metaData: pickNotDeprecated(meta, metaData),
+                        }),
+                    ),
+                );
+            }
+        },
+        {
+            onSuccess: (
+                response,
+                {
+                    resource,
+                    successNotification,
+                    dataProviderName,
+                    invalidates = ["list", "many"],
+                    values,
+                    meta,
+                    metaData,
+                },
+            ) => {
+                const resourcePlural = pluralize.plural(resource);
+
+                const notificationConfig =
+                    typeof successNotification === "function"
+                        ? successNotification(response, values, resource)
+                        : successNotification;
+
+                handleNotification(notificationConfig, {
+                    key: `createMany-${resource}-notification`,
+                    message: translate(
+                        "notifications.createSuccess",
+                        {
+                            resource: translate(
+                                `${resource}.${resource}`,
+                                resource,
+                            ),
+                        },
+                        `Successfully created ${resourcePlural}`,
+                    ),
+                    description: translate("notifications.success", "Success"),
+                    type: "success",
+                });
+
+                invalidateStore({
+                    resource,
+                    dataProviderName: pickDataProvider(
+                        resource,
+                        dataProviderName,
+                        resources,
+                    ),
+                    invalidates,
+                });
+
+                const ids = response?.data
+                    .filter((item) => item?.id !== undefined)
+                    .map((item) => item.id!);
+
+                publish?.({
+                    channel: `resources/${resource}`,
+                    type: "created",
+                    payload: {
+                        ids,
+                    },
+                    date: new Date(),
+                });
+
+                const { fields, operation, variables, ...rest } =
+                    pickNotDeprecated(meta, metaData) || {};
+
+                log?.mutate({
+                    action: "createMany",
+                    resource,
+                    data: values,
+                    meta: {
+                        dataProviderName: pickDataProvider(
+                            resource,
+                            dataProviderName,
+                            resources,
+                        ),
+                        ids,
+                        ...rest,
+                    },
+                });
+            },
+            onError: (err: TError, { resource, errorNotification, values }) => {
+                const notificationConfig =
+                    typeof errorNotification === "function"
+                        ? errorNotification(err, values, resource)
+                        : errorNotification;
+
+                handleNotification(notificationConfig, {
+                    key: `createMany-${resource}-notification`,
+                    description: err.message,
+                    message: translate(
+                        "notifications.createError",
+                        {
+                            resource: translate(
+                                `${resource}.${resource}`,
+                                resource,
+                            ),
+                            statusCode: err.statusCode,
+                        },
+                        `There was an error creating ${resource} (status code: ${err.statusCode}`,
+                    ),
+                    type: "error",
+                });
+            },
+            ...mutationOptions,
+        },
+    );
+
+    return mutation;
+};