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);
  };