fix(fetch): restore urlEncodeParameters support for the fetch client (#3343) (#3405)

* refactor(core,query): relocate makeRouteSafe to @orval/core

Move makeRouteSafe and wrapRouteParameters from @orval/query/utils into
@orval/core/getters/route so non-query packages can reuse them without
introducing a reverse dependency on @orval/query. Update query/src/client.ts
to import makeRouteSafe from @orval/core and move the related unit tests
to core/getters/route.test.ts. Behavior is unchanged.

This prepares for the follow-up fix that restores urlEncodeParameters
support in @orval/fetch (#3343).

Signed-off-by: zeriong <jaeryong95@gmail.com>

* fix(fetch): restore urlEncodeParameters support (#3343)

The fetch client generator stopped honoring the `urlEncodeParameters`
output option after commit cb06139 (#2168) accidentally dropped the
guard introduced by #2292. Generated URL helpers interpolated path
parameters as-is, so values containing reserved characters (`/`, `#`,
`?`, ...) leaked into the request URL.

Re-apply `makeRouteSafe(route)` at the top of `generateRequestFunction`
in `@orval/fetch`, mirroring the axios path in `@orval/query`. This wraps
each `\${param}` segment with `encodeURIComponent(String(...))`. Query
parameters remain handled by `URLSearchParams` as before; this option
only affects path parameters.

Add a dedicated fetch + `urlEncodeParameters` snapshot fixture so a
future regression in the fetch path won't be silently absorbed by the
`dateParams` fixture.

* docs(output): clarify urlEncodeParameters scope and limitations

State explicitly that the option wraps only path parameters (query
parameters are already encoded by the underlying client) and note that
array/object path parameters fall back to `String(value)` instead of
following their OpenAPI `style` serialization, since orval does not
generate `style: simple|matrix|label` for path parameters.

* test(fetch): simplify urlEncodeParameters fixture to avoid CI snapshot drift

The model files generated by this fixture exhibited a JSDoc reflow only
on CI (Ubuntu) that didn't reproduce locally, while the same petstore
spec under other fixtures stayed stable. Drop `schemas` and `mock` from
the fixture so it only emits `endpoints.ts`; that single file still
exercises the regression covered by #3343 — `${encodeURIComponent(
String(petId))}` is asserted in the URL helper output.

* test(fetch): refresh urlEncodeParameters snapshot for new JSDoc reflow

After the master merge of #3393 (`fix(core): handle multi-line
descriptions in JSDoc generation`), the core now emits multi-line
JSDoc with proper ` * ` line prefixes. Regenerate the snapshot for
this PR's new fixture so it matches the post-#3393 output. The
`encodeURIComponent(String(petId))` assertions covering #3343 are
preserved.

---------

Signed-off-by: zeriong <jaeryong95@gmail.com>

Author: zeriong

docs/content/docs/reference/configuration/output.mdx

@@ -1694,7 +1694,9 @@ Make all parameters optional except path parameters.
 **Type:** `Boolean`
 **Default:** `false`
 
-Enable URL encoding of path/query parameters.
+Wrap each path parameter with `encodeURIComponent(String(...))` in generated URL helpers. This option only affects path parameters; query parameters are typically encoded by the underlying client (`URLSearchParams`, `axios`, etc.).
+
+Path parameters are stringified via `String(value)` before encoding, so array (`style: simple|matrix|label`) and object path parameters are not serialized according to their OpenAPI `style` — they fall back to the default `String(value)` representation.
 
 ### optionsParamRequired
 

packages/core/src/getters/route.test.ts

@@ -11,6 +11,8 @@ import {
   getFullRoute,
   getRoute,
   getRouteAsArray,
+  makeRouteSafe,
+  wrapRouteParameters,
 } from './route';
 
 describe('getRoute getter', () => {
@@ -267,3 +269,57 @@ describe('getRouteAsArray getter', () => {
     expect(getRouteAsArray(input)).toEqual(output);
   });
 });
+
+describe('wrapRouteParameters', () => {
+  it('wraps parameters correctly', () => {
+    const result = wrapRouteParameters(
+      '/user/${id}/profile',
+      'prefix-',
+      '-suffix',
+    );
+    expect(result).toBe('/user/${prefix-id-suffix}/profile');
+  });
+
+  it('handles no parameters gracefully', () => {
+    const result = wrapRouteParameters('/user/profile', 'prefix-', '-suffix');
+    expect(result).toBe('/user/profile');
+  });
+
+  it('handles empty route', () => {
+    const result = wrapRouteParameters('', 'prefix-', '-suffix');
+    expect(result).toBe('');
+  });
+});
+
+describe('makeRouteSafe', () => {
+  it('encodes URI components in parameters', () => {
+    const result = makeRouteSafe('/search/${query}/bla/${something}');
+    expect(result).toBe(
+      '/search/${encodeURIComponent(String(query))}/bla/${encodeURIComponent(String(something))}',
+    );
+  });
+
+  it('encodes adjacent parameters separately', () => {
+    const result = makeRouteSafe('/x/${a}${b}');
+    expect(result).toBe(
+      '/x/${encodeURIComponent(String(a))}${encodeURIComponent(String(b))}',
+    );
+  });
+
+  it('encodes parameters mixed with literal separators', () => {
+    const result = makeRouteSafe('/files/${name}.${ext}');
+    expect(result).toBe(
+      '/files/${encodeURIComponent(String(name))}.${encodeURIComponent(String(ext))}',
+    );
+  });
+
+  it('handles no special characters gracefully', () => {
+    const result = makeRouteSafe('/search/query');
+    expect(result).toBe('/search/query');
+  });
+
+  it('handles empty route', () => {
+    const result = makeRouteSafe('');
+    expect(result).toBe('');
+  });
+});

packages/core/src/getters/route.ts

@@ -1,3 +1,4 @@
+import { TEMPLATE_TAG_REGEX } from '../constants';
 import type {
   BaseUrlFromConstant,
   BaseUrlFromSpec,
@@ -145,6 +146,17 @@ export function getBaseUrlRuntimeImports(
   }));
 }
 
+// Emits a codegen string: wraps each `${param}` segment of a template-literal
+// route so the generated client encodes path parameters at request time.
+export const wrapRouteParameters = (
+  route: string,
+  prepend: string,
+  append: string,
+): string => route.replaceAll(TEMPLATE_TAG_REGEX, `\${${prepend}$1${append}}`);
+
+export const makeRouteSafe = (route: string): string =>
+  wrapRouteParameters(route, 'encodeURIComponent(String(', '))');
+
 // Creates a mixed use array with path variables and string from template string route
 export function getRouteAsArray(route: string): string {
   return route

packages/fetch/src/index.ts

@@ -11,6 +11,7 @@ import {
   type GeneratorVerbOptions,
   GetterPropType,
   isObject,
+  makeRouteSafe,
   type OpenApiParameterObject,
   type OpenApiReferenceObject,
   type OpenApiSchemaObject,
@@ -68,8 +69,14 @@ export const generateRequestFunction = (
     override,
     doc,
   }: GeneratorVerbOptions,
-  { route, context, pathRoute }: GeneratorOptions,
+  { route: _route, context, pathRoute }: GeneratorOptions,
 ) => {
+  let route = _route;
+
+  if (context.output.urlEncodeParameters) {
+    route = makeRouteSafe(route);
+  }
+
   const isRequestOptions = override.requestOptions !== false;
   const isFormData = !override.formData.disabled;
   const isFormUrlEncoded = override.formUrlEncoded !== false;

packages/query/src/client.ts

@@ -15,6 +15,7 @@ import {
   isObject,
   isSyntheticDefaultImportsAllow,
   kebab,
+  makeRouteSafe,
   OutputHttpClient,
   pascal,
   toObjectString,
@@ -24,12 +25,7 @@ import {
   generateRequestFunction as generateFetchRequestFunction,
 } from '@orval/fetch';
 
-import {
-  getHasSignal,
-  makeRouteSafe,
-  vueUnRefParams,
-  vueWrapTypeWithMaybeRef,
-} from './utils';
+import { getHasSignal, vueUnRefParams, vueWrapTypeWithMaybeRef } from './utils';
 
 export const AXIOS_DEPENDENCIES = [
   {

packages/query/src/utils.test.ts

@@ -1,50 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import {
-  makeRouteSafe,
-  normalizeQueryOptions,
-  wrapRouteParameters,
-} from './utils';
-
-describe('wrapRouteParameters', () => {
-  it('wraps parameters correctly', () => {
-    const result = wrapRouteParameters(
-      '/user/${id}/profile',
-      'prefix-',
-      '-suffix',
-    );
-    expect(result).toBe('/user/${prefix-id-suffix}/profile');
-  });
-
-  it('handles no parameters gracefully', () => {
-    const result = wrapRouteParameters('/user/profile', 'prefix-', '-suffix');
-    expect(result).toBe('/user/profile');
-  });
-
-  it('handles empty route', () => {
-    const result = wrapRouteParameters('', 'prefix-', '-suffix');
-    expect(result).toBe('');
-  });
-});
-
-describe('makeRouteSafe', () => {
-  it('encodes URI components in parameters', () => {
-    const result = makeRouteSafe('/search/${query}/bla/${something}');
-    expect(result).toBe(
-      '/search/${encodeURIComponent(String(query))}/bla/${encodeURIComponent(String(something))}',
-    );
-  });
-
-  it('handles no special characters gracefully', () => {
-    const result = makeRouteSafe('/search/query');
-    expect(result).toBe('/search/query');
-  });
-
-  it('handles empty route', () => {
-    const result = makeRouteSafe('');
-    expect(result).toBe('');
-  });
-});
+import { normalizeQueryOptions } from './utils';
 
 describe('normalizeQueryOptions', () => {
   it('should include useOperationIdAsQueryKey when provided', () => {

packages/query/src/utils.ts

@@ -12,7 +12,6 @@ import {
   OutputClient,
   type OutputClientFunc,
   type QueryOptions,
-  TEMPLATE_TAG_REGEX,
 } from '@orval/core';
 
 export const normalizeQueryOptions = (
@@ -137,15 +136,6 @@ export const vueUnRefParams = (props: GetterProps): string => {
     .join('\n');
 };
 
-export const wrapRouteParameters = (
-  route: string,
-  prepend: string,
-  append: string,
-): string => route.replaceAll(TEMPLATE_TAG_REGEX, `\${${prepend}$1${append}}`);
-
-export const makeRouteSafe = (route: string): string =>
-  wrapRouteParameters(route, 'encodeURIComponent(String(', '))');
-
 export const isVue = (client: OutputClient | OutputClientFunc) =>
   OutputClient.VUE_QUERY === client;
 

tests/__snapshots__/fetch/dateParams/pets/pets.ts

@@ -100,8 +100,8 @@ export const getListPetsByCountryUrl = (
   const stringifiedParams = normalizedParams.toString();
 
   return stringifiedParams.length > 0
-    ? `/pets-by-country/${country}?${stringifiedParams}`
-    : `/pets-by-country/${country}`;
+    ? `/pets-by-country/${encodeURIComponent(String(country))}?${stringifiedParams}`
+    : `/pets-by-country/${encodeURIComponent(String(country))}`;
 };
 
 /**
@@ -170,8 +170,8 @@ export const getListPetsByAgeUrl = (
   const stringifiedParams = normalizedParams.toString();
 
   return stringifiedParams.length > 0
-    ? `/pets-by-age/${age}?${stringifiedParams}`
-    : `/pets-by-age/${age}`;
+    ? `/pets-by-age/${encodeURIComponent(String(age))}?${stringifiedParams}`
+    : `/pets-by-age/${encodeURIComponent(String(age))}`;
 };
 
 /**