@navios/react-query 1.0.0-alpha.1 → 1.0.1

package/src/__tests__/prefetch.spec.mts

@@ -0,0 +1,310 @@
+import { QueryClient } from '@tanstack/react-query'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  createPrefetchHelper,
+  createPrefetchHelpers,
+  prefetchAll,
+} from '../query/prefetch.mjs'
+
+describe('createPrefetchHelper', () => {
+  let queryClient: QueryClient
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    })
+  })
+
+  it('should create a prefetch helper with all methods', () => {
+    const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+      queryKey: ['users', params.userId] as const,
+      queryFn: async () => ({ id: params.userId, name: 'Test User' }),
+    }))
+
+    const helper = createPrefetchHelper(mockQueryOptions)
+
+    expect(helper).toHaveProperty('prefetch')
+    expect(helper).toHaveProperty('ensureData')
+    expect(helper).toHaveProperty('getQueryOptions')
+    expect(helper).toHaveProperty('prefetchMany')
+    expect(typeof helper.prefetch).toBe('function')
+    expect(typeof helper.ensureData).toBe('function')
+    expect(typeof helper.getQueryOptions).toBe('function')
+    expect(typeof helper.prefetchMany).toBe('function')
+  })
+
+  describe('prefetch', () => {
+    it('should call queryClient.prefetchQuery with correct options', async () => {
+      const mockQueryFn = vi.fn().mockResolvedValue({ id: '123', name: 'Test' })
+      const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: mockQueryFn,
+      }))
+
+      const helper = createPrefetchHelper(mockQueryOptions)
+      await helper.prefetch(queryClient, { userId: '123' })
+
+      expect(mockQueryOptions).toHaveBeenCalledWith({ userId: '123' })
+      expect(mockQueryFn).toHaveBeenCalled()
+    })
+
+    it('should prefetch data and store in cache', async () => {
+      const userData = { id: '456', name: 'Cached User' }
+      const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: async () => userData,
+      }))
+
+      const helper = createPrefetchHelper(mockQueryOptions)
+      await helper.prefetch(queryClient, { userId: '456' })
+
+      const cachedData = queryClient.getQueryData(['users', '456'])
+      expect(cachedData).toEqual(userData)
+    })
+  })
+
+  describe('ensureData', () => {
+    it('should return data after ensuring it exists in cache', async () => {
+      const userData = { id: '789', name: 'Ensured User' }
+      const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: async () => userData,
+      }))
+
+      const helper = createPrefetchHelper(mockQueryOptions)
+      const result = await helper.ensureData(queryClient, { userId: '789' })
+
+      expect(result).toEqual(userData)
+    })
+
+    it('should not refetch if data is already cached', async () => {
+      const mockQueryFn = vi.fn().mockResolvedValue({ id: '111', name: 'User' })
+      const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: mockQueryFn,
+      }))
+
+      // Pre-populate cache
+      queryClient.setQueryData(['users', '111'], {
+        id: '111',
+        name: 'Cached User',
+      })
+
+      const helper = createPrefetchHelper(mockQueryOptions)
+      const result = await helper.ensureData(queryClient, { userId: '111' })
+
+      expect(result).toEqual({ id: '111', name: 'Cached User' })
+      expect(mockQueryFn).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('getQueryOptions', () => {
+    it('should return query options for given params', () => {
+      const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: async () => ({ id: params.userId }),
+      }))
+
+      const helper = createPrefetchHelper(mockQueryOptions)
+      const options = helper.getQueryOptions({ userId: 'abc' })
+
+      expect(mockQueryOptions).toHaveBeenCalledWith({ userId: 'abc' })
+      expect(options).toHaveProperty('queryKey', ['users', 'abc'])
+      expect(options).toHaveProperty('queryFn')
+    })
+  })
+
+  describe('prefetchMany', () => {
+    it('should prefetch multiple queries in parallel', async () => {
+      const mockQueryFn = vi.fn().mockImplementation(async (userId: string) => ({
+        id: userId,
+        name: `User ${userId}`,
+      }))
+
+      const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: () => mockQueryFn(params.userId),
+      }))
+
+      const helper = createPrefetchHelper(mockQueryOptions)
+      await helper.prefetchMany(queryClient, [
+        { userId: '1' },
+        { userId: '2' },
+        { userId: '3' },
+      ])
+
+      expect(queryClient.getQueryData(['users', '1'])).toEqual({
+        id: '1',
+        name: 'User 1',
+      })
+      expect(queryClient.getQueryData(['users', '2'])).toEqual({
+        id: '2',
+        name: 'User 2',
+      })
+      expect(queryClient.getQueryData(['users', '3'])).toEqual({
+        id: '3',
+        name: 'User 3',
+      })
+    })
+
+    it('should handle empty params list', async () => {
+      const mockQueryOptions = vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: async () => ({ id: params.userId }),
+      }))
+
+      const helper = createPrefetchHelper(mockQueryOptions)
+      await helper.prefetchMany(queryClient, [])
+
+      expect(mockQueryOptions).not.toHaveBeenCalled()
+    })
+  })
+})
+
+describe('createPrefetchHelpers', () => {
+  let queryClient: QueryClient
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    })
+  })
+
+  it('should create helpers for multiple queries', () => {
+    const queries = {
+      user: vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: async () => ({ id: params.userId }),
+      })),
+      posts: vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId, 'posts'] as const,
+        queryFn: async () => [{ id: '1', title: 'Post 1' }],
+      })),
+    }
+
+    const helpers = createPrefetchHelpers(queries)
+
+    expect(helpers).toHaveProperty('user')
+    expect(helpers).toHaveProperty('posts')
+    expect(helpers.user).toHaveProperty('prefetch')
+    expect(helpers.posts).toHaveProperty('prefetch')
+  })
+
+  it('should work with individual helpers independently', async () => {
+    const queries = {
+      user: vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: async () => ({ id: params.userId, name: 'User' }),
+      })),
+      posts: vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId, 'posts'] as const,
+        queryFn: async () => [{ id: '1', title: 'Post' }],
+      })),
+    }
+
+    const helpers = createPrefetchHelpers(queries)
+
+    await helpers.user.prefetch(queryClient, { userId: '123' })
+    await helpers.posts.prefetch(queryClient, { userId: '123' })
+
+    expect(queryClient.getQueryData(['users', '123'])).toEqual({
+      id: '123',
+      name: 'User',
+    })
+    expect(queryClient.getQueryData(['users', '123', 'posts'])).toEqual([
+      { id: '1', title: 'Post' },
+    ])
+  })
+})
+
+describe('prefetchAll', () => {
+  let queryClient: QueryClient
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    })
+  })
+
+  it('should prefetch all queries in parallel', async () => {
+    const userHelper = createPrefetchHelper(
+      vi.fn((params: { userId: string }) => ({
+        queryKey: ['users', params.userId] as const,
+        queryFn: async () => ({ id: params.userId, name: 'User' }),
+      })),
+    )
+
+    const postsHelper = createPrefetchHelper(
+      vi.fn((params: { userId: string; limit: number }) => ({
+        queryKey: ['users', params.userId, 'posts', params.limit] as const,
+        queryFn: async () => [{ id: '1', title: 'Post' }],
+      })),
+    )
+
+    await prefetchAll(queryClient, [
+      { helper: userHelper, params: { userId: '123' } },
+      { helper: postsHelper, params: { userId: '123', limit: 10 } },
+    ])
+
+    expect(queryClient.getQueryData(['users', '123'])).toEqual({
+      id: '123',
+      name: 'User',
+    })
+    expect(queryClient.getQueryData(['users', '123', 'posts', 10])).toEqual([
+      { id: '1', title: 'Post' },
+    ])
+  })
+
+  it('should handle empty prefetches array', async () => {
+    await expect(prefetchAll(queryClient, [])).resolves.toBeUndefined()
+  })
+
+  it('should handle errors in individual prefetches', async () => {
+    const errorHelper = createPrefetchHelper<
+      Record<string, never>,
+      { error: boolean }
+    >(
+      vi.fn(() => ({
+        queryKey: ['error'] as const,
+        queryFn: async (): Promise<{ error: boolean }> => {
+          throw new Error('Fetch failed')
+        },
+      })),
+    )
+
+    const successHelper = createPrefetchHelper<
+      Record<string, never>,
+      { success: boolean }
+    >(
+      vi.fn(() => ({
+        queryKey: ['success'] as const,
+        queryFn: async () => ({ success: true }),
+      })),
+    )
+
+    // prefetchAll should not throw even if individual queries fail
+    // because prefetchQuery doesn't throw
+    await expect(
+      prefetchAll(queryClient, [
+        { helper: errorHelper, params: {} },
+        { helper: successHelper, params: {} },
+      ]),
+    ).resolves.toBeUndefined()
+
+    // Success query should still be cached
+    expect(queryClient.getQueryData(['success'])).toEqual({ success: true })
+  })
+})

package/src/client/__type-tests__/from-endpoint.spec-d.mts

@@ -1,4 +1,8 @@
-import type { EndpointHandler, ErrorSchemaRecord } from '@navios/builder'
+import type {
+  EndpointHandler,
+  ErrorSchemaRecord,
+  StreamHandler,
+} from '@navios/builder'
 import type { DataTag, UseSuspenseQueryOptions } from '@tanstack/react-query'
 import type { z } from 'zod/v4'
 
@@ -126,9 +130,23 @@ declare const endpointWithErrors: EndpointHandler<
   false
 >
 
-// NOTE: Stream endpoints are not tested here due to type compatibility issues
-// with mutationFromEndpoint. StreamHandler<Config> doesn't match the expected
-// EndpointOptions | BaseEndpointOptions constraint correctly.
+// Stream endpoints for testing
+declare const streamEndpoint: StreamHandler<
+  {
+    method: 'GET'
+    url: '/files/$fileId/download'
+  },
+  false
+>
+
+declare const streamEndpointWithRequest: StreamHandler<
+  {
+    method: 'POST'
+    url: '/files/generate'
+    requestSchema: typeof requestSchema
+  },
+  false
+>
 
 // Discriminator mode endpoints
 declare const endpointWithErrorsDiscriminator: EndpointHandler<
@@ -360,9 +378,39 @@ describe('ClientInstance<false> mutationFromEndpoint() method', () => {
     })
   })
 
-  // NOTE: Stream endpoints with mutationFromEndpoint are commented out due to type issues.
-  // The mutationFromEndpoint signature expects EndpointOptions | BaseEndpointOptions,
-  // but StreamHandler doesn't match correctly, resulting in `never` return type.
+  describe('stream endpoints', () => {
+    test('stream endpoint returns Blob', () => {
+      const mutation = client.mutationFromEndpoint(streamEndpoint)
+      const { mutate, data } = mutation()
+
+      // Should require urlParams for stream endpoint
+      mutate({ urlParams: { fileId: '123' } })
+
+      // Data should be Blob, not never
+      assertType<Blob | undefined>(data)
+    })
+
+    test('stream endpoint with request schema', () => {
+      const mutation = client.mutationFromEndpoint(streamEndpointWithRequest)
+      const { mutate, data } = mutation()
+
+      // Should require data for stream endpoint with requestSchema
+      mutate({ data: { name: 'test', email: 'test@test.com' } })
+
+      // Data should be Blob
+      assertType<Blob | undefined>(data)
+    })
+
+    test('stream endpoint with processResponse', () => {
+      client.mutationFromEndpoint(streamEndpoint, {
+        processResponse: (data) => {
+          // data should be Blob
+          assertType<Blob>(data)
+          return { url: URL.createObjectURL(data) }
+        },
+      })
+    })
+  })
 
   describe('callback options', () => {
     test('onMutate receives variables and context', () => {

package/src/client/__type-tests__/infinite-query.spec-d.mts

@@ -70,7 +70,7 @@ describe('ClientInstance<false> infiniteQuery() method', () => {
         url: '/users',
         querySchema,
         responseSchema,
-        getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
+        getNextPageParam: (_lastPage, _allPages, _lastPageParam, _allPageParams) =>
           undefined,
       })
 

package/src/client/types/from-endpoint.mts

@@ -1,5 +1,4 @@
 import type {
-  BaseEndpointConfig,
   BaseEndpointOptions,
   EndpointOptions,
   InferEndpointParams,
@@ -319,27 +318,6 @@ export interface ClientFromEndpointMethods<
       ? MutationHelpers<Config['url'], Result>
       : {}) &
     (Config extends EndpointOptions
-      ? EndpointHelper<
-          {
-            method: Config['method']
-            url: Config['url']
-            responseSchema: Config['responseSchema']
-            querySchema: Config['querySchema']
-            requestSchema: Config['requestSchema']
-            errorSchema: Config['errorSchema']
-            urlParamsSchema: Config['urlParamsSchema']
-          },
-          UseDiscriminator
-        >
-      : StreamHelper<
-          {
-            method: Config['method']
-            url: Config['url']
-            querySchema: Config['querySchema']
-            requestSchema: Config['requestSchema']
-            errorSchema: Config['errorSchema']
-            urlParamsSchema: Config['urlParamsSchema']
-          },
-          UseDiscriminator
-        >)
+      ? EndpointHelper<Config, UseDiscriminator>
+      : StreamHelper<Config, UseDiscriminator>)
 }

package/src/common/types.mts

@@ -24,6 +24,25 @@ export type ProcessResponseFunction<TData = unknown, TVariables = unknown> = (
   variables: TVariables,
 ) => Promise<TData> | TData
 
+/**
+ * Compute the response input type based on discriminator and error schema.
+ * When UseDiscriminator=true and errorSchema is present, errors are included as a union.
+ * When UseDiscriminator=false, only the success type is returned (errors are thrown).
+ *
+ * @template UseDiscriminator - Whether to include error types in the response union
+ * @template ResponseSchema - The success response schema
+ * @template ErrorSchema - The error schema record (optional)
+ */
+export type ComputeResponseInput<
+  UseDiscriminator extends boolean,
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+> = UseDiscriminator extends true
+  ? ErrorSchema extends ErrorSchemaRecord
+    ? z.output<ResponseSchema> | InferErrorSchemaOutput<ErrorSchema>
+    : z.output<ResponseSchema>
+  : z.output<ResponseSchema>
+
 /**
  * Options for creating a client instance.
  *

package/src/mutation/optimistic.mts

@@ -8,7 +8,7 @@ import type { QueryClient } from '@tanstack/react-query'
  * @template TQueryData - The query cache data type
  */
 export interface OptimisticUpdateConfig<
-  TData,
+  _TData,
   TVariables,
   TQueryData,
 > {
@@ -86,6 +86,9 @@ export interface OptimisticUpdateCallbacks<TData, TVariables, TQueryData> {
  * 2. onError: Rollback cache to previous value on failure
  * 3. onSettled: Invalidate query to refetch fresh data
  *
+ * @experimental This API is experimental and may change in future versions.
+ * Use with caution in production code.
+ *
  * @param config - Configuration for the optimistic update
  * @returns Object containing onMutate, onError, and onSettled callbacks
  *
@@ -206,6 +209,9 @@ export function createOptimisticUpdate<
  *
  * Useful when a mutation affects multiple cached queries.
  *
+ * @experimental This API is experimental and may change in future versions.
+ * Use with caution in production code.
+ *
  * @param configs - Array of optimistic update configurations
  * @returns Combined callbacks that handle all specified queries
  *

package/src/mutation/types.mts

@@ -13,26 +13,10 @@ import type {
 } from '@tanstack/react-query'
 import type { z, ZodObject, ZodType } from 'zod/v4'
 
-import type { ProcessResponseFunction } from '../common/types.mjs'
-
-/**
- * Compute the response input type based on discriminator and error schema.
- * When UseDiscriminator=true and errorSchema is present, errors are included as a union.
- * When UseDiscriminator=false, only the success type is returned (errors are thrown).
- *
- * @template UseDiscriminator - Whether to include error types in the response union
- * @template ResponseSchema - The success response schema
- * @template ErrorSchema - The error schema record (optional)
- */
-type ComputeResponseInput<
-  UseDiscriminator extends boolean,
-  ResponseSchema extends ZodType,
-  ErrorSchema extends ErrorSchemaRecord | undefined,
-> = UseDiscriminator extends true
-  ? ErrorSchema extends ErrorSchemaRecord
-    ? z.output<ResponseSchema> | InferErrorSchemaOutput<ErrorSchema>
-    : z.output<ResponseSchema>
-  : z.output<ResponseSchema>
+import type {
+  ComputeResponseInput,
+  ProcessResponseFunction,
+} from '../common/types.mjs'
 
 /**
  * Arguments for mutation functions based on URL params, request schema, and query schema.

package/src/query/types.mts

@@ -2,10 +2,8 @@ import type {
   AnyEndpointConfig,
   BaseEndpointConfig,
   EndpointOptions,
-  ErrorSchemaRecord,
   HttpMethod,
   InferEndpointReturn,
-  InferErrorSchemaOutput,
   RequestArgs,
   Simplify,
   UrlHasParams,
@@ -20,26 +18,7 @@ import type {
 } from '@tanstack/react-query'
 import type { z, ZodObject, ZodType } from 'zod/v4'
 
-import type { Split } from '../common/types.mjs'
-
-/**
- * Compute the response input type based on discriminator and error schema.
- * When UseDiscriminator=true and errorSchema is present, errors are included as a union.
- * When UseDiscriminator=false, only the success type is returned (errors are thrown).
- *
- * @template UseDiscriminator - Whether to include error types in the response union
- * @template ResponseSchema - The success response schema
- * @template ErrorSchema - The error schema record (optional)
- */
-type ComputeResponseInput<
-  UseDiscriminator extends boolean,
-  ResponseSchema extends ZodType,
-  ErrorSchema extends ErrorSchemaRecord | undefined,
-> = UseDiscriminator extends true
-  ? ErrorSchema extends ErrorSchemaRecord
-    ? z.output<ResponseSchema> | InferErrorSchemaOutput<ErrorSchema>
-    : z.output<ResponseSchema>
-  : z.output<ResponseSchema>
+import type { ComputeResponseInput, Split } from '../common/types.mjs'
 
 /**
  * Helper type to extract the result type from processResponse.