Requests file is marked as depreciated in the migration guide

[seriouslag]

Per the title, there is no information on what will replace the functionality of the request file.

I personally use a request file for most of my projects.

https://heyapi.vercel.app/openapi-ts/migrating.html

[mrlubos]

@seriouslag we need to gather more information about what people use custom requests for. Ideally, we can replace those use cases with features, for example interceptors cover some of the cases with modifying requests/responses. If we're unable to do so, you should be able to write your own wrapper as you do now. But instead of passing it as a config value, you'd plug it into our packages. This is related to our effort around extracting core folder into separate client package #308 Once that is done, you should be able to use whatever implementation of request function you want!

[mrlubos]

We definitely plan to add a setup wizard at some point, and this would be a part of it. Are you able to share your custom request file(s) at all? Since we don't have separate packages yet it's only theoretical, but what I meant by plugins might look like this.

// your index.ts
import { useCustomRequest } from '@hey-api/client-axios'

import { myCustomRequest } from './myCustomRequest'

useCustomRequest(myCustomRequest) // <-- TypeScript will complain if function doesn't match types

With this approach, we also want to solve some issues around integrations with Axios specifically. In the past, this package had to play catchup with Axios as they updated their config, see ferdikoomen/openapi-typescript-codegen#2067 for example. This isn't ideal for neither us nor users. We will remove the requests parameter only after we have covered these use cases so keep them coming!

[seriouslag]

I am not following your train of thought here.

Why would I be importing your packages into my files other than a config file?

I only want to import the generated code.

IMO whatever library is used to fetch data, (fetch, axios, etc) should be hidden from the end-use except for generation of generated code.

Some rough thoughts of the API I am thinking about.

/** ********************************* */
// index.ts from '@hey-api/core';

interface Property {
  type: string;
  format?: string;
  // other common properties to do conversions
  // can expand later
}

interface PropertyMiddleware<UncovertedType, ConvertedType> {
  /**
    * path(s) to custom class/type to import for generated code types to work;
    * Could be left empty in the case of Date
    */
   import?: string|string[]|((property: Property) => (string|string[]));
   /**
    * This is the string representation of what will be set for the type in the generated files
    * Would be 'Date' for the case of Date
    */
   convertedType: string;
   /**
    * This will be used on build and runtime
    * Checks if the property should be converted
    * checkProperty: (prop) => prop.type === 'string' && prop.format === 'date-time',
    */
  checkProperty: (property: Property) => boolean
  /**
    * This will be used on runtime clients to convert data at the service layer.
    * property is the OpenAPI definition ;
    * 
    * Convert data would would only be called if checkProperty is true.
    * convertData: (data, _prop) => new Date(data),
    */
  convertData: (data: UncovertedType, property: Property) => ConvertedType;
}

export type SyncRequestInterceptor = <Data,NewData = Data>(req: Request<Data>) => Request<NewData>;
export type AsyncRequestInterceptor = <Data,NewData = Data>(req: Request<Data>) => Request<NewData>;

export type RequestInterceptor = SyncRequestInterceptor|AsyncRequestInterceptor;

export type SyncResponseInterceptor = <Data, NewData = Data>(res: Response<Data) => Promise<Response<NewData>>;
export type AsyncResponseInterceptor = <Data, NewData = Data>(res: Response<Data) => Promise<Response<NewData>>;

export type ResponseInterceptor = SyncResponseInterceptor|AsyncResponseInterceptor;

/**
  * could override some of these properties with the CLI (client, outputFolder)
  */
export type Config = {
  /**
   * @default 'fetch'
   */
  client?: 'fetch'|'axios'|'etc';
  /**
   * @default '/generated'
   */
  outputFolder?: string;
  propertyMiddleware?: PropertyMiddleware[];
  requestInterceptors?: Array<RequestInterceptor>;
  responseInterceptor?: Array<ResponseInterceptor>;
}

export type Client = {
  request: <TRequest, TResponse>(request: Request<TRequest>) => Response<TResponse>
}

/** ********************************* */
// config file, only config the user needs to configure for this library to generate code
// Example of a .openapi-ts.config.mjs 
import { Config, PropertyMiddleware, SyncRequestInterceptor } form '@hey-api/core';

const DateMiddleware: PropertyMiddleware<string, Date> = {
  convertedType: 'Date',
  checkProperty: (prop) => prop.type === 'string' && prop.format === 'date-time',
  convertData: (data, _prop) => new Date(data),
}

const ApiHeadersInterceptor: SyncRequestInterceptor = (request) => {
  return {
     ...request,
     headers: {
       ...request.headers,
       'My-Custom-Header': 'MyValue',
    },
  };
}

const: Config = {
  outputFolder: './openapi/requests/'
  client: 'axios',
  propertyMiddleware: [DateMiddleware],
  requestInterceptors: [ApiHeadersInterceptor],
  responseInterceptors: [],
};

export default Config;

/** ********************************* */
// clients file will be generated depending on the client selected (axios, fetch, etc)
// client.ts
import { type Client } from '@hey-api/core';
import { AxiosClient } from '@hey-api/client-axios';

export const HttpClient: Client =  new AxiosClient(
// inject config here
);

/** ********************************* */
// services file could remain the same for any library that is used to fetch data
// services.ts
import { type Client } from '@hey-api/core';
import { HttpClient } from './client'; 

export class BananaService {
 public static getBananas() {
   return HttpClient.request('GET', '/bananas');
 }
}
/** ********************************* */

As I am writing this I feel a plugin system would be great.

I need to think on that more, but imagine a Zod plugin that generates Zod objects from the openapi spec then infers the model types from the zod types.
Then the services could validate the request/response based on the zod objects.

[mrlubos]

Yep, Zod is one of the most common packages among our users and it's in backlog to address (as is TanStack Query). I will come back to this later, thanks for starting this discussion!

[mrlubos]

As for your question "why would I import...," you're already importing our package. Except it's generated on the fly, which means the code to generate it has to be bundled with the type generator and it gets re-created on every run even if nothing changed.

It's also harder to test for us. Additionally, by separating them, we're forced to think about how these packages might communicate with each other through APIs which should lead to better outcomes for everyone (see the Axios config problem above)

[mrlubos]

@seriouslag Fetch API client is in beta, want to give it a try? You can also check out the demo if you don't have time to try it right now. Would love to hear your thoughts!

[martinssonj]

We use the request to extend ApiError with response headers. We also need the response headers for successful requests so we add some logic for that as well. Otherwise, we would not need it.

[mrlubos]

Thank you, will keep this in mind!

[mrlubos]

@martinssonj I don't know if you can use Fetch API client, but if yes, it's available now. There's also a demo if you don't have time to try it right now. Ignore if not relevant to you, otherwise I'd love your feedback!

[martinssonj]

Hi, I am trying the fetch client now instead. Can a custom transformer be added to get headers from the response?

[mrlubos]

@martinssonj you can get any header from the raw response object, is that not enough?

[martinssonj]

Yep, you are correct. I think I am now using the library correctly :)

[martinssonj]

Another issue related to request.ts is that before in openapi-typescript-codegen it looked like:

import FormData from 'form-data';
import fetch, { Headers } from 'node-fetch';

this but now in this library it looks like this:

import fetch, { FormData, Headers } from 'node-fetch';

But only node-fetch 3 exports FormData and node-fetch 2 does not so we get some compilation error.

We would like to use node-fetch 3 but it is ESM only so it is difficult to upgrade right now.

[mrlubos]

@jordanshatford curious on your thoughts about this since you worked on this part

[jordanshatford]

@martinssonj what version of node are you using. Is there any reason you can't use "fetch" since it does provide support in nodejs

[martinssonj]

We are using Node 20. The last time I tried fetch it did not work as expected but that was probably an earlier Node version.

[mrlubos]

@martinssonj does fetch work for you now? Have you tried the new client?