Merge pull request #421 from OpenAPI-Qraft/feat/optional-parameters-for-the-query-fn

radist2s · web-flow · commit e87020228c91 · 2026-04-03T20:51:21.000+04:00
feat: allow query-fn options without parameters when all operation params are optional
diff --git a/.changeset/cold-pets-design.md b/.changeset/cold-pets-design.md
@@ -0,0 +1,7 @@
+---
+'@openapi-qraft/tanstack-query-react-plugin': minor
+'@openapi-qraft/tanstack-query-react-types': minor
+'@openapi-qraft/react': minor
+---
+
+When an operation has only optional parameters, the imperative operation function now accepts `QueryFnOptions` (e.g. `signal`, `meta`) without requiring a `parameters` argument. This matches how optional request fields are already handled for hooks and improves typing for direct `qraft.<service>.<operation>(…)` calls.
diff --git a/packages/react-client/src/tests/qraftAPIClient.test.tsx b/packages/react-client/src/tests/qraftAPIClient.test.tsx
@@ -2172,21 +2172,55 @@ describe('Qraft uses Operation Query Function', () => {
     );
   });
 
-  it('uses Operation Query without arguments', async () => {
-    const { qraft } = createClient();
+  describe('uses Operation Query without arguments', () => {
+    it('uses Operation Query without invoke options', async () => {
+      const { qraft } = createClient();
 
-    const { data, error } = await qraft.files.findAll();
+      const { data, error } = await qraft.files.findAll();
 
-    expect(
-      error satisfies
-        | Services['files']['findAll']['types']['error']
-        | Error
-        | undefined
-    ).toBeUndefined();
+      expect(
+        error satisfies
+          | Services['files']['findAll']['types']['error']
+          | Error
+          | undefined
+      ).toBeUndefined();
 
-    expect(
-      data satisfies Services['files']['findAll']['types']['data'] | undefined
-    ).toEqual(filesFindAllResponsePayloadFixtures);
+      expect(
+        data satisfies Services['files']['findAll']['types']['data'] | undefined
+      ).toEqual(filesFindAllResponsePayloadFixtures);
+    });
+
+    it('uses Operation Query with `signal` without `parameters`', async () => {
+      const { qraft } = createClient();
+
+      const requestFnSpy = vi.fn(requestFn) as typeof requestFn;
+
+      const controller = new AbortController();
+      const signal = controller.signal;
+
+      const { data, error } = await qraft.files.findAll(
+        { signal },
+        requestFnSpy
+      );
+
+      expect(
+        error satisfies
+          | Services['files']['findAll']['types']['error']
+          | Error
+          | undefined
+      ).toBeUndefined();
+
+      expect(
+        data satisfies Services['files']['findAll']['types']['data'] | undefined
+      ).toEqual(filesFindAllResponsePayloadFixtures);
+
+      expect(requestFnSpy).toHaveBeenCalledWith(
+        qraft.files.findAll.schema,
+        expect.objectContaining({
+          signal,
+        })
+      );
+    });
   });
 
   it('uses Operation Query with `queryKey`', async () => {
diff --git a/packages/tanstack-query-react-plugin/src/__snapshots__/explicit-import-extensions/services/FilesService.ts.snapshot.ts b/packages/tanstack-query-react-plugin/src/__snapshots__/explicit-import-extensions/services/FilesService.ts.snapshot.ts
@@ -4,7 +4,7 @@
  */
 
 import type { paths } from "../../openapi.js";
-import type { DeepReadonly, InvalidateQueryFilters, MutationFiltersByMutationKey, MutationFiltersByParameters, MutationVariables, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationMutationFnOptions, ServiceOperationMutationKey, ServiceOperationQueryKey, ServiceOperationUseMutationOptions, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
+import type { DeepReadonly, InvalidateQueryFilters, MutationFiltersByMutationKey, MutationFiltersByParameters, MutationVariables, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptions, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationMutationFnOptions, ServiceOperationMutationKey, ServiceOperationQueryKey, ServiceOperationUseMutationOptions, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
 import type { CancelOptions, DefinedInitialDataInfiniteOptions, DefinedInitialDataOptions, DefinedUseInfiniteQueryResult, DefinedUseQueryResult, InfiniteQueryPageParamsOptions, InvalidateOptions, Mutation, MutationCache, MutationState, NoInfer, QueryState, RefetchOptions, ResetOptions, SetDataOptions, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, Updater, UseInfiniteQueryResult, UseMutationResult, UseQueryResult, UseSuspenseInfiniteQueryOptions, UseSuspenseInfiniteQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult } from "@tanstack/react-query";
 export interface FilesService {
     /** @summary Get a files by ID */
@@ -803,7 +803,7 @@ export interface FilesService {
          * @deprecated
          * @summary Get a file list
          */
-        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetFileListSchema, GetFileListParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetFileListParameters, TMeta, TSignal> | void), client?: (schema: GetFileListSchema, options: {
+        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetFileListSchema, GetFileListParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetFileListParameters, TMeta, TSignal> | QueryFnOptions<TMeta, TSignal> | void), client?: (schema: GetFileListSchema, options: {
             parameters: GetFileListParameters;
             signal?: TSignal;
             meta?: TMeta;
diff --git a/packages/tanstack-query-react-plugin/src/__snapshots__/operation-parameters-type-wrapper/services/FilesService.ts.snapshot.ts b/packages/tanstack-query-react-plugin/src/__snapshots__/operation-parameters-type-wrapper/services/FilesService.ts.snapshot.ts
@@ -4,7 +4,7 @@
  */
 
 import type { paths } from "../../openapi.d.ts";
-import type { DeepReadonly, InvalidateQueryFilters, MutationFiltersByMutationKey, MutationFiltersByParameters, MutationVariables, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationMutationFnOptions, ServiceOperationMutationKey, ServiceOperationQueryKey, ServiceOperationUseMutationOptions, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
+import type { DeepReadonly, InvalidateQueryFilters, MutationFiltersByMutationKey, MutationFiltersByParameters, MutationVariables, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptions, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationMutationFnOptions, ServiceOperationMutationKey, ServiceOperationQueryKey, ServiceOperationUseMutationOptions, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
 import type { CancelOptions, DefinedInitialDataInfiniteOptions, DefinedInitialDataOptions, DefinedUseInfiniteQueryResult, DefinedUseQueryResult, InfiniteQueryPageParamsOptions, InvalidateOptions, Mutation, MutationCache, MutationState, NoInfer, QueryState, RefetchOptions, ResetOptions, SetDataOptions, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, Updater, UseInfiniteQueryResult, UseMutationResult, UseQueryResult, UseSuspenseInfiniteQueryOptions, UseSuspenseInfiniteQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult } from "@tanstack/react-query";
 import type { ParametersWrapper } from "../../type-overrides/parameters-wrapper.js";
 export interface FilesService {
@@ -804,7 +804,7 @@ export interface FilesService {
          * @deprecated
          * @summary Get a file list
          */
-        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetFileListSchema, GetFileListParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetFileListParameters, TMeta, TSignal> | void), client?: (schema: GetFileListSchema, options: {
+        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetFileListSchema, GetFileListParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetFileListParameters, TMeta, TSignal> | QueryFnOptions<TMeta, TSignal> | void), client?: (schema: GetFileListSchema, options: {
             parameters: GetFileListParameters;
             signal?: TSignal;
             meta?: TMeta;
diff --git a/packages/tanstack-query-react-plugin/src/__snapshots__/queryable-write-operations/services/FilesService.ts.snapshot.ts b/packages/tanstack-query-react-plugin/src/__snapshots__/queryable-write-operations/services/FilesService.ts.snapshot.ts
@@ -4,7 +4,7 @@
  */
 
 import type { paths } from "../../openapi.d.ts";
-import type { DeepReadonly, InvalidateQueryFilters, MutationFiltersByMutationKey, MutationFiltersByParameters, MutationVariables, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationMutationFnOptions, ServiceOperationMutationKey, ServiceOperationQueryKey, ServiceOperationUseMutationOptions, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
+import type { DeepReadonly, InvalidateQueryFilters, MutationFiltersByMutationKey, MutationFiltersByParameters, MutationVariables, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptions, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationMutationFnOptions, ServiceOperationMutationKey, ServiceOperationQueryKey, ServiceOperationUseMutationOptions, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
 import type { CancelOptions, DefinedInitialDataInfiniteOptions, DefinedInitialDataOptions, DefinedUseInfiniteQueryResult, DefinedUseQueryResult, InfiniteQueryPageParamsOptions, InvalidateOptions, Mutation, MutationCache, MutationState, NoInfer, QueryState, RefetchOptions, ResetOptions, SetDataOptions, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, Updater, UseInfiniteQueryResult, UseMutationResult, UseQueryResult, UseSuspenseInfiniteQueryOptions, UseSuspenseInfiniteQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult } from "@tanstack/react-query";
 export interface FilesService {
     /** @summary Get a files by ID */
@@ -1664,7 +1664,7 @@ export interface FilesService {
          * @deprecated
          * @summary Get a file list
          */
-        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetFileListSchema, GetFileListParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetFileListParameters, TMeta, TSignal> | void), client?: (schema: GetFileListSchema, options: {
+        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetFileListSchema, GetFileListParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetFileListParameters, TMeta, TSignal> | QueryFnOptions<TMeta, TSignal> | void), client?: (schema: GetFileListSchema, options: {
             parameters: GetFileListParameters;
             signal?: TSignal;
             meta?: TMeta;
diff --git a/packages/tanstack-query-react-plugin/src/__snapshots__/root-level-security-inheritance/services/AccountsService.ts.snapshot.ts b/packages/tanstack-query-react-plugin/src/__snapshots__/root-level-security-inheritance/services/AccountsService.ts.snapshot.ts
@@ -4,12 +4,12 @@
  */
 
 import type { paths } from "../../openapi.d.ts";
-import type { DeepReadonly, InvalidateQueryFilters, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationQueryKey, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
+import type { DeepReadonly, InvalidateQueryFilters, OperationError, OperationInfiniteData, PartialParameters, QueryFiltersByParameters, QueryFiltersByQueryKey, QueryFnOptions, QueryFnOptionsByParameters, QueryFnOptionsByQueryKey, RequestFnResponse, ServiceOperationEnsureInfiniteQueryDataOptions, ServiceOperationEnsureQueryDataOptions, ServiceOperationFetchInfiniteQueryOptions, ServiceOperationFetchQueryOptions, ServiceOperationInfiniteQueryKey, ServiceOperationQueryKey, UseQueryOptionsForUseQueries, UseQueryOptionsForUseSuspenseQuery, WithOptional, QraftServiceOperationsToken } from "@openapi-qraft/tanstack-query-react-types";
 import type { CancelOptions, DefinedInitialDataInfiniteOptions, DefinedInitialDataOptions, DefinedUseInfiniteQueryResult, DefinedUseQueryResult, InfiniteQueryPageParamsOptions, InvalidateOptions, NoInfer, QueryState, RefetchOptions, ResetOptions, SetDataOptions, UndefinedInitialDataInfiniteOptions, UndefinedInitialDataOptions, Updater, UseInfiniteQueryResult, UseQueryResult, UseSuspenseInfiniteQueryOptions, UseSuspenseInfiniteQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult } from "@tanstack/react-query";
 export interface AccountsService {
     getAccounts: {
         /**/
-        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetAccountsSchema, GetAccountsParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetAccountsParameters, TMeta, TSignal> | void), client?: (schema: GetAccountsSchema, options: {
+        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetAccountsSchema, GetAccountsParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetAccountsParameters, TMeta, TSignal> | QueryFnOptions<TMeta, TSignal> | void), client?: (schema: GetAccountsSchema, options: {
             parameters: GetAccountsParameters;
             signal?: TSignal;
             meta?: TMeta;
@@ -232,7 +232,7 @@ export interface AccountsService {
     };
     getAccountProfile: {
         /**/
-        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetAccountProfileSchema, GetAccountProfileParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetAccountProfileParameters, TMeta, TSignal> | void), client?: (schema: GetAccountProfileSchema, options: {
+        <TMeta extends Record<string, any>, TSignal extends AbortSignal = AbortSignal>(options: QueryFnOptionsByQueryKey<GetAccountProfileSchema, GetAccountProfileParameters, TMeta, TSignal> | (QueryFnOptionsByParameters<GetAccountProfileParameters, TMeta, TSignal> | QueryFnOptions<TMeta, TSignal> | void), client?: (schema: GetAccountProfileSchema, options: {
             parameters: GetAccountProfileParameters;
             signal?: TSignal;
             meta?: TMeta;
diff --git a/packages/tanstack-query-react-types/src/service-operation/ServiceOperationQueryFn.ts b/packages/tanstack-query-react-types/src/service-operation/ServiceOperationQueryFn.ts
@@ -1,5 +1,6 @@
 import type {
   AreAllOptional,
+  QueryFnOptions,
   QueryFnOptionsByParameters,
   QueryFnOptionsByQueryKey,
   RequestFnResponse,
@@ -18,7 +19,10 @@ export interface ServiceOperationQueryFn<
     options:
       | QueryFnOptionsByQueryKey<TSchema, TQueryParams, TMeta, TSignal>
       | (AreAllOptional<TQueryParams> extends true
-          ? QueryFnOptionsByParameters<TQueryParams, TMeta, TSignal> | void
+          ?
+              | QueryFnOptionsByParameters<TQueryParams, TMeta, TSignal>
+              | QueryFnOptions<TMeta, TSignal>
+              | void
           : QueryFnOptionsByParameters<TQueryParams, TMeta, TSignal>),
     client?: (
       schema: TSchema,
diff --git a/packages/tanstack-query-react-types/src/shared/ServiceOperationQuery.ts b/packages/tanstack-query-react-types/src/shared/ServiceOperationQuery.ts
@@ -1,20 +1,24 @@
 import type { ServiceOperationQueryKey } from '@openapi-qraft/tanstack-query-react-types';
 import type { DeepReadonly } from './DeepReadonly.js';
 
-interface QueryFnOptionsBase<
+export interface QueryFnOptions<
   TMeta extends Record<string, any>,
   TSignal extends AbortSignal = AbortSignal,
 > {
   signal?: TSignal;
   meta?: TMeta;
+  /**
+   * Base URL to use for the request
+   * @example 'https://api.example.com'
+   */
+  baseUrl?: string;
 }
 
 export interface QueryFnOptionsByParameters<
   TParams,
   TMeta extends Record<string, any>,
   TSignal extends AbortSignal = AbortSignal,
->
-  extends QueryFnOptionsBase<TMeta, TSignal>, QueryFnBaseUrlOptions {
+> extends QueryFnOptions<TMeta, TSignal> {
   parameters: DeepReadonly<TParams>;
 
   queryKey?: never;
@@ -25,17 +29,8 @@ export interface QueryFnOptionsByQueryKey<
   TParams,
   TMeta extends Record<string, any>,
   TSignal extends AbortSignal = AbortSignal,
->
-  extends QueryFnOptionsBase<TMeta, TSignal>, QueryFnBaseUrlOptions {
+> extends QueryFnOptions<TMeta, TSignal> {
   queryKey: ServiceOperationQueryKey<TSchema, TParams>;
 
   parameters?: never;
 }
-
-interface QueryFnBaseUrlOptions {
-  /**
-   * Base URL to use for the request
-   * @example 'https://api.example.com'
-   */
-  baseUrl?: string;
-}
diff --git a/turbo.json b/turbo.json
@@ -9,7 +9,7 @@
     "test": {
       "cache": true,
       "dependsOn": ["write-package-version-file", "^build"],
-      "outputs": ["coverage/**"]
+      "outputs": []
     },
     "typecheck": {
       "cache": true,
