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

package/src/client/types/helpers.mts

@@ -0,0 +1,140 @@
+import type {
+  BaseEndpointOptions,
+  EndpointHandler,
+  EndpointOptions,
+  ErrorSchemaRecord,
+  HttpMethod,
+  InferErrorSchemaOutput,
+  StreamHandler,
+} from '@navios/builder'
+import type { z, ZodType } from 'zod/v4'
+
+/**
+ * Compute the base result 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).
+ */
+export type ComputeBaseResult<
+  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>
+
+/**
+ * Helper type to compute the response data type based on errorSchema presence and UseDiscriminator.
+ *
+ * When `UseDiscriminator` is `true` and `errorSchema` exists, returns `ResponseType | ErrorTypes`.
+ * When `UseDiscriminator` is `false`, returns only `ResponseType` (errors are thrown).
+ *
+ * @deprecated Use ComputeBaseResult instead (same logic, different parameter order)
+ */
+export type ResponseDataType<
+  Response extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+  UseDiscriminator extends boolean = false,
+> = ComputeBaseResult<UseDiscriminator, Response, ErrorSchema>
+
+/**
+ * Helper type that attaches the endpoint to query/mutation results.
+ * Supports both new const generic pattern and legacy pattern with individual parameters.
+ *
+ * New pattern (2 args):
+ * @template Options - EndpointOptions from builder (new const generic pattern)
+ * @template UseDiscriminator - When true, errors are returned as union types
+ *
+ * Legacy pattern (4-5 args):
+ * @template Method - HTTP method
+ * @template Url - URL template
+ * @template RequestSchema - Request body schema
+ * @template ResponseSchema - Response schema
+ * @template QuerySchema - Query params schema (optional)
+ */
+export type EndpointHelper<
+  OptionsOrMethod extends EndpointOptions | HttpMethod = EndpointOptions,
+  UseDiscriminatorOrUrl extends boolean | string = false,
+  RequestSchema = undefined,
+  ResponseSchema extends ZodType = ZodType,
+  QuerySchema = undefined,
+> = OptionsOrMethod extends EndpointOptions
+  ? UseDiscriminatorOrUrl extends boolean
+    ? {
+        endpoint: EndpointHandler<OptionsOrMethod, UseDiscriminatorOrUrl>
+      }
+    : never
+  : OptionsOrMethod extends HttpMethod
+    ? UseDiscriminatorOrUrl extends string
+      ? {
+          endpoint: EndpointHandler<
+            EndpointOptions & {
+              method: OptionsOrMethod
+              url: UseDiscriminatorOrUrl
+              requestSchema: RequestSchema
+              responseSchema: ResponseSchema
+              querySchema: QuerySchema
+            },
+            false
+          >
+        }
+      : never
+    : never
+
+// Legacy export for backwards compatibility
+/** @deprecated Use EndpointHelper instead */
+export type ClientEndpointHelper<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  RequestSchema = unknown,
+  ResponseSchema extends z.ZodType = z.ZodType,
+  QuerySchema = unknown,
+> = EndpointHelper<Method, Url, RequestSchema, ResponseSchema, QuerySchema>
+
+/**
+ * Helper type that attaches a stream endpoint to mutation results.
+ * Supports both new const generic pattern and legacy pattern with individual parameters.
+ *
+ * New pattern (2 args):
+ * @template Options - BaseEndpointOptions from builder (new const generic pattern)
+ * @template UseDiscriminator - When true, errors are returned as union types
+ *
+ * Legacy pattern (4-6 args):
+ * @template Method - HTTP method
+ * @template Url - URL template
+ * @template QuerySchema - Query params schema
+ * @template RequestSchema - Request body schema
+ * @template ErrorSchema - Error schema (optional)
+ * @template UrlParamsSchema - URL params schema (optional)
+ */
+export type StreamHelper<
+  OptionsOrMethod extends BaseEndpointOptions | HttpMethod = BaseEndpointOptions,
+  UseDiscriminatorOrUrl extends boolean | string = false,
+  QuerySchema = undefined,
+  RequestSchema = undefined,
+  ErrorSchema = undefined,
+  UrlParamsSchema = undefined,
+> = OptionsOrMethod extends BaseEndpointOptions
+  ? UseDiscriminatorOrUrl extends boolean
+    ? {
+        endpoint: StreamHandler<OptionsOrMethod, UseDiscriminatorOrUrl>
+      }
+    : never
+  : OptionsOrMethod extends HttpMethod
+    ? UseDiscriminatorOrUrl extends string
+      ? {
+          endpoint: StreamHandler<
+            BaseEndpointOptions & {
+              method: OptionsOrMethod
+              url: UseDiscriminatorOrUrl
+              querySchema: QuerySchema
+              requestSchema: RequestSchema
+              errorSchema: ErrorSchema
+              urlParamsSchema: UrlParamsSchema
+            },
+            false
+          >
+        }
+      : never
+    : never

package/src/client/types/index.mts

@@ -0,0 +1,26 @@
+export * from './helpers.mjs'
+export * from './query.mjs'
+export * from './infinite-query.mjs'
+export * from './mutation.mjs'
+export * from './multipart-mutation.mjs'
+export * from './from-endpoint.mjs'
+
+import type { ClientFromEndpointMethods } from './from-endpoint.mjs'
+import type { ClientInfiniteQueryMethods } from './infinite-query.mjs'
+import type { ClientMultipartMutationMethods } from './multipart-mutation.mjs'
+import type { ClientMutationMethods } from './mutation.mjs'
+import type { ClientQueryMethods } from './query.mjs'
+
+/**
+ * The main client instance interface.
+ * Provides methods for creating queries, infinite queries, and mutations.
+ *
+ * @template UseDiscriminator - When `true`, errors are returned as union types.
+ *   When `false` (default), errors are thrown and not included in TData.
+ */
+export interface ClientInstance<UseDiscriminator extends boolean = false>
+  extends ClientQueryMethods<UseDiscriminator>,
+    ClientInfiniteQueryMethods<UseDiscriminator>,
+    ClientMutationMethods<UseDiscriminator>,
+    ClientMultipartMutationMethods<UseDiscriminator>,
+    ClientFromEndpointMethods<UseDiscriminator> {}

package/src/client/types/infinite-query.mts

@@ -0,0 +1,133 @@
+import type {
+  EndpointOptions,
+  ErrorSchemaRecord,
+  HttpMethod,
+  InferEndpointParams,
+  Simplify,
+} from '@navios/builder'
+import type {
+  DataTag,
+  InfiniteData,
+  UseSuspenseInfiniteQueryOptions,
+} from '@tanstack/react-query'
+import type { z, ZodObject, ZodType } from 'zod/v4'
+
+import type { Split } from '../../common/types.mjs'
+import type { QueryHelpers } from '../../query/types.mjs'
+import type { ComputeBaseResult, EndpointHelper } from './helpers.mjs'
+
+/**
+ * Extended endpoint options interface for infinite query that includes processResponse and pagination.
+ */
+interface InfiniteQueryEndpointConfig<
+  _UseDiscriminator extends boolean,
+  Method extends HttpMethod,
+  Url extends string,
+  QuerySchema extends ZodObject,
+  RequestSchema extends ZodType | undefined,
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+  UrlParamsSchema extends ZodObject | undefined,
+  TBaseResult,
+  PageResult,
+> extends EndpointOptions {
+  method: Method
+  url: Url
+  querySchema: QuerySchema
+  requestSchema?: RequestSchema
+  responseSchema: ResponseSchema
+  errorSchema?: ErrorSchema
+  urlParamsSchema?: UrlParamsSchema
+  processResponse?: (data: TBaseResult) => PageResult
+  getNextPageParam: (
+    lastPage: PageResult,
+    allPages: PageResult[],
+    lastPageParam: z.infer<QuerySchema> | undefined,
+    allPageParams: z.infer<QuerySchema>[] | undefined,
+  ) => z.input<QuerySchema> | undefined
+  getPreviousPageParam?: (
+    firstPage: PageResult,
+    allPages: PageResult[],
+    lastPageParam: z.infer<QuerySchema> | undefined,
+    allPageParams: z.infer<QuerySchema>[] | undefined,
+  ) => z.input<QuerySchema>
+}
+
+/**
+ * Infinite query method using decomposed generics pattern for proper processResponse typing.
+ *
+ * @template UseDiscriminator - When `true`, errors are returned as union types.
+ *   When `false` (default), errors are thrown and not included in TData.
+ */
+export interface ClientInfiniteQueryMethods<
+  UseDiscriminator extends boolean = false,
+> {
+  /**
+   * Creates a type-safe infinite query with automatic type inference.
+   *
+   * Uses decomposed generic pattern to infer types from the configuration object.
+   * All schema combinations are handled by a single method.
+   *
+   * @example
+   * ```ts
+   * const getUsers = client.infiniteQuery({
+   *   method: 'GET',
+   *   url: '/users',
+   *   querySchema: z.object({ page: z.number() }),
+   *   responseSchema: z.array(userSchema),
+   *   getNextPageParam: (lastPage, allPages, lastPageParam) => {
+   *     return lastPage.length > 0 ? { page: (lastPageParam?.page ?? 0) + 1 } : undefined
+   *   },
+   * })
+   *
+   * const { data } = getUsers.useSuspense({ params: { page: 0 } })
+   * ```
+   */
+  infiniteQuery<
+    const Method extends HttpMethod = HttpMethod,
+    const Url extends string = string,
+    const QuerySchema extends ZodObject = ZodObject,
+    const RequestSchema extends ZodType | undefined = undefined,
+    const ResponseSchema extends ZodType = ZodType,
+    const ErrorSchema extends ErrorSchemaRecord | undefined = undefined,
+    const UrlParamsSchema extends ZodObject | undefined = undefined,
+    const TBaseResult = ComputeBaseResult<
+      UseDiscriminator,
+      ResponseSchema,
+      ErrorSchema
+    >,
+    const PageResult = TBaseResult,
+    const Options extends EndpointOptions = {
+      method: Method
+      url: Url
+      querySchema: QuerySchema
+      requestSchema: RequestSchema
+      responseSchema: ResponseSchema
+      errorSchema: ErrorSchema
+      urlParamsSchema: UrlParamsSchema
+    },
+  >(
+    config: InfiniteQueryEndpointConfig<
+      UseDiscriminator,
+      Method,
+      Url,
+      QuerySchema,
+      RequestSchema,
+      ResponseSchema,
+      ErrorSchema,
+      UrlParamsSchema,
+      TBaseResult,
+      PageResult
+    >,
+  ): ((
+    params: Simplify<InferEndpointParams<Options>>,
+  ) => UseSuspenseInfiniteQueryOptions<
+    PageResult,
+    Error,
+    InfiniteData<PageResult>,
+    DataTag<Split<Url, '/'>, PageResult, Error>,
+    z.output<QuerySchema>
+  >) &
+    QueryHelpers<Url, QuerySchema, PageResult, true, RequestSchema> &
+    EndpointHelper<Options, UseDiscriminator>
+}

package/src/client/types/multipart-mutation.mts

@@ -0,0 +1,264 @@
+import type {
+  ErrorSchemaRecord,
+  Simplify,
+  UrlHasParams,
+  UrlParams,
+} from '@navios/builder'
+import type {
+  MutationFunctionContext,
+  UseMutationResult,
+} from '@tanstack/react-query'
+import type { ZodObject, ZodType } from 'zod/v4'
+
+import type { MutationArgs, MutationHelpers } from '../../mutation/types.mjs'
+import type { ComputeBaseResult, EndpointHelper } from './helpers.mjs'
+
+/**
+ * Multipart mutation method overloads for ClientInstance.
+ *
+ * @template UseDiscriminator - When `true`, errors are returned as union types.
+ *   When `false` (default), errors are thrown and not included in TData.
+ */
+export interface ClientMultipartMutationMethods<
+  UseDiscriminator extends boolean = false,
+> {
+  // ============================================================================
+  // MULTIPART MUTATION METHODS
+  // ============================================================================
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    QuerySchema extends ZodObject = ZodObject,
+    Response extends ZodType = ZodType,
+    ErrorSchema extends ErrorSchemaRecord | undefined = undefined,
+    TBaseResult = ComputeBaseResult<UseDiscriminator, Response, ErrorSchema>,
+    Result = unknown,
+    OnMutateResult = unknown,
+    Context = unknown,
+    UseKey extends true = true,
+  >(config: {
+    method: Method
+    url: Url
+    useKey: UseKey
+    requestSchema: RequestSchema
+    querySchema: QuerySchema
+    responseSchema: Response
+    errorSchema?: ErrorSchema
+    processResponse: (data: TBaseResult) => Result | Promise<Result>
+    useContext?: () => Context
+    onMutate?: (
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context & MutationFunctionContext,
+    ) => OnMutateResult | Promise<OnMutateResult>
+    onSuccess?: (
+      data: NoInfer<Result>,
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onError?: (
+      error: Error,
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onSettled?: (
+      data: NoInfer<Result> | undefined,
+      error: Error | null,
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+  }): ((
+    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, QuerySchema>,
+    OnMutateResult
+  >) &
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    QuerySchema extends ZodObject = ZodObject,
+    Response extends ZodType = ZodType,
+    ErrorSchema extends ErrorSchemaRecord | undefined = undefined,
+    TBaseResult = ComputeBaseResult<UseDiscriminator, Response, ErrorSchema>,
+    Result = unknown,
+    OnMutateResult = unknown,
+    Context = unknown,
+  >(config: {
+    method: Method
+    url: Url
+    requestSchema: RequestSchema
+    querySchema: QuerySchema
+    responseSchema: Response
+    errorSchema?: ErrorSchema
+    processResponse: (data: TBaseResult) => Result | Promise<Result>
+    useContext?: () => Context
+    onMutate?: (
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context & MutationFunctionContext,
+    ) => OnMutateResult | Promise<OnMutateResult>
+    onSuccess?: (
+      data: NoInfer<Result>,
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onError?: (
+      error: Error,
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onSettled?: (
+      data: NoInfer<Result> | undefined,
+      error: Error | null,
+      variables: Simplify<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+  }): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, QuerySchema>,
+    OnMutateResult
+  >) &
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    Response extends ZodType = ZodType,
+    ErrorSchema extends ErrorSchemaRecord | undefined = undefined,
+    TBaseResult = ComputeBaseResult<UseDiscriminator, Response, ErrorSchema>,
+    Result = unknown,
+    OnMutateResult = unknown,
+    Context = unknown,
+  >(config: {
+    method: Method
+    url: Url
+    requestSchema: RequestSchema
+    responseSchema: Response
+    errorSchema?: ErrorSchema
+    processResponse: (data: TBaseResult) => Result | Promise<Result>
+    useContext?: () => Context
+    onMutate?: (
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context & MutationFunctionContext,
+    ) => OnMutateResult | Promise<OnMutateResult>
+    onSuccess?: (
+      data: NoInfer<Result>,
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onError?: (
+      error: Error,
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onSettled?: (
+      data: NoInfer<Result> | undefined,
+      error: Error | null,
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+  }): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, undefined>,
+    OnMutateResult
+  >) &
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response>
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    Response extends ZodType = ZodType,
+    ErrorSchema extends ErrorSchemaRecord | undefined = undefined,
+    TBaseResult = ComputeBaseResult<UseDiscriminator, Response, ErrorSchema>,
+    Result = unknown,
+    OnMutateResult = unknown,
+    Context = unknown,
+    UseKey extends true = true,
+  >(config: {
+    method: Method
+    url: Url
+    useKey: UseKey
+    requestSchema: RequestSchema
+    responseSchema: Response
+    errorSchema?: ErrorSchema
+    processResponse: (data: TBaseResult) => Result | Promise<Result>
+    useContext?: () => Context
+    onMutate?: (
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context & MutationFunctionContext,
+    ) => OnMutateResult | Promise<OnMutateResult>
+    onSuccess?: (
+      data: NoInfer<Result>,
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onError?: (
+      error: Error,
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+    onSettled?: (
+      data: NoInfer<Result> | undefined,
+      error: Error | null,
+      variables: Simplify<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context &
+        MutationFunctionContext & {
+          onMutateResult: OnMutateResult | undefined
+        },
+    ) => void | Promise<void>
+  }): ((
+    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, undefined>,
+    OnMutateResult
+  >) &
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response>
+}