Add docs to useQuery and useQueries

apps/web/components/NextJsExample.tsx

@@ -88,18 +88,6 @@ const isRestoringOwner = (isRestoringOwner?: boolean): boolean => {
 // Ensure fixtures are not added to the restored owner.
 if (!isRestoringOwner()) createFixtures();
 
-const logSyncState = (): void => {
-  evolu.subscribeSyncState(() => {
-    // eslint-disable-next-line no-console
-    console.log(evolu.getSyncState());
-  });
-};
-
-// Ensure logSyncState is called only once with hot reloading.
-// Without GlobalValue, people could be confused about why logSyncState
-// logs 2x, 3x, etc.
-GlobalValue.globalValue("NextJsExample/logSyncState", logSyncState);
-
 export const NextJsExample = memo(function NextJsExample() {
   const [currentTab, setCurrentTab] = useState<"todos" | "categories">("todos");
 
@@ -430,3 +418,15 @@ const prompt = <From extends string, To>(
   }
   onSuccess(a.right);
 };
+
+const logSyncState = (): void => {
+  evolu.subscribeSyncState(() => {
+    // eslint-disable-next-line no-console
+    console.log(evolu.getSyncState());
+  });
+};
+
+// Ensure logSyncState is called only once with hot reloading.
+// Without GlobalValue, people could be confused about why logSyncState
+// logs 2x, 3x, etc.
+GlobalValue.globalValue("NextJsExample/logSyncState", logSyncState);

packages/evolu-common-react/src/index.tsx

@@ -59,41 +59,55 @@ export interface EvoluReact<S extends Schema = Schema> extends Evolu<S> {
   ) => QueryResult<R>;
 
   /**
-   * `useQuery` React Hook performs a database query and returns an object with
-   * `rows` and `row` properties that are automatically updated when data
-   * changes.
+   * Load and subscribe to the Query, and return an object with `rows` and `row`
+   * properties that are automatically updated when data changes.
    *
-   * ### Example
+   * 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}.
+   *
+   * ### Examples
    *
    * ```ts
-   * const a = 1;
+   * // Get all rows.
+   * const { rows } = useQuery(allTodos);
+   *
+   * // Get the first row (it can be null).
+   * const { row } = useQuery(todoById(1));
+   *
+   * // Get all rows, but without subscribing to changes.
+   * const { rows } = useQuery(allTodos, { once: true });
+   *
+   * // Prefetch all rows
+   * const allTodos = evolu.createQuery((db) =>
+   *   db.selectFrom("todo").selectAll(),
+   * );
+   * // Load before usage.
+   * const allTodosPromise = evolu.loadQuery(allTodos);
+   * // A usage.
+   * const { rows } = useQuery(allTodos, { promise: allTodosPromise });
    * ```
    */
   readonly useQuery: <R extends Row>(
     query: Query<R>,
     options?: Partial<{
-      /** TODO: B */
+      /** Without subscribing to changes. */
       readonly once: boolean;
 
       /** Reuse existing promise instead of loading so query will not suspense. */
       readonly promise: Promise<QueryResult<R>>;
     }>,
   ) => QueryResult<R>;
 
-  /**
-   * TODO: Docs For more than one query, always use useQueries Hook to avoid
-   * loading waterfalls and to cache loading promises. This is possible of
-   * course: const foo = use(useEvolu().loadQuery(todos)) but it will not cache
-   * loading promise nor subscribe updates. That's why we have useQuery and
-   * useQueries.
-   */
+  /** The same as {@link useQuery}, but for many queries. */
   readonly useQueries: <
     R extends Row,
     Q extends Queries<R>,
     OQ extends Queries<R>,
   >(
     queries: [...Q],
     options?: Partial<{
+      /** Queries that should be only loaded, not subscribed to. */
       readonly once: [...OQ];
       /** Reuse existing promises instead of loading so query will not suspense. */
       readonly promises: [