Added explicit types for useQueries() options. Added jsdoc examples.

Author: Chriztiaan

packages/tanstack-react-query/src/hooks/useQueries.ts

@@ -31,48 +31,86 @@ export type EnhancedExplicitQueryResults<T extends readonly unknown[]> = {
   [K in keyof T]: Tanstack.UseQueryResult<T[K][]> & { queryKey: Tanstack.QueryKey };
 };
 
+export type UseQueriesExplicitWithCombineOptions<T extends readonly unknown[], TCombined> = {
+  queries: readonly [...{ [K in keyof T]: PowerSyncQueryOption<T[K]> }];
+  combine: (results: EnhancedExplicitQueryResults<T>) => TCombined;
+};
+
+export type UseQueriesExplicitWithoutCombineOptions<T extends readonly unknown[]> = {
+  queries: readonly [...{ [K in keyof T]: PowerSyncQueryOption<T[K]> }];
+  combine?: undefined;
+};
+
+export type UseQueriesAutoInferenceWithCombineOptions<TQueries extends readonly PowerSyncQueryOption[], TCombined> = {
+  queries: readonly [...TQueries];
+  combine: (results: EnhancedInferQueryResults<TQueries>) => TCombined;
+};
+
+export type UseQueriesAutoInferenceWithoutCombineOptions<TQueries extends readonly PowerSyncQueryOption[]> = {
+  queries: readonly [...TQueries];
+  combine?: undefined;
+};
+
+export type UseQueriesBaseOptions = {
+  queries: readonly (Tanstack.UseQueryOptions & PowerSyncQueryOptions<unknown>)[];
+  combine?: (results: (Tanstack.UseQueryResult<unknown, unknown> & { queryKey: Tanstack.QueryKey })[]) => unknown;
+};
+
 // Explicit generic typing with combine
 export function useQueries<T extends readonly unknown[], TCombined>(
-  options: {
-    queries: readonly [...{ [K in keyof T]: PowerSyncQueryOption<T[K]> }];
-    combine: (results: EnhancedExplicitQueryResults<T>) => TCombined;
-  },
+  options: UseQueriesExplicitWithCombineOptions<T, TCombined>,
   queryClient?: Tanstack.QueryClient
 ): TCombined;
 
 // Explicit generic typing without combine
 export function useQueries<T extends readonly unknown[]>(
-  options: {
-    queries: readonly [...{ [K in keyof T]: PowerSyncQueryOption<T[K]> }];
-    combine?: undefined;
-  },
+  options: UseQueriesExplicitWithoutCombineOptions<T>,
   queryClient?: Tanstack.QueryClient
 ): ExplicitQueryResults<T>;
 
 // Auto inference with combine
 export function useQueries<TQueries extends readonly PowerSyncQueryOption[], TCombined>(
-  options: {
-    queries: readonly [...TQueries];
-    combine: (results: EnhancedInferQueryResults<TQueries>) => TCombined;
-  },
+  options: UseQueriesAutoInferenceWithCombineOptions<TQueries, TCombined>,
   queryClient?: Tanstack.QueryClient
 ): TCombined;
 
 // Auto inference without combine
 export function useQueries<TQueries extends readonly PowerSyncQueryOption[]>(
-  options: {
-    queries: readonly [...TQueries];
-    combine?: undefined;
-  },
+  options: UseQueriesAutoInferenceWithoutCombineOptions<TQueries>,
   queryClient?: Tanstack.QueryClient
 ): InferQueryResults<TQueries>;
 
-// Implementation
+/**
+ * @example
+ * ```
+ * const { data, error, isLoading } = useQueries({
+ *     queries: [
+ *       { queryKey: ['lists'], query: 'SELECT * from lists' },
+ *       { queryKey: ['todos'], query: 'SELECT * from todos' }
+ *     ],
+ * })
+ * ```
+ *
+ * @example
+ * ```
+ * const ids = [1, 2, 3];
+ * const combinedQueries = useQueries({
+ *   queries: ids.map((id) => ({
+ *     queryKey: ['post', id],
+ *     query: 'SELECT * from lists where id = ?',
+ *     parameters: [id],
+ *   })),
+ *   combine: (results) => {
+ *     return {
+ *       data: results.map((result) => result.data),
+ *       pending: results.some((result) => result.isPending),
+ *     }
+ *   },
+ * });
+ * ```
+ */
 export function useQueries(
-  options: {
-    queries: readonly (Tanstack.UseQueryOptions & PowerSyncQueryOptions<unknown>)[];
-    combine?: (results: (Tanstack.UseQueryResult<unknown, unknown> & { queryKey: Tanstack.QueryKey })[]) => unknown;
-  },
+  options: UseQueriesBaseOptions,
   queryClient: Tanstack.QueryClient = Tanstack.useQueryClient()
 ) {
   const powerSync = usePowerSync();

packages/tanstack-react-query/src/hooks/useQuery.ts

@@ -10,12 +10,44 @@ export type PowerSyncQueryOptions<T> = {
 
 export type UseBaseQueryOptions<TQueryOptions> = TQueryOptions & PowerSyncQueryOptions<any>;
 
+/**
+ *
+ * Uses the `queryFn` to execute the query. No different from the base `useQuery` hook.
+ *
+ * @example
+ * ```
+ * const { data, error, isLoading } = useQuery({
+ *   queryKey: ['lists'],
+ *   queryFn: getTodos,
+ * });
+ * ```
+ */
 export function useQuery<TData = unknown, TError = Tanstack.DefaultError>(
   options: UseBaseQueryOptions<Tanstack.UseQueryOptions<TData, TError>> & { query?: undefined },
   queryClient?: Tanstack.QueryClient
 ): Tanstack.UseQueryResult<TData, TError>;
 
-// Overload when 'query' is present
+/**
+ *
+ * Uses the `query` to execute the PowerSync query.
+ *
+ * @example
+ * ```
+ * const { data, error, isLoading } = useQuery({
+ *   queryKey: ['lists'],
+ *   query: 'SELECT * from lists where id = ?',
+ *   parameters: ['id-1']
+ * });
+ * ```
+ *
+ * @example
+ * ```
+ * const { data, error, isLoading } = useQuery({
+ *   queryKey: ['lists'],
+ *   query: compilableQuery,
+ * });
+ * ```
+ */
 export function useQuery<TData = unknown, TError = Tanstack.DefaultError>(
   options: UseBaseQueryOptions<Tanstack.UseQueryOptions<TData[], TError>> & { query: string | CompilableQuery<TData> },
   queryClient?: Tanstack.QueryClient
@@ -28,12 +60,36 @@ export function useQuery<TData = unknown, TError = Tanstack.DefaultError>(
   return useQueryCore(options, queryClient, Tanstack.useQuery);
 }
 
+/**
+ *
+ * Uses the `queryFn` to execute the query. No different from the base `useSuspenseQuery` hook.
+ *
+ * @example
+ * ```
+ * const { data } = useSuspenseQuery({
+ *   queryKey: ['lists'],
+ *   queryFn: getTodos,
+ * });
+ * ```
+ */
 export function useSuspenseQuery<TData = unknown, TError = Tanstack.DefaultError>(
   options: UseBaseQueryOptions<Tanstack.UseSuspenseQueryOptions<TData, TError>> & { query?: undefined },
   queryClient?: Tanstack.QueryClient
 ): Tanstack.UseSuspenseQueryResult<TData, TError>;
 
-// Overload when 'query' is present
+/***
+ *
+ * Uses the `query` to execute the PowerSync query.
+ *
+ * @example
+ * ```
+ * const { data } = useSuspenseQuery({
+ *   queryKey: ['lists'],
+ *   query: 'SELECT * from lists where id = ?',
+ *   parameters: ['id-1']
+ * });
+ * ```
+ */
 export function useSuspenseQuery<TData = unknown, TError = Tanstack.DefaultError>(
   options: UseBaseQueryOptions<Tanstack.UseSuspenseQueryOptions<TData[], TError>> & {
     query: string | CompilableQuery<TData>;