Accessing response headers with the pinia-colada plugin

[spladug]

Hi! I love openapi-ts, thank you for the great tool.

I'm trying out using the pinia-colada plugin with my app but wanted to raise an edge case I've run into. Our app uses Link headers for pagination, much like the GitHub API does. Since the pagination metadata isn't in the JSON response payload, there needs to be a little extra processing before returning from the query function. I had something like this in my code:

const examplePaginatedEndpointQueryPaginated = defineQueryOptions((options?: Options<ExamplePaginatedEndpointQueryData>) => ({
  key: examplePaginatedEndpointQueryKey(options),
  query: async (context) => {
    const response = await examplePaginatedEndpoint({
      ...options,
      ...context,
      throwOnError: true,
    })
    return { items: response.data, pagination: extractPaginationMetadata(response) }
  },
  placeholderData: (previousData) => previousData, // https://pinia-colada.esm.dev/guide/paginated-queries.html#Keeping-the-old-data
}))

That is, it's nearly a copy-paste of the generated query definition but with a transform for mapping the response object to the query result. (Plus the placeholderData thing recommended by pinia colada for pagination, but that's less important).

I see a few paths forward:

• define one of these custom transform query options for each paginated query as I need them
  • obviously this works but kinda gets rid of a lot of the benefit of the codegen
• write an openapi-ts plugin custom to my app to generate said
  • the OpenAPI spec is annotated with an x-paginated field for the relevant endpoints so this is something that can be automated
  • this generally seems like the best approach, but I see in the docs and the recent commit history that the plugin API is very much in flux right now so it seems a little dangerous to build off it at the moment?
• add some sort of ability to the openapi-ts pinia colada plugin to add in transformers to the query options before query results are returned to pinia colada
  • i'm not 100% sure how the typing would work on this though. especially if they're conditional

I was wondering what you'd recommend doing here?

Thank you!

[mrlubos]

@spladug can you share your spec? When there are small changes like this, the answer I'm looking for is "how can I allow you to do them without writing your own plugin?" Can you show your extractPaginationMetadata() function?

[spladug]

Here's the extract function implementation:

import { parseLinkHeader } from "@web3-storage/parse-link-header"

export type PaginationMetadata = {
  next: string | null
  prev: string | null
}

const extractPageParam = (url: string | undefined) => {
  if (!url) return null
  const urlObj = new URL(url)
  return urlObj.searchParams.get("page")
}

export const extractPaginationMetadata = (response: { response: Response }): PaginationMetadata => {
  const linkHeader = response.response.headers.get("link")
  const links = parseLinkHeader(linkHeader)
  return {
    next: extractPageParam(links?.next?.url),
    prev: extractPageParam(links?.prev?.url),
  }
}

The spec is here: https://api.wattcarbon.com/#tag/Devices/operation/Devices-list_devices / https://api.wattcarbon.com/openapi.json

[jedzej]

We're facing very similar issue with very limited error response information, but not with pinia-colada, but with tanstack query plugin. The cause seems to be the same API design decisions taken for both.

I want to access status code in the error to decide whether to retry a failed request or not

  const mutation = useMutation({
    ...myMutation(),
    retry: (count, err) => {
      err // <- ONLY ERROR CONTENT IS HERE, NO STATUS, NO HEADERS
    },
  });

The reason for that is this code in generated xxx/@tanstack/react-query.gen.ts

  const mutationOptions: UseMutationOptions<myMutationResponse, myMutationError, Options<myMutationData>> = {
    mutationFn: async (localOptions) => {
      const { data } = await myMutation({
        ...options,
        ...localOptions,
        throwOnError: true, // <----- ALWAYS TRUE
      });
      return data;
    },
  };

Which in conjunction with generated xxx/client/client.ts causes the limited access described above

    if (opts.throwOnError) {
      throw finalError; // <------ SKIP RESPONSE OBJECT, THROW ONLY THE JSON BODY
    }

    // TODO: we probably want to return error and improve types
    return opts.responseStyle === "data"
      ? undefined
      : {
          error: finalError,
          ...result,
        };

Would be great if we had the possibility to access the whole response object. Right now it seems to be not supported at all, am I right?