@strato-admin/core 0.1.1 → 0.3.0

package/dist/ra-core/src/dataProvider/useGetMany.d.ts

@@ -0,0 +1,49 @@
+import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { RaRecord, GetManyParams } from '../types';
+/**
+ * Call the dataProvider.getMany() method and return the resolved result
+ * as well as the loading state.
+ *
+ * The return value updates according to the request state:
+ *
+ * - start: { isPending: true, refetch }
+ * - success: { data: [data from store], isPending: false, refetch }
+ * - error: { error: [error from response], isPending: false, refetch }
+ *
+ * This hook will return the cached result when called a second time
+ * with the same parameters, until the response arrives.
+ *
+ * @param {string} resource The resource name, e.g. 'posts'
+ * @param {Params} params The getMany parameters { ids, meta }
+ * @param {Object} options Options object to pass to the queryClient.
+ * May include side effects to be executed upon success or failure, e.g. { onSuccess: () => { refresh(); } }
+ *
+ * @typedef Params
+ * @prop params.ids The ids to get, e.g. [123, 456, 789]
+ * @prop params.meta Optional meta parameters
+ *
+ * @returns The current request state. Destructure as { data, error, isPending, refetch }.
+ *
+ * @example
+ *
+ * import { useGetMany } from 'react-admin';
+ *
+ * const PostTags = ({ post }) => {
+ *     const { data, isPending, error } = useGetMany(
+ *         'tags',
+ *         { ids: post.tags },
+ *     );
+ *     if (isPending) { return <Loading />; }
+ *     if (error) { return <p>ERROR</p>; }
+ *     return <ul>{data.map(tag =>
+ *         <li key={tag.id}>{tag.name}</li>
+ *     )}</ul>;
+ * };
+ */
+export declare const useGetMany: <RecordType extends RaRecord = any, ErrorType = Error>(resource: string, params: Partial<GetManyParams<RecordType>>, options?: UseGetManyOptions<RecordType, ErrorType>) => UseGetManyHookValue<RecordType, ErrorType>;
+export type UseGetManyOptions<RecordType extends RaRecord = any, ErrorType = Error> = Omit<UseQueryOptions<RecordType[], ErrorType>, 'queryKey' | 'queryFn'> & {
+    onSuccess?: (data: RecordType[]) => void;
+    onError?: (error: ErrorType) => void;
+    onSettled?: (data?: RecordType[], error?: ErrorType | null) => void;
+};
+export type UseGetManyHookValue<RecordType extends RaRecord = any, ErrorType = Error> = UseQueryResult<RecordType[], ErrorType>;

package/dist/ra-core/src/dataProvider/useGetMany.js

@@ -0,0 +1,143 @@
+import { useEffect, useRef } from 'react';
+import { useQuery, useQueryClient, } from '@tanstack/react-query';
+import { useDataProvider } from './useDataProvider';
+import { useEvent } from '../util';
+/**
+ * Call the dataProvider.getMany() method and return the resolved result
+ * as well as the loading state.
+ *
+ * The return value updates according to the request state:
+ *
+ * - start: { isPending: true, refetch }
+ * - success: { data: [data from store], isPending: false, refetch }
+ * - error: { error: [error from response], isPending: false, refetch }
+ *
+ * This hook will return the cached result when called a second time
+ * with the same parameters, until the response arrives.
+ *
+ * @param {string} resource The resource name, e.g. 'posts'
+ * @param {Params} params The getMany parameters { ids, meta }
+ * @param {Object} options Options object to pass to the queryClient.
+ * May include side effects to be executed upon success or failure, e.g. { onSuccess: () => { refresh(); } }
+ *
+ * @typedef Params
+ * @prop params.ids The ids to get, e.g. [123, 456, 789]
+ * @prop params.meta Optional meta parameters
+ *
+ * @returns The current request state. Destructure as { data, error, isPending, refetch }.
+ *
+ * @example
+ *
+ * import { useGetMany } from 'react-admin';
+ *
+ * const PostTags = ({ post }) => {
+ *     const { data, isPending, error } = useGetMany(
+ *         'tags',
+ *         { ids: post.tags },
+ *     );
+ *     if (isPending) { return <Loading />; }
+ *     if (error) { return <p>ERROR</p>; }
+ *     return <ul>{data.map(tag =>
+ *         <li key={tag.id}>{tag.name}</li>
+ *     )}</ul>;
+ * };
+ */
+export const useGetMany = (resource, params, options = {}) => {
+    const { ids, meta } = params;
+    const dataProvider = useDataProvider();
+    const queryClient = useQueryClient();
+    const { onError = noop, onSuccess = noop, onSettled = noop, enabled, ...queryOptions } = options;
+    const onSuccessEvent = useEvent(onSuccess);
+    const onErrorEvent = useEvent(onError);
+    const onSettledEvent = useEvent(onSettled);
+    const result = useQuery({
+        queryKey: [
+            resource,
+            'getMany',
+            {
+                ids: !ids || ids.length === 0 ? [] : ids.map(id => String(id)),
+                meta,
+            },
+        ],
+        queryFn: queryParams => {
+            if (!ids || ids.length === 0) {
+                // no need to call the dataProvider
+                return Promise.resolve([]);
+            }
+            return dataProvider
+                .getMany(resource, {
+                ids,
+                meta,
+                signal: dataProvider.supportAbortSignal === true
+                    ? queryParams.signal
+                    : undefined,
+            })
+                .then(({ data }) => data);
+        },
+        placeholderData: () => {
+            const records = !ids || ids.length === 0
+                ? []
+                : ids.map(id => queryClient.getQueryData([
+                    resource,
+                    'getOne',
+                    { id: String(id), meta },
+                ]));
+            if (records.some(record => record === undefined)) {
+                return undefined;
+            }
+            else {
+                return records;
+            }
+        },
+        retry: false,
+        enabled: enabled ?? ids != null,
+        ...queryOptions,
+    });
+    const metaValue = useRef(meta);
+    const resourceValue = useRef(resource);
+    useEffect(() => {
+        metaValue.current = meta;
+    }, [meta]);
+    useEffect(() => {
+        resourceValue.current = resource;
+    }, [resource]);
+    useEffect(() => {
+        if (result.data === undefined ||
+            result.error != null ||
+            result.isFetching)
+            return;
+        // optimistically populate the getOne cache
+        result.data.forEach(record => {
+            queryClient.setQueryData([
+                resourceValue.current,
+                'getOne',
+                { id: String(record.id), meta: metaValue.current },
+            ], oldRecord => oldRecord ?? record);
+        });
+        onSuccessEvent(result.data);
+    }, [
+        queryClient,
+        onSuccessEvent,
+        result.data,
+        result.error,
+        result.isFetching,
+    ]);
+    useEffect(() => {
+        if (result.error == null || result.isFetching)
+            return;
+        onErrorEvent(result.error);
+    }, [onErrorEvent, result.error, result.isFetching]);
+    useEffect(() => {
+        if (result.status === 'pending' || result.isFetching)
+            return;
+        onSettledEvent(result.data, result.error);
+    }, [
+        onSettledEvent,
+        result.data,
+        result.error,
+        result.status,
+        result.isFetching,
+    ]);
+    return result;
+};
+const noop = () => undefined;

package/dist/ra-core/src/dataProvider/useGetManyAggregate.d.ts

@@ -0,0 +1,62 @@
+import { UseQueryOptions } from '@tanstack/react-query';
+import { UseGetManyHookValue } from './useGetMany';
+import { RaRecord, GetManyParams } from '../types';
+/**
+ * Call the dataProvider.getMany() method and return the resolved result
+ * as well as the loading state.
+ *
+ * The return value updates according to the request state:
+ *
+ * - start: { isPending: true, isFetching: true, refetch }
+ * - success: { data: [data from response], isPending: false, isFetching: false, refetch }
+ * - error: { error: [error from response], isPending: false, isFetching: false, refetch }
+ *
+ * This hook will return the cached result when called a second time
+ * with the same parameters, until the response arrives.
+ *
+ * This hook aggregates and deduplicates calls to the same resource, so for instance, if an app calls:
+ *
+ * useGetManyAggregate('tags', [1, 2, 3]);
+ * useGetManyAggregate('tags', [3, 4]);
+ *
+ * during the same tick, the hook will only call the dataProvider once with the following parameters:
+ *
+ * dataProvider.getMany('tags', [1, 2, 3, 4])
+ *
+ * @param resource The resource name, e.g. 'posts'
+ * @param {Params} params The getMany parameters { ids, meta }
+ * @param {Object} options Options object to pass to the dataProvider.
+ * @param {boolean} options.enabled Flag to conditionally run the query. If it's false, the query will not run
+ * @param {Function} options.onSuccess Side effect function to be executed upon success, e.g. { onSuccess: { refresh: true } }
+ * @param {Function} options.onError Side effect function to be executed upon failure, e.g. { onError: error => notify(error.message) }
+ *
+ * @typedef Params
+ * @prop params.ids The ids to get, e.g. [123, 456, 789]
+ * @prop params.meta Optional meta parameters
+
+ * @returns The current request state. Destructure as { data, error, isPending, isFetching, refetch }.
+ *
+ * @example
+ *
+ * import { useGetManyAggregate, useRecordContext } from 'react-admin';
+ *
+ * const PostTags = () => {
+ *     const record = useRecordContext();
+ *     const { data, isPending, error } = useGetManyAggregate('tags', { ids: record.tagIds });
+ *     if (isPending) { return <Loading />; }
+ *     if (error) { return <p>ERROR</p>; }
+ *     return (
+ *          <ul>
+ *              {data.map(tag => (
+ *                  <li key={tag.id}>{tag.name}</li>
+ *              ))}
+ *          </ul>
+ *      );
+ * };
+ */
+export declare const useGetManyAggregate: <RecordType extends RaRecord = any, ErrorType = Error>(resource: string, params: Partial<GetManyParams<RecordType>>, options?: UseGetManyAggregateOptions<RecordType, ErrorType>) => UseGetManyHookValue<RecordType, ErrorType>;
+export type UseGetManyAggregateOptions<RecordType extends RaRecord = any, ErrorType = Error> = Omit<UseQueryOptions<RecordType[], ErrorType>, 'queryKey' | 'queryFn'> & {
+    onSuccess?: (data: RecordType[]) => void;
+    onError?: (error: ErrorType) => void;
+    onSettled?: (data?: RecordType[], error?: ErrorType | null) => void;
+};

package/dist/ra-core/src/dataProvider/useGetManyAggregate.js

@@ -0,0 +1,295 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { useQueryClient, useQuery, } from '@tanstack/react-query';
+import union from 'lodash/union.js';
+import { useDataProvider } from './useDataProvider';
+import { useEvent } from '../util';
+/**
+ * Call the dataProvider.getMany() method and return the resolved result
+ * as well as the loading state.
+ *
+ * The return value updates according to the request state:
+ *
+ * - start: { isPending: true, isFetching: true, refetch }
+ * - success: { data: [data from response], isPending: false, isFetching: false, refetch }
+ * - error: { error: [error from response], isPending: false, isFetching: false, refetch }
+ *
+ * This hook will return the cached result when called a second time
+ * with the same parameters, until the response arrives.
+ *
+ * This hook aggregates and deduplicates calls to the same resource, so for instance, if an app calls:
+ *
+ * useGetManyAggregate('tags', [1, 2, 3]);
+ * useGetManyAggregate('tags', [3, 4]);
+ *
+ * during the same tick, the hook will only call the dataProvider once with the following parameters:
+ *
+ * dataProvider.getMany('tags', [1, 2, 3, 4])
+ *
+ * @param resource The resource name, e.g. 'posts'
+ * @param {Params} params The getMany parameters { ids, meta }
+ * @param {Object} options Options object to pass to the dataProvider.
+ * @param {boolean} options.enabled Flag to conditionally run the query. If it's false, the query will not run
+ * @param {Function} options.onSuccess Side effect function to be executed upon success, e.g. { onSuccess: { refresh: true } }
+ * @param {Function} options.onError Side effect function to be executed upon failure, e.g. { onError: error => notify(error.message) }
+ *
+ * @typedef Params
+ * @prop params.ids The ids to get, e.g. [123, 456, 789]
+ * @prop params.meta Optional meta parameters
+
+ * @returns The current request state. Destructure as { data, error, isPending, isFetching, refetch }.
+ *
+ * @example
+ *
+ * import { useGetManyAggregate, useRecordContext } from 'react-admin';
+ *
+ * const PostTags = () => {
+ *     const record = useRecordContext();
+ *     const { data, isPending, error } = useGetManyAggregate('tags', { ids: record.tagIds });
+ *     if (isPending) { return <Loading />; }
+ *     if (error) { return <p>ERROR</p>; }
+ *     return (
+ *          <ul>
+ *              {data.map(tag => (
+ *                  <li key={tag.id}>{tag.name}</li>
+ *              ))}
+ *          </ul>
+ *      );
+ * };
+ */
+export const useGetManyAggregate = (resource, params, options = {}) => {
+    const dataProvider = useDataProvider();
+    const queryClient = useQueryClient();
+    const { onError = noop, onSuccess = noop, onSettled = noop, enabled, ...queryOptions } = options;
+    const onSuccessEvent = useEvent(onSuccess);
+    const onErrorEvent = useEvent(onError);
+    const onSettledEvent = useEvent(onSettled);
+    const { ids, meta } = params;
+    const placeholderData = useMemo(() => {
+        const records = (Array.isArray(ids) ? ids : [ids]).map(id => queryClient.getQueryData([
+            resource,
+            'getOne',
+            { id: String(id), meta },
+        ]));
+        if (records.some(record => record === undefined)) {
+            return undefined;
+        }
+        else {
+            return records;
+        }
+    }, [ids, queryClient, resource, meta]);
+    const result = useQuery({
+        queryKey: [
+            resource,
+            'getMany',
+            {
+                ids: (Array.isArray(ids) ? ids : [ids]).map(id => String(id)),
+                meta,
+            },
+        ],
+        queryFn: queryParams => new Promise((resolve, reject) => {
+            if (!ids || ids.length === 0) {
+                // no need to call the dataProvider
+                return resolve([]);
+            }
+            // debounced / batched fetch
+            return callGetManyQueries({
+                resource,
+                ids,
+                meta,
+                resolve,
+                reject,
+                dataProvider,
+                queryClient,
+                signal: dataProvider.supportAbortSignal === true
+                    ? queryParams.signal
+                    : undefined,
+            });
+        }),
+        placeholderData,
+        enabled: enabled ?? ids != null,
+        retry: false,
+        ...queryOptions,
+    });
+    const metaValue = useRef(meta);
+    const resourceValue = useRef(resource);
+    useEffect(() => {
+        metaValue.current = meta;
+    }, [meta]);
+    useEffect(() => {
+        resourceValue.current = resource;
+    }, [resource]);
+    useEffect(() => {
+        if (result.data === undefined ||
+            result.error != null ||
+            result.isFetching)
+            return;
+        // optimistically populate the getOne cache
+        (result.data ?? []).forEach(record => {
+            queryClient.setQueryData([
+                resourceValue.current,
+                'getOne',
+                { id: String(record.id), meta: metaValue.current },
+            ], oldRecord => oldRecord ?? record);
+        });
+        onSuccessEvent(result.data);
+    }, [
+        queryClient,
+        onSuccessEvent,
+        result.data,
+        result.error,
+        result.isFetching,
+    ]);
+    useEffect(() => {
+        if (result.error == null || result.isFetching)
+            return;
+        onErrorEvent(result.error);
+    }, [onErrorEvent, result.error, result.isFetching]);
+    useEffect(() => {
+        if (result.status === 'pending' || result.isFetching)
+            return;
+        onSettledEvent(result.data, result.error);
+    }, [
+        onSettledEvent,
+        result.data,
+        result.error,
+        result.status,
+        result.isFetching,
+    ]);
+    return result;
+};
+/**
+ * Batch all calls to a function into one single call with the arguments of all the calls.
+ *
+ * @example
+ * let sum = 0;
+ * const add = (args) => { sum = args.reduce((arg, total) => total + arg, 0); };
+ * const addBatched = batch(add);
+ * addBatched(2);
+ * addBatched(8);
+ * // add will be called once with arguments [2, 8]
+ * // and sum will be equal to 10
+ */
+const batch = fn => {
+    let capturedArgs = [];
+    let timeout = null;
+    return (arg) => {
+        capturedArgs.push(arg);
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(() => {
+            timeout = null;
+            fn([...capturedArgs]);
+            capturedArgs = [];
+        }, 0);
+    };
+};
+/**
+ * Group and execute all calls to the dataProvider.getMany() method for the current tick
+ *
+ * Thanks to batch(), this function executes at most once per tick,
+ * whatever the number of calls to useGetManyAggregate().
+ */
+const callGetManyQueries = batch((calls) => {
+    const dataProvider = calls[0].dataProvider;
+    const queryClient = calls[0].queryClient;
+    /**
+     * Aggregate calls by resource and meta
+     *
+     * callsByResourceAndMeta will look like:
+     * {
+     *     'posts|{"test":true}': [{ resource, ids, resolve, reject, dataProvider, queryClient }, ...],
+     *     'posts|{"test":false}': [{ resource, ids, resolve, reject, dataProvider, queryClient }, ...],
+     *     tags: [{ resource, ids, resolve, reject, dataProvider, queryClient }, ...],
+     * }
+     */
+    const callsByResourceAndMeta = calls.reduce((acc, callArgs) => {
+        const key = `${callArgs.resource}|${JSON.stringify(callArgs.meta)}`;
+        if (!acc[key]) {
+            acc[key] = [];
+        }
+        acc[key].push(callArgs);
+        return acc;
+    }, {});
+    /**
+     * For each resource/meta association, aggregate ids and call dataProvider.getMany() once
+     */
+    Object.keys(callsByResourceAndMeta).forEach(resource => {
+        const callsForResource = callsByResourceAndMeta[resource];
+        const uniqueResource = callsForResource.reduce((acc, { resource }) => resource || acc, '' // Should never happen as we always have a resource in callArgs but makes TS happy
+        );
+        /**
+         * Extract ids from queries, aggregate and deduplicate them
+         *
+         * @example from [[1, 2], [2, null, 3], [4, null]] to [1, 2, 3, 4]
+         */
+        const aggregatedIds = callsForResource
+            .reduce((acc, { ids }) => union(acc, ids), []) // concat + unique
+            .filter(v => v != null && v !== ''); // remove null values
+        const uniqueMeta = callsForResource.reduce((acc, { meta }) => meta || acc, undefined);
+        if (aggregatedIds.length === 0) {
+            // no need to call the data provider if all the ids are null
+            callsForResource.forEach(({ resolve }) => {
+                resolve([]);
+            });
+            return;
+        }
+        const callThatHasAllAggregatedIds = callsForResource.find(({ ids, signal }) => JSON.stringify(ids) === JSON.stringify(aggregatedIds) &&
+            !signal?.aborted);
+        if (callThatHasAllAggregatedIds) {
+            // There is only one call (no aggregation), or one of the calls has the same ids as the sum of all calls.
+            // Either way, we can't trigger a new fetchQuery with the same signature, as it's already pending.
+            // Therefore, we reply with the dataProvider
+            const { dataProvider, resource, ids, meta, signal } = callThatHasAllAggregatedIds;
+            dataProvider
+                .getMany(resource, { ids, meta, signal })
+                .then(({ data }) => data)
+                .then(data => {
+                // We must then resolve all the pending calls with the data they requested
+                callsForResource.forEach(({ ids, resolve }) => {
+                    resolve(data.filter(record => ids
+                        .map(id => String(id))
+                        .includes(String(record.id))));
+                });
+            }, error => {
+                // All pending calls must also receive the error
+                callsForResource.forEach(({ reject }) => {
+                    reject(error);
+                });
+            });
+            return;
+        }
+        /**
+         * Call dataProvider.getMany() with the aggregatedIds,
+         * and resolve each of the promises using the results
+         */
+        queryClient
+            .fetchQuery({
+            queryKey: [
+                uniqueResource,
+                'getMany',
+                {
+                    ids: aggregatedIds.map(id => String(id)),
+                    meta: uniqueMeta,
+                },
+            ],
+            queryFn: queryParams => dataProvider
+                .getMany(uniqueResource, {
+                ids: aggregatedIds,
+                meta: uniqueMeta,
+                signal: dataProvider.supportAbortSignal === true
+                    ? queryParams.signal
+                    : undefined,
+            })
+                .then(({ data }) => data),
+        })
+            .then(data => {
+            callsForResource.forEach(({ ids, resolve }) => {
+                resolve(data.filter(record => ids
+                    .map(id => String(id))
+                    .includes(String(record.id))));
+            });
+        })
+            .catch(error => callsForResource.forEach(({ reject }) => reject(error)));
+    });
+});
+const noop = () => undefined;

package/dist/ra-core/src/dataProvider/useGetManyReference.d.ts

@@ -0,0 +1,62 @@
+import { UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { RaRecord, GetManyReferenceParams, GetManyReferenceResult } from '../types';
+/**
+ * Call the dataProvider.getManyReference() method and return the resolved result
+ * as well as the loading state.
+ *
+ * The return value updates according to the request state:
+ *
+ * - start: { isPending: true, refetch }
+ * - success: { data: [data from store], total: [total from response], isPending: false, refetch }
+ * - error: { error: [error from response], isPending: false, refetch }
+ *
+ * This hook will return the cached result when called a second time
+ * with the same parameters, until the response arrives.
+ *
+ * @param {string} resource The resource name, e.g. 'posts'
+ * @param {Params} params The getManyReference parameters { target, id, pagination, sort, filter, meta }
+ * @param {Object} options Options object to pass to the queryClient.
+ * May include side effects to be executed upon success or failure, e.g. { onSuccess: () => { refresh(); } }
+ *
+ * @typedef Params
+ * @prop params.target The target resource key, e.g. 'post_id'
+ * @prop params.id The identifier of the record to look for in target, e.g. '123'
+ * @prop params.pagination The request pagination { page, perPage }, e.g. { page: 1, perPage: 10 }
+ * @prop params.sort The request sort { field, order }, e.g. { field: 'id', order: 'DESC' }
+ * @prop params.filter The request filters, e.g. { title: 'hello, world' }
+ * @prop params.meta Optional meta parameters
+ *
+ * @returns The current request state. Destructure as { data, total, error, isPending, refetch }.
+ *
+ * @example
+ *
+ * import { useGetManyReference, useRecordContext } from 'react-admin';
+ *
+ * const PostComments = () => {
+ *     const record = useRecordContext();
+ *     // fetch all comments related to the current record
+ *     const { data, isPending, error } = useGetManyReference(
+ *         'comments',
+ *         { target: 'post_id', id: record.id, pagination: { page: 1, perPage: 10 }, sort: { field: 'published_at', order: 'DESC' } }
+ *     );
+ *     if (isPending) { return <Loading />; }
+ *     if (error) { return <p>ERROR</p>; }
+ *     return <ul>{data.map(comment =>
+ *         <li key={comment.id}>{comment.body}</li>
+ *     )}</ul>;
+ * };
+ */
+export declare const useGetManyReference: <RecordType extends RaRecord = any, ErrorType = Error>(resource: string, params?: Partial<GetManyReferenceParams>, options?: UseGetManyReferenceHookOptions<RecordType, ErrorType>) => UseGetManyReferenceHookValue<RecordType, ErrorType>;
+export type UseGetManyReferenceHookOptions<RecordType extends RaRecord = any, ErrorType = Error> = Omit<UseQueryOptions<GetManyReferenceResult<RecordType>, ErrorType>, 'queryKey' | 'queryFn'> & {
+    onSuccess?: (data: GetManyReferenceResult<RecordType>) => void;
+    onError?: (error: ErrorType) => void;
+    onSettled?: (data?: GetManyReferenceResult<RecordType>, error?: ErrorType | null) => void;
+};
+export type UseGetManyReferenceHookValue<RecordType extends RaRecord = any, ErrorType = Error> = UseQueryResult<RecordType[], ErrorType> & {
+    total?: number;
+    pageInfo?: {
+        hasNextPage?: boolean;
+        hasPreviousPage?: boolean;
+    };
+    meta?: any;
+};