Attach additional metadata information on the sdk method

[SukkaW]

Problem

We have been building our own SWR solution on top of the Hey API that looks like this:

import { addPet, findPetsByStatus } from 'sdk';

// our wrapped version of useSWR and useSWRMutation that accepts sdk method and sdk method arg
import { useData, useMutation } from './data';

export default function Example() {
  const { isMutating: isAdding, trigger: triggerAddPet } = useMutation(addPet);
  const { data, error, isLoading } = useData(findPetsByStatus, { query: { status: ['available'] } });

  return (
    <div>
      <button type="button" onClick={() => trigger({ body: { id: 1, name: 'Kitty', photoUrls: [] } })}>
        Add Pet
      </button>
      <ul>
        {data?.map((pet) => (
          <li key={pet.id}>{pet.name}</li>
        ))}
      </ul>
    </div>
  );
}

We are using SWR's React provider to do global error handling:

<SWRConfig
  value={{
    onError(error, swrKey, swrOptions) {
      const [sdkMethodFn, sdkMethodArg, someOtherOptions] = swrKey;
      // logging, error reporting, maybe an error toast, etc.
      console.error({ error, sdkMethodFn, sdkMethodArg, someOtherOptions });
    }
  }}
/>

With global error handling, we only have access to what SDK method function and what parameter are producing the issue, we don't have a human-readable name (sdkMethodFn.name can and will be broken by bundler and minifier) and other metadata (like the API path endpoint or the HTTP request method).

Proposal

What I am proposing is to expose some of the metadata field onto the generated method function. I am proposing:

Flat Mode

/**
 * Finds Pets by status
 *
 * Multiple status values can be provided with comma separated strings
 */
export const findPetsByStatus = <ThrowOnError extends boolean = true>(options: Options<FindPetsByStatusData, ThrowOnError>) => (options.client ?? client).get<FindPetsByStatusResponses, FindPetsByStatusErrors, ThrowOnError>({
    requestValidator: async (data) => await zFindPetsByStatusData.parseAsync(data),
    responseValidator: async (data) => await zFindPetsByStatusResponse.parseAsync(data),
    url: '/pet/findByStatus/MultipleExamples',
    ...options
});

findPetsByStatus.metadata = {
  name: 'findPetsByStatus',
  method: 'GET',
  url: '/pet/findByStatus/MultipleExamples',
  requestSchema: zFindPetsByStatusData,
  responseSchema: zFindPetsByStatusResponse
};

Instance Mode

class Sdk extends HetAPIClient {
    /**
     * Finds Pets by status
     *
     * Multiple status values can be provided with comma separated strings
     */
    public findPetsByStatus<ThrowOnError extends boolean = true>(options: Options<FindPetsByStatusData, ThrowOnError>) {
        return (options.client ?? this.client).get<FindPetsByStatusResponses, FindPetsByStatusErrors, ThrowOnError>({
            requestValidator: async (data) => await zFindPetsByStatusData.parseAsync(data),
            responseValidator: async (data) => await zFindPetsByStatusResponse.parseAsync(data),
            url: '/pet/findByStatus/MultipleExamples',
            ...options
        });
    }
}

Sdk.prototype.findPetsByStatus.metadata = {
  name: 'findPetsByStatus',
  method: 'GET',
  url: '/pet/findByStatus/MultipleExamples',
  requestSchema: zFindPetsByStatusData
  responseSchema: zFindPetsByStatusResponse
};

Alternative

A way to tap into the Hey API's client/client.gen.ts so we can attach metadata ourselves.

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔ ｜ pullfrog.com}

[mrlubos]

@SukkaW Can you show the alternative approach? At least some pseudo code if you didn't think about it in more detail.

Which specific fields/information do you need?

[mrlubos]

@SukkaW Would any of your problems be solved by the SWR plugin?

[SukkaW]

@SukkaW Would any of your problems be solved by the SWR plugin?

I am afraid not. The current SWR plugin really does not do much. #2956 only provides generation of key and fetcher, it does not even generate React Hooks like useAddPet or useFindPetByStatus, let alone global error handling via <SWRConfig />.

@SukkaW Can you show the alternative approach? At least some pseudo code if you didn't think about it in more detail.

Sure.

In the ideal world, I really want to use throwOnError: false, since this way we can have { data, error, request, response }, and this return object can easily be extended to have more fields:

const {
  data, error,
  request, response,
  name, url, method,
  requestSchema, responseSchema
} = findPetByStatys({ ... });

...that we can do whatever logging we want.

However, currently, throwOnError: false is broken. It will still throw errors even if throwsOnError is set to false, e.g.:

openapi-ts/examples/openapi-ts-ky/src/client/client/client.gen.ts

Lines 55 to 57 in 6e46330

	if (opts.requestValidator) {
	await opts.requestValidator(opts);
	}

openapi-ts/examples/openapi-ts-ky/src/client/client/client.gen.ts

Lines 254 to 256 in 6e46330

	if (opts.responseValidator) {
	await opts.responseValidator(data);
	}

..if either opts.requestValidator or opts.responseValidator throws an error, and it will, because Hey API's zod validation uses parseAsync:

openapi-ts/packages/openapi-ts-tests/main/test/__snapshots__/2.0.x/plugins/@hey-api/transformers/type-format-zod/sdk.gen.ts

Lines 24 to 26 in 6e46330

	requestValidator: async (data) => await zPostFooData.parseAsync(data),
	responseTransformer: postFooResponseTransformer,
	responseValidator: async (data) => await zPostFooResponse.parseAsync(data),

...which will throw a ZodError on validation fail, this error is never caught by the client and leaks.

This is the root cause behind both #2204 and #3150, which you overlooked.

If throwOnError: false will cause errors to be thrown, we might as well just use throwOnError: true.

But this means we do not have much useful information:

try {
  const { data: pets, request, response } = await findPetsByStatus({ query: { status: [] } });
  // we only have request and response if the `findPetsByStatus` succeeds.
  // but what happens if it fails?
} catch (e) {
  // The error thrown here is barebones; we don't have anything to work on.
}

In the realworld, here is how I implemented our SWR solution:

const { data, error, isLoading } = useData(findPetsByStatus, { query: { status: ['available'] } });
// useData is just a wrapped version of the useSWR, which translates into:
useSWR(
  [findPetsByStatus, { query: { status: ['available'] } }] /* swr key */
);

// Ideally, we'd want to have this, but #2956 doesn't do this:
useFindPetsByStatus({ query: { status: ['available'] } });

// fetchMiddleware is where fetcher is injected and the sdk is actually invoked:
const fetchMiddleware: SWRMiddleware =
  (useSWRNext) =>
  (key: InternalSWRKey, _: any, config: any): SWRResponse => {
    // We initialized our client with `createClient()` somewhere else, and stored in a React context:
    const client = useClient();

    const fetcher = useCallback(
      async (key: InternalSWRKey) => {
        // sdkMethod: findPetsByStatus
        // sdkArg: { query: { status: ['available'] } }
        const [sdkMethod, sdkArg] = key;

        try {
          return await sdkMethod({
            client, // from useClient();
            ...sdkArg
          });
        } catch (e) {
          // We only have access to `sdkMethod` and `sdkArg`
          // There is really no useful information we can work with
        }
      },
      [sdkClient],
    );

    return useSWRNext(key, fetcher, config);
  };

[SukkaW]

Here is a copy of the disscussion of me and @mrlubos here about the metadata:

Normally, when you call editPet, the data is submitted to the backend, and you expect useListPet() to automatically revalidate the cache so that "Component B" will re-render with the latest data.

However, in order to do so, we need a way to find the connection between editPet and listPet here.

Currently, editPet and listPet are two different Hey API generated SDK exported methods, and there is no way to make connections between those two methods.

If we can make the connection here, it is very easy for SWR to implement the auto revalidation.

One way to do it is to expose extra metadata here.
Let's say Hey API codegen-ed SDK exports method like this:

export const getPetById = Object.assign(
  function getPetById(options) {
    return (options.client ?? client)[method]({
      /* codegen client o */
      url: '/pets/{planetId}'
    })
  },
  {
    id: 'getPetById',
    method: 'get',
    url: '/pets/{planetId}',
    responseSchema: zGetPetResponse
  }
)

getPetById would still be callable as getPetById(options), but now we can also access the URL metadata via getPetById.url.

With RESTful API, now updatePetById and getPetById would have the same URL /pets/{planetId}, hence the connection.

OpenAPI spec may also include tags, we can have an option to expose that as metadata as well.

class Service {
  getById = Object.assign<MethodFunctionType, MetadataType>(
    () => { // must use arrow function here for correct `this`
      return client[method]();
    },
    { metadata }
 );
}

class Service {
  public static getById = Object.assign<MethodFunctionType, MetadataType>(
    (options) => {
      return (options.client ?? client)[method]();
    },
    { metadata }
 );
}

[mrlubos]

@SukkaW maybe a good starting point would be to add Resolvers to the SDK plugin so you have an escape hatch to build your own output however you like? What do you think

[SukkaW]

@mrlubos I have created an initial fix of this issue in #3923

However, as I am not familiar with the resolver on SDK concept here (I am only aware of resolver on Validation right now), would you mind continuing from that PR so that this behavior can be customizable?