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

package/src/client/types/mutation.mts

@@ -0,0 +1,176 @@
+import type {
+  EndpointOptions,
+  ErrorSchemaRecord,
+  HttpMethod,
+  RequestArgs,
+  Simplify,
+  UrlHasParams,
+  UrlParams,
+} from '@navios/builder'
+import type {
+  MutationFunctionContext,
+  UseMutationResult,
+} from '@tanstack/react-query'
+import type { ZodObject, ZodType } from 'zod/v4'
+
+import type { MutationHelpers } from '../../mutation/types.mjs'
+import type { ComputeBaseResult, EndpointHelper } from './helpers.mjs'
+
+/**
+ * Compute variables type from URL, schemas
+ */
+type ComputeVariables<
+  Url extends string,
+  QuerySchema extends ZodObject | undefined,
+  RequestSchema extends ZodType | undefined,
+  UrlParamsSchema extends ZodObject | undefined,
+> = Simplify<RequestArgs<Url, QuerySchema, RequestSchema, UrlParamsSchema>>
+
+/**
+ * Extended endpoint options interface for mutation that includes processResponse and callbacks.
+ */
+interface MutationEndpointConfig<
+  _UseDiscriminator extends boolean,
+  Method extends HttpMethod,
+  Url extends string,
+  QuerySchema extends ZodObject | undefined,
+  RequestSchema extends ZodType | undefined,
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+  UrlParamsSchema extends ZodObject | undefined,
+  UseKey extends boolean,
+  TBaseResult,
+  Result,
+  OnMutateResult,
+  Context,
+  Variables,
+> extends EndpointOptions {
+  method: Method
+  url: Url
+  querySchema?: QuerySchema
+  requestSchema?: RequestSchema
+  responseSchema: ResponseSchema
+  errorSchema?: ErrorSchema
+  urlParamsSchema?: UrlParamsSchema
+  processResponse?: (data: TBaseResult) => Result | Promise<Result>
+  useContext?: () => Context
+  useKey?: UseKey
+  onMutate?: (
+    variables: Variables,
+    context: Context & MutationFunctionContext,
+  ) => OnMutateResult | Promise<OnMutateResult>
+  onSuccess?: (
+    data: NoInfer<Result>,
+    variables: Variables,
+    context: Context &
+      MutationFunctionContext & {
+        onMutateResult: OnMutateResult | undefined
+      },
+  ) => void | Promise<void>
+  onError?: (
+    error: Error,
+    variables: Variables,
+    context: Context &
+      MutationFunctionContext & {
+        onMutateResult: OnMutateResult | undefined
+      },
+  ) => void | Promise<void>
+  onSettled?: (
+    data: NoInfer<Result> | undefined,
+    error: Error | null,
+    variables: Variables,
+    context: Context &
+      MutationFunctionContext & {
+        onMutateResult: OnMutateResult | undefined
+      },
+  ) => void | Promise<void>
+}
+
+/**
+ * Mutation 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 ClientMutationMethods<
+  UseDiscriminator extends boolean = false,
+> {
+  /**
+   * Creates a type-safe mutation 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 createUser = client.mutation({
+   *   method: 'POST',
+   *   url: '/users',
+   *   requestSchema: createUserSchema,
+   *   responseSchema: userSchema,
+   *   processResponse: (data) => data,
+   * })
+   *
+   * const { mutate } = createUser()
+   * mutate({ data: { name: 'John' } })
+   * ```
+   */
+  mutation<
+    const Method extends HttpMethod = HttpMethod,
+    const Url extends string = string,
+    const QuerySchema extends ZodObject | undefined = undefined,
+    const RequestSchema extends ZodType | undefined = undefined,
+    const ResponseSchema extends ZodType = ZodType,
+    const ErrorSchema extends ErrorSchemaRecord | undefined = undefined,
+    const UrlParamsSchema extends ZodObject | undefined = undefined,
+    const UseKey extends boolean = false,
+    const TBaseResult = ComputeBaseResult<
+      UseDiscriminator,
+      ResponseSchema,
+      ErrorSchema
+    >,
+    const Result = TBaseResult,
+    const OnMutateResult = unknown,
+    const Context = unknown,
+    const Variables = ComputeVariables<
+      Url,
+      QuerySchema,
+      RequestSchema,
+      UrlParamsSchema
+    >,
+    const Options extends EndpointOptions = {
+      method: Method
+      url: Url
+      querySchema: QuerySchema
+      requestSchema: RequestSchema
+      responseSchema: ResponseSchema
+      errorSchema: ErrorSchema
+      urlParamsSchema: UrlParamsSchema
+    },
+  >(
+    config: MutationEndpointConfig<
+      UseDiscriminator,
+      Method,
+      Url,
+      QuerySchema,
+      RequestSchema,
+      ResponseSchema,
+      ErrorSchema,
+      UrlParamsSchema,
+      UseKey,
+      TBaseResult,
+      Result,
+      OnMutateResult,
+      Context,
+      Variables
+    >,
+  ): ((
+    ...args: UseKey extends true
+      ? UrlHasParams<Url> extends true
+        ? [{ urlParams: UrlParams<Url> }]
+        : [{}]
+      : []
+  ) => UseMutationResult<Result, Error, Variables, OnMutateResult>) &
+    (UseKey extends true ? MutationHelpers<Url, Result> : {}) &
+    EndpointHelper<Options, UseDiscriminator>
+}

package/src/client/types/query.mts

@@ -0,0 +1,132 @@
+import type {
+  EndpointOptions,
+  ErrorSchemaRecord,
+  HttpMethod,
+  InferEndpointParams,
+  Simplify,
+} from '@navios/builder'
+import type { DataTag, UseSuspenseQueryOptions } from '@tanstack/react-query'
+import type { 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'
+
+/**
+ * Helper type to build endpoint options without including undefined properties.
+ * This ensures HasProperty correctly identifies missing properties.
+ */
+type BuildEndpointOptions<
+  Method extends HttpMethod,
+  Url extends string,
+  QuerySchema extends ZodObject | undefined,
+  RequestSchema extends ZodType | undefined,
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+  UrlParamsSchema extends ZodObject | undefined,
+> = {
+  method: Method
+  url: Url
+  responseSchema: ResponseSchema
+} & (QuerySchema extends undefined ? {} : { querySchema: QuerySchema }) &
+  (RequestSchema extends undefined ? {} : { requestSchema: RequestSchema }) &
+  (ErrorSchema extends undefined ? {} : { errorSchema: ErrorSchema }) &
+  (UrlParamsSchema extends undefined
+    ? {}
+    : { urlParamsSchema: UrlParamsSchema })
+
+/**
+ * Extended endpoint options interface for query that includes processResponse.
+ */
+interface QueryEndpointConfig<
+  Method extends HttpMethod,
+  Url extends string,
+  QuerySchema extends ZodObject | undefined,
+  RequestSchema extends ZodType | undefined,
+  ResponseSchema extends ZodType,
+  ErrorSchema extends ErrorSchemaRecord | undefined,
+  UrlParamsSchema extends ZodObject | undefined,
+  TBaseResult,
+  Result,
+> extends EndpointOptions {
+  method: Method
+  url: Url
+  querySchema?: QuerySchema
+  requestSchema?: RequestSchema
+  responseSchema: ResponseSchema
+  errorSchema?: ErrorSchema
+  urlParamsSchema?: UrlParamsSchema
+  processResponse?: (data: TBaseResult) => Result
+}
+
+/**
+ * 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 ClientQueryMethods<UseDiscriminator extends boolean = false> {
+  /**
+   * Creates a type-safe 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 getUser = client.query({
+   *   method: 'GET',
+   *   url: '/users/$userId',
+   *   responseSchema: userSchema,
+   *   urlParamsSchema: z.object({ userId: z.string().uuid() }),
+   * })
+   *
+   * const { data } = getUser.useSuspense({ urlParams: { userId: '123' } })
+   * ```
+   */
+  query<
+    const Method extends HttpMethod = HttpMethod,
+    const Url extends string = string,
+    const QuerySchema extends ZodObject | undefined = undefined,
+    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 Result = TBaseResult,
+    const Options extends EndpointOptions = BuildEndpointOptions<
+      Method,
+      Url,
+      QuerySchema,
+      RequestSchema,
+      ResponseSchema,
+      ErrorSchema,
+      UrlParamsSchema
+    >,
+  >(
+    config: QueryEndpointConfig<
+      Method,
+      Url,
+      QuerySchema,
+      RequestSchema,
+      ResponseSchema,
+      ErrorSchema,
+      UrlParamsSchema,
+      TBaseResult,
+      Result
+    >,
+  ): ((
+    params: Simplify<InferEndpointParams<Options>>,
+  ) => UseSuspenseQueryOptions<
+    Result,
+    Error,
+    Result,
+    DataTag<Split<Url, '/'>, Result, Error>
+  >) &
+    QueryHelpers<Url, QuerySchema, Result, false, RequestSchema> &
+    EndpointHelper<Options, UseDiscriminator>
+}