@evolu/react/dist/useQuery.js

Evolu for React

import { use } from "react";
import { useEvolu } from "./useEvolu.js";
import { useQuerySubscription } from "./useQuerySubscription.js";
import { useIsSsr } from "./useIsSsr.js";
/**
 * Load and subscribe to the Query, and return an object with `rows` and `row`
 * properties that are automatically updated when data changes.
 *
 * Note that {@link useQuery} uses React Suspense. It means every usage of
 * {@link useQuery} blocks rendering until loading is completed. To avoid loading
 * waterfall with more queries, use {@link useQueries}.
 *
 * The `promise` option allows preloading queries before rendering, which can be
 * useful for complex queries that might take noticeable time even with local
 * data. However, this is rarely needed as local queries are typically fast.
 *
 * ### Example
 *
 * ```ts
 * // Get all rows.
 * const rows = useQuery(allTodos);
 *
 * // Get rows for a specific todo (the first row can be null).
 * const rows = useQuery(todoById(1));
 *
 * // Get all rows, but without subscribing to changes.
 * const rows = useQuery(allTodos, { once: true });
 *
 * // Preload a query (rarely needed).
 * const allTodosPromise = evolu.loadQuery(allTodos);
 * const rows = useQuery(allTodos, { promise: allTodosPromise });
 * ```
 */
export const useQuery = (query, options = {}) => {
    const evolu = useEvolu();
    const isSSR = useIsSsr();
    if (isSSR) {
        if (!options.promise)
            void evolu.loadQuery(query);
    }
    else {
        use(options.promise ?? evolu.loadQuery(query));
    }
    return useQuerySubscription(query, options);
};