feat: Add useOperationIdAsQueryKey option for query key generation (#2314)

* feat: Add useOperationIdAsQueryKey option for query key generation

This commit adds a new configuration option useOperationIdAsQueryKey to the query
options that allows users to generate query keys using the OpenAPI operation ID
instead of the route string.

Changes Made:
- Added useOperationIdAsQueryKey option to QueryOptions and NormalizedQueryOptions interfaces
- Modified query key generation logic to use operation ID when enabled
- Added support for the new option in normalizeQueryOptions function
- Added comprehensive tests for the new functionality

Benefits:
- Stable keys that dont change when route paths are modified
- Cleaner, more semantic query keys
- Consistent naming across applications
- Backward compatible (defaults to false)

Fixes #2096

* docs: Add useOperationIdAsQueryKey documentation and cleanup

- Added comprehensive documentation for the useOperationIdAsQueryKey option
  in the existing output configuration docs
- Removed accidental .tool-versions file that's not part of the project structure
- Added code examples showing the difference between default and new behavior
- Integrated documentation into the existing project structure

* fix: add missing entries in options.ts

* fix: run yarn format

* fix: add props to queryKey if they are part of the path

* Update packages/query/src/index.ts

Co-authored-by: Shodai Suzuki <info@soartec-lab.work>

* Update index.ts

Co-authored-by: Shodai Suzuki <info@soartec-lab.work>

---------

Co-authored-by: Shodai Suzuki <info@soartec-lab.work>

Author: mortik

docs/src/pages/reference/configuration/output.md

@@ -1372,6 +1372,48 @@ Default Value: `false`.
 
 Use to make Orval generate query keys as arrays instead of strings.
 
+#### useOperationIdAsQueryKey
+
+Type: `Boolean`.
+
+Default Value: `false`.
+
+Use to generate query keys using the OpenAPI operation ID instead of the route path. This provides more stable and semantic query keys that don't change when route paths are modified.
+
+**Example:**
+
+```js
+module.exports = {
+  petstore: {
+    output: {
+      override: {
+        query: {
+          useOperationIdAsQueryKey: true,
+        },
+      },
+    },
+  },
+};
+```
+
+**Generated code comparison:**
+
+Default behavior (`useOperationIdAsQueryKey: false`):
+
+```typescript
+const getPetByIdQueryKey = (petId: string) => {
+  return [`/pets/${petId}`] as const;
+};
+```
+
+With `useOperationIdAsQueryKey: true`:
+
+```typescript
+const getPetByIdQueryKey = (petId: string) => {
+  return ['getPetById', petId] as const;
+};
+```
+
 #### version
 
 Type: `number`.

packages/core/src/types.ts

@@ -586,6 +586,7 @@ export type NormalizedQueryOptions = {
   shouldExportHttpClient?: boolean;
   shouldExportQueryKey?: boolean;
   shouldSplitQueryKey?: boolean;
+  useOperationIdAsQueryKey?: boolean;
   signal?: boolean;
   version?: 3 | 4 | 5;
 };
@@ -606,6 +607,7 @@ export type QueryOptions = {
   shouldExportHttpClient?: boolean;
   shouldExportQueryKey?: boolean;
   shouldSplitQueryKey?: boolean;
+  useOperationIdAsQueryKey?: boolean;
   signal?: boolean;
   version?: 3 | 4 | 5;
 };

packages/orval/src/utils/options.ts

@@ -739,6 +739,19 @@ const normalizeQueryOptions = (
       : {
           signal: globalOptions.signal,
         }),
+    ...(isUndefined(globalOptions.useOperationIdAsQueryKey)
+      ? {}
+      : {
+          useOperationIdAsQueryKey: globalOptions.useOperationIdAsQueryKey,
+        }),
+    ...(isUndefined(queryOptions.useOperationIdAsQueryKey)
+      ? {}
+      : { useOperationIdAsQueryKey: queryOptions.useOperationIdAsQueryKey }),
+    ...(isUndefined(globalOptions.signal)
+      ? {}
+      : {
+          signal: globalOptions.signal,
+        }),
     ...(isUndefined(queryOptions.signal)
       ? {}
       : { signal: queryOptions.signal }),

packages/query/src/index.ts

@@ -1328,11 +1328,16 @@ const generateQueryHook = async (
         ? getRouteAsArray(route) // Note: this is required for reactivity to work, we will lose it if route params are converted into string, only as array they will be tracked // TODO: add tests for this
         : `\`${route}\``;
 
+
+    // Use operation ID as query key if enabled, otherwise use route string
+    const queryKeyIdentifier = override.query.useOperationIdAsQueryKey
+      ? operationName : routeString;
+
     // Note: do not unref() params in Vue - this will make key lose reactivity
     const queryKeyFn = `${
       override.query.shouldExportQueryKey ? 'export ' : ''
     }const ${queryKeyFnName} = (${queryKeyProps}) => {
-    return [${routeString}${queryParams ? ', ...(params ? [params]: [])' : ''}${
+    return [${queryKeyIdentifier}${queryParams ? ', ...(params ? [params]: [])' : ''}${
       body.implementation ? `, ${body.implementation}` : ''
     }] as const;
     }`;

packages/query/src/utils.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest';
-import { makeRouteSafe, wrapRouteParameters } from './utils';
+import {
+  makeRouteSafe,
+  normalizeQueryOptions,
+  wrapRouteParameters,
+} from './utils';
 
 describe('wrapRouteParameters', () => {
   it('wraps parameters correctly', () => {
@@ -40,3 +44,26 @@ describe('makeRouteSafe', () => {
     expect(result).toBe('');
   });
 });
+
+describe('normalizeQueryOptions', () => {
+  it('should include useOperationIdAsQueryKey when provided', () => {
+    const result = normalizeQueryOptions(
+      { useOperationIdAsQueryKey: true },
+      '/workspace',
+    );
+    expect(result.useOperationIdAsQueryKey).toBe(true);
+  });
+
+  it('should not include useOperationIdAsQueryKey when false', () => {
+    const result = normalizeQueryOptions(
+      { useOperationIdAsQueryKey: false },
+      '/workspace',
+    );
+    expect(result.useOperationIdAsQueryKey).toBeUndefined();
+  });
+
+  it('should not include useOperationIdAsQueryKey when not provided', () => {
+    const result = normalizeQueryOptions({}, '/workspace');
+    expect(result.useOperationIdAsQueryKey).toBeUndefined();
+  });
+});

packages/query/src/utils.ts

@@ -60,6 +60,9 @@ export const normalizeQueryOptions = (
       ? { shouldExportHttpClient: true }
       : {}),
     ...(queryOptions.shouldSplitQueryKey ? { shouldSplitQueryKey: true } : {}),
+    ...(queryOptions.useOperationIdAsQueryKey
+      ? { useOperationIdAsQueryKey: true }
+      : {}),
   };
 };