Easy Customisation of Response Code

[danclaytondev]

Hi,

I have been looking for a way to change the status code to a 201, to make best use of HTTP semantics.

I have seen that the way to do this is by defining a custom ResultHandler. I have made what I think is pretty much the defaultResultHandler, and changed the success code to 201. I want all the default functionality, apart from the status code. It looks like this:

const httpCreatedResultHandler = createResultHandler({
  getPositiveResponse: (output: IOSchema) => ({
    schema: z.object({
    status: z.literal("success"),
    data: output,
    }),
    statusCode: 201,
  }),
  getNegativeResponse: () =>
    z.object({
    status: z.literal("error"),
    error: z.object({
        message: z.string(),
    }),
    }),
  handler: ({ error, input, output, request, response, logger }) => {
    if (!error) {
    response.status(201).json({
        status: "success" as const,
        data: output,
    });
    return;
    }
    const statusCode = getStatusCodeFromError(error);
    if (statusCode === 500) {
    logger.error(`Internal server error\n${error.stack}\n`, {
        url: request.url,
        payload: input,
    });
    }
    response.status(statusCode).json({
    status: "error" as const,
    error: { message: getMessageFromError(error) },
    });
  },
});

I just wanted to ask whether this is the easiest way to do this. I would like the generated documentation to reflect the code which this does thankfully. But if I want a 202 handler as well, I will need to do this again and it seems a bit verbose!

This library is great, and I just wanted to see if I was understanding it properly :)

Thank you!

[RobinTail]

Hello, @danclaytondev .

Well, currently express-zod-api's documentation generator supports only one status code per positive and negative response. Though you can customize them exactly the way you did, I made this for simplicity, suggesting to reflect the details in the response response payload.

200 OK
201 Created
202 Accepted

Instead of encoding such details as "created" and "accepted" within the status code, consider having a property in the payload with a usual status code 200 OK.

const customResultHandler = createResultHandler({
  getPositiveResponse: (output: IOSchema) => z.object({
    status: z.literal("success"),
    detail: z.literal("created").or(z.literal("accepted"))
    data: output,
  }), // ...
})

However, in case you really want to have those status codes, but you don't want to repeat yourself, consider making a creator-function, that can produce result handlers for you, like this:

const makeResultHandler = (statusCode: number) => createResultHandler({
  getPositiveResponse: (output: IOSchema) => ({
    schema: z.object({
      status: z.literal("success"),
      data: output,
    }),
    statusCode, // <—— comes from the higher context
  }), // ...
}) );

[RobinTail]

@danclaytondev , would you like to help me in testing the feature #1431 ?

[danclaytondev]

Yes I would like to help!

[RobinTail]

Awesome, @danclaytondev .
I've just published a dev preview version 16.2.0-beta1 🚀
That version supports declaration of different response schemas for multiple status codes.

This is an example factory with a features kind of ResultHandler:

express-zod-api/example/factories.ts

Line 91 in 749fafc

export const statusDependingFactory = new EndpointsFactory({

And this is an example endpoint produced on that factory:
https://github.com/RobinTail/express-zod-api/blob/better-status-codes2/example/endpoints/create-user.ts

More details in the Changelog: https://github.com/RobinTail/express-zod-api/blob/better-status-codes2/CHANGELOG.md#1620

Consider installing that version and using the featured syntax for making a result handler according to your needs.
Please test how it responds and how it generates the documentation of your API.

Please let me know the results of your test including the ResultHandler you made.
In case of confusion or unclarity or lack of documentation, please let me know as well.
Thank you, @danclaytondev

[RobinTail]

@danclaytondev , I published version 16.2.0-beta2 which has some fixed and improvements comparing to first one.
Please check it out instead of -beta1.
Thank you.

[danclaytondev]

Hi @RobinTail! I have installed and tested 16.2.0-beta2, and it works as described/expected :). The ResultHandler I made ended up being the exact same as you have suggested in the changelog. I like the way we can supply either the same schema with different statusCodes, or multiple responses. That adds quite a lot of flexibility to the endpoints.

I am interested in your thinking on having both statusCode and statusCodes on the getPositiveResponse method. I wonder whether the type could be:

statusCode: number | number[]

and the framework detects whether it is an array or a single response code. I am not sure if that is possible, or even a good idea, I just thought I would suggest it.

How it works in beta2 is fine, and I tested using both statusCode at the same time as statusCodes, and it used the statusCode as the higher priority, which makes sense. The documentation still worked!

[RobinTail]

Thank you very much, @danclaytondev .
Yes, I had I lot of considerations on the way of declaring singular or multiple entities.
So far, I'm following a practice on having dedicated properties for arrays because it takes less syntax to handle.
Maybe I will combine all variations in one property later, but it would require to make a breaking change.
I will consider it.
Anyway, thank you for participating in the testing of the beta version and your review.

[RobinTail]

For those looking for a solution to the same problem,
the feature is available in version 16.2.0 🚀 — see Changelog for details.