@navios/react-query 0.7.1 → 1.0.0

package/src/query/make-options.mts

@@ -1,34 +1,83 @@
-import type { AbstractEndpoint, AnyEndpointConfig } from '@navios/builder'
+import type {
+  EndpointHandler,
+  EndpointOptions,
+  InferEndpointReturn,
+  Simplify,
+} from '@navios/builder'
 import type {
   DataTag,
   QueryClient,
   UseQueryOptions,
   UseSuspenseQueryOptions,
 } from '@tanstack/react-query'
+import type { ZodObject, ZodType } from 'zod/v4'
 
 import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/react-query'
 
 import type { Split } from '../common/types.mjs'
-import type { QueryArgs, QueryParams } from './types.mjs'
+import type { QueryArgs, QueryHelpers, QueryResult } from './types.mjs'
 
 import { createQueryKey } from './key-creator.mjs'
 
+/**
+ * Options for makeQueryOptions.
+ */
+export interface MakeQueryOptionsParams<
+  Options extends EndpointOptions,
+  UseDiscriminator extends boolean = false,
+  Result = QueryResult<Options, UseDiscriminator>,
+> {
+  keyPrefix?: string[]
+  keySuffix?: string[]
+  onFail?: (err: unknown) => void
+  processResponse: (
+    data: InferEndpointReturn<Options, UseDiscriminator>,
+  ) => Result
+}
+
 /**
  * Creates query options for a given endpoint.
  *
  * Returns a function that generates TanStack Query options when called with params.
  * The returned function also has helper methods attached (use, useSuspense, invalidate, etc.)
  *
- * @param endpoint - The navios endpoint to create query options for
+ * Uses const generics pattern to automatically infer types from the endpoint configuration.
+ *
+ * @param endpoint - The navios endpoint handler (from builder's declareEndpoint)
  * @param options - Query configuration including processResponse
  * @param baseQuery - Optional base query options to merge
  * @returns A function that generates query options with attached helpers
+ *
+ * @example
+ * ```ts
+ * const getUser = api.declareEndpoint({
+ *   method: 'GET',
+ *   url: '/users/$userId',
+ *   responseSchema: userSchema,
+ * })
+ *
+ * const queryOptions = makeQueryOptions(getUser, {
+ *   processResponse: (data) => data,
+ * })
+ *
+ * const { data } = queryOptions.useSuspense({ urlParams: { userId: '123' } })
+ * ```
  */
 export function makeQueryOptions<
-  Config extends AnyEndpointConfig,
-  Options extends QueryParams<Config>,
+  const Options extends EndpointOptions,
+  UseDiscriminator extends boolean = false,
+  Result = QueryResult<Options, UseDiscriminator>,
   BaseQuery extends Omit<
-    UseQueryOptions<ReturnType<Options['processResponse']>, Error, any>,
+    UseQueryOptions<Result, Error, any>,
+    | 'queryKey'
+    | 'queryFn'
+    | 'getNextPageParam'
+    | 'initialPageParam'
+    | 'enabled'
+    | 'throwOnError'
+    | 'placeholderData'
+  > = Omit<
+    UseQueryOptions<Result, Error, any>,
     | 'queryKey'
     | 'queryFn'
     | 'getNextPageParam'
@@ -38,34 +87,58 @@ export function makeQueryOptions<
     | 'placeholderData'
   >,
 >(
-  endpoint: AbstractEndpoint<Config>,
-  options: Options,
-  baseQuery: BaseQuery = {} as BaseQuery,
-) {
+  endpoint: EndpointHandler<Options, UseDiscriminator>,
+  options: MakeQueryOptionsParams<Options, UseDiscriminator, Result>,
+  baseQuery?: BaseQuery,
+): ((
+  params: Simplify<
+    QueryArgs<
+      Options['url'],
+      Options extends { querySchema: infer Q extends ZodObject }
+        ? Q
+        : undefined,
+      Options extends { requestSchema: infer R extends ZodType } ? R : undefined
+    >
+  >,
+) => UseSuspenseQueryOptions<
+  Result,
+  Error,
+  BaseQuery extends { select: (...args: any[]) => infer T } ? T : Result,
+  DataTag<Split<Options['url'], '/'>, Result, Error>
+>) &
+  QueryHelpers<
+    Options['url'],
+    Options extends { querySchema: infer Q extends ZodObject } ? Q : undefined,
+    Result,
+    false,
+    Options extends { requestSchema: infer R extends ZodType } ? R : undefined
+  > {
   const config = endpoint.config
-  const queryKey = createQueryKey(config, options, false)
+  const queryKey = createQueryKey(config as any, options as any, false)
   const processResponse = options.processResponse
 
   const result = (
-    params: QueryArgs<Config['url'], Config['querySchema']>,
-  ): Options['processResponse'] extends (...args: any[]) => infer Result
-    ? UseSuspenseQueryOptions<
-        Result,
-        Error,
-        BaseQuery['select'] extends (...args: any[]) => infer T ? T : Result,
-        DataTag<Split<Config['url'], '/'>, Result, Error>
+    params: Simplify<
+      QueryArgs<
+        Options['url'],
+        Options extends { querySchema: infer Q extends ZodObject }
+          ? Q
+          : undefined,
+        Options extends { requestSchema: infer R extends ZodType }
+          ? R
+          : undefined
       >
-    : never => {
-    // @ts-expect-error TS2322 We know that the processResponse is defined
+    >,
+  ): any => {
     return queryOptions({
-      queryKey: queryKey.dataTag(params),
-      queryFn: async ({ signal }): Promise<ReturnType<Options['processResponse']>> => {
+      queryKey: queryKey.dataTag(params as any),
+      queryFn: async ({ signal }): Promise<Result> => {
         let result
         try {
           result = await endpoint({
             signal,
             ...params,
-          })
+          } as any)
         } catch (err) {
           if (options.onFail) {
             options.onFail(err)
@@ -73,38 +146,106 @@ export function makeQueryOptions<
           throw err
         }
 
-        return processResponse(result) as ReturnType<Options['processResponse']>
+        return processResponse(result)
       },
       ...baseQuery,
     })
   }
-  result.queryKey = queryKey
-  result.use = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
+
+  /** The query key creator for this endpoint */
+  result.queryKey = queryKey as any
+
+  /**
+   * React hook that executes the query.
+   * Uses `useQuery` from TanStack Query internally.
+   *
+   * @param params - URL parameters, query parameters, and request body
+   * @returns Query result with data, isLoading, error, etc.
+   */
+  result.use = (params: any) => {
     return useQuery(result(params))
   }
 
-  result.useSuspense = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
+  /**
+   * React hook that executes the query with Suspense support.
+   * Uses `useSuspenseQuery` from TanStack Query internally.
+   * The component will suspend while loading and throw on error.
+   *
+   * @param params - URL parameters, query parameters, and request body
+   * @returns Query result with data guaranteed to be defined
+   */
+  result.useSuspense = (params: any) => {
     return useSuspenseQuery(result(params))
   }
 
-  result.invalidate = (
-    queryClient: QueryClient,
-    params: QueryArgs<Config['url'], Config['querySchema']>,
-  ) => {
-    return queryClient.invalidateQueries({
-      queryKey: result.queryKey.dataTag(params),
-    })
+  /**
+   * Creates a function that invalidates a specific query in the cache.
+   * Call the returned function to trigger the invalidation.
+   *
+   * @param queryClient - The TanStack Query client instance
+   * @param params - The exact parameters used for this query
+   * @returns A function that when called invalidates the query
+   *
+   * @example
+   * ```ts
+   * const invalidate = getUser.invalidate(queryClient, { urlParams: { userId: '123' } })
+   * await invalidate() // Invalidates this specific query
+   * ```
+   */
+  result.invalidate = (queryClient: QueryClient, params: any) => {
+    return () =>
+      queryClient.invalidateQueries({
+        queryKey: result.queryKey.dataTag(params),
+      })
   }
 
-  result.invalidateAll = (
-    queryClient: QueryClient,
-    params: QueryArgs<Config['url'], Config['querySchema']>,
-  ) => {
-    return queryClient.invalidateQueries({
-      queryKey: result.queryKey.filterKey(params),
-      exact: false,
-    })
+  /**
+   * Creates a function that invalidates all queries matching the URL pattern.
+   * Useful for invalidating all queries for a resource regardless of query params.
+   *
+   * @param queryClient - The TanStack Query client instance
+   * @param params - URL parameters only (query params are ignored for matching)
+   * @returns A function that when called invalidates all matching queries
+   *
+   * @example
+   * ```ts
+   * const invalidateAll = getUserPosts.invalidateAll(queryClient, { urlParams: { userId: '123' } })
+   * await invalidateAll() // Invalidates all getUserPosts queries for user 123
+   * ```
+   */
+  result.invalidateAll = (queryClient: QueryClient, params: any) => {
+    return () =>
+      queryClient.invalidateQueries({
+        queryKey: result.queryKey.filterKey(params),
+        exact: false,
+      })
   }
 
-  return result
+  return result as unknown as ((
+    params: Simplify<
+      QueryArgs<
+        Options['url'],
+        Options extends { querySchema: infer Q extends ZodObject }
+          ? Q
+          : undefined,
+        Options extends { requestSchema: infer R extends ZodType }
+          ? R
+          : undefined
+      >
+    >,
+  ) => UseSuspenseQueryOptions<
+    Result,
+    Error,
+    BaseQuery extends { select: (...args: any[]) => infer T } ? T : Result,
+    DataTag<Split<Options['url'], '/'>, Result, Error>
+  >) &
+    QueryHelpers<
+      Options['url'],
+      Options extends { querySchema: infer Q extends ZodObject }
+        ? Q
+        : undefined,
+      Result,
+      false,
+      Options extends { requestSchema: infer R extends ZodType } ? R : undefined
+    >
 }

package/src/query/prefetch.mts

@@ -0,0 +1,326 @@
+import type {
+  FetchQueryOptions,
+  QueryClient,
+  QueryKey,
+} from '@tanstack/react-query'
+
+/**
+ * Type for a query options creator function that returns TanStack Query options.
+ *
+ * This matches the return type of `client.query()` from the navios react-query client.
+ */
+export type QueryOptionsCreator<TParams, TData, TError = Error> = (
+  params: TParams,
+) => FetchQueryOptions<TData, TError, TData, QueryKey>
+
+/**
+ * Helper utilities for prefetching queries.
+ *
+ * @template TParams - The query parameters type
+ * @template TData - The query data type
+ * @template TError - The error type (defaults to Error)
+ */
+export interface PrefetchHelper<TParams, TData, TError = Error> {
+  /**
+   * Prefetch query data on the server.
+   *
+   * Use this in server components or getServerSideProps to
+   * prefetch data before rendering.
+   *
+   * @param queryClient - The QueryClient instance
+   * @param params - Parameters for the query
+   * @returns Promise that resolves when prefetch is complete
+   *
+   * @example
+   * ```tsx
+   * // In a Next.js Server Component
+   * const queryClient = new QueryClient()
+   * await prefetch.prefetch(queryClient, { urlParams: { userId: '1' } })
+   * return (
+   *   <HydrationBoundary state={dehydrate(queryClient)}>
+   *     <UserProfile userId="1" />
+   *   </HydrationBoundary>
+   * )
+   * ```
+   */
+  prefetch: (queryClient: QueryClient, params: TParams) => Promise<void>
+
+  /**
+   * Ensure query data exists in cache. Fetches only if not cached.
+   *
+   * Returns the cached or fetched data.
+   *
+   * @param queryClient - The QueryClient instance
+   * @param params - Parameters for the query
+   * @returns Promise that resolves to the query data
+   *
+   * @example
+   * ```tsx
+   * // Ensure data exists before rendering
+   * const userData = await prefetch.ensureData(queryClient, {
+   *   urlParams: { userId: '1' },
+   * })
+   * console.log('User:', userData.name)
+   * ```
+   */
+  ensureData: (queryClient: QueryClient, params: TParams) => Promise<TData>
+
+  /**
+   * Get the query options for a given set of parameters.
+   *
+   * Useful for advanced use cases or when you need to
+   * customize the prefetch behavior.
+   *
+   * @param params - Parameters for the query
+   * @returns The query options object
+   *
+   * @example
+   * ```tsx
+   * const options = prefetch.getQueryOptions({ urlParams: { userId: '1' } })
+   * await queryClient.prefetchQuery({
+   *   ...options,
+   *   staleTime: 60000, // Override stale time for prefetch
+   * })
+   * ```
+   */
+  getQueryOptions: (
+    params: TParams,
+  ) => FetchQueryOptions<TData, TError, TData, QueryKey>
+
+  /**
+   * Prefetch multiple queries in parallel.
+   *
+   * @param queryClient - The QueryClient instance
+   * @param paramsList - Array of parameters for multiple queries
+   * @returns Promise that resolves when all prefetches complete
+   *
+   * @example
+   * ```tsx
+   * // Prefetch multiple users in parallel
+   * await prefetch.prefetchMany(queryClient, [
+   *   { urlParams: { userId: '1' } },
+   *   { urlParams: { userId: '2' } },
+   *   { urlParams: { userId: '3' } },
+   * ])
+   * ```
+   */
+  prefetchMany: (
+    queryClient: QueryClient,
+    paramsList: TParams[],
+  ) => Promise<void>
+}
+
+/**
+ * Creates a type-safe prefetch helper for SSR/RSC.
+ *
+ * This utility wraps a query options creator to provide convenient
+ * methods for server-side data fetching and hydration.
+ *
+ * @param queryOptionsCreator - A function that creates query options (from client.query())
+ * @returns A prefetch helper object with prefetch, ensureData, and getQueryOptions methods
+ *
+ * @example
+ * ```tsx
+ * // 1. Create your query
+ * const getUserQuery = client.query({
+ *   method: 'GET',
+ *   url: '/users/$userId',
+ *   responseSchema: userSchema,
+ * })
+ *
+ * // 2. Create prefetch helper
+ * const userPrefetch = createPrefetchHelper(getUserQuery)
+ *
+ * // 3. Use in server component
+ * async function UserPage({ userId }: { userId: string }) {
+ *   const queryClient = new QueryClient()
+ *
+ *   await userPrefetch.prefetch(queryClient, {
+ *     urlParams: { userId },
+ *   })
+ *
+ *   return (
+ *     <HydrationBoundary state={dehydrate(queryClient)}>
+ *       <UserProfile userId={userId} />
+ *     </HydrationBoundary>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js App Router
+ * import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
+ * import { createPrefetchHelper } from '@navios/react-query'
+ *
+ * // Define queries
+ * const getPostsQuery = client.query({
+ *   method: 'GET',
+ *   url: '/posts',
+ *   querySchema: z.object({ page: z.number() }),
+ *   responseSchema: postsSchema,
+ * })
+ *
+ * const postsPrefetch = createPrefetchHelper(getPostsQuery)
+ *
+ * // Server Component
+ * export default async function PostsPage() {
+ *   const queryClient = new QueryClient()
+ *
+ *   await postsPrefetch.prefetch(queryClient, {
+ *     params: { page: 1 },
+ *   })
+ *
+ *   return (
+ *     <HydrationBoundary state={dehydrate(queryClient)}>
+ *       <PostsList />
+ *     </HydrationBoundary>
+ *   )
+ * }
+ * ```
+ */
+export function createPrefetchHelper<TParams, TData, TError = Error>(
+  queryOptionsCreator: QueryOptionsCreator<TParams, TData, TError>,
+): PrefetchHelper<TParams, TData, TError> {
+  return {
+    prefetch: async (queryClient: QueryClient, params: TParams) => {
+      const options = queryOptionsCreator(params)
+      await queryClient.prefetchQuery(options)
+    },
+
+    ensureData: async (queryClient: QueryClient, params: TParams) => {
+      const options = queryOptionsCreator(params)
+      return queryClient.ensureQueryData(options)
+    },
+
+    getQueryOptions: (params: TParams) => {
+      return queryOptionsCreator(params)
+    },
+
+    prefetchMany: async (queryClient: QueryClient, paramsList: TParams[]) => {
+      await Promise.all(
+        paramsList.map((params) => {
+          const options = queryOptionsCreator(params)
+          return queryClient.prefetchQuery(options)
+        }),
+      )
+    },
+  }
+}
+
+/**
+ * Creates multiple prefetch helpers from a record of query options creators.
+ *
+ * Useful when you have multiple queries that need to be prefetched together.
+ *
+ * @param queries - Record of query options creator functions
+ * @returns Record of prefetch helpers with the same keys
+ *
+ * @example
+ * ```tsx
+ * // Define all your queries
+ * const queries = {
+ *   user: client.query({
+ *     method: 'GET',
+ *     url: '/users/$userId',
+ *     responseSchema: userSchema,
+ *   }),
+ *   posts: client.query({
+ *     method: 'GET',
+ *     url: '/users/$userId/posts',
+ *     responseSchema: postsSchema,
+ *   }),
+ * }
+ *
+ * // Create all prefetch helpers at once
+ * const prefetchers = createPrefetchHelpers(queries)
+ *
+ * // Use in server component
+ * async function UserPage({ userId }: { userId: string }) {
+ *   const queryClient = new QueryClient()
+ *
+ *   await Promise.all([
+ *     prefetchers.user.prefetch(queryClient, { urlParams: { userId } }),
+ *     prefetchers.posts.prefetch(queryClient, { urlParams: { userId } }),
+ *   ])
+ *
+ *   return (
+ *     <HydrationBoundary state={dehydrate(queryClient)}>
+ *       <UserProfileWithPosts userId={userId} />
+ *     </HydrationBoundary>
+ *   )
+ * }
+ * ```
+ */
+export function createPrefetchHelpers<
+  T extends Record<string, QueryOptionsCreator<any, any, any>>,
+>(
+  queries: T,
+): {
+  [K in keyof T]: T[K] extends QueryOptionsCreator<
+    infer TParams,
+    infer TData,
+    infer TError
+  >
+    ? PrefetchHelper<TParams, TData, TError>
+    : never
+} {
+  const result = {} as {
+    [K in keyof T]: T[K] extends QueryOptionsCreator<
+      infer TParams,
+      infer TData,
+      infer TError
+    >
+      ? PrefetchHelper<TParams, TData, TError>
+      : never
+  }
+
+  for (const key of Object.keys(queries) as Array<keyof T>) {
+    // @ts-expect-error - TypeScript can't infer this properly
+    result[key] = createPrefetchHelper(queries[key])
+  }
+
+  return result
+}
+
+/**
+ * Prefetch multiple queries from different query creators in parallel.
+ *
+ * @param queryClient - The QueryClient instance
+ * @param prefetches - Array of { helper, params } objects
+ * @returns Promise that resolves when all prefetches complete
+ *
+ * @example
+ * ```tsx
+ * const userPrefetch = createPrefetchHelper(getUserQuery)
+ * const postsPrefetch = createPrefetchHelper(getPostsQuery)
+ *
+ * async function DashboardPage({ userId }: { userId: string }) {
+ *   const queryClient = new QueryClient()
+ *
+ *   await prefetchAll(queryClient, [
+ *     { helper: userPrefetch, params: { urlParams: { userId } } },
+ *     { helper: postsPrefetch, params: { urlParams: { userId }, params: { limit: 10 } } },
+ *   ])
+ *
+ *   return (
+ *     <HydrationBoundary state={dehydrate(queryClient)}>
+ *       <Dashboard userId={userId} />
+ *     </HydrationBoundary>
+ *   )
+ * }
+ * ```
+ */
+export async function prefetchAll(
+  queryClient: QueryClient,
+  prefetches: Array<{
+    helper: PrefetchHelper<any, any, any>
+    params: unknown
+  }>,
+): Promise<void> {
+  await Promise.all(
+    prefetches.map(({ helper, params }) =>
+      helper.prefetch(queryClient, params),
+    ),
+  )
+}