@refinedev/core 4.0.0

package/src/hooks/import/index.tsx

@@ -0,0 +1,336 @@
+import { useEffect, useState } from "react";
+import { parse, ParseConfig } from "papaparse";
+import chunk from "lodash/chunk";
+
+import { useCreate, useCreateMany, useResource } from "@hooks";
+import { MapDataFn, BaseRecord, HttpError, MetaQuery } from "../../interfaces";
+import {
+    importCSVMapper,
+    sequentialPromises,
+    pickNotDeprecated,
+} from "@definitions";
+import { UseCreateReturnType } from "../../hooks/data/useCreate";
+import { UseCreateManyReturnType } from "../../hooks/data/useCreateMany";
+
+export type ImportSuccessResult<TVariables, TData> = {
+    request: TVariables[];
+    type: "success";
+    response: TData[];
+};
+
+export type ImportErrorResult<TVariables> = {
+    request: TVariables[];
+    type: "error";
+    response: HttpError[];
+};
+
+export type OnFinishParams<TVariables, TData> = {
+    succeeded: ImportSuccessResult<TVariables, TData>[];
+    errored: ImportErrorResult<TVariables>[];
+};
+
+export type OnProgressParams = {
+    totalAmount: number;
+    processedAmount: number;
+};
+
+export type ImportOptions<
+    TItem,
+    TVariables = any,
+    TData extends BaseRecord = BaseRecord,
+> = {
+    /**
+     * Resource name for API data interactions.
+     * @default Resource name that it reads from route
+     * @deprecated `resourceName` is deprecated. Use `resource` instead.
+     */
+    resourceName?: string;
+    /**
+     * Resource name for API data interactions.
+     * @default Resource name that it reads from route
+     */
+    resource?: string;
+    /**
+     * A mapping function that runs for every record. Mapped data will be included in the file contents.
+     */
+    mapData?: MapDataFn<TItem, TVariables>;
+    /**
+     * Custom Papa Parse options.
+     * @type [`ParseConfig`](https://www.papaparse.com/docs)
+     */
+    paparseOptions?: ParseConfig;
+    /**
+     * Requests batch size. If it is 1, all records are sent one by one. By default, it is [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) to send all records in one batch. If it is more than 1, `createMany` should be implemented on DataProvider.
+     */
+    batchSize?: number;
+    /**
+     * Called with errors and successful responses when all requests are sent.
+     */
+    onFinish?: (results: OnFinishParams<TVariables, TData>) => void;
+    /**
+     *  Metadata query for `dataProvider`
+     */
+    meta?: MetaQuery;
+    /**
+     *  Metadata query for `dataProvider`
+     * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+     */
+    metaData?: MetaQuery;
+    /**
+     *  A callback function that returns a current state of uploading process.
+     *
+     *  Ex: `percentage = onProgressParams.processedAmount / onProgressParams.totalAmount * 100`
+     */
+    onProgress?: (onProgressParams: OnProgressParams) => void;
+    /**
+     * If there is more than one `dataProvider`, you should use the `dataProviderName` that you will use.
+     */
+    dataProviderName?: string;
+};
+
+export type CreatedValuesType<TVariables, TData> =
+    | ImportSuccessResult<TVariables, TData>
+    | ImportErrorResult<TVariables>;
+
+export type HandleChangeType<TVariables, TData> = (onChangeParams: {
+    file: Partial<File>;
+}) => Promise<CreatedValuesType<TVariables, TData>[]>;
+
+export type UseImportInputPropsType = {
+    type: "file";
+    accept: string;
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+};
+
+export type UseImportReturnType<
+    TData extends BaseRecord = BaseRecord,
+    TVariables = {},
+    TError extends HttpError = HttpError,
+> = {
+    inputProps: UseImportInputPropsType;
+    mutationResult:
+        | UseCreateReturnType<TData, TError, TVariables>
+        | UseCreateManyReturnType<TData, TError, TVariables>;
+    isLoading: boolean;
+    handleChange: HandleChangeType<TVariables, TData>;
+};
+
+/**
+ * `useImport` hook allows you to handle your csv import logic easily.
+ *
+ * @see {@link https://refine.dev/docs/core/hooks/import-export/useImport} for more details.
+ *
+ * @typeParam TItem - Interface of parsed csv data
+ * @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 useImport = <
+    TItem = any,
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+    TVariables = any,
+>({
+    resourceName,
+    resource: resourceFromProps,
+    mapData = (item) => item as unknown as TVariables,
+    paparseOptions,
+    batchSize = Number.MAX_SAFE_INTEGER,
+    onFinish,
+    meta,
+    metaData,
+    onProgress,
+    dataProviderName,
+}: ImportOptions<TItem, TVariables, TData> = {}): UseImportReturnType<
+    TData,
+    TVariables,
+    TError
+> => {
+    const [processedAmount, setProcessedAmount] = useState<number>(0);
+    const [totalAmount, setTotalAmount] = useState<number>(0);
+    const [isLoading, setIsLoading] = useState(false);
+
+    const { resource } = useResource(resourceFromProps ?? resourceName);
+
+    const createMany = useCreateMany<TData, TError, TVariables>();
+    const create = useCreate<TData, TError, TVariables>();
+
+    let mutationResult:
+        | UseCreateReturnType<TData, TError, TVariables>
+        | UseCreateManyReturnType<TData, TError, TVariables>;
+
+    if (batchSize === 1) {
+        mutationResult = create;
+    } else {
+        mutationResult = createMany;
+    }
+
+    const handleCleanup = () => {
+        setTotalAmount(0);
+        setProcessedAmount(0);
+        setIsLoading(false);
+    };
+
+    const handleFinish = (
+        createdValues: CreatedValuesType<TVariables, TData>[],
+    ) => {
+        const result = {
+            succeeded: createdValues.filter(
+                (item) => item.type === "success",
+            ) as unknown as ImportSuccessResult<TVariables, TData>[],
+            errored: createdValues.filter(
+                (item) => item.type === "error",
+            ) as unknown as ImportErrorResult<TVariables>[],
+        };
+
+        onFinish?.(result);
+        setIsLoading(false);
+    };
+
+    useEffect(() => {
+        onProgress?.({ totalAmount, processedAmount });
+    }, [totalAmount, processedAmount]);
+
+    const handleChange: HandleChangeType<TVariables, TData> = ({ file }) => {
+        handleCleanup();
+        return new Promise<CreatedValuesType<TVariables, TData>[]>(
+            (resolve) => {
+                setIsLoading(true);
+                parse(file as any, {
+                    complete: async ({ data }: { data: unknown[][] }) => {
+                        const values = importCSVMapper(data, mapData);
+
+                        setTotalAmount(values.length);
+
+                        if (batchSize === 1) {
+                            // Create Processor Functions
+                            const valueFns = values.map((value) => {
+                                const fn = async () => {
+                                    const response = await create.mutateAsync({
+                                        resource: resource?.name ?? "",
+                                        values: value,
+                                        successNotification: false,
+                                        errorNotification: false,
+                                        dataProviderName,
+                                        meta: pickNotDeprecated(meta, metaData),
+                                        metaData: pickNotDeprecated(
+                                            meta,
+                                            metaData,
+                                        ),
+                                    });
+
+                                    return { response, value };
+                                };
+                                return fn;
+                            });
+                            // Sequentially run processor functions and process resolves/rejects
+                            const createdValues = await sequentialPromises(
+                                valueFns,
+                                ({ response, value }) => {
+                                    setProcessedAmount((currentAmount) => {
+                                        return currentAmount + 1;
+                                    });
+
+                                    return {
+                                        response: [response.data],
+                                        type: "success",
+                                        request: [value],
+                                    } as ImportSuccessResult<TVariables, TData>;
+                                },
+                                (error: HttpError, index) => {
+                                    return {
+                                        response: [error],
+                                        type: "error",
+                                        request: [values[index]],
+                                    } as ImportErrorResult<TVariables>;
+                                },
+                            );
+                            // Resolve with created values
+                            resolve(createdValues);
+                        } else {
+                            // Create Chunks
+                            const chunks = chunk(values, batchSize);
+                            // Create Chunk Processor Functions
+                            const chunkedFns = chunks.map((chunkedValues) => {
+                                const fn = async () => {
+                                    const response =
+                                        await createMany.mutateAsync({
+                                            resource: resource?.name ?? "",
+                                            values: chunkedValues,
+                                            successNotification: false,
+                                            errorNotification: false,
+                                            dataProviderName,
+                                            meta: pickNotDeprecated(
+                                                meta,
+                                                metaData,
+                                            ),
+                                            metaData: pickNotDeprecated(
+                                                meta,
+                                                metaData,
+                                            ),
+                                        });
+
+                                    return {
+                                        response,
+                                        value: chunkedValues,
+                                        currentBatchLength:
+                                            chunkedValues.length,
+                                    };
+                                };
+
+                                return fn;
+                            });
+                            // Sequentially run chunked functions and process resolves/rejects
+                            const createdValues = await sequentialPromises(
+                                chunkedFns,
+                                ({ response, currentBatchLength, value }) => {
+                                    setProcessedAmount((currentAmount) => {
+                                        return (
+                                            currentAmount + currentBatchLength
+                                        );
+                                    });
+
+                                    return {
+                                        response: response.data,
+                                        type: "success",
+                                        request: value,
+                                    } as ImportSuccessResult<TVariables, TData>;
+                                },
+                                (error: HttpError, index) => {
+                                    return {
+                                        response: [error],
+                                        type: "error",
+                                        request: chunks[index],
+                                    } as ImportErrorResult<TVariables>;
+                                },
+                            );
+                            // resolve with all created values
+                            resolve(createdValues);
+                        }
+                    },
+
+                    ...paparseOptions,
+                });
+            },
+        ).then((createdValues) => {
+            handleFinish(createdValues);
+            return createdValues;
+        });
+    };
+
+    return {
+        inputProps: {
+            type: "file",
+            accept: ".csv",
+            onChange: (event: React.ChangeEvent<HTMLInputElement>) => {
+                if (event.target.files && event.target.files.length > 0) {
+                    handleChange({ file: event.target.files[0] });
+                }
+            },
+        },
+        mutationResult,
+        isLoading,
+        handleChange,
+    };
+};

package/src/hooks/index.ts

@@ -0,0 +1,24 @@
+export * from "./auth";
+export * from "./data";
+export * from "./live";
+export * from "./resource";
+export * from "./notification";
+export * from "./translate";
+export * from "./refine";
+export * from "./export";
+export * from "./form";
+export * from "./redirection";
+export * from "./navigation";
+export * from "./show";
+export * from "./import";
+export * from "./modal";
+export * from "./router";
+export { useRouterType } from "../contexts/router-picker";
+export * from "./legacy-router";
+export * from "./accessControl";
+export * from "./useSelect";
+export * from "./useTable";
+export * from "./auditLog";
+export * from "./invalidate";
+export * from "./breadcrumb";
+export * from "./menu";

package/src/hooks/invalidate/index.tsx

@@ -0,0 +1,62 @@
+import { useCallback } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+
+import { useResource } from "@hooks/resource";
+import { queryKeys, pickDataProvider } from "@definitions";
+import { BaseKey, IQueryKeys } from "../../interfaces";
+
+export type UseInvalidateProp = {
+    resource?: string;
+    id?: BaseKey;
+    dataProviderName?: string;
+    invalidates: Array<keyof IQueryKeys> | false;
+};
+
+export const useInvalidate = (): ((props: UseInvalidateProp) => void) => {
+    const { resources } = useResource();
+    const queryClient = useQueryClient();
+
+    const invalidate = useCallback(
+        ({
+            resource,
+            dataProviderName,
+            invalidates,
+            id,
+        }: UseInvalidateProp) => {
+            if (invalidates === false) {
+                return;
+            }
+            const queryKey = queryKeys(
+                resource,
+                pickDataProvider(resource, dataProviderName, resources),
+            );
+
+            invalidates.forEach((key) => {
+                switch (key) {
+                    case "all":
+                        queryClient.invalidateQueries(queryKey.all);
+                        break;
+                    case "list":
+                        queryClient.invalidateQueries(queryKey.list());
+                        break;
+                    case "many":
+                        queryClient.invalidateQueries(queryKey.many());
+                        break;
+                    case "resourceAll":
+                        queryClient.invalidateQueries(queryKey.resourceAll);
+                        break;
+                    case "detail":
+                        queryClient.invalidateQueries(
+                            queryKey.detail(id || ""),
+                        );
+                        break;
+                    default:
+                        break;
+                }
+            });
+        },
+        [],
+    );
+
+    return invalidate;
+};

package/src/hooks/legacy-router/index.ts

@@ -0,0 +1 @@
+export * from "./useRouterContext";

package/src/hooks/legacy-router/useRouterContext.ts

@@ -0,0 +1,18 @@
+import { useContext } from "react";
+import { RouterContext, defaultProvider } from "@contexts/legacy-router";
+
+export const useRouterContext = () => {
+    const routerContextValues = useContext(RouterContext);
+
+    const { useHistory, useLocation, useParams, Prompt, Link, routes } =
+        routerContextValues ?? defaultProvider;
+
+    return {
+        useHistory,
+        useLocation,
+        useParams,
+        Prompt,
+        Link,
+        routes,
+    };
+};

package/src/hooks/live/index.ts

@@ -0,0 +1,4 @@
+export * from "./useResourceSubscription";
+export * from "./useLiveMode";
+export * from "./useSubscription";
+export * from "./usePublish";

package/src/hooks/live/useLiveMode/index.ts

@@ -0,0 +1,12 @@
+import { useContext } from "react";
+import { LiveModeProps, IRefineContext } from "../../../interfaces";
+import { RefineContext } from "@contexts/refine";
+
+export const useLiveMode = (
+    liveMode: LiveModeProps["liveMode"],
+): LiveModeProps["liveMode"] => {
+    const { liveMode: liveModeFromContext } =
+        useContext<IRefineContext>(RefineContext);
+
+    return liveMode ?? liveModeFromContext;
+};

package/src/hooks/live/usePublish/index.ts

@@ -0,0 +1,10 @@
+import { useContext } from "react";
+
+import { LiveContext } from "@contexts/live";
+import { ILiveContext } from "../../../interfaces";
+
+export const usePublish: () => NonNullable<ILiveContext>["publish"] = () => {
+    const liveContext = useContext<ILiveContext>(LiveContext);
+
+    return liveContext?.publish;
+};

package/src/hooks/live/useResourceSubscription/index.ts

@@ -0,0 +1,99 @@
+import { useContext, useEffect } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+    BaseKey,
+    CrudFilters,
+    CrudSorting,
+    ILiveContext,
+    IRefineContext,
+    LiveEvent,
+    LiveModeProps,
+    MetaQuery,
+    Pagination,
+} from "../../../interfaces";
+import { LiveContext } from "@contexts/live";
+import { RefineContext } from "@contexts/refine";
+import { queryKeys } from "@definitions";
+
+export type UseResourceSubscriptionProps = {
+    channel: string;
+    params?: {
+        ids?: BaseKey[];
+        id?: BaseKey;
+        meta?: MetaQuery;
+        /**
+         * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+         */
+        metaData?: MetaQuery;
+        pagination?: Pagination;
+        /**
+         * @deprecated `hasPagination` is deprecated, use `pagination.mode` instead.
+         */
+        hasPagination?: boolean;
+        /**
+         * @deprecated `sort` is deprecated. Use `sorters` instead.
+         */
+        sort?: CrudSorting;
+        sorters?: CrudSorting;
+        filters?: CrudFilters;
+        subscriptionType: "useList" | "useOne" | "useMany";
+        [key: string]: any;
+    };
+    types: LiveEvent["type"][];
+    resource?: string;
+    enabled?: boolean;
+} & LiveModeProps;
+
+export type PublishType = {
+    (event: LiveEvent): void;
+};
+
+export const useResourceSubscription = ({
+    resource,
+    params,
+    channel,
+    types,
+    enabled = true,
+    liveMode: liveModeFromProp,
+    onLiveEvent,
+}: UseResourceSubscriptionProps): void => {
+    const queryClient = useQueryClient();
+    const queryKey = queryKeys(resource);
+
+    const liveDataContext = useContext<ILiveContext>(LiveContext);
+    const {
+        liveMode: liveModeFromContext,
+        onLiveEvent: onLiveEventContextCallback,
+    } = useContext<IRefineContext>(RefineContext);
+
+    const liveMode = liveModeFromProp ?? liveModeFromContext;
+
+    useEffect(() => {
+        let subscription: any;
+
+        if (liveMode && liveMode !== "off" && enabled) {
+            subscription = liveDataContext?.subscribe({
+                channel,
+                params: {
+                    resource,
+                    ...params,
+                },
+                types,
+                callback: (event) => {
+                    if (liveMode === "auto") {
+                        queryClient.invalidateQueries(queryKey.resourceAll);
+                    }
+
+                    onLiveEvent?.(event);
+                    onLiveEventContextCallback?.(event);
+                },
+            });
+        }
+
+        return () => {
+            if (subscription) {
+                liveDataContext?.unsubscribe(subscription);
+            }
+        };
+    }, [enabled]);
+};

package/src/hooks/live/useSubscription/index.ts

@@ -0,0 +1,85 @@
+import { useContext, useEffect } from "react";
+
+import { LiveContext } from "@contexts/live";
+import {
+    BaseKey,
+    CrudFilters,
+    CrudSorting,
+    ILiveContext,
+    LiveEvent,
+    MetaQuery,
+    Pagination,
+} from "../../../interfaces";
+
+export type UseSubscriptionProps = {
+    /**
+     * Channel name to subscribe.
+     */
+    channel: string;
+    /**
+     * Callback that is run when new events from subscription arrive.
+     */
+    onLiveEvent: (event: LiveEvent) => void;
+    /**
+     * Type of events to subscribe. `"*"` means all events.
+     * @type Array<"deleted" | "updated" | "created" | "*" | string>
+     */
+    types?: LiveEvent["type"][];
+    /**
+     * Determines subscription should subscribe or not.
+     * @type Array<"deleted" | "updated" | "created" | "*" | string>
+     */
+    enabled?: boolean;
+    params?: {
+        ids?: BaseKey[];
+        id?: BaseKey;
+        meta?: MetaQuery;
+        /**
+         * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+         */
+        metaData?: MetaQuery;
+        pagination?: Pagination;
+        /**
+         * @deprecated `hasPagination` is deprecated, use `pagination.mode` instead.
+         */
+        hasPagination?: boolean;
+        /**
+         * @deprecated `sort` is deprecated, use `sorters` instead.
+         */
+        sort?: CrudSorting;
+        sorters?: CrudSorting;
+        filters?: CrudFilters;
+        subscriptionType?: "useList" | "useOne" | "useMany";
+        resource?: string;
+        [key: string]: any;
+    };
+};
+
+export const useSubscription = ({
+    params,
+    channel,
+    types = ["*"],
+    enabled = true,
+    onLiveEvent,
+}: UseSubscriptionProps): void => {
+    const liveDataContext = useContext<ILiveContext>(LiveContext);
+
+    useEffect(() => {
+        let subscription: any;
+
+        if (enabled) {
+            subscription = liveDataContext?.subscribe({
+                channel,
+                params,
+                types,
+                callback: onLiveEvent,
+            });
+        }
+
+        return () => {
+            if (subscription) {
+                liveDataContext?.unsubscribe(subscription);
+            }
+        };
+    }, [enabled]);
+};

package/src/hooks/memoized/index.tsx

@@ -0,0 +1,16 @@
+import { useRef } from "react";
+import isEqual from "lodash/isEqual";
+
+/**
+ * Hook that memoizes the given value with deep equality.
+ * @internal
+ */
+export const useMemoized = <T = unknown,>(value: T): T => {
+    const ref = useRef(value);
+
+    if (!isEqual(ref.current, value)) {
+        ref.current = value;
+    }
+
+    return ref.current;
+};

package/src/hooks/menu/index.ts

@@ -0,0 +1 @@
+export { useMenu } from "./useMenu";