Custom Query Param Serialization in fetch Client

[sina-saeedi]

Hi everyone,

I’m using Orval with the fetch client and noticed a limitation with query parameter serialization. The generated code uses URLSearchParams.toString(), which doesn’t support indexed arrays or custom formats:
const stringifiedParams = new URLSearchParams(params).toString();

I know Orval allows providing a custom fetch client, but the challenge is that it still generates the full URL and passes that to my custom fetch. To apply custom serialization, I’d have to parse the URL back into parameters, reserialize them in my desired format, and then reconstruct the URL which feels redundant and less optimal.

Is there a known pattern for handling this that I'm missing?

[melloware]

i think custom fetch client is the way to go.

[rroberrt]

But a custom fetch client mutator still gets the URL from the "serializer" when using the fetch client:

export const getFooUrl = (params?: FooParams) => {
  const normalizedParams = new URLSearchParams();

  Object.entries(params || {}).forEach(([key, value]) => {
    if (value !== undefined) {
      normalizedParams.append(key, value === null ? 'null' : value.toString());
    }
  });

  const stringifiedParams = normalizedParams.toString();

  return stringifiedParams.length > 0 ? `/?${stringifiedParams}` : `/`;
};

Which one cannot control via paramsSerializer as per the docs:

Note: Only valid when using Axios or Angular.

[rroberrt]

To add to the above, it would not be possible to deserialize the returned URL inside the client mutator to re-serialize if you pass e.g. an object as a query parameter, because that turns it into:

/?foo=%5Bobject+Object%5D

[pick7]

You should not need to parse the already-built URL in a custom fetch client anymore. Orval has a request-level override.paramsSerializer hook that is valid for the fetch client too.

Example:

// orval.config.ts
import { defineConfig } from 'orval'

export default defineConfig({
  api: {
    input: './openapi.yaml',
    output: {
      client: 'fetch',
      target: './src/api.ts',
      override: {
        paramsSerializer: {
          path: './src/custom-params-serializer.ts',
          name: 'customParamsSerializer',
        },
      },
    },
  },
})

// src/custom-params-serializer.ts
import qs from 'qs'

export const customParamsSerializer = (
  params: Record<string, unknown> | undefined,
): string => {
  return qs.stringify(params ?? {}, {
    arrayFormat: 'indices', // foo[0]=a&foo[1]=b
    skipNulls: true,
    encodeValuesOnly: true,
  })
}

For the fetch client, the serializer must return the raw query string without the leading ?. Once this is configured, Orval delegates query string construction to your function instead of using the built-in URLSearchParams path, so the custom fetch mutator only has to execute the request.

If only a few endpoints need this, put the same paramsSerializer under override.operations.<operationId> or override.tags.<tagName> instead of making it global.