Advise on how to write a typed response handler

[waza-ari]

I'm using the openapi-typescript and openapi-fetch library on top of my NextJS project with server actions to handle form data. One reference implementation looks pretty much like this:

type ServerActionResponse<T> =
  | {
      status: 'success';
      data: T;
      correlationId?: string;
    }
  | {
      status: 'error';
      message: string;
      correlationId?: string;
    }

export async function registerMember(
  data: UserMemberRegister
): Promise<ServerActionResponse<UserMemberRegisterResponse>> {
  try {
    SignupSchema.parse(data);
    const response = await client.POST('/api/v1/user/register/member', { body: data });
    if (response.response.status !== 201) {
      return {
        status: 'error',
        correlationId: response.response.headers.get('X-Request-ID') || undefined,
        message: (response.error.detail as string) || 'Something went wrong. Please try again.'
      };
    }
    return {
      status: 'success',
      data: response.data
    };
  } catch (e) {
    return {
      status: 'error',
      message: 'Something went wrong. Please try again.'
    };
  }
}

Basically it takes the data from the client side, validates it, sends the request and performs basic validation. The API returns a header containing a unique request ID, so I'm returning this as well. Much of that code is pretty boilerplate, ideally I'd want to do something like this:

export async function registerMember(
  data: UserMemberRegister
): Promise<ServerActionResponse<UserMemberRegisterResponse>> {
  SignupSchema.parse(data);
  const response = await client.POST('/api/v1/user/register/member', { body: data });
  return handleResponse(response, 201)
}

Where the handleResponse function would do all the validation. I'm having quite some trouble to come up with the method signature though, as the type of FetchResponse is generic:

type FetchResponse<T, O> = {
    data: ParseAsResponse<FilterKeys<SuccessResponse<ResponseObjectMap<T>>, MediaType>, O>;
    error?: never;
    response: Response;
} | {
    data?: never;
    error: FilterKeys<ErrorResponse<ResponseObjectMap<T>>, MediaType>;
    response: Response;
}

The data attribute uses types which are not exported by the library. Any idea how to handle this use-case without repeating myself?

[drwpow]

This seems related to #1440, a bit. The openapi-typescript-helpers package is meant to help a bit with creating some of these layered inferences yourself, but it’s really hard to do in general, and it usually takes a bit of time to get what you want.

As a general tip: a lot of good inference comes from making full use of the extends keyword, and most of the library is just nesting those really (really) deeply to infer the correct path. In your case, you could do something like:

type ResponseData = response extends { data: any } ? response["data"] : never;
const data: ResponseData = response.data;

(this is contrived, and doesn’t do what you want, but it just shows how I debug these things step-by-step)

The second tip is when you’re crossing the boundary into handleResponse, you won’t be able to type the response parameter directly; you’ll need to rely on generics like ClientMethod does. The reason is when you re-type something, you essentially lose all inference, and tell TypeScript “this type could be any possible type of the options given.” But when you use generics, you’re giving TypeScript a hint that it needs to pick up where the parent function left off, and some work needs to be done figuring out what this specific instance is typed as. This can often be tricky, and leads in not-so-straightforward code.

Really, a lot of this advanced TypeScript stuff is just taking it slow, and taking it step-by-step. None of the type inference in this library were created first pass; they were built step-by-step and refined and cleaned up over a long time. Just try and introspect the next layer, and keep going layer-by-layer until you get where you want.

[waza-ari]

Hi, first of all, thank you so much for taking the time and answer these questions (and for providing the library in the first place). I decided to go down a little different route, inspired by #1440 you mentioned. Essentially, I'm using a custom GET method like this:

import type { FetchOptions, FetchResponse } from 'openapi-fetch';
import type { PathsWithMethod, FilterKeys, SuccessResponse } from 'openapi-typescript-helpers';
import { paths } from './v1';

const client = createClient<paths>({ baseUrl: process.env.NEXT_PUBLIC_API_BASE_URL });

export async function apiGet<
  Path extends PathsWithMethod<paths, 'get'>,
  Init extends FetchOptions<FilterKeys<paths[Path], 'get'>>,
  Response extends FetchResponse<paths[Path]['get'], SuccessResponse<paths[Path]['get']['responses']>>['data']
>(path: Path, init: Init): Promise<Response> {
  const { data, error, response } = await client.GET(path, { ...init });
  if (error) {
    const suffix = [401, 403, 404].includes(response.status) ? `_${response.status}` : '';
    throw new Error(`API_ERROR${suffix}`, { cause: error });
  }
  return data as Response;
}

This method is used in NextJS async React Server Components like this, with full autocompletion working

import { apiGet } from '@/lib/api/client';

const Page = async ({ params }: { params: { id: number } }) => {
  const item = await apiGet('/api/v1/inventory/item/{inventory_item_id}', {
    params: { path: { inventory_item_id: params.id } }
  });

  // ...
}

Based on the custom error message and the fact that NextJS forwards server errors to the client, I can easily handle errors in a error.tsx file. That is obviously a very opinionated way of doing it, but it works fine for me.

'use client';

import { signIn } from 'next-auth/react';
import Image from 'next/image';

const supportedErrors = {
  API_ERROR_404: {
    title: 'Not Found.'
  },
  API_ERROR: {
    title: 'Other API error.'
  },
  default: {
    title: 'Ooops - There was an error',
  }
};

export function isKeyOfObject<T extends object>(key: string | number | symbol, obj: T): key is keyof T {
  return key in obj;
}

const Error = ({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) => {

  const error_index = isKeyOfObject(error.message, supportedErrors) ? error.message : 'default';

  return (
    <Container container spacing={4}>
      <Grid container spacing={4} direction={'row-reverse'}>
          // Do whatever you want with {error.title} or extend it any way you want
      </Grid>
      <Grid xs={12}>
        <h2>Details</h2>
        <pre>{error.stack}</pre>
      </Grid>
    </Container>
  );
};

export default Error;